@arcote.tech/arc-chat 0.5.5 → 0.5.7

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@arcote.tech/arc-chat",
   "type": "module",
-  "version": "0.5.5",
+  "version": "0.5.7",
   "private": false,
   "description": "Chat module with AI integration for Arc framework",
   "main": "./src/index.ts",
@@ -10,11 +10,11 @@
     "type-check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@arcote.tech/arc": "^0.5.5",
-    "@arcote.tech/arc-ai": "^0.5.5",
-    "@arcote.tech/arc-auth": "^0.5.5",
-    "@arcote.tech/arc-ds": "^0.5.5",
-    "@arcote.tech/platform": "^0.5.5",
+    "@arcote.tech/arc": "^0.5.7",
+    "@arcote.tech/arc-ai": "^0.5.7",
+    "@arcote.tech/arc-auth": "^0.5.7",
+    "@arcote.tech/arc-ds": "^0.5.7",
+    "@arcote.tech/platform": "^0.5.7",
     "lucide-react": ">=0.400.0",
     "react": ">=18.0.0",
     "typescript": "^5.0.0"

package/src/chat-builder.ts

@@ -12,7 +12,7 @@ import type { AccountId, Token } from "@arcote.tech/arc-auth";
 import type { AIConfig, ArcToolAny } from "@arcote.tech/arc-ai";
 import { tool as createToolFactory } from "@arcote.tech/arc-ai";
 import type { ArcTokenAny } from "@arcote.tech/arc";
-import type { FnProtection, FnProtectionCheck } from "@arcote.tech/arc";
+import type { ViewProtectionFn } from "@arcote.tech/arc";
 import { createMessageId, createMessageAggregate } from "./aggregates/message";
 import { createAiGenerationListener, createAiResumeListener } from "./listeners/ai-generation-listener";
 import { createChatStreamRoute } from "./routes/chat-stream-route";
@@ -35,6 +35,12 @@ export interface ChatReactComponentOptions {
   }) => ReactNode;
   /** Partial overrides for chat i18n labels. Falls back to English defaults. */
   labels?: Partial<ChatLabels>;
+  /**
+   * Content rendered at the bottom of the scrollable messages area,
+   * after the last message/tool. Useful for persistent UI like stage
+   * advancement bars. Scrolls with messages.
+   */
+  footer?: ReactNode;
 }
 
 // ─── Chat Data ──────────────────────────────────────────────────
@@ -99,7 +105,17 @@ export class ArcChat<const Data extends ArcChatData = DefaultChatData> {
     } as any);
   }
 
