@arcote.tech/arc-chat 0.5.2 → 0.5.6

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@arcote.tech/arc-chat",
   "type": "module",
-  "version": "0.5.2",
+  "version": "0.5.6",
   "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.2",
-    "@arcote.tech/arc-ai": "^0.5.2",
-    "@arcote.tech/arc-auth": "^0.5.2",
-    "@arcote.tech/arc-ds": "^0.5.2",
-    "@arcote.tech/platform": "^0.5.2",
+    "@arcote.tech/arc": "^0.5.6",
+    "@arcote.tech/arc-ai": "^0.5.6",
+    "@arcote.tech/arc-auth": "^0.5.6",
+    "@arcote.tech/arc-ds": "^0.5.6",
+    "@arcote.tech/platform": "^0.5.6",
     "lucide-react": ">=0.400.0",
     "react": ">=18.0.0",
     "typescript": "^5.0.0"

package/src/aggregates/message.ts

@@ -28,6 +28,21 @@ export type MessageAggregateData = {
   scopeId: ArcId<any>;
   accountId: ArcId<any>;
   userToken: Token;
+  /**
+   * Optional scope restriction function used by the message aggregate's
+   * `.protectBy()` call. Receives the token payload and returns an object
+   * of field→value restrictions (see Arc protectBy contract).
+   *
+   * Default: `(p) => ({ scopeId: p.workspaceId })` — assumes the chat is
+   * identified by the workspace id (matches the strategy use-case where
+   * `chat(...).identifyBy(workspaceId)`).
+   *
+   * Chats identified by anything else (e.g. `contentTopicId`) should pass
+   * `() => ({})` — no per-field restriction. The protection token itself
+   * still gates access; cross-scope leakage is bounded by the aggregate
+   * this chat belongs to.
+   */
+  protectCheck?: (payload: any) => Record<string, unknown>;
 };
 
 export const createMessageAggregate = <
