@agentforge-io/core 2.0.18 → 2.0.19

package/dist/domain/conversation.d.ts

@@ -20,6 +20,20 @@ export interface Message {
     content: string;
     toolCalls?: ToolCallRecord[];
     usage?: TokenUsage;
+    /**
+     * Free-form metadata the host can attach to a message. The runtime is
+     * agnostic about its contents — it persists and surfaces it back. Used
+     * today by:
+     *
+     *   - `tool_approvals`: synthetic assistant message carries
+     *     `{ kind: 'awaiting_approval', approvalId, toolName, expiresAt }`
+     *     so the chat client can render an Approve/Deny card inline
+     *     instead of plain text.
+     *
+     * Add new kinds without a schema migration — the field is JSONB in
+     * the persistence adapter.
+     */
+    metadata?: Record<string, unknown>;
     createdAt: Date;
 }
 export type NewConversation = Pick<Conversation, 'userId' | 'agentId'> & Partial<Omit<Conversation, 'id' | 'createdAt' | 'updatedAt'>>;

package/dist/services/agent.service.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AgentService = exports.AgentForbiddenError = void 0;
+const tool_approval_gate_1 = require("./tool-approval-gate");
 class AgentForbiddenError extends Error {
     constructor(reason) {
         super(`Usage limit exceeded: ${reason}`);
@@ -240,18 +241,73 @@ class AgentService {
         const resolvedExtras = await this.resolveExtraTools(agent.connectorOwnerUserId ?? params.userId);
         const filter = params.overrides?.extraToolsFilter;
         const extraTools = filter && resolvedExtras ? filter(resolvedExtras) : resolvedExtras;
-        for await (const chunk of this.runner.stream(agent, messages, {
-            userId: params.userId,
-            conversationId: params.conversationId,
-            agentId: conv.agentId,
-            messageId: 'streaming',
-            agent: { timezone: agent.timezone },
-        }, { ...(params.overrides ?? {}), extraTools })) {
-            if (chunk.type === 'text_delta')
-                fullContent += chunk.delta;
-            if (chunk.type === 'usage')
-                finalUsage = chunk.usage;
-            yield chunk;
+        try {
+            for await (const chunk of this.runner.stream(agent, messages, {
+                userId: params.userId,
+                conversationId: params.conversationId,
+                agentId: conv.agentId,
+                messageId: 'streaming',
+                agent: { timezone: agent.timezone },
+            }, { ...(params.overrides ?? {}), extraTools })) {
+                if (chunk.type === 'text_delta')
+                    fullContent += chunk.delta;
+                if (chunk.type === 'usage')
+                    finalUsage = chunk.usage;
+                yield chunk;
+            }
+        }
+        catch (err) {
+            // Tool-approval gate decisions surface as typed exceptions. We
+            // intercept them HERE so the SSE consumer sees a structured
+            // chunk instead of a torn-down generator. Each branch also
+            // persists a synthetic assistant message carrying the metadata
+            // the chat client needs to re-render the card on reload — the
+            // stream may close, but the conversation history doesn't lose
+            // context.
+            if ((0, tool_approval_gate_1.isToolApprovalRequired)(err)) {
+                yield {
+                    type: 'awaiting_approval',
+                    approvalId: err.approvalId,
+                    toolName: err.toolName,
+                    expiresAt: err.expiresAt,
+                };
+                await this.conversations.addMessage({
+                    conversationId: params.conversationId,
+                    userId: params.userId,
+                    role: 'assistant',
+                    // Plain-text body so legacy clients (or a server reload of
+                    // history into a non-aware client) still get a readable
+                    // line. The card lives in `metadata`.
+                    content: `(waiting for approval to run \`${err.toolName}\`)`,
+                    metadata: {
+                        kind: 'awaiting_approval',
+                        approvalId: err.approvalId,
+                        toolName: err.toolName,
+                        expiresAt: err.expiresAt,
+                    },
+                });
+                return;
+            }
+            if ((0, tool_approval_gate_1.isToolBlockedError)(err)) {
+                yield {
+                    type: 'tool_blocked',
+                    toolName: err.toolName,
+                    reason: err.reason,
+                };
+                await this.conversations.addMessage({
+                    conversationId: params.conversationId,
+                    userId: params.userId,
+                    role: 'assistant',
+                    content: err.reason ?? `Tool "${err.toolName}" is blocked.`,
+                    metadata: {
+                        kind: 'tool_blocked',
+                        toolName: err.toolName,
+                        reason: err.reason,
+                    },
+                });
+                return;
+            }
+            throw err;
         }
         if (fullContent) {
             await this.conversations.addMessage({

package/dist/services/conversation.service.d.ts

@@ -23,6 +23,9 @@ export declare class ConversationService {
         content: string;
         toolCalls?: ToolCallRecord[];
         usage?: TokenUsage;
+        /** Optional structured payload. See `Message.metadata` in
+         *  `domain/conversation.ts` for usage. */
+        metadata?: Record<string, unknown>;
     }): Promise<Message>;
     /** Throws on not-found OR cross-user access. */
     private loadOwned;

package/dist/services/conversation.service.js

@@ -34,6 +34,7 @@ class ConversationService {
             content: params.content,
             toolCalls: params.toolCalls,
             usage: params.usage,
+            metadata: params.metadata,
         });
         await this.convRepo.updateStats(params.conversationId, {
             addInputTokens: params.usage?.inputTokens,
@@ -94,6 +95,7 @@ class ConversationService {
             content: msg.content,
             toolCalls: msg.toolCalls,
             usage: msg.usage,
+            metadata: msg.metadata,
             createdAt: msg.createdAt,
         };
     }

package/dist/types/agent.types.d.ts

@@ -173,6 +173,27 @@ export type StreamChunk = {
 } | {
     type: 'usage';
     usage: TokenUsage;
+} | {
+    /**
+     * Emitted by the runtime when a tool dispatch hit
+     * `ToolApprovalGate.check() → { kind: 'approval' }`. The stream
+     * ends right after this chunk — the runner is paused until the
+     * approval is decided. The chat client renders an Approve/Deny
+     * card based on the carried fields; after Approve the client
+     * triggers a fresh `sendMessage("continue")` and the gate's
+     * fast-path consumes the pending row.
+     */
+    type: 'awaiting_approval';
+    approvalId: string;
+    toolName: string;
+    expiresAt: string;
+} | {
+    /** Emitted when a tool dispatch hit `kind: 'blocked'`. Mirrors the
+     *  shape above so the client renders a terminal-error card with
+     *  the same component. */
+    type: 'tool_blocked';
+    toolName: string;
+    reason?: string;
 } | {
     type: 'done';
     messageId: string;
@@ -207,5 +228,9 @@ export interface MessageRecord {
     content: string;
     toolCalls?: ToolCallRecord[];
     usage?: TokenUsage;
+    /** Structured payload mirror of `Message.metadata`. Same kinds, same
+     *  back-compat semantics. Lets the chat history endpoint pass the
+     *  approval-card / blocked-tool markers through to the client. */
+    metadata?: Record<string, unknown>;
     createdAt: Date;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentforge-io/core",
-  "version": "2.0.18",
+  "version": "2.0.19",
   "description": "Framework-free AI runtime SDK. Owns: agent loop (Anthropic), conversations, tools, streaming, agent-job queue, SdkHooks. Identity, billing, infra (email/uploads/secrets) live in the host's modules — not here.",
   "license": "MIT",
   "main": "dist/index.js",