-  protectBy<T extends ArcTokenAny>(token: T, check: FnProtectionCheck<T>) {
+  /**
+   * Restrict chat access by token + read filter on token params.
+   *
+   * The callback receives **raw token params** (not a `TokenInstance`),
+   * mirroring `aggregate.protectBy` semantics — the chat's underlying
+   * Message aggregate is filtered by the returned WHERE clause. This
+   * matches the runtime behaviour in `build()` below where
+   * `protectByCheck` is forwarded directly into the message aggregate's
+   * view protection.
+   */
+  protectBy<T extends ArcTokenAny>(token: T, check: ViewProtectionFn<T>) {
     return new ArcChat<Merge<Data, { protectBy: T; protectByCheck: typeof check }>>({
       ...this.data,
       protectBy: token,
@@ -267,6 +283,7 @@ export class ArcChat<const Data extends ArcChatData = DefaultChatData> {
         showWebSearch: options.showWebSearch,
         renderSendButton: options.renderSendButton,
         labels: options.labels,
+        footer: options.footer,
       });
     }
 

package/src/index.ts

@@ -16,7 +16,7 @@ export type { StreamSession } from "./streaming/stream-registry";
 
 // --- Listener ---
 export { createAiGenerationListener } from "./listeners/ai-generation-listener";
-export type { AiGenerationListenerConfig } from "./listeners/ai-generation-listener";
+export type { AiGenerationListenerConfig, InstructionResult } from "./listeners/ai-generation-listener";
 
 // --- Routes ---
 export { createChatStreamRoute } from "./routes/chat-stream-route";

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

@@ -87,28 +87,46 @@ function buildHistory(
 
 // ─── Instructions ───────────────────────────────────────────────
 
+/**
+ * Result from an instruction handler. Can be a plain string (prompt only)
+ * or an object with prompt + optional tool filtering.
+ */
+export interface InstructionResult {
+  /** System prompt text sent to the LLM. */
+  prompt: string;
+  /**
+   * If provided, only tools whose names appear in this array will be
+   * sent to the LLM for this generation call. Tools not listed are
+   * hidden — the LLM cannot call them. Omit to send all registered tools.
+   */
+  enabledTools?: string[];
+}
+
 /**
  * Render the system prompt by invoking the consumer's `instruction()` handler
  * with a thin wrapper around the listener's ctx. Always called fresh — never
  * cached — so dynamic state (e.g. identity just updated by a tool call) shows
  * up in the next provider call.
+ *
+ * Returns `{ prompt, enabledTools? }`. When the handler returns a plain string,
+ * it's wrapped as `{ prompt: str }` with no tool filtering.
  */
 async function buildInstructions(
   instruction: ArcFunction<any> | undefined,
   ctx: any,
   scopeId: string,
-): Promise<string> {
-  if (!instruction?.handler) return "";
+): Promise<InstructionResult> {
+  if (!instruction?.handler) return { prompt: "" };
   const instructionCtx = {
     query: (element: ArcContextElement<any>) => ctx.query(element),
     mutate: (element: ArcContextElement<any>) => ctx.mutate(element),
-    // The chat's `identifyBy` value (= scopeId of the conversation thread).
-    // Lets the consumer prompt scope its queries to the current entity.
     identifyBy: scopeId,
     scopeId,
   };
   const result = await (instruction.handler as Function)(instructionCtx);
-  return typeof result === "string" ? result : "";
+  if (typeof result === "string") return { prompt: result };
+  if (result && typeof result === "object" && "prompt" in result) return result as InstructionResult;
+  return { prompt: "" };
 }
 
 // ─── Conversation mode selection ────────────────────────────────
@@ -197,7 +215,12 @@ async function runGenerationLoop(config: RunLoopConfig) {
     while (executionCount <= maxExecutionCount) {
       // Always re-render instructions — picks up state mutated by tool calls
       // in the previous iteration (e.g. updateIdentity).
-      const instructions = await buildInstructions(instruction, ctx, scopeId);
+      const instructionResult = await buildInstructions(instruction, ctx, scopeId);
+
+      // Filter tools if instruction handler specified enabledTools
+      const effectiveToolDefs = instructionResult.enabledTools
+        ? toolDefs?.filter((td) => instructionResult.enabledTools!.includes(td.name))
+        : toolDefs;
 
       const lastResponseId = findLastResponseId(history);
       const conversation = makeConversation(
@@ -210,9 +233,9 @@ async function runGenerationLoop(config: RunLoopConfig) {
       const result = await provider.streamComplete(
         {
           model,
-          instructions,
+          instructions: instructionResult.prompt,
           conversation,
-          tools: toolDefs,
+          tools: effectiveToolDefs,
           toolChoice,
         },
         (chunk) => {

package/src/react/chat-component.tsx

@@ -21,6 +21,11 @@ interface ChatComponentConfig {
   }) => ReactNode;
   /** Partial overrides for chat i18n labels. Falls back to English defaults. */
   labels?: Partial<ChatLabels>;
+  /**
+   * Content rendered at the bottom of the scrollable messages area,
+   * after the last message/tool. Scrolls with messages.
+   */
+  footer?: ReactNode;
 }
 
 type TimelineItem =
@@ -38,6 +43,7 @@ export function createChatComponent(
     showWebSearch = true,
     renderSendButton,
     labels,
+    footer,
   } = config;
   const toolsMap = new Map(tools.map((t) => [t.name, t]));
 
@@ -48,6 +54,7 @@ export function createChatComponent(
     const sessionIdRef = useRef<string | null>(null);
     const currentAssistantIdRef = useRef<string | null>(null);
     const lastHistoryLenRef = useRef(0);
+    const resumedSessionRef = useRef<string | null>(null);
 
     const queries = scope.useQuery();
     const mutations = scope.useMutation();
@@ -158,7 +165,50 @@ export function createChatComponent(
       }
     }, [historyLen, isStreaming]);
 
+    // ─── SSE stream consumer ────────────────────────────────────
+    // Reusable: handles fetch + read loop + processEvent dispatch.
+    // Caller is responsible for setting isStreaming/sessionIdRef before
+    // and clearing them after (different lifecycle in send vs respond vs resume).
+    const consumeStream = useCallback(
+      async (sessionId: string): Promise<void> => {
+        const streamUrl = `/route/chat/${chatName}/stream/${sessionId}`;
+        const response = await fetch(streamUrl, {
+          credentials: "include",
+          headers: { Accept: "text/event-stream" },
+        });
+        if (!response.ok) throw new Error(`Stream failed: ${response.status}`);
+
+        const reader = response.body!.getReader();
+        const decoder = new TextDecoder();
+        let partialLine = "";
+
+        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 processEventRef.current?.(event);
+              } catch {}
+            }
+          }
+        }
+        if (partialLine.startsWith("data: ")) {
+          try {
+            const event = JSON.parse(partialLine.slice(6)) as ChatStreamEvent;
+            await processEventRef.current?.(event);
+          } catch {}
+        }
+      },
+      [],
+    );
+
     // ─── SSE event processing ───────────────────────────────────
+    const processEventRef = useRef<((event: ChatStreamEvent) => Promise<void>) | null>(null);
     const processEvent = useCallback(
       async (event: ChatStreamEvent) => {
         switch (event.type) {
@@ -314,6 +364,32 @@ export function createChatComponent(
       [chatLabels],
     );
 
+    // Keep ref in sync so consumeStream (stable callback) can call latest version
+    processEventRef.current = processEvent;
+
+    // ─── Resume SSE on mount if there's an active generation ────
+    // After page reload, if the DB shows isGenerating=true with sessionId,
+    // we reconnect to the stream registry to consume any in-flight events.
+    useEffect(() => {
+      if (!scopeId) return;
+      const sid = sessionIdRef.current;
+      if (!sid) return;
+      if (resumedSessionRef.current === sid) return;
+      if (!isStreaming) return;
+      resumedSessionRef.current = sid;
+      (async () => {
+        try {
+          await consumeStream(sid);
+        } catch {
+          // Stream may have already ended or been GC'd — fall through
+        } finally {
+          setIsStreaming(false);
+          sessionIdRef.current = null;
+          currentAssistantIdRef.current = null;
+        }
+      })();
+    }, [isStreaming, scopeId, consumeStream]);
+
     // ─── Send message ───────────────────────────────────────────
     const handleSend = useCallback(
       async (content: string, options: SendMessageOptions) => {
@@ -557,6 +633,7 @@ export function createChatComponent(
           "div",
           { className: "max-w-3xl mx-auto w-full space-y-4 flex-1" },
           ...timelineElements,
+          footer,
         ),
         createElement(Chat, {
           messages: [],