Agent Chat Channel

// ---------------------------------------------------------------------------
// Actor types
// ---------------------------------------------------------------------------

/** Who can participate in a chat conversation */
export type ChatActorKind = 'user' | 'agent' | 'system';

/** A participant in a chat conversation */
export interface ChatActor {
  /** Unique identifier (user ID or agent code) */
  id: string;

  /** Actor classification */
  kind: ChatActorKind;

  /** Display name (e.g. "Jane Doe" or "Mechanical Agent") */
  displayName: string;

  /** Agent code when kind is 'agent' (e.g. 'ME', 'EE', 'FW') */
  agentCode?: string;
}

// ---------------------------------------------------------------------------
// Message types
// ---------------------------------------------------------------------------

/** Delivery status of a chat message */
export type MessageStatus = 'sending' | 'sent' | 'delivered' | 'error';

/** A single message in a chat thread */
export interface ChatMessage {
  /** Unique message identifier */
  id: string;

  /** Thread this message belongs to */
  threadId: string;

  /** Who sent this message */
  actor: ChatActor;

  /** Message content (Markdown supported) */
  content: string;

  /** Current delivery status */
  status: MessageStatus;

  /** ISO timestamp when the message was created */
  createdAt: string;

  /** ISO timestamp when the message was last updated (e.g. streaming complete) */
  updatedAt?: string;

  /** Optional reference to a graph entity this message relates to */
  graphRef?: ChatGraphRef;
}

/** Reference to a graph entity for contextual messages */
export interface ChatGraphRef {
  /** Node ID in the design graph */
  nodeId: string;

  /** Node type (e.g. 'requirement', 'component', 'test') */
  nodeType: string;

  /** Human-readable label */
  label: string;
}

// ---------------------------------------------------------------------------
// Scope types
// ---------------------------------------------------------------------------

/** Defines the context for a chat conversation */
export interface ChatScope {
  /** What kind of entity this conversation is about */
  kind: 'session' | 'approval' | 'bom-entry' | 'digital-twin-node' | 'project';

  /** ID of the scoped entity (session ID, approval ID, BOM entry ID, node ID, or project ID) */
  entityId: string;

  /** Optional human-readable label for the scoped entity */
  label?: string;
}

// ---------------------------------------------------------------------------
// Thread and channel types
// ---------------------------------------------------------------------------

/** A conversation thread between an engineer and one or more agents */
export interface ChatThread {
  /** Unique thread identifier */
  id: string;

  /** Conversation scope — what this thread is about */
  scope: ChatScope;

  /** Channel this thread belongs to */
  channelId: string;

  /** Thread title (auto-generated or user-defined) */
  title: string;

  /** All messages in this thread (may be paginated) */
  messages: ChatMessage[];

  /** Participants in this thread */
  participants: ChatActor[];

  /** ISO timestamp when the thread was created */
  createdAt: string;

  /** ISO timestamp of the most recent message */
  lastMessageAt: string;

  /** Whether the thread is archived */
  archived: boolean;
}

/** A chat channel groups threads by scope kind */
export interface ChatChannel {
  /** Unique channel identifier */
  id: string;

  /** Channel display name (e.g. "Approvals", "BOM", "General") */
  name: string;

  /** Scope kind this channel serves */
  scopeKind: ChatScope['kind'];

  /** Number of unread messages across all threads in this channel */
  unreadCount: number;
}

/** Payload for chat.message.created events */
export interface ChatMessageCreatedEvent {
  /** The complete message that was created */
  message: ChatMessage;

  /** Thread ID for targeted UI updates */
  threadId: string;
}

/** Payload for chat.message.chunk events (streaming LLM responses) */
export interface ChatMessageChunkEvent {
  /** Message ID being streamed */
  messageId: string;

  /** Thread ID for targeted UI updates */
  threadId: string;

  /** The text chunk to append */
  chunk: string;

  /** Whether this is the final chunk */
  done: boolean;
}

/** Payload for chat.agent.typing events */
export interface ChatAgentTypingEvent {
  /** Thread ID where the agent is typing */
  threadId: string;

  /** The agent that is typing */
  agent: ChatActor;

  /** Whether the agent started or stopped typing */
  isTyping: boolean;
}