@@ -35,16 +50,31 @@ export const createMessageAggregate = <
 >(
   data: Data,
 ) => {
-  const { messageId, scopeId, userToken } = data;
+  const { messageId, scopeId, userToken, protectCheck } = data;
+  const scopeCheck =
+    protectCheck ?? ((p: { workspaceId: string }) => ({ scopeId: p.workspaceId }));
 
   return aggregate(`${data.name}Messages`, messageId, {
     scopeId,
     role: string(),
-    content: string(),
+    /** User message text, or tool_result content. Empty for assistant rows. */
+    content: string().optional(),
+    /**
+     * Assistant message blocks — JSON-serialized AssistantContentBlock[].
+     * Preserves text/tool_call ordering produced by the model in a single
+     * provider response. Empty for non-assistant rows.
+     */
+    blocks: string().optional(),
     model: string().optional(),
+    /** Tool result rows: name + id of the tool call this responds to. */
     toolName: string().optional(),
     toolCallId: string().optional(),
     sessionId: string().optional(),
+    /**
+     * For assistant rows: provider-issued response ID for THIS turn. Used by
+     * the listener to anchor `previous_response_id` continuation requests on
+     * the next turn (OpenAI Responses API).
+     */
     previousResponseId: string().optional(),
     isGenerating: boolean().optional(),
     usage: string().optional(),
@@ -77,14 +107,17 @@ export const createMessageAggregate = <
       },
     )
 
-    // ─── assistantResponded — AI generates text ─────────────────
+    // ─── assistantResponded — AI generates one turn ─────────────
+    // The `blocks` field is the JSON-serialized AssistantContentBlock[]
+    // produced by the provider for this single turn — text and tool_call
+    // blocks interleaved in the order the model emitted them.
     .publicEvent(
       "assistantResponded",
       {
         messageId,
         scopeId,
         sessionId: string(),
-        content: string(),
+        blocks: string(),
         model: string().optional(),
         previousResponseId: string().optional(),
         isGenerating: boolean().optional(),
@@ -94,7 +127,7 @@ export const createMessageAggregate = <
         await ctx.set(p.messageId, {
           scopeId: p.scopeId,
           role: "assistant",
-          content: p.content,
+          blocks: p.blocks,
           model: p.model,
           sessionId: p.sessionId,
           previousResponseId: p.previousResponseId,
@@ -104,33 +137,6 @@ export const createMessageAggregate = <
       },
     )
 
-    // ─── toolCalled — AI invokes a tool ─────────────────────────
-    .publicEvent(
-      "toolCalled",
-      {
-        messageId,
-        scopeId,
-        sessionId: string(),
-        toolName: string(),
-        toolCallId: string(),
-        content: string(),
-        previousResponseId: string().optional(),
-      },
-      async (ctx, event) => {
-        const p = event.payload;
-        await ctx.set(p.messageId, {
-          scopeId: p.scopeId,
-          role: "tool_call",
-          content: p.content,
-          toolName: p.toolName,
-          toolCallId: p.toolCallId,
-          sessionId: p.sessionId,
-          previousResponseId: p.previousResponseId,
-          createdAt: event.createdAt,
-        });
-      },
-    )
-
     // ─── toolExecuted — server tool returns result ──────────────
     .publicEvent(
       "toolExecuted",
@@ -182,7 +188,7 @@ export const createMessageAggregate = <
       },
     )
 
-    // ─── generationCompleted — AI loop finished ────��────────────
+    // ─── generationCompleted — AI loop finished ─────────────────
     .publicEvent(
       "generationCompleted",
       {
@@ -192,7 +198,9 @@ export const createMessageAggregate = <
       },
       async (ctx, event) => {
         const p = event.payload;
-        await ctx.set(p.messageId, {
+        // PARTIAL update — `ctx.set` replaces the whole row and would null
+        // out scopeId/role/blocks. Use `modify` to only flip isGenerating.
+        await ctx.modify(p.messageId, {
           isGenerating: false,
           usage: p.usage,
         } as any);
@@ -225,13 +233,15 @@ export const createMessageAggregate = <
       ),
     )
 
-    // ─── saveAssistantMessage ─────��─────────────────────────────
+    // ─── saveAssistantMessage ───────────────────────────────────
+    // `blocks` is the JSON-serialized AssistantContentBlock[] from the
+    // provider's response — single source of truth for the model's output.
     .mutateMethod(
       "saveAssistantMessage",
       (fn) => fn.withParams({
         scopeId,
         sessionId: string(),
-        content: string(),
+        blocks: string(),
         model: string().optional(),
         previousResponseId: string().optional(),
         isGenerating: boolean().optional(),
@@ -243,7 +253,7 @@ export const createMessageAggregate = <
             messageId: msgId,
             scopeId: params.scopeId,
             sessionId: params.sessionId,
-            content: params.content,
+            blocks: params.blocks,
             model: params.model,
             previousResponseId: params.previousResponseId,
             isGenerating: params.isGenerating,
@@ -253,34 +263,6 @@ export const createMessageAggregate = <
       ),
     )
 
-    // ─── saveToolCall ────────────���──────────────────────────────
-    .mutateMethod(
-      "saveToolCall",
-      (fn) => fn.withParams({
-        scopeId,
-        sessionId: string(),
-        toolName: string(),
-        toolCallId: string(),
-        content: string(),
-        previousResponseId: string().optional(),
-      }).handle(
-        ONLY_SERVER &&
-        (async (ctx, params) => {
-          const msgId = messageId.generate();
-          await ctx.toolCalled.emit({
-            messageId: msgId,
-            scopeId: params.scopeId,
-            sessionId: params.sessionId,
-            toolName: params.toolName,
-            toolCallId: params.toolCallId,
-            content: params.content,
-            previousResponseId: params.previousResponseId,
-          });
-          return { messageId: msgId };
-        }),
-      ),
-    )
-
     // ─── saveToolResult — server tool executed ──────────────────
     .mutateMethod(
       "saveToolResult",
@@ -356,7 +338,11 @@ export const createMessageAggregate = <
       ),
     )
 
-    // ─── startStage — initiate stage with greeting ──────────────
+    // ─── startStage — initiate stage with a default priming prompt ─
+    // Stored as role="system" so the UI timeline hides it, but the AI
+    // generation listener still picks it up as a conversational turn
+    // (mapped to "user" for LLM providers that don't support system role
+    // mid-conversation — see ai-generation-listener buildHistory).
     .mutateMethod(
       "startStage",
       (fn) => fn.withParams({
@@ -365,18 +351,49 @@ export const createMessageAggregate = <
       }).handle(
         ONLY_SERVER &&
         (async (ctx, params) => {
-          const userMsgId = messageId.generate();
+          const msgId = messageId.generate();
           const sessionId = `session_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
 
           await ctx.messageSent.emit({
-            messageId: userMsgId,
+            messageId: msgId,
             scopeId: params.scopeId,
             sessionId,
-            role: "user",
+            role: "system",
             content: "Rozpocznij ten etap. Przywitaj się i zadaj pierwsze pytanie.",
-            model: params.model ?? "gpt-5.4-nano",
+            model: params.model ?? "gpt-5.4-mini",
           });
-          return { messageId: userMsgId, sessionId };
+          return { messageId: msgId, sessionId };
+        }),
+      ),
+    )
+
+    // ─── systemMessage — inject a developer-supplied priming prompt ─
+    // Used by stage onEnter hooks to inject context-aware welcome prompts
+    // (e.g. "User finished identity — greet them and ask about goals").
+    // Stored with role="system" — the UI filters it out of the timeline
+    // (see chat-component Restore timeline loop) while the AI generation
+    // listener still sees it in history as a conversational turn.
+    .mutateMethod(
+      "systemMessage",
+      (fn) => fn.withParams({
+        scopeId,
+        content: string().minLength(1),
+        model: string().optional(),
+      }).handle(
+        ONLY_SERVER &&
+        (async (ctx, params) => {
+          const msgId = messageId.generate();
+          const sessionId = `session_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
+
+          await ctx.messageSent.emit({
+            messageId: msgId,
+            scopeId: params.scopeId,
+            sessionId,
+            role: "system",
+            content: params.content,
+            model: params.model ?? "gpt-5.4-mini",
+          });
+          return { messageId: msgId, sessionId };
         }),
       ),
     )
@@ -391,7 +408,7 @@ export const createMessageAggregate = <
         ),
     )
 
-    .protectBy(userToken, (p: { workspaceId: string }) => ({ scopeId: p.workspaceId }));
+    .protectBy(userToken, scopeCheck as any);
 };
 
 export type MessageAggregate = ReturnType<typeof createMessageAggregate>;

package/src/chat-builder.ts

@@ -17,7 +17,31 @@ import { createMessageId, createMessageAggregate } from "./aggregates/message";
 import { createAiGenerationListener, createAiResumeListener } from "./listeners/ai-generation-listener";
 import { createChatStreamRoute } from "./routes/chat-stream-route";
 import { createChatComponent } from "./react/chat-component";
-import type { ComponentType } from "react";
+import type { ChatLabels } from "@arcote.tech/arc-ds";
+import type { ComponentType, ReactNode } from "react";
+
+export interface ChatReactComponentOptions {
+  /** Show the model selector dropdown in ChatInput. Default true. */
+  showModelSelector?: boolean;
+  /** Show the web search toggle in ChatInput. Default true. */
+  showWebSearch?: boolean;
+  /**
+   * Render slot for ChatInput's send button. Receives `onClick` and
+   * `disabled` — caller renders its own button (e.g. branded with a logo).
+   */
+  renderSendButton?: (props: {
+    onClick: () => void;
+    disabled: boolean;
+  }) => 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 ──────────────────────────────────────────────────
 
@@ -167,6 +191,15 @@ export class ArcChat<const Data extends ArcChatData = DefaultChatData> {
       scopeId: identifyBy,
       accountId,
       userToken: protectByToken ?? userToken,
+      // Forward consumer's protectBy check so chats with non-workspace
+      // identifyBy (e.g. `contentTopicId`) can supply a custom scope
+      // restriction instead of inheriting the default
+      // `{ scopeId: p.workspaceId }` which only makes sense for
+      // workspace-scoped chats.
+      protectCheck: protectByCheck as
+        | ((p: any) => Record<string, unknown>)
+        | undefined
+        ?? undefined,
     });
 
     // Collect query/mutate from instruction + tools
@@ -229,11 +262,18 @@ export class ArcChat<const Data extends ArcChatData = DefaultChatData> {
       streamRoute,
     ];
 
-    function toReactComponent(): ComponentType<{ scope: any; identifyBy: string }> {
+    function toReactComponent(
+      options: ChatReactComponentOptions = {},
+    ): ComponentType<{ scope: any; identifyBy: string }> {
       return createChatComponent({
         chatName: name,
         tools,
         messageElementName: `${name}Messages`,
+        showModelSelector: options.showModelSelector,
+        showWebSearch: options.showWebSearch,
+        renderSendButton: options.renderSendButton,
+        labels: options.labels,
+        footer: options.footer,
       });
     }
 

package/src/index.ts

@@ -1,6 +1,6 @@
 // --- Builder API ---
 export { chat, ArcChat } from "./chat-builder";
-export type { ChatConfig, ArcChatData } from "./chat-builder";
+export type { ChatConfig, ArcChatData, ChatReactComponentOptions } from "./chat-builder";
 
 // --- Aggregate factories & types ---
 export { createMessageAggregate, createMessageId } from "./aggregates/message";
@@ -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";