@arcote.tech/arc-chat 0.4.9 → 0.5.0

package/src/listeners/ai-generation-listener.ts

@@ -0,0 +1,293 @@
+/// <reference path="../arc.d.ts" />
+import { listener, type ArcContextElement } from "@arcote.tech/arc";
+import type { ArcToolAny, LLMProvider, Message, ToolContext } from "@arcote.tech/arc-ai";
+import type { PrepareContext, PrepareParams, PrepareResult } from "../chat-builder";
+import {
+  createStreamSession,
+  getStreamSession,
+  deleteStreamSession,
+} from "../streaming/stream-registry";
+
+// ─── Config ─────────────────────────────────────────────────────
+
+export interface AiGenerationListenerConfig {
+  name: string;
+  messageElement: any;
+  resolveProvider: (model: string) => LLMProvider | undefined;
+  prepare?: (ctx: PrepareContext, params: PrepareParams) => Promise<PrepareResult>;
+  tools: ArcToolAny[];
+  clientTools: ArcToolAny[];
+  toolMutationElements: ArcContextElement<any>[];
+  maxExecutionCount: number;
+}
+
+// ─── Factory ────────────────────────────────────────────────────
+
+export function createAiGenerationListener(config: AiGenerationListenerConfig) {
+  const {
+    name,
+    messageElement,
+    resolveProvider,
+    prepare,
+    tools: defaultTools,
+    clientTools: defaultClientTools,
+    toolMutationElements,
+    maxExecutionCount: defaultMaxExecution,
+  } = config;
+
+  const messageSentEvent = messageElement.getEvent("messageSent");
+
+  return listener(`${name}AiGeneration`)
+    .listenTo([messageSentEvent])
+    .async()
+    .query([messageElement])
+    .mutate([messageElement, ...toolMutationElements])
+    .handle(async (ctx, event) => {
+      const payload = event.payload;
+      const {
+        sessionId,
+        scopeId,
+        content: userContent,
+        model: modelName,
+      } = payload;
+
+      // 1. Get or create stream session
+      let session = getStreamSession(sessionId);
+      if (!session) {
+        session = createStreamSession(sessionId);
+      }
+
+      // 2. Resolve provider
+      const model = modelName ?? "gpt-4o";
+      const provider = resolveProvider(model);
+      if (!provider) {
+        session.push({
+          type: "error",
+          sessionId,
+          error: `Provider not found for model: ${model}`,
+        });
+        session.close();
+        deleteStreamSession(sessionId);
+        return;
+      }
+
+      // 3. Call prepare callback to get instructions, tools, clientTools
+      let instructions = "";
+      let serverTools = defaultTools;
+      let clientTools = defaultClientTools;
+
+      if (prepare) {
+        const prepareCtx: PrepareContext = {
+          query: (element) => ctx.query(element),
+          mutate: (element) => ctx.mutate(element),
+        };
+        const prepareResult = await prepare(prepareCtx, {
+          content: userContent,
+          identifyBy: scopeId,
+          model,
+        });
+        instructions = prepareResult.instructions;
+        if (prepareResult.tools) serverTools = prepareResult.tools;
+        if (prepareResult.clientTools) clientTools = prepareResult.clientTools;
+      }
+
+      // Build server tools map
+      const serverToolsMap = new Map(serverTools.map((t) => [t.name, t]));
+      const serverToolNames = [...serverToolsMap.keys()];
+
+      // Build tool defs for LLM (server + client)
+      const allToolsForLLM = [...serverTools, ...clientTools];
+      const toolDefs = allToolsForLLM.length > 0
+        ? allToolsForLLM.map((t) => t.toJsonSchema())
+        : undefined;
+
+      // 4. Load conversation history
+      const history = await ctx.query(messageElement).getByScope({ scopeId });
+
+      // 5. Build messages array
+      const messages: Message[] = [];
+
+      if (instructions) {
+        messages.push({ role: "system", content: instructions });
+      }
+
+      for (const msg of history) {
+        if (msg.role === "user" && msg.content === userContent && msg._id === payload.messageId) {
+          continue;
+        }
+        messages.push({
+          role: msg.role as Message["role"],
+          content: msg.content,
+        });
+      }
+
+      messages.push({ role: "user", content: userContent });
+
+      // 6. Build tool context for server tool execution
+      const toolCtx: ToolContext = {
+        mutate: (element) => ctx.mutate(element),
+        query: (element) => ctx.query(element),
+        identifyBy: scopeId,
+      };
+
+      // 7. AI generation loop
+      let executionCount = 0;
+      let fullContent = "";
+      let previousResponseId: string | undefined;
+
+      try {
+        while (executionCount <= defaultMaxExecution) {
+          const result = await provider.streamComplete(
+            { model, messages, tools: toolDefs, previousResponseId },
+            (chunk) => {
+              switch (chunk.type) {
+                case "content_delta":
+                  if (chunk.content) {
+                    fullContent += chunk.content;
+                    session!.push({
+                      type: "content_delta",
+                      sessionId,
+                      content: chunk.content,
+                    });
+                  }
+                  break;
+                case "usage_update":
+                  session!.push({
+                    type: "usage_update",
+                    sessionId,
+                    usage: chunk.usage,
+                  });
+                  break;
+              }
+            },
+          );
+
+          if (result.content) {
+            fullContent = result.content;
+          }
+          previousResponseId = result.responseId;
+
+          // No tool calls — generation complete
+          if (
+            result.finishReason !== "tool_call" ||
+            result.toolCalls.length === 0
+          ) {
+            await ctx.mutate(messageElement).completeAssistantMessage({
+              scopeId,
+              sessionId,
+              content: fullContent,
+              model,
+              usage: JSON.stringify(result.usage),
+            });
+
+            session.push({
+              type: "done",
+              sessionId,
+              usage: result.usage,
+              finishReason: result.finishReason,
+              executionCount,
+            });
+            break;
+          }
+
+          // Separate server vs client tool calls
+          const serverCalls = result.toolCalls.filter((tc) =>
+            serverToolNames.includes(tc.name),
+          );
+          const clientCalls = result.toolCalls.filter(
+            (tc) => !serverToolNames.includes(tc.name),
+          );
+
+          // Execute server tools with aggregate context
+          for (const tc of serverCalls) {
+            session.push({
+              type: "server_tool_start",
+              sessionId,
+              toolCall: tc,
+              executionCount,
+            });
+
+            const tool = serverToolsMap.get(tc.name);
+            let resultContent: string;
+            let isError = false;
+
+            if (tool) {
+              try {
+                resultContent = await tool.executeWithContext(tc.arguments, toolCtx);
+              } catch (err) {
+                resultContent = `Tool execution error: ${err instanceof Error ? err.message : String(err)}`;
+                isError = true;
+              }
+            } else {
+              resultContent = `Tool "${tc.name}" not found on server`;
+              isError = true;
+            }
+
+            session.push({
+              type: "server_tool_result",
+              sessionId,
+              toolResult: {
+                toolCallId: tc.id,
+                name: tc.name,
+                content: resultContent,
+                isError,
+              },
+              executionCount,
+            });
+
+            messages.push({
+              role: "tool",
+              content: resultContent,
+              toolCallId: tc.id,
+              name: tc.name,
+            });
+          }
+
+          // Request client tool execution
+          if (clientCalls.length > 0) {
+            session.push({
+              type: "client_tool_request",
+              sessionId,
+              toolCalls: clientCalls,
+              executionCount,
+            });
+
+            try {
+              const clientResults =
+                await session.waitForClientToolResults();
+
+              for (const tr of clientResults) {
+                messages.push({
+                  role: "tool",
+                  content: tr.content,
+                  toolCallId: tr.toolCallId,
+                  name: tr.name,
+                });
+              }
+            } catch (err) {
+              session.push({
+                type: "error",
+                sessionId,
+                error: `Client tool execution failed: ${err instanceof Error ? err.message : String(err)}`,
+                executionCount,
+              });
+              break;
+            }
+          }
+
+          fullContent = "";
+          executionCount++;
+        }
+      } catch (err) {
+        session.push({
+          type: "error",
+          sessionId,
+          error: `AI generation error: ${err instanceof Error ? err.message : String(err)}`,
+          executionCount,
+        });
+      } finally {
+        session.close();
+        deleteStreamSession(sessionId);
+      }
+    });
+}