export type WebSocketEventType =
  // ... existing event types ...
  | 'chat.message.created'
  | 'chat.message.chunk'
  | 'chat.agent.typing'
  | 'chat.thread.created';

const EVENT_MAP: Record<string, InvalidationRule> = {
  // ... existing entries ...

  "chat.message.created": {
    keys: [["chat-threads"]],
  },
  "chat.thread.created": {
    keys: [["chat-threads"], ["chat-channels"]],
  },
};

import { client } from "@/api/client";
import type {
  ChatThread,
  ChatChannel,
  ChatMessage,
  ChatScope,
} from "@/types/chat";
import type { PaginatedResponse } from "@/types/common";

// ---------------------------------------------------------------------------
// Query parameters
// ---------------------------------------------------------------------------

export interface GetChatThreadsParams {
  /** Filter by channel ID */
  channelId?: string;
  /** Filter by scope kind */
  scopeKind?: ChatScope['kind'];
  /** Filter by scope entity ID */
  entityId?: string;
  /** Include archived threads */
  includeArchived?: boolean;
  /** Pagination limit */
  limit?: number;
  /** Pagination offset */
  offset?: number;
}

export interface CreateChatThreadPayload {
  /** Conversation scope */
  scope: ChatScope;
  /** Optional initial message content */
  initialMessage?: string;
  /** Optional thread title (auto-generated if omitted) */
  title?: string;
}

export interface SendChatMessagePayload {
  /** Message content (Markdown) */
  content: string;
  /** Optional graph reference */
  graphRef?: {
    nodeId: string;
    nodeType: string;
    label: string;
  };
}

// ---------------------------------------------------------------------------
// Endpoints
// ---------------------------------------------------------------------------

/**
 * List chat threads with optional filtering and pagination.
 */
export async function getChatThreads(
  params?: GetChatThreadsParams,
): Promise<PaginatedResponse<ChatThread>> {
  const { data } = await client.get<PaginatedResponse<ChatThread>>(
    "/chat/threads",
    { params },
  );
  return data;
}

/**
 * Retrieve a single chat thread by ID, including all messages.
 */
export async function getChatThread(id: string): Promise<ChatThread> {
  const { data } = await client.get<ChatThread>(`/chat/threads/${id}`);
  return data;
}

/**
 * Create a new chat thread with a given scope.
 */
export async function createChatThread(
  payload: CreateChatThreadPayload,
): Promise<ChatThread> {
  const { data } = await client.post<ChatThread>("/chat/threads", payload);
  return data;
}

/**
 * Send a message in an existing chat thread.
 * The backend routes the message to the appropriate domain agent.
 */
export async function sendChatMessage(
  threadId: string,
  payload: SendChatMessagePayload,
): Promise<ChatMessage> {
  const { data } = await client.post<ChatMessage>(
    `/chat/threads/${threadId}/messages`,
    payload,
  );
  return data;
}

/**
 * List available chat channels.
 */
export async function getChatChannels(): Promise<ChatChannel[]> {
  const { data } = await client.get<{ channels: ChatChannel[] }>(
    "/chat/channels",
  );
  return data.channels;
}

import {
  useQuery,
  useMutation,
  useQueryClient,
  type UseQueryOptions,
} from "@tanstack/react-query";
import {
  getChatThreads,
  getChatThread,
  getChatChannels,
  createChatThread,
  sendChatMessage,
  type GetChatThreadsParams,
  type CreateChatThreadPayload,
  type SendChatMessagePayload,
} from "@/api/endpoints/chat";
import type { PaginatedResponse } from "@/types/common";
import type { ChatThread, ChatChannel, ChatMessage } from "@/types/chat";

// ---------------------------------------------------------------------------
// Queries
// ---------------------------------------------------------------------------

/**
 * Fetch chat threads with optional filtering. Refetches every 30 seconds.
 */
export function useChatThreads(
  params?: GetChatThreadsParams,
  options?: Partial<UseQueryOptions<PaginatedResponse<ChatThread>>>,
) {
  return useQuery<PaginatedResponse<ChatThread>>({
    queryKey: ["chat-threads", params],
    queryFn: () => getChatThreads(params),
    staleTime: 30_000,
    refetchInterval: 30_000,
    ...options,
  });
}

/**
 * Fetch a single chat thread by ID, including all messages.
 */
