@agentforge-io/chat-sdk 2.0.17 → 2.0.19

package/dist/entities.d.ts

@@ -24,10 +24,20 @@ export type ChatMessageMetadata = {
     approvalId: string;
     toolName: string;
     expiresAt: string;
+    /** Friendly connector display name surfaced by the server when
+     *  available (e.g. `'Granola'`). Lets the View render a
+     *  natural-language card without the host having to map slugs
+     *  to product names. */
+    connectorName?: string;
+    /** First line of the tool's description from the connector
+     *  definition. Used as a one-line "what will happen" hint. */
+    toolDescription?: string;
 } | {
     kind: 'tool_blocked';
     toolName: string;
     reason?: string;
+    connectorName?: string;
+    toolDescription?: string;
 } | {
     kind: string;
     [k: string]: unknown;

package/dist/react.d.ts

@@ -17,6 +17,59 @@
  */
 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>;
+/**
+ * Localizable copy for the approval / blocked bubbles. Pass via the
+ * `approvalCopy` prop on `<ChatWidget>` to drop the defaults (Spanish,
+ * conversational) and tailor every line to your audience.
+ *
+ * Functions receive whatever context the server enriched the chunk
+ * with — typically a friendly connector name like `'Granola'`. When
+ * the server didn't supply it, the function is called with `undefined`
+ * and the implementation should pick a sensible generic line. The
+ * widget itself never references the raw tool slug in copy.
+ */
+export interface ApprovalCopy {
+    title: string;
+    body: (ctx: {
+        connectorName?: string;
+        toolDescription?: string;
+    }) => string;
+    approveLabel: string;
+    approveBusyLabel: string;
+    denyLabel: string;
+    denyBusyLabel: string;
+    approvedPill: string;
+    deniedPill: string;
+    /** Shown when the host didn't wire `onApprovalAction` — the visitor
+     *  can't decide from inside the widget so we tell them where to go. */
+    readOnlyHint: string;
+    /** Used by the `expires in …` countdown. Receives minutes/seconds
+     *  and returns the formatted string. */
+    expiresIn: (mins: number, secs: number) => string;
+    /** Block bubble title + body. */
+    blockedTitle: string;
+    blockedBody: (ctx: {
+        connectorName?: string;
+        reason?: string;
+    }) => string;
+}
 export interface ChatWidgetProps {
     /** Public chat token (`aft_*`) issued from the admin UI. */
     token: string;
@@ -38,6 +91,18 @@ 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;
+    /**
+     * Override any subset of the approval-card copy. Keys you don't
+     * provide fall back to the Spanish defaults in `DEFAULT_APPROVAL_COPY`.
+     * Use this for translations or to match your product's voice.
+     */
+    approvalCopy?: Partial<ApprovalCopy>;
 }
 /**
  * Drop-in chat widget. Owns its own `ChatSession` and re-renders on every

package/dist/react.js

@@ -153,12 +153,38 @@ function renderMarkdown(src) {
     }
     return out.join('');
 }
+/**
+ * Defaults are Spanish + conversational. The host overrides individual
+ * keys via the `approvalCopy` prop; unset keys keep these values.
+ */
+const DEFAULT_APPROVAL_COPY = {
+    title: 'Necesito tu permiso',
+    body: ({ connectorName }) => connectorName
+        ? `¿Me das permiso para usar ${connectorName}?`
+        : '¿Me das permiso para continuar?',
+    approveLabel: 'Permitir',
+    approveBusyLabel: 'Permitiendo…',
+    denyLabel: 'No, gracias',
+    denyBusyLabel: 'Cancelando…',
+    approvedPill: 'Listo, continuando…',
+    deniedPill: 'Cancelado',
+    readOnlyHint: 'Pídele al administrador del workspace que lo apruebe.',
+    expiresIn: (m, s) => m >= 60
+        ? `Expira en ${Math.floor(m / 60)}h ${m % 60}m`
+        : `Expira en ${m}m ${s.toString().padStart(2, '0')}s`,
+    blockedTitle: 'No disponible',
+    blockedBody: ({ connectorName, reason }) => reason ??
+        (connectorName
+            ? `No puedo usar ${connectorName} en esta cuenta.`
+            : 'No puedo usar esa herramienta en esta cuenta.'),
+};
 /**
  * Drop-in chat widget. Owns its own `ChatSession` and re-renders on every
  * 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, approvalCopy, } = props;
+    const copy = { ...DEFAULT_APPROVAL_COPY, ...(approvalCopy ?? {}) };
     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 +304,28 @@ 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, copy: copy, 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. `silent: true` keeps the literal
+                                // "continue" prompt out of the visible transcript —
+                                // the visitor just sees the assistant's next reply
+                                // appearing under the "Approved" pill.
+                                if (!session)
+                                    return;
+                                setTimeout(() => {
+                                    void session.send('continue', { silent: true });
+                                }, 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, copy, onApprovalAction, onContinue, }) {
+    const kind = message.metadata?.kind;
+    if (kind === 'awaiting_approval') {
+        return ((0, jsx_runtime_1.jsx)(ApprovalBubble, { message: message, copy: copy, onAction: onApprovalAction, onContinue: onContinue }));
+    }
+    if (kind === 'tool_blocked') {
+        return (0, jsx_runtime_1.jsx)(BlockedBubble, { message: message, copy: copy });
+    }
     const cls = `af-msg af-msg-${message.role}${message.role === 'assistant' && message.isStreaming
         ? message.content
             ? ' af-msg-streaming'
@@ -299,6 +344,78 @@ 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, copy, 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, copy.expiresIn);
+    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: copy.title }), (0, jsx_runtime_1.jsx)("div", { className: "af-approval-body", children: copy.body({
+                    connectorName: meta.connectorName,
+                    toolDescription: meta.toolDescription,
+                }) }), 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' ? copy.approvedPill : copy.deniedPill })), !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' ? copy.approveBusyLabel : copy.approveLabel }), (0, jsx_runtime_1.jsx)("button", { type: "button", className: "af-approval-btn af-approval-deny", disabled: busy !== null, onClick: () => act('deny'), children: busy === 'deny' ? copy.denyBusyLabel : copy.denyLabel })] })), !decided && !onAction && ((0, jsx_runtime_1.jsx)("div", { className: "af-approval-hint", children: copy.readOnlyHint })), 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, copy, }) {
+    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: copy.blockedTitle }), (0, jsx_runtime_1.jsx)("div", { className: "af-blocked-body", children: copy.blockedBody({
+                    connectorName: meta.connectorName,
+                    reason: meta.reason,
+                }) })] }));
+}
+/** Live "expires in" countdown. Returns null after the deadline.
+ *  The format function is host-supplied so the label stays localisable —
+ *  the hook itself doesn't hard-code any user-facing string. */
+function useExpiresIn(iso, format) {
+    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;
+    return format(m, 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 +519,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.d.ts

@@ -42,8 +42,18 @@ export declare class ChatSession {
      * Send a user message. Opens the conversation on first call. Returns the
      * final assistant content for callers that want to await it; the same
      * content is also emitted via `message_added` / `message_updated`.
+     *
+     * `silent: true` suppresses the user-message bubble that would normally
+     * appear in the view layer. Used by the tool-approval auto-continue
+     * flow: after the visitor clicks Approve, the widget fires a hidden
+     * `send('continue', { silent: true })` so the gate's fast-path
+     * triggers without leaking a literal "continue" message into the
+     * conversation. The server still sees a regular user message and the
+     * agent's reply comes back through the normal stream.
      */
-    send(text: string): Promise<string>;
+    send(text: string, opts?: {
+        silent?: boolean;
+    }): Promise<string>;
     private runStream;
     private runNonStream;
     private appendMessage;

package/dist/session.js

@@ -142,8 +142,16 @@ class ChatSession {
      * Send a user message. Opens the conversation on first call. Returns the
      * final assistant content for callers that want to await it; the same
      * content is also emitted via `message_added` / `message_updated`.
+     *
+     * `silent: true` suppresses the user-message bubble that would normally
+     * appear in the view layer. Used by the tool-approval auto-continue
+     * flow: after the visitor clicks Approve, the widget fires a hidden
+     * `send('continue', { silent: true })` so the gate's fast-path
+     * triggers without leaking a literal "continue" message into the
+     * conversation. The server still sees a regular user message and the
+     * agent's reply comes back through the normal stream.
      */
-    async send(text) {
+    async send(text, opts) {
         const trimmed = text.trim();
         if (!trimmed)
             return '';
@@ -152,12 +160,14 @@ class ChatSession {
         }
         if (!this.started)
             await this.start();
-        this.appendMessage({
-            id: makeMessageId('u'),
-            role: 'user',
-            content: trimmed,
-            createdAt: new Date(),
-        });
+        if (!opts?.silent) {
+            this.appendMessage({
+                id: makeMessageId('u'),
+                role: 'user',
+                content: trimmed,
+                createdAt: new Date(),
+            });
+        }
         const assistant = {
             id: makeMessageId('a'),
             role: 'assistant',
@@ -202,9 +212,14 @@ class ChatSession {
                             approvalId: c.approvalId,
                             toolName: c.toolName,
                             expiresAt: c.expiresAt,
+                            connectorName: c.connectorName,
+                            toolDescription: c.toolDescription,
                         };
                         assistant.content =
-                            full || `(waiting for approval to run \`${c.toolName}\`)`;
+                            full ||
+                                (c.connectorName
+                                    ? `Necesito tu permiso para usar ${c.connectorName}.`
+                                    : `Necesito tu permiso para continuar.`);
                         this.updateMessage(assistant);
                         continue;
                     }
@@ -214,9 +229,15 @@ class ChatSession {
                             kind: 'tool_blocked',
                             toolName: c.toolName,
                             reason: c.reason,
+                            connectorName: c.connectorName,
+                            toolDescription: c.toolDescription,
                         };
                         assistant.content =
-                            full || c.reason || `Tool "${c.toolName}" is blocked.`;
+                            full ||
+                                c.reason ||
+                                (c.connectorName
+                                    ? `No puedo usar ${c.connectorName} en esta cuenta.`
+                                    : `No puedo usar esa herramienta en esta cuenta.`);
                         this.updateMessage(assistant);
                         continue;
                     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentforge-io/chat-sdk",
-  "version": "2.0.17",
+  "version": "2.0.19",
   "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",