@smooai/chat-widget 0.11.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smooai/chat-widget",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Embeddable AI chat as a framework-light web component — the Aurora Glass design, streaming replies, grounded sources, and per-brand theming. Speaks the smooth-operator WebSocket protocol.",
   "license": "MIT",
   "author": "SmooAI",
@@ -58,7 +58,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@smooai/smooth-operator": "^1.8.0",
+    "@smooai/smooth-operator": "^1.21.1",
     "libphonenumber-js": "^1.13.7",
     "zustand": "^5.0.14"
   },

package/src/config.ts

@@ -141,6 +141,16 @@ export interface ChatWidgetConfig {
      * `require*` flags are ignored and the pre-chat form is skipped.
      */
     allowAnonymous?: boolean;
+    /**
+     * Show the agent's tool activity (grep / read_file / bash / knowledge_search…)
+     * as inline chips interleaved with its prose, mirroring the smooth daemon SPA.
+     *
+     * Defaults to **`false`**: for a customer-facing support widget, surfacing raw
+     * tool calls to an end-user is usually undesirable, so tool activity is hidden
+     * and only the assistant's prose renders. Enable it for internal / power-user
+     * surfaces where seeing what the agent did mid-turn is valuable.
+     */
+    showToolActivity?: boolean;
     /** Theme overrides. */
     theme?: ChatWidgetTheme;
 }
