@agentforge-io/core 2.0.19 → 2.0.20

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

@@ -29,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
@@ -265,44 +297,58 @@ class AgentService {
             // 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 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}\`)`,
+                    // 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: err.reason ?? `Tool "${err.toolName}" is blocked.`,
+                    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;

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

@@ -187,6 +187,16 @@ export type StreamChunk = {
     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
@@ -194,6 +204,8 @@ export type StreamChunk = {
     type: 'tool_blocked';
     toolName: string;
     reason?: string;
+    connectorName?: string;
+    toolDescription?: string;
 } | {
     type: 'done';
     messageId: string;

package/package.json

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