@agentforge-io/chat-sdk 2.0.15 → 2.0.17

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/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.15",
+  "version": "2.0.17",
   "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",