@agentforge-io/chat-sdk 2.0.16 → 2.0.18

package/dist/entities.d.ts

@@ -4,6 +4,34 @@
  * and easy to reason about.
  */
 export type ChatRole = 'user' | 'assistant' | 'system';
+/**
+ * Structured payload attached to messages the server tagged with a
+ * non-text intent. Today's kinds:
+ *
+ *   - `awaiting_approval`: a tool the agent wanted to run requires
+ *     human approval. The View layer renders an Approve/Deny card
+ *     using `approvalId` + `toolName`. After Approve the client should
+ *     auto-send a "continue" follow-up so the gate's fast-path consumes
+ *     the pending row and the turn finishes.
+ *   - `tool_blocked`: a tool was hard-blocked by the gate. Terminal,
+ *     no action — render as an error card.
+ *
+ * Future kinds extend this union without breaking back-compat: the
+ * View checks `kind` and falls back to plain text when it's unknown.
+ */
+export type ChatMessageMetadata = {
+    kind: 'awaiting_approval';
+    approvalId: string;
+    toolName: string;
+    expiresAt: string;
+} | {
+    kind: 'tool_blocked';
+    toolName: string;
+    reason?: string;
+} | {
+    kind: string;
+    [k: string]: unknown;
+};
 export interface ChatMessage {
     /** Stable client-side id so view layers can key off it. */
     id: string;
@@ -15,6 +43,10 @@ export interface ChatMessage {
     /** True while the assistant is still streaming this message. The UI uses
      *  this to render a caret/cursor next to a half-written reply. */
     isStreaming?: boolean;
+    /** Structured payload for non-text messages (approval cards, blocked
+     *  errors, …). View layers should branch on `metadata.kind` before
+     *  falling back to `content`. */
+    metadata?: ChatMessageMetadata;
 }
 export interface ChatAgentSummary {
     slug: string;

package/dist/index.d.ts

@@ -10,4 +10,4 @@
 export { ChatSession } from './session';
 export { HttpTransport } from './transport';
 export type { StreamEvent, ServerStreamChunk, TransportError, } from './transport';
-export type { ChatAgentSummary, ChatEvent, ChatMessage, ChatRole, ChatSessionOptions, ChatSessionState, ChatSessionStatus, ChatTheme, } from './entities';
+export type { ChatAgentSummary, ChatEvent, ChatMessage, ChatMessageMetadata, ChatRole, ChatSessionOptions, ChatSessionState, ChatSessionStatus, ChatTheme, } from './entities';

package/dist/react.d.ts

@@ -17,6 +17,23 @@
  */
 import { type CSSProperties } from 'react';
 import type { ChatTheme } from './entities';
+/**
+ * Optional callback invoked when the visitor clicks the Approve/Deny
+ * button on a tool-approval bubble. When omitted, the bubble renders
+ * as a read-only "waiting" hint — the visitor can't decide from inside
+ * the widget. When wired, the widget calls this with `{approvalId,
+ * action}` and the host implementation typically POSTs to
+ * `/public/chat/approvals/:id/{approve|deny}` with the visitor's
+ * `browserSessionId` for ownership verification.
+ *
+ * Throwing or rejecting from the handler keeps the bubble in its
+ * pending state and surfaces the error inline so the visitor can
+ * retry.
+ */
+export type ApprovalActionHandler = (args: {
+    approvalId: string;
+    action: 'approve' | 'deny';
+}) => Promise<void>;
 export interface ChatWidgetProps {
     /** Public chat token (`aft_*`) issued from the admin UI. */
     token: string;
@@ -38,6 +55,12 @@ export interface ChatWidgetProps {
     className?: string;
     /** Inline style on the root container. */
     style?: CSSProperties;
+    /**
+     * Handler for tool-approval bubble actions. See `ApprovalActionHandler`
+     * for the contract. Omit to render approval messages as read-only
+     * hints.
+     */
+    onApprovalAction?: ApprovalActionHandler;
 }
 /**
  * Drop-in chat widget. Owns its own `ChatSession` and re-renders on every

package/dist/react.js

@@ -158,7 +158,7 @@ function renderMarkdown(src) {
  * SDK event. Consumers don't need to read `session.getState()` themselves.
  */
 function ChatWidget(props) {
-    const { token, apiBaseUrl, inline = false, position, browserSessionId, resumeConversationId, stream, className, style, } = props;
+    const { token, apiBaseUrl, inline = false, position, browserSessionId, resumeConversationId, stream, className, style, onApprovalAction, } = props;
     const [session, setSession] = (0, react_1.useState)(null);
     const [status, setStatus] = (0, react_1.useState)('idle');
     const [agent, setAgent] = (0, react_1.useState)();
@@ -278,9 +278,31 @@ function ChatWidget(props) {
     };
     return ((0, jsx_runtime_1.jsxs)("div", { className: rootClass, style: rootStyle, "data-style-id": styleId, children: [!inline && ((0, jsx_runtime_1.jsx)("button", { type: "button", className: "af-toggle", "aria-label": open ? 'Close chat' : 'Open chat', "aria-expanded": open, onClick: () => setOpen((v) => !v), children: open ? (0, jsx_runtime_1.jsx)(CloseIcon, {}) : (0, jsx_runtime_1.jsx)(ChatIcon, {}) })), (0, jsx_runtime_1.jsxs)("div", { className: `af-panel ${open ? 'af-open' : ''}`, children: [(0, jsx_runtime_1.jsxs)("div", { className: "af-header", children: [theme?.avatarUrl ? (
                             // eslint-disable-next-line @next/next/no-img-element
-                            (0, jsx_runtime_1.jsx)("img", { className: "af-header-avatar", src: theme.avatarUrl, alt: "" })) : null, (0, jsx_runtime_1.jsxs)("div", { className: "af-header-info", children: [(0, jsx_runtime_1.jsx)("div", { className: "af-header-title", children: theme?.title ?? agent?.name ?? 'Chat' }), (0, jsx_runtime_1.jsx)("div", { className: "af-header-subtitle", children: status === 'loading' ? 'Loading…' : agent?.description ?? '' })] }), !inline && ((0, jsx_runtime_1.jsx)("button", { type: "button", className: "af-close", onClick: () => setOpen(false), "aria-label": "Close chat", children: (0, jsx_runtime_1.jsx)(CloseIcon, {}) }))] }), (0, jsx_runtime_1.jsx)("div", { className: "af-messages", ref: messagesRef, children: messages.map((m) => ((0, jsx_runtime_1.jsx)(MessageBubble, { message: m }, m.id))) }), lastError && status === 'error' && ((0, jsx_runtime_1.jsx)("div", { className: "af-error", children: lastError })), (0, jsx_runtime_1.jsxs)("div", { className: "af-input-row", children: [(0, jsx_runtime_1.jsx)("textarea", { className: "af-input", value: draft, onChange: (e) => setDraft(e.target.value), onKeyDown: onKeyDown, placeholder: "Type a message\u2026", rows: 1, disabled: status === 'ended' || status === 'loading' || status === 'idle' }), (0, jsx_runtime_1.jsx)("button", { type: "button", className: "af-send", onClick: handleSend, disabled: sendDisabled, "aria-label": "Send message", children: (0, jsx_runtime_1.jsx)(SendIcon, {}) })] }), (0, jsx_runtime_1.jsx)("div", { className: "af-footer", children: "Powered by AgentForge" })] })] }));
+                            (0, jsx_runtime_1.jsx)("img", { className: "af-header-avatar", src: theme.avatarUrl, alt: "" })) : null, (0, jsx_runtime_1.jsxs)("div", { className: "af-header-info", children: [(0, jsx_runtime_1.jsx)("div", { className: "af-header-title", children: theme?.title ?? agent?.name ?? 'Chat' }), (0, jsx_runtime_1.jsx)("div", { className: "af-header-subtitle", children: status === 'loading' ? 'Loading…' : agent?.description ?? '' })] }), !inline && ((0, jsx_runtime_1.jsx)("button", { type: "button", className: "af-close", onClick: () => setOpen(false), "aria-label": "Close chat", children: (0, jsx_runtime_1.jsx)(CloseIcon, {}) }))] }), (0, jsx_runtime_1.jsx)("div", { className: "af-messages", ref: messagesRef, children: messages.map((m) => ((0, jsx_runtime_1.jsx)(MessageBubble, { message: m, onApprovalAction: onApprovalAction, onContinue: () => {
+                                // After a successful Approve, kick the next turn so the
+                                // gate's fast-path consumes the approval and the tool
+                                // actually runs. Delay = let the "Approved" pill flash
+                                // for a beat before the assistant bubble appears.
+                                if (!session)
+                                    return;
+                                setTimeout(() => {
+                                    void session.send('continue');
+                                }, 250);
+                            } }, m.id))) }), lastError && status === 'error' && ((0, jsx_runtime_1.jsx)("div", { className: "af-error", children: lastError })), (0, jsx_runtime_1.jsxs)("div", { className: "af-input-row", children: [(0, jsx_runtime_1.jsx)("textarea", { className: "af-input", value: draft, onChange: (e) => setDraft(e.target.value), onKeyDown: onKeyDown, placeholder: "Type a message\u2026", rows: 1, disabled: status === 'ended' || status === 'loading' || status === 'idle' }), (0, jsx_runtime_1.jsx)("button", { type: "button", className: "af-send", onClick: handleSend, disabled: sendDisabled, "aria-label": "Send message", children: (0, jsx_runtime_1.jsx)(SendIcon, {}) })] }), (0, jsx_runtime_1.jsx)("div", { className: "af-footer", children: "Powered by AgentForge" })] })] }));
 }