export function useChatThread(
  id: string | undefined,
  options?: Partial<UseQueryOptions<ChatThread>>,
) {
  return useQuery<ChatThread>({
    queryKey: ["chat-thread", id],
    queryFn: () => getChatThread(id!),
    enabled: !!id,
    staleTime: 10_000,
    ...options,
  });
}

/**
 * Fetch available chat channels.
 */
export function useChatChannels(
  options?: Partial<UseQueryOptions<ChatChannel[]>>,
) {
  return useQuery<ChatChannel[]>({
    queryKey: ["chat-channels"],
    queryFn: getChatChannels,
    staleTime: 60_000,
    ...options,
  });
}

// ---------------------------------------------------------------------------
// Mutations
// ---------------------------------------------------------------------------

/**
 * Create a new chat thread. Invalidates the thread list on success.
 */
export function useCreateChatThread() {
  const queryClient = useQueryClient();

  return useMutation<ChatThread, Error, CreateChatThreadPayload>({
    mutationFn: createChatThread,
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ["chat-threads"] });
      queryClient.invalidateQueries({ queryKey: ["chat-channels"] });
    },
  });
}

/**
 * Send a message in a chat thread. Invalidates the specific thread on success.
 */
export function useSendChatMessage() {
  const queryClient = useQueryClient();

  return useMutation<
    ChatMessage,
    Error,
    { threadId: string; payload: SendChatMessagePayload }
  >({
    mutationFn: ({ threadId, payload }) =>
      sendChatMessage(threadId, payload),
    onSuccess: (_data, { threadId }) => {
      queryClient.invalidateQueries({ queryKey: ["chat-thread", threadId] });
      queryClient.invalidateQueries({ queryKey: ["chat-threads"] });
    },
  });
}

import { create } from "zustand";

// ---------------------------------------------------------------------------
// Types
// ---------------------------------------------------------------------------

export interface ChatStoreState {
  /** Whether the persistent chat sidebar is open. */
  sidebarOpen: boolean;

  /** ID of the thread currently displayed in the sidebar. */
  activeSidebarThreadId: string | null;

  /**
   * Streaming content accumulator, keyed by message ID.
   * Each entry holds the concatenated chunks received so far.
   */
  streamingContent: Record<string, string>;

  /**
   * Set of thread IDs where an agent is currently typing.
   */
  typingThreadIds: Set<string>;
}

export interface ChatStoreActions {
  /** Open the sidebar, optionally jumping to a specific thread. */
  openSidebar: (threadId?: string) => void;

  /** Close the sidebar. */
  closeSidebar: () => void;

  /** Append a streaming chunk to a message's accumulator. */
  appendStreamChunk: (messageId: string, chunk: string) => void;

  /** Clear streaming content for a message (called when streaming completes). */
  clearStreamContent: (messageId: string) => void;

  /** Set the typing indicator for a thread. */
  setAgentTyping: (threadId: string, isTyping: boolean) => void;
}

export type ChatStore = ChatStoreState & ChatStoreActions;

// ---------------------------------------------------------------------------
// Store
// ---------------------------------------------------------------------------

export const useChatStore = create<ChatStore>()((set) => ({
  // -- state defaults -------------------------------------------------------
  sidebarOpen: false,
  activeSidebarThreadId: null,
  streamingContent: {},
  typingThreadIds: new Set(),

  // -- actions --------------------------------------------------------------

  openSidebar: (threadId) =>
    set({
      sidebarOpen: true,
      ...(threadId ? { activeSidebarThreadId: threadId } : {}),
    }),

  closeSidebar: () =>
    set({ sidebarOpen: false }),

  appendStreamChunk: (messageId, chunk) =>
    set((state) => ({
      streamingContent: {
        ...state.streamingContent,
        [messageId]: (state.streamingContent[messageId] ?? "") + chunk,
      },
    })),

  clearStreamContent: (messageId) =>
    set((state) => {
      const { [messageId]: _, ...rest } = state.streamingContent;
      return { streamingContent: rest };
    }),

  setAgentTyping: (threadId, isTyping) =>
    set((state) => {
      const next = new Set(state.typingThreadIds);
      if (isTyping) {
        next.add(threadId);
      } else {
        next.delete(threadId);
      }
      return { typingThreadIds: next };
    }),
}));