@agentforge-io/core 2.0.18 → 2.0.20

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.d.ts

@@ -105,6 +105,19 @@ export declare class AgentService {
      *  authenticated user's connector tools (Gmail, Drive, …) on the fly
      *  via `overrides.extraTools`. Optional — connectors are opt-in. */
     connectorRegistry?: ConnectorRegistryService | undefined);
+    /**
+     * Look up the human-friendly connector name + tool description for a
+     * given tool slug. Powers the friendly copy in `awaiting_approval` /
+     * `tool_blocked` cards: the visitor sees "Granola" instead of
+     * `granola_list_meetings`. Returns `undefined` for built-in / MCP
+     * tools, or when the registry isn't wired — the chat client falls
+     * back to the raw `toolName` in that case.
+     *
+     * Iterates every registered connector definition. The registry is
+     * small (handful of entries) so this is O(connectors × tools);
+     * acceptable for the rare per-approval call path.
+     */
+    private describeTool;
     /**
      * Fetch the connector tools the user has authorized, swallowing failures.
      * The agent loop must keep working even if a connector's refresh token is

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}`);
@@ -28,6 +29,38 @@ class AgentService {
         this.hooks = hooks;
         this.connectorRegistry = connectorRegistry;
     }
+    /**
+     * Look up the human-friendly connector name + tool description for a
+     * given tool slug. Powers the friendly copy in `awaiting_approval` /
+     * `tool_blocked` cards: the visitor sees "Granola" instead of
+     * `granola_list_meetings`. Returns `undefined` for built-in / MCP
+     * tools, or when the registry isn't wired — the chat client falls
+     * back to the raw `toolName` in that case.
+     *
+     * Iterates every registered connector definition. The registry is
+     * small (handful of entries) so this is O(connectors × tools);
+     * acceptable for the rare per-approval call path.
+     */
+    describeTool(toolName) {
+        if (!this.connectorRegistry)
+            return undefined;
+        try {
+            for (const def of this.connectorRegistry.list()) {
+                for (const factory of def.tools) {
+                    if (factory.definition.name === toolName) {
+                        return {
+                            connectorName: def.name,
+                            toolDescription: factory.definition.description,
+                        };
+                    }
+                }
+            }
+        }
+        catch {
+            // Registry is misconfigured — fall back to bare tool name.
+        }
+        return undefined;
+    }
     /**
      * Fetch the connector tools the user has authorized, swallowing failures.
      * The agent loop must keep working even if a connector's refresh token is
@@ -240,18 +273,87 @@ 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)) {
+                const ctx = this.describeTool(err.toolName);
+                yield {
+                    type: 'awaiting_approval',
+                    approvalId: err.approvalId,
+                    toolName: err.toolName,
+                    expiresAt: err.expiresAt,
+                    connectorName: ctx?.connectorName,
+                    toolDescription: ctx?.toolDescription,
+                };
+                await this.conversations.addMessage({
+                    conversationId: params.conversationId,
+                    userId: params.userId,
+                    role: 'assistant',
+                    // Plain-text fallback. Friendly enough for legacy clients
+                    // that don't render `metadata.kind`. The structured card
+                    // lives in `metadata` for capable widgets.
+                    content: ctx?.connectorName
+                        ? `Necesito tu permiso para usar ${ctx.connectorName}.`
+                        : `Necesito tu permiso para continuar.`,
+                    metadata: {
+                        kind: 'awaiting_approval',
+                        approvalId: err.approvalId,
+                        toolName: err.toolName,
+                        expiresAt: err.expiresAt,
+                        connectorName: ctx?.connectorName,
+                        toolDescription: ctx?.toolDescription,
+                    },
+                });
+                return;
+            }
+            if ((0, tool_approval_gate_1.isToolBlockedError)(err)) {
+                const ctx = this.describeTool(err.toolName);
+                yield {
+                    type: 'tool_blocked',
+                    toolName: err.toolName,
+                    reason: err.reason,
+                    connectorName: ctx?.connectorName,
+                    toolDescription: ctx?.toolDescription,
+                };
+                await this.conversations.addMessage({
+                    conversationId: params.conversationId,
+                    userId: params.userId,
+                    role: 'assistant',
+                    content: ctx?.connectorName
+                        ? `No puedo usar ${ctx.connectorName} en esta cuenta.`
+                        : `No puedo usar esa herramienta en esta cuenta.`,
+                    metadata: {
+                        kind: 'tool_blocked',
+                        toolName: err.toolName,
+                        reason: err.reason,
+                        connectorName: ctx?.connectorName,
+                        toolDescription: ctx?.toolDescription,
+                    },
+                });
+                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,39 @@ 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;
+    /** Human-friendly connector name (`'Granola'`, `'Notion'`). The
+     *  runner enriches it from the registry so the chat widget can
+     *  render a sentence like "I need permission to use Granola"
+     *  instead of the raw tool slug. Optional — clients fall back
+     *  to `toolName` when the runtime doesn't supply this. */
+    connectorName?: string;
+    /** Human-friendly first sentence of the tool's description.
+     *  Same story: enables the widget to say what the tool DOES in
+     *  natural language. Optional. */
+    toolDescription?: 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;
+    connectorName?: string;
+    toolDescription?: string;
 } | {
     type: 'done';
     messageId: string;
@@ -207,5 +240,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.20",
   "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",