-function MessageBubble({ message }) {
+function MessageBubble({ message, onApprovalAction, onContinue, }) {
+    // Structured metadata takes precedence over plain text. The server
+    // tags messages with `kind: 'awaiting_approval' | 'tool_blocked'`
+    // and the widget renders a dedicated bubble for each — unknown
+    // kinds fall through to the markdown renderer with the plain text
+    // body the server also persists.
+    const kind = message.metadata?.kind;
+    if (kind === 'awaiting_approval') {
+        return ((0, jsx_runtime_1.jsx)(ApprovalBubble, { message: message, onAction: onApprovalAction, onContinue: onContinue }));
+    }
+    if (kind === 'tool_blocked') {
+        return (0, jsx_runtime_1.jsx)(BlockedBubble, { message: message });
+    }
     const cls = `af-msg af-msg-${message.role}${message.role === 'assistant' && message.isStreaming
         ? message.content
             ? ' af-msg-streaming'
@@ -299,6 +321,72 @@ function MessageBubble({ message }) {
     // User & system messages stay as plain text — they're typed verbatim.
     return (0, jsx_runtime_1.jsx)("div", { className: cls, children: message.content });
 }
+/**
+ * Awaiting-approval bubble. Renders the tool name + a countdown, and
+ * either the Approve/Deny buttons (when the host wired the handler)
+ * or a read-only hint. After a successful approve, fires `onContinue`
+ * so the chat auto-sends "continue" and the gate's fast-path consumes
+ * the row on the next turn.
+ */
+function ApprovalBubble({ message, onAction, onContinue, }) {
+    const meta = message.metadata;
+    const [busy, setBusy] = (0, react_1.useState)(null);
+    const [decided, setDecided] = (0, react_1.useState)(null);
+    const [err, setErr] = (0, react_1.useState)(null);
+    const remaining = useExpiresIn(meta?.expiresAt);
+    if (!meta)
+        return null;
+    const act = async (action) => {
+        if (!onAction)
+            return;
+        setBusy(action);
+        setErr(null);
+        try {
+            await onAction({ approvalId: meta.approvalId, action });
+            setDecided(action === 'approve' ? 'approved' : 'denied');
+            if (action === 'approve')
+                onContinue();
+        }
+        catch (e) {
+            setErr(e instanceof Error ? e.message : String(e));
+        }
+        finally {
+            setBusy(null);
+        }
+    };
+    return ((0, jsx_runtime_1.jsxs)("div", { className: "af-msg af-msg-approval", children: [(0, jsx_runtime_1.jsx)("div", { className: "af-approval-title", children: "Awaiting approval" }), (0, jsx_runtime_1.jsxs)("div", { className: "af-approval-body", children: ["The agent wants to run", ' ', (0, jsx_runtime_1.jsx)("code", { className: "af-approval-tool", children: meta.toolName }), "."] }), remaining && !decided && ((0, jsx_runtime_1.jsx)("div", { className: "af-approval-meta", children: remaining })), decided && ((0, jsx_runtime_1.jsx)("div", { className: `af-approval-pill af-approval-pill-${decided}`, children: decided === 'approved' ? 'Approved — retrying…' : 'Denied' })), !decided && onAction && ((0, jsx_runtime_1.jsxs)("div", { className: "af-approval-actions", children: [(0, jsx_runtime_1.jsx)("button", { type: "button", className: "af-approval-btn af-approval-approve", disabled: busy !== null, onClick: () => act('approve'), children: busy === 'approve' ? 'Approving…' : 'Approve' }), (0, jsx_runtime_1.jsx)("button", { type: "button", className: "af-approval-btn af-approval-deny", disabled: busy !== null, onClick: () => act('deny'), children: busy === 'deny' ? 'Denying…' : 'Deny' })] })), !decided && !onAction && ((0, jsx_runtime_1.jsx)("div", { className: "af-approval-hint", children: "A workspace admin needs to review this." })), err && (0, jsx_runtime_1.jsx)("div", { className: "af-approval-error", children: err })] }));
+}
+/**
+ * Terminal "tool blocked" bubble. No action — just informs the visitor
+ * that the tool the agent tried isn't available.
+ */
+function BlockedBubble({ message }) {
+    const meta = message.metadata;
+    if (!meta)
+        return null;
+    return ((0, jsx_runtime_1.jsxs)("div", { className: "af-msg af-msg-blocked", children: [(0, jsx_runtime_1.jsx)("div", { className: "af-blocked-title", children: "Tool blocked" }), (0, jsx_runtime_1.jsxs)("div", { className: "af-blocked-body", children: [(0, jsx_runtime_1.jsx)("code", { className: "af-approval-tool", children: meta.toolName }), " is blocked by the workspace admin.", ' ', meta.reason ?? ''] })] }));
+}
+/** Live "expires in" countdown. Returns null after the deadline. */
+function useExpiresIn(iso) {
+    const [, force] = (0, react_1.useState)(0);
+    (0, react_1.useEffect)(() => {
+        if (!iso)
+            return;
+        const t = setInterval(() => force((n) => n + 1), 1000);
+        return () => clearInterval(t);
+    }, [iso]);
+    if (!iso)
+        return null;
+    const ms = new Date(iso).getTime() - Date.now();
+    if (!Number.isFinite(ms) || ms <= 0)
+        return null;
+    const totalSeconds = Math.floor(ms / 1000);
+    const m = Math.floor(totalSeconds / 60);
+    const s = totalSeconds % 60;
+    if (m >= 60)
+        return `Expires in ${Math.floor(m / 60)}h ${m % 60}m`;
+    return `Expires in ${m}m ${s.toString().padStart(2, '0')}s`;
+}
 function ChatIcon() {
     return ((0, jsx_runtime_1.jsx)("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", "aria-hidden": true, children: (0, jsx_runtime_1.jsx)("path", { d: "M21 11.5a8.38 8.38 0 0 1-.9 3.8 8.5 8.5 0 0 1-7.6 4.7 8.38 8.38 0 0 1-3.8-.9L3 21l1.9-5.7a8.38 8.38 0 0 1-.9-3.8 8.5 8.5 0 0 1 4.7-7.6 8.38 8.38 0 0 1 3.8-.9h.5a8.48 8.48 0 0 1 8 8v.5z" }) }));
 }
@@ -402,4 +490,25 @@ const WIDGET_CSS = `
 .af-send svg { width: 16px; height: 16px; }
 .af-error { padding: 10px 16px; font-size: 12px; color: #b91c1c; background: #fef2f2; border-top: 1px solid #fee2e2; }
 .af-footer { padding: 6px 12px; font-size: 10px; color: var(--af-muted); text-align: center; background: var(--af-bubble-bg); border-top: 1px solid var(--af-border); }
+/* Approval and blocked bubbles. Amber for needs-decision, red for
+ * won't-happen. Same animation-in as the regular .af-msg so the
+ * transition feels uniform. */
+.af-msg-approval { align-self: flex-start; max-width: 90%; padding: 12px 14px; border-radius: 14px; border-bottom-left-radius: 4px; font-size: 13px; line-height: 1.5; background: #fffbeb; border: 1px solid #fde68a; color: #7c2d12; animation: af-msg-in 220ms cubic-bezier(0.2, 0.8, 0.2, 1); }
+.af-approval-title { font-weight: 600; font-size: 13px; margin-bottom: 4px; }
+.af-approval-body { font-size: 13px; line-height: 1.5; }
+.af-approval-tool { background: rgba(0,0,0,0.06); padding: 1px 6px; border-radius: 4px; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 12px; }
+.af-approval-meta { font-size: 11px; margin-top: 6px; color: #92400e; }
+.af-approval-actions { display: flex; gap: 8px; margin-top: 10px; }
+.af-approval-btn { padding: 6px 12px; font-size: 12px; font-weight: 600; border-radius: 8px; cursor: pointer; transition: opacity 0.15s ease; }
+.af-approval-btn:disabled { opacity: 0.6; cursor: not-allowed; }
+.af-approval-approve { background: var(--af-primary); color: white; border: none; }
+.af-approval-deny { background: white; color: #7c2d12; border: 1px solid #fde68a; }
+.af-approval-pill { display: inline-block; margin-top: 8px; padding: 2px 8px; border-radius: 999px; font-size: 11px; font-weight: 600; }
+.af-approval-pill-approved { background: #dcfce7; color: #166534; }
+.af-approval-pill-denied { background: #fee2e2; color: #991b1b; }
+.af-approval-hint { font-size: 12px; margin-top: 8px; color: #7c2d12; }
+.af-approval-error { font-size: 11px; margin-top: 6px; color: #b91c1c; }
+.af-msg-blocked { align-self: flex-start; max-width: 90%; padding: 10px 14px; border-radius: 14px; border-bottom-left-radius: 4px; font-size: 13px; line-height: 1.5; background: #fef2f2; border: 1px solid #fecaca; color: #7f1d1d; animation: af-msg-in 220ms cubic-bezier(0.2, 0.8, 0.2, 1); }
+.af-blocked-title { font-weight: 600; font-size: 13px; margin-bottom: 4px; }
+.af-blocked-body { font-size: 12px; line-height: 1.5; }
 `;

package/dist/session.js

@@ -80,6 +80,7 @@ class ChatSession {
                                 role: m.role,
                                 content: m.content,
                                 createdAt: new Date(m.createdAt),
+                                metadata: m.metadata,
                             });
                         }
                         if (history.status === 'completed') {
@@ -186,6 +187,39 @@ class ChatSession {
                 }
                 if (evt.kind === 'chunk') {
                     sawAnyChunk = true;
+                    // Approval gate intercepts. The server emits one of these as
+                    // the final chunk before closing the stream; we mutate the
+                    // in-flight assistant message with the structured payload so
+                    // the View can swap the bubble for an Approve/Deny card. The
+                    // text body falls back to a sensible plain-text version so a
+                    // legacy widget (no metadata renderer) still shows something
+                    // readable.
+                    const chunkType = evt.chunk.type;
+                    if (chunkType === 'awaiting_approval') {
+                        const c = evt.chunk;
+                        assistant.metadata = {
+                            kind: 'awaiting_approval',
+                            approvalId: c.approvalId,
+                            toolName: c.toolName,
+                            expiresAt: c.expiresAt,
+                        };
+                        assistant.content =
+                            full || `(waiting for approval to run \`${c.toolName}\`)`;
+                        this.updateMessage(assistant);
+                        continue;
+                    }
+                    if (chunkType === 'tool_blocked') {
+                        const c = evt.chunk;
+                        assistant.metadata = {
+                            kind: 'tool_blocked',
+                            toolName: c.toolName,
+                            reason: c.reason,
+                        };
+                        assistant.content =
+                            full || c.reason || `Tool "${c.toolName}" is blocked.`;
+                        this.updateMessage(assistant);
+                        continue;
+                    }
                     const delta = extractDelta(evt.chunk);
                     if (!delta)
                         continue;
@@ -207,7 +241,12 @@ class ChatSession {
             // than leaving an empty assistant bubble. Most often this means the
             // backend swallowed an exception inside streamMessage (e.g. the
             // history query failed or the runner rejected the model).
-            if (!full) {
+            //
+            // Exception: when the stream ended on an approval / blocked
+            // chunk, the bubble carries that structured payload and is a
+            // legitimate terminal state — not a missing reply. Skip the
+            // "empty response" guard for those.
+            if (!full && !assistant.metadata) {
                 throw new Error(sawAnyChunk
                     ? 'The model returned an empty response.'
                     : 'No response received from the server.');

package/dist/transport.d.ts

@@ -77,6 +77,10 @@ export declare class HttpTransport {
             role: 'user' | 'assistant' | 'system';
             content: string;
             createdAt: string;
+            /** Structured payload for non-text messages (approval cards,
+             *  blocked errors). Passed through unchanged from the server's
+             *  message row so a reload re-renders the same card. */
+            metadata?: Record<string, unknown>;
         }>;
     } | null>;
     endConversation(conversationId: string, browserSessionId: string): Promise<void>;

package/dist/transport.js

@@ -107,6 +107,7 @@ class HttpTransport {
                 role: m.role,
                 content: m.content,
                 createdAt: m.createdAt,
+                metadata: m.metadata,
             })),
         };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentforge-io/chat-sdk",
-  "version": "2.0.16",
+  "version": "2.0.18",
   "description": "Framework-free chat session SDK for AgentForge public chat tokens. Headless — no DOM. Drop into any frontend (React, Vue, Svelte, vanilla) and listen for events.",
   "license": "MIT",
   "main": "dist/index.js",