package/src/react/index.ts

@@ -9,3 +9,7 @@ export type {
   Question,
   QuestionAnswers,
 } from "@arcote.tech/arc-ds";
+
+// Chat hook
+export { useChat } from "./use-chat";
+export type { UseChatConfig, UseChatReturn } from "./use-chat";

package/src/react/use-chat.ts

@@ -0,0 +1,260 @@
+import { useState, useCallback, useRef, useEffect } from "react";
+import type {
+  ChatStreamEvent,
+  ToolCall,
+  ToolResult,
+} from "@arcote.tech/arc-ai";
+import type { ChatMessageData, ToolUse } from "@arcote.tech/arc-ds";
+
+// ─── Config ─────────────────────────────────────────────────────
+
+export interface UseChatConfig {
+  chatName: string;
+  baseUrl?: string;
+  identifyBy?: string;
+  onClientToolCall?: (toolCalls: ToolCall[]) => Promise<ToolResult[]>;
+  onToolUse?: (toolCall: ToolCall, result: string) => ToolUse | undefined;
+  queries?: {
+    getByScope: (params: { scopeId: string }) => readonly [any[] | undefined, boolean];
+  };
+  mutations?: {
+    sendMessage: (params: Record<string, any>) => Promise<any>;
+  };
+}
+
+// ─── Return Type ────────────────────────────────────────────────
+
+export interface UseChatReturn {
+  messages: ChatMessageData[];
+  isStreaming: boolean;
+  sendMessage: (content: string, options: { model: string }) => Promise<void>;
+  setMessages: React.Dispatch<React.SetStateAction<ChatMessageData[]>>;
+}
+
+// ─── Hook ───────────────────────────────────────────────────────
+
+export function useChat(config: UseChatConfig): UseChatReturn {
+  const [messages, setMessages] = useState<ChatMessageData[]>([]);
+  const [isStreaming, setIsStreaming] = useState(false);
+
+  const configRef = useRef(config);
+  configRef.current = config;
+
+  // Sync identifyBy and load history
+  const scopeId = config.identifyBy;
+  const historyResult = config.queries?.getByScope(
+    scopeId ? { scopeId } : { scopeId: "" },
+  );
+  const historyData = scopeId ? historyResult?.[0] : undefined;
+
+  useEffect(() => {
+    if (!historyData || historyData.length === 0 || isStreaming) return;
+
+    const mapped: ChatMessageData[] = historyData.map((msg) => ({
+      id: msg._id,
+      role: msg.role as "user" | "assistant",
+      content: msg.content,
+    }));
+
+    setMessages(mapped);
+  }, [historyData?.length, scopeId]);
+
+  // Cleanup
+  const eventSourceRef = useRef<EventSource | null>(null);
+  useEffect(() => {
+    return () => {
+      eventSourceRef.current?.close();
+    };
+  }, []);
+
+  const sendMessage = useCallback(
+    async (content: string, options: { model: string }) => {
+      if (isStreaming) return;
+
+      const { mutations, chatName, baseUrl, onClientToolCall, onToolUse } =
+        configRef.current;
+      const currentScopeId = configRef.current.identifyBy;
+
+      if (!mutations || !currentScopeId) {
+        console.error("useChat: mutations or identifyBy not provided");
+        return;
+      }
+
+      setIsStreaming(true);
+
+      const userMsgId = `user_${Date.now()}`;
+      setMessages((prev) => [
+        ...prev,
+        { id: userMsgId, role: "user", content },
+      ]);
+
+      try {
+        const sendResult = await mutations.sendMessage({
+          scopeId: currentScopeId,
+          content,
+          model: options.model,
+        });
+
+        const { sessionId } = sendResult as { sessionId: string; messageId: string };
+        if (!sessionId) {
+          throw new Error("No sessionId returned from sendMessage");
+        }
+
+        const routeBase = baseUrl ?? "";
+        const streamUrl = `${routeBase}/route/chat/${chatName}/stream/${sessionId}`;
+
+        const response = await fetch(streamUrl, {
+          credentials: "include",
+          headers: { Accept: "text/event-stream" },
+        });
+
+        if (!response.ok) {
+          throw new Error(`Stream connection failed: ${response.status}`);
+        }
+
+        const assistantMsgId = `assistant_${Date.now()}`;
+        setMessages((prev) => [
+          ...prev,
+          { id: assistantMsgId, role: "assistant", content: "", isStreaming: true },
+        ]);
+
+        const reader = response.body!.getReader();
+        const decoder = new TextDecoder();
+        let partialLine = "";
+        const toolUses: ToolUse[] = [];
+
+        const processEvent = async (event: ChatStreamEvent) => {
+          switch (event.type) {
+            case "content_delta":
+              if (event.content) {
+                setMessages((prev) =>
+                  prev.map((msg) =>
+                    msg.id === assistantMsgId
+                      ? { ...msg, content: msg.content + event.content }
+                      : msg,
+                  ),
+                );
+              }
+              break;
+
+            case "server_tool_result":
+              if (event.toolResult && event.toolCall) {
+                const toolUse = onToolUse?.(event.toolCall, event.toolResult.content);
+                if (toolUse) {
+                  toolUses.push(toolUse);
+                  setMessages((prev) =>
+                    prev.map((msg) =>
+                      msg.id === assistantMsgId
+                        ? { ...msg, toolUses: [...toolUses] }
+                        : msg,
+                    ),
+                  );
+                }
+              }
+              break;
+
+            case "client_tool_request":
+              if (event.toolCalls && onClientToolCall) {
+                try {
+                  const results = await onClientToolCall(event.toolCalls);
+
+                  const toolsUrl = `${routeBase}/route/chat/${chatName}/tools/${sessionId}`;
+                  await fetch(toolsUrl, {
+                    method: "POST",
+                    credentials: "include",
+                    headers: { "Content-Type": "application/json" },
+                    body: JSON.stringify({ toolResults: results }),
+                  });
+
+                  for (const tc of event.toolCalls) {
+                    const result = results.find((r) => r.toolCallId === tc.id);
+                    if (result) {
+                      const toolUse = onToolUse?.(tc, result.content);
+                      if (toolUse) toolUses.push(toolUse);
+                    }
+                  }
+
+                  if (toolUses.length > 0) {
+                    setMessages((prev) =>
+                      prev.map((msg) =>
+                        msg.id === assistantMsgId
+                          ? { ...msg, toolUses: [...toolUses] }
+                          : msg,
+                      ),
+                    );
+                  }
+                } catch (err) {
+                  console.error("Client tool execution failed:", err);
+                }
+              }
+              break;
+
+            case "done":
+              setMessages((prev) =>
+                prev.map((msg) =>
+                  msg.id === assistantMsgId
+                    ? { ...msg, isStreaming: false }
+                    : msg,
+                ),
+              );
+              setIsStreaming(false);
+              break;
+
+            case "error":
+              setMessages((prev) =>
+                prev.map((msg) =>
+                  msg.id === assistantMsgId
+                    ? { ...msg, content: msg.content || event.error || "An error occurred", isStreaming: false }
+                    : msg,
+                ),
+              );
+              setIsStreaming(false);
+              break;
+          }
+        };
+
+        while (true) {
+          const { value, done } = await reader.read();
+          if (done) break;
+
+          const text = partialLine + decoder.decode(value, { stream: true });
+          const lines = text.split("\n");
+          partialLine = lines.pop() ?? "";
+
+          for (const line of lines) {
+            if (line.startsWith("data: ")) {
+              try {
+                const event = JSON.parse(line.slice(6)) as ChatStreamEvent;
+                await processEvent(event);
+              } catch {}
+            }
+          }
+        }
+
+        if (partialLine.startsWith("data: ")) {
+          try {
+            const event = JSON.parse(partialLine.slice(6)) as ChatStreamEvent;
+            await processEvent(event);
+          } catch {}
+        }
+
+        setIsStreaming(false);
+        setMessages((prev) =>
+          prev.map((msg) =>
+            msg.id === assistantMsgId ? { ...msg, isStreaming: false } : msg,
+          ),
+        );
+      } catch (err) {
+        const errorMsg = err instanceof Error ? err.message : "Unknown error";
+        setMessages((prev) => [
+          ...prev,
+          { id: `error_${Date.now()}`, role: "assistant" as const, content: `Error: ${errorMsg}` },
+        ]);
+        setIsStreaming(false);
+      }
+    },
+    [isStreaming],
+  );
+
+  return { messages, isStreaming, sendMessage, setMessages };
+}