@@ -194,6 +204,7 @@ export function resolveConfig(config: ChatWidgetConfig): ResolvedConfig {
         collectConsent: config.collectConsent ?? true,
         allowChatRestore: config.allowChatRestore ?? true,
         allowAnonymous: config.allowAnonymous ?? false,
+        showToolActivity: config.showToolActivity ?? false,
         theme: {
             text: theme.text ?? '#f8fafc',
             background: theme.background ?? '#040d30',

package/src/conversation.ts

@@ -61,6 +61,32 @@ export type { Citation };
 
 export type Role = 'user' | 'assistant';
 
+/**
+ * One tool invocation within an assistant turn. Mirrors the smooth daemon SPA's
+ * `ToolCall` (`crates/smooth-web/web/src/operator.ts`): opens `done: false` on the
+ * tool call and resolves on the tool result.
+ */
+export interface ToolCall {
+    /** Stable id for keyed rendering (assigned when the call opens). */
+    id: string;
+    name: string;
+    /** Raw arguments, JSON-stringified. */
+    args: string;
+    /** Present once the tool resolves. */
+    result?: string;
+    isError?: boolean;
+    done: boolean;
+}
+
+/**
+ * One ordered segment of an assistant turn: a run of prose, or a tool call.
+ * Preserves the interleave order the model produced (say a bit → call a tool →
+ * say a bit → …) so the UI can render tool chips INLINE where the model called
+ * them. Mirrors the daemon SPA's `MessageBlock`. Only populated when the widget
+ * is configured with `showToolActivity: true`.
+ */
+export type MessageBlock = { kind: 'text'; text: string } | { kind: 'tool'; tool: ToolCall };
+
 export interface ChatMessage {
     id: string;
     role: Role;
@@ -68,6 +94,12 @@ export interface ChatMessage {
     text: string;
     /** True while an assistant message is still streaming. */
     streaming: boolean;
+    /**
+     * Ordered text + tool segments, interleaved as the model produced them. Present
+     * only on assistant messages when `showToolActivity` is enabled (absent
+     * otherwise — the default popover renders `text` alone, byte-for-byte unchanged).
+     */
+    blocks?: MessageBlock[];
     /**
      * Sources that grounded an assistant answer, when the terminal
      * `eventual_response` carried any. Optional + back-compatible: absent when
@@ -93,6 +125,9 @@ export type ConnectionStatus = 'idle' | 'connecting' | 'ready' | 'error' | 'clos
  *   Resume with {@link ConversationController.verifyOtp}.
  * - `confirm` — the agent wants to run a state-mutating tool and needs approval.
  *   Resume with {@link ConversationController.confirmTool}.
+ * - `interaction` — the agent raised a Rich Interaction (structured card, e.g.
+ *   identity intake). Resume with {@link ConversationController.submitInteraction}
+ *   or {@link ConversationController.declineInteraction}.
  */
 export type Interrupt =
     | {
@@ -106,7 +141,28 @@ export type Interrupt =
           error?: string;
           attemptsRemaining?: number;
       }
-    | { kind: 'confirm'; toolId?: string; actionDescription?: string };
+    | { kind: 'confirm'; toolId?: string; actionDescription?: string }
+    | {
+          kind: 'interaction';
+          /** Server-generated interaction instance id (echoed on submit). */
+          interactionId: string;
+          /** The Rich Interaction kind (e.g. `identity_intake`) — selects the card. */
+          interactionKind: string;
+          /** Kind-specific render spec (identity_intake: `{ fields: [...] }`). */
+          spec: Record<string, unknown>;
+          /** Why the agent raised it (card header copy). */
+          reason?: string;
+          /** Per-field server-side validation errors (from `interaction_invalid`). */
+          errors?: { field: string; message: string }[];
+      };
+
+/**
+ * The Rich-Interaction render capabilities this widget declares at session
+ * create (`supports`). Must stay aligned with the card registry in
+ * `element.ts` (`INTERACTION_CARDS`) — registering a card IS declaring its
+ * capability; a test asserts the two match.
+ */
+export const SUPPORTED_INTERACTION_CAPABILITIES: readonly string[] = ['identity_form'];
 
 export interface UserInfo {
     name?: string;
@@ -220,6 +276,52 @@ function wireMessageToChat(m: WireMessage, idx: number): ChatMessage | null {
     return { id: typeof m.id === 'string' ? m.id : `hist-${idx}`, role, text, streaming: false };
 }
 
+let toolSeq = 0;
+const nextToolId = (): string => `tool-${++toolSeq}`;
+
+/** Grow the trailing text block, or open a new one if the last block was a tool. */
+function growTextBlock(blocks: MessageBlock[], text: string): void {
+    if (!text) return;
+    const last = blocks[blocks.length - 1];
+    if (last && last.kind === 'text') last.text += text;
+    else blocks.push({ kind: 'text', text });
+}
+
+/**
+ * Fold a `stream_chunk` node-state into the ordered block list, returning `true`
+ * when the chunk carried tool activity.
+ *
+ * Tool activity rides `state.rawResponse.toolCall` / `state.rawResponse.toolResult`
+ * — **NOT** `state.toolResult`. Reading the wrong path leaves every chip stuck on
+ * "running…" forever (the exact bug the daemon SPA hit and this mirror avoids).
+ */
+function applyToolChunk(blocks: MessageBlock[], state: unknown): boolean {
+    const raw = (state as { rawResponse?: unknown } | null | undefined)?.rawResponse;
+    if (!raw || typeof raw !== 'object') return false;
+    const call = (raw as { toolCall?: { name?: string; arguments?: unknown } }).toolCall;
+    const res = (raw as { toolResult?: { name?: string; isError?: boolean; result?: unknown } }).toolResult;
+    if (call) {
+        const args = typeof call.arguments === 'string' ? call.arguments : JSON.stringify(call.arguments ?? {});
+        blocks.push({ kind: 'tool', tool: { id: nextToolId(), name: call.name ?? '', args, done: false } });
+        return true;
+    }
+    if (res) {
+        const result = typeof res.result === 'string' ? res.result : JSON.stringify(res.result ?? '');
+        // Complete the most-recent still-open tool block matching this name.
+        for (let i = blocks.length - 1; i >= 0; i--) {
+            const b = blocks[i];
+            if (b && b.kind === 'tool' && b.tool.name === (res.name ?? '') && !b.tool.done) {
+                b.tool.done = true;
+                b.tool.isError = !!res.isError;
+                b.tool.result = result;
+                break;
+            }
+        }
+        return true;
+    }
+    return false;
+}
+
 export class ConversationController {
     private readonly config: ChatWidgetConfig;
     private readonly events: ConversationEvents;
@@ -232,6 +334,9 @@ export class ConversationController {
     /** requestId of the in-flight turn — used to resume OTP / tool confirmations. */
     private activeRequestId: string | null = null;
     private interrupt: Interrupt | null = null;
+    /** Values from the last interaction submit, merged into the persisted
+     *  identity (identity_intake only) once the server acks them. */
+    private pendingInteractionValues: { kind: string; values: Record<string, unknown> } | null = null;
     private identityRestore: IdentityRestore = { phase: 'idle' };
     /**
      * True once the resume probe (persisted-pointer get_session OR the
@@ -337,6 +442,41 @@ export class ConversationController {
         this.setInterrupt(null);
     }
 
+    /**
+     * Submit a Rich Interaction card to resume the parked turn. The server
+     * routes to the kind's validator: invalid values come back as an
+     * `interaction_invalid` event (the card re-renders with per-field errors —
+     * the turn stays parked); a valid submit is acked and the turn resumes.
+     * No-op if not awaiting an interaction.
+     */
+    submitInteraction(values: Record<string, unknown>): void {
+        if (!this.client || !this.sessionId || !this.activeRequestId || this.interrupt?.kind !== 'interaction') return;
+        // Stash the values so the ack (immediate_response) can merge accepted
+        // identity values into the persisted store.
+        this.pendingInteractionValues = { kind: this.interrupt.interactionKind, values };
+        this.client.submitInteraction({
+            sessionId: this.sessionId,
+            requestId: this.activeRequestId,
+            interactionId: this.interrupt.interactionId,
+            kind: this.interrupt.interactionKind,
+            values,
+        });
+    }
+
+    /** Decline the pending Rich Interaction; the agent continues without it. */
+    declineInteraction(): void {
+        if (!this.client || !this.sessionId || !this.activeRequestId || this.interrupt?.kind !== 'interaction') return;
+        this.client.submitInteraction({
+            sessionId: this.sessionId,
+            requestId: this.activeRequestId,
+            interactionId: this.interrupt.interactionId,
+            kind: this.interrupt.interactionKind,
+            declined: true,
+        });
+        this.pendingInteractionValues = null;
+        this.setInterrupt(null);
+    }
+
     private nextId(prefix: string): string {
         this.seq += 1;
         return `${prefix}-${this.seq}-${Date.now().toString(36)}`;
@@ -543,6 +683,10 @@ export class ConversationController {
             userName: state.identity.name,
             userEmail: state.identity.email,
             browserFingerprint: this.fingerprint(),
+            // Declare the Rich-Interaction cards this widget can render (derived
+            // from the card registry), so the server emits `interaction_required`
+            // for those kinds instead of the conversational fallback.
+            supports: [...SUPPORTED_INTERACTION_CAPABILITIES],
             ...(metadata ? { metadata } : {}),
         });
         this.sessionId = session.sessionId;
@@ -608,7 +752,8 @@ export class ConversationController {
         this.messages.push({ id: this.nextId('u'), role: 'user', text: trimmed, streaming: false });
 
         // 2. Placeholder assistant bubble we grow as tokens arrive.
-        const assistant: ChatMessage = { id: this.nextId('a'), role: 'assistant', text: '', streaming: true };
+        const showTools = this.config.showToolActivity === true;
+        const assistant: ChatMessage = { id: this.nextId('a'), role: 'assistant', text: '', streaming: true, blocks: showTools ? [] : undefined };
         this.messages.push(assistant);
         this.emitMessages();
 
@@ -621,6 +766,14 @@ export class ConversationController {
                     const token = event.token ?? event.data?.token ?? '';
                     if (token) {
                         assistant.text += token;
+                        // Grow the trailing text block so prose interleaves with any
+                        // tool chips in the order the model produced them.
+                        if (showTools && assistant.blocks) growTextBlock(assistant.blocks, token);
+                        this.emitMessages();
+                    }
+                } else if (showTools && event.type === 'stream_chunk') {
+                    // Tool activity (gated). Read state.rawResponse.toolCall/.toolResult.
+                    if (assistant.blocks && applyToolChunk(assistant.blocks, event.data?.state)) {
                         this.emitMessages();
                     }
                 } else {
@@ -649,6 +802,11 @@ export class ConversationController {
             if (suggestions.length > 0) {
                 assistant.suggestions = suggestions;
             }
+            // Only keep blocks for turns that actually invoked a tool — a prose-only
+            // turn drops back to the normal markdown text path (with the final text).
+            if (assistant.blocks && !assistant.blocks.some((b) => b.kind === 'tool')) {
+                assistant.blocks = undefined;
+            }
             assistant.streaming = false;
             this.emitMessages();
         } catch (err) {
@@ -700,7 +858,51 @@ export class ConversationController {
             case 'write_confirmation_required':
                 this.setInterrupt({ kind: 'confirm', toolId: str(inner.toolId), actionDescription: str(inner.actionDescription) });
                 break;
-            default:
+            case 'interaction_required': {
+                const interactionId = str(inner.interactionId);
+                const kind = str(inner.kind);
+                const spec = inner.spec && typeof inner.spec === 'object' ? (inner.spec as Record<string, unknown>) : {};
+                if (!interactionId || !kind) break; // not renderable — ignore
+                this.pendingInteractionValues = null;
+                this.setInterrupt({
+                    kind: 'interaction',
+                    interactionId,
+                    interactionKind: kind,
+                    spec,
+                    reason: str(inner.reason),
+                });
+                break;
+            }
+            case 'interaction_invalid':
+                if (this.interrupt?.kind === 'interaction' && this.interrupt.interactionId === str(inner.interactionId)) {
+                    const errors: { field: string; message: string }[] = [];
+                    if (Array.isArray(inner.errors)) {
+                        for (const e of inner.errors) {
+                            if (!e || typeof e !== 'object') continue;
+                            const o = e as Record<string, unknown>;
+                            const field = str(o.field);
+                            if (field) errors.push({ field, message: str(o.message) ?? 'Invalid value' });
+                        }
+                    }
+                    this.pendingInteractionValues = null;
+                    this.setInterrupt({ ...this.interrupt, errors });
+                }
+                break;
+            case 'immediate_response':
+                // Mid-turn immediate_response while an interaction card is showing
+                // is the submit/decline ack: the park resolved — clear the card
+                // and, for accepted identity values, persist them.
+                if (this.interrupt?.kind === 'interaction') {
+                    const pending = this.pendingInteractionValues;
+                    if (pending && pending.kind === 'identity_intake') {
+                        const v = pending.values as { name?: string; email?: string; phone?: string };
+                        this.store.getState().mergeIdentity({ name: v.name, email: v.email, phone: v.phone });
+                    }
+                    this.pendingInteractionValues = null;
+                    this.setInterrupt(null);
+                }
+                break;
+                        default:
                 break;
         }
     }