package/src/routes/chat-stream-route.ts

@@ -0,0 +1,31 @@
+import { route } from "@arcote.tech/arc";
+import type { Token } from "@arcote.tech/arc-auth";
+import { getStreamSession } from "../streaming/stream-registry";
+
+export function createChatStreamRoute(config: {
+  name: string;
+  userToken: Token;
+}) {
+  return route(`${config.name}ChatStream`)
+    .path(`/chat/${config.name}/stream/:sessionId`)
+    .protectBy(config.userToken, () => true)
+    .handle({
+      GET: async (_ctx, _req: Request, params: Record<string, string>) => {
+        const session = getStreamSession(params.sessionId);
+        if (!session) {
+          return new Response(
+            JSON.stringify({ error: "Session not found" }),
+            { status: 404, headers: { "Content-Type": "application/json" } },
+          );
+        }
+
+        return new Response(session.createReadableStream(), {
+          headers: {
+            "Content-Type": "text/event-stream",
+            "Cache-Control": "no-cache",
+            Connection: "keep-alive",
+          },
+        });
+      },
+    });
+}

package/src/routes/tool-results-route.ts

@@ -0,0 +1,49 @@
+import { route } from "@arcote.tech/arc";
+import type { Token } from "@arcote.tech/arc-auth";
+import { getStreamSession } from "../streaming/stream-registry";
+
+export function createToolResultsRoute(config: {
+  name: string;
+  userToken: Token;
+}) {
+  return route(`${config.name}ChatToolResults`)
+    .path(`/chat/${config.name}/tools/:sessionId`)
+    .protectBy(config.userToken, () => true)
+    .handle({
+      POST: async (
+        _ctx,
+        req: Request,
+        params: Record<string, string>,
+      ) => {
+        const session = getStreamSession(params.sessionId);
+        if (!session) {
+          return new Response(
+            JSON.stringify({ error: "Session not found" }),
+            { status: 404, headers: { "Content-Type": "application/json" } },
+          );
+        }
+
+        if (session.isClosed()) {
+          return new Response(
+            JSON.stringify({ error: "Session already closed" }),
+            { status: 410, headers: { "Content-Type": "application/json" } },
+          );
+        }
+
+        const body = (await req.json()) as {
+          toolResults: Array<{
+            toolCallId: string;
+            name: string;
+            content: string;
+            isError: boolean;
+          }>;
+        };
+
+        session.resolveClientToolResults(body.toolResults);
+
+        return new Response(JSON.stringify({ ok: true }), {
+          headers: { "Content-Type": "application/json" },
+        });
+      },
+    });
+}