@agentforge-io/core 2.0.19 → 2.0.21

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

@@ -4,6 +4,7 @@ import type { SdkHooks } from '../types/hooks';
 import type { AgentRunnerService } from './agent-runner.service';
 import type { ConversationService } from './conversation.service';
 import type { ConnectorRegistryService } from './connector-registry.service';
+import type { ApprovalCopywriterService } from './approval-copywriter.service';
 /**
  * Minimal record the host's agent-config layer must supply to resolve
  * agents by `(tenantId, slug)` or by id. The SDK doesn't care where this
@@ -94,6 +95,11 @@ export declare class AgentService {
      *  authenticated user's connector tools (Gmail, Drive, …) on the fly
      *  via `overrides.extraTools`. Optional — connectors are opt-in. */
     private readonly connectorRegistry?;
+    /** When wired, the AgentService asks this service to generate the
+     *  microcopy shown in the in-chat approval bubble. Falls back to a
+     *  meta-only render on the client when unwired or when generation
+     *  fails. */
+    private readonly copywriter?;
     constructor(agents: AgentDefinition[], runner: AgentRunnerService, conversations: ConversationService, 
     /** When wired, agents created via the admin UI are looked up here first;
      *  the hardcoded `agents` array remains a fallback for legacy installs. */
@@ -104,7 +110,25 @@ export declare class AgentService {
     /** When wired, every streamMessage / sendMessage call attaches the
      *  authenticated user's connector tools (Gmail, Drive, …) on the fly
      *  via `overrides.extraTools`. Optional — connectors are opt-in. */
-    connectorRegistry?: ConnectorRegistryService | undefined);
+    connectorRegistry?: ConnectorRegistryService | undefined, 
+    /** When wired, the AgentService asks this service to generate the
+     *  microcopy shown in the in-chat approval bubble. Falls back to a
+     *  meta-only render on the client when unwired or when generation
+     *  fails. */
+    copywriter?: ApprovalCopywriterService | 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

@@ -21,13 +21,51 @@ class AgentService {
     /** When wired, every streamMessage / sendMessage call attaches the
      *  authenticated user's connector tools (Gmail, Drive, …) on the fly
      *  via `overrides.extraTools`. Optional — connectors are opt-in. */
-    connectorRegistry) {
+    connectorRegistry, 
+    /** When wired, the AgentService asks this service to generate the
+     *  microcopy shown in the in-chat approval bubble. Falls back to a
+     *  meta-only render on the client when unwired or when generation
+     *  fails. */
+    copywriter) {
         this.agents = agents;
         this.runner = runner;
         this.conversations = conversations;
         this.resolver = resolver;
         this.hooks = hooks;
         this.connectorRegistry = connectorRegistry;
+        this.copywriter = copywriter;
+    }
+    /**
+     * 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.
@@ -265,44 +303,80 @@ 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);
+                const copy = await this.copywriter?.generate({
+                    kind: 'approval',
+                    toolName: err.toolName,
+                    connectorName: ctx?.connectorName,
+                    toolDescription: ctx?.toolDescription,
+                    recentMessages: extractRecentForCopywriter(messages),
+                    agentPersona: agent.systemPrompt,
+                });
                 yield {
                     type: 'awaiting_approval',
                     approvalId: err.approvalId,
                     toolName: err.toolName,
                     expiresAt: err.expiresAt,
+                    connectorName: ctx?.connectorName,
+                    toolDescription: ctx?.toolDescription,
+                    copy,
                 };
                 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 for legacy clients that don't render
+                    // `metadata.kind`. Capable widgets read the structured card
+                    // from `metadata.copy`.
+                    content: copy?.body ??
+                        (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,
+                        copy,
                     },
                 });
                 return;
             }
             if ((0, tool_approval_gate_1.isToolBlockedError)(err)) {
+                const ctx = this.describeTool(err.toolName);
+                const copy = await this.copywriter?.generate({
+                    kind: 'blocked',
+                    toolName: err.toolName,
+                    connectorName: ctx?.connectorName,
+                    toolDescription: ctx?.toolDescription,
+                    recentMessages: extractRecentForCopywriter(messages),
+                    agentPersona: agent.systemPrompt,
+                });
                 yield {
                     type: 'tool_blocked',
                     toolName: err.toolName,
                     reason: err.reason,
+                    connectorName: ctx?.connectorName,
+                    toolDescription: ctx?.toolDescription,
+                    copy,
                 };
                 await this.conversations.addMessage({
                     conversationId: params.conversationId,
                     userId: params.userId,
                     role: 'assistant',
-                    content: err.reason ?? `Tool "${err.toolName}" is blocked.`,
+                    content: copy?.blockedBody ??
+                        (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,
+                        copy,
                     },
                 });
                 return;
@@ -383,6 +457,20 @@ class AgentService {
     }
 }
 exports.AgentService = AgentService;
+/**
+ * Pull the last few text-only turns out of the Anthropic message array
+ * for the approval copywriter. We strip tool blocks because they are
+ * not useful for language/tone detection and they can be long. Returns
+ * the most recent 6 turns, each capped to ~600 chars.
+ */
+function extractRecentForCopywriter(messages) {
+    const trimmed = messages
+        .map((m) => ({ role: m.role, content: m.content?.trim?.() ?? '' }))
+        .filter((m) => m.content.length > 0)
+        .slice(-6)
+        .map((m) => ({ role: m.role, content: m.content.slice(0, 600) }));
+    return trimmed;
+}
 /**
  * Map a persisted `AgentRecord` to the runtime `AgentDefinition` the runner
  * expects. The `context` column (plain-text knowledge) is prepended to the

package/dist/services/approval-copywriter.service.d.ts

@@ -0,0 +1,57 @@
+export interface ApprovalCopyBundle {
+    title: string;
+    body: string;
+    approveLabel: string;
+    approveBusyLabel: string;
+    denyLabel: string;
+    denyBusyLabel: string;
+    approvedPill: string;
+    deniedPill: string;
+    readOnlyHint: string;
+    blockedTitle: string;
+    blockedBody: string;
+    /** Formatter hint for "Expires in Xm Ys". The SDK fills the time. */
+    expiresPrefix: string;
+}
+export interface ApprovalCopywriterInput {
+    toolName: string;
+    connectorName?: string;
+    toolDescription?: string;
+    kind: 'approval' | 'blocked';
+    /** Last few turns of the conversation. The model uses these to pick
+     *  language, tone and any references the user already established. */
+    recentMessages?: {
+        role: 'user' | 'assistant';
+        content: string;
+    }[];
+    /** Optional agent persona/instructions excerpt so the copy keeps the
+     *  agent's voice. Trimmed to a few hundred chars by the caller. */
+    agentPersona?: string;
+}
+/**
+ * Generates a natural-language approval copy bundle for the bubble the
+ * chat widget renders when the tool-approval gate pauses a run.
+ *
+ * Why a dedicated service: the SDK used to ship a hardcoded English (then
+ * Spanish) string set. That doesn't scale — different tenants speak
+ * different languages, and the bubble should sound like the rest of the
+ * agent's voice, not a generic system prompt. Delegating copy to the
+ * model that's already shaping the conversation keeps tone, locale and
+ * register coherent without dictionaries to maintain.
+ *
+ * The actual model call is Haiku (cheap + ~200ms) with a tight token cap.
+ * If anything goes wrong — timeout, parse error, missing API key — the
+ * caller gets `undefined` and falls back to a meta-only render. The gate
+ * MUST keep working when the copywriter doesn't.
+ */
+export declare class ApprovalCopywriterService {
+    private readonly client;
+    private readonly cache;
+    constructor(opts: {
+        apiKey?: string;
+        baseURL?: string;
+    });
+    generate(input: ApprovalCopywriterInput): Promise<ApprovalCopyBundle | undefined>;
+    private cacheKey;
+    private callModel;
+}

package/dist/services/approval-copywriter.service.js

@@ -0,0 +1,176 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApprovalCopywriterService = void 0;
+const sdk_1 = __importDefault(require("@anthropic-ai/sdk"));
+const crypto_1 = require("crypto");
+const CACHE_TTL_MS = 5 * 60 * 1000;
+const HAIKU_MODEL = 'claude-haiku-4-5-20251001';
+const HAIKU_MAX_TOKENS = 400;
+const HAIKU_TIMEOUT_MS = 2_500;
+/**
+ * Generates a natural-language approval copy bundle for the bubble the
+ * chat widget renders when the tool-approval gate pauses a run.
+ *
+ * Why a dedicated service: the SDK used to ship a hardcoded English (then
+ * Spanish) string set. That doesn't scale — different tenants speak
+ * different languages, and the bubble should sound like the rest of the
+ * agent's voice, not a generic system prompt. Delegating copy to the
+ * model that's already shaping the conversation keeps tone, locale and
+ * register coherent without dictionaries to maintain.
+ *
+ * The actual model call is Haiku (cheap + ~200ms) with a tight token cap.
+ * If anything goes wrong — timeout, parse error, missing API key — the
+ * caller gets `undefined` and falls back to a meta-only render. The gate
+ * MUST keep working when the copywriter doesn't.
+ */
+class ApprovalCopywriterService {
+    constructor(opts) {
+        this.cache = new Map();
+        if (!opts.apiKey) {
+            this.client = undefined;
+            return;
+        }
+        this.client = new sdk_1.default({
+            apiKey: opts.apiKey,
+            baseURL: opts.baseURL,
+        });
+    }
+    async generate(input) {
+        if (!this.client)
+            return undefined;
+        const key = this.cacheKey(input);
+        const hit = this.cache.get(key);
+        if (hit && hit.expiresAt > Date.now())
+            return hit.value;
+        try {
+            const value = await this.callModel(input);
+            if (!value)
+                return undefined;
+            this.cache.set(key, { value, expiresAt: Date.now() + CACHE_TTL_MS });
+            return value;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    cacheKey(input) {
+        const recent = (input.recentMessages ?? [])
+            .slice(-3)
+            .map((m) => `${m.role[0]}:${m.content.slice(0, 120)}`)
+            .join('|');
+        const raw = [
+            input.kind,
+            input.toolName,
+            input.connectorName ?? '',
+            input.toolDescription ?? '',
+            input.agentPersona?.slice(0, 200) ?? '',
+            recent,
+        ].join('
');
+        return (0, crypto_1.createHash)('sha1').update(raw).digest('hex');
+    }
+    async callModel(input) {
+        const recent = (input.recentMessages ?? [])
+            .slice(-6)
+            .map((m) => `${m.role.toUpperCase()}: ${m.content.slice(0, 600)}`)
+            .join('\n');
+        const targetLabel = input.connectorName ?? input.toolName;
+        const whatItDoes = input.toolDescription
+            ? `It does: ${input.toolDescription}`
+            : '';
+        const personaLine = input.agentPersona
+            ? `Agent persona: ${input.agentPersona.slice(0, 400)}`
+            : '';
+        const guidance = input.kind === 'approval'
+            ? `The agent paused because it wants to use the "${targetLabel}" capability and needs the user's permission. Write a short, warm bubble that matches the language, tone and register of the conversation so far. Mention "${targetLabel}" naturally. Keep it conversational — not corporate or robotic.`
+            : `The agent tried to use the "${targetLabel}" capability but it is blocked on this account. Write a short bubble that tells the user clearly, in the language and tone of the conversation, that this action isn't available. Do not blame them. Do not invite retrying.`;
+        const system = [
+            'You write microcopy for an in-chat permission card. Output STRICT JSON, no prose, no code fences.',
+            'Match the language of the most recent USER message. If the conversation is empty, default to English.',
+            'Keep all strings under ~80 chars unless noted. Buttons under ~20 chars.',
+            'No emojis. No markdown.',
+        ].join(' ');
+        const userPrompt = [
+            guidance,
+            whatItDoes,
+            personaLine,
+            '',
+            'Recent conversation (most recent last):',
+            recent || '(none)',
+            '',
+            'Return JSON with exactly these keys (all strings):',
+            '{',
+            '  "title": "headline of the bubble",',
+            '  "body": "one sentence asking permission or explaining the block",',
+            '  "approveLabel": "primary button when asking permission",',
+            '  "approveBusyLabel": "primary button while confirming",',
+            '  "denyLabel": "secondary button when asking permission",',
+            '  "denyBusyLabel": "secondary button while confirming",',
+            '  "approvedPill": "tiny status pill after the user approved",',
+            '  "deniedPill": "tiny status pill after the user denied",',
+            '  "readOnlyHint": "tiny line shown when the bubble is read-only (e.g. on history)",',
+            '  "blockedTitle": "headline when the action is blocked",',
+            '  "blockedBody": "one sentence explaining the block",',
+            '  "expiresPrefix": "short prefix shown before the countdown, e.g. \\"Expires in\\""',
+            '}',
+        ].join('\n');
+        const ac = new AbortController();
+        const timer = setTimeout(() => ac.abort(), HAIKU_TIMEOUT_MS);
+        try {
+            const res = await this.client.messages.create({
+                model: HAIKU_MODEL,
+                max_tokens: HAIKU_MAX_TOKENS,
+                temperature: 0.4,
+                system,
+                messages: [{ role: 'user', content: userPrompt }],
+            }, { signal: ac.signal });
+            const text = res.content
+                .filter((b) => b.type === 'text')
+                .map((b) => b.text)
+                .join('')
+                .trim();
+            return parseBundle(text);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+exports.ApprovalCopywriterService = ApprovalCopywriterService;
+function parseBundle(text) {
+    const jsonStart = text.indexOf('{');
+    const jsonEnd = text.lastIndexOf('}');
+    if (jsonStart < 0 || jsonEnd <= jsonStart)
+        return undefined;
+    let obj;
+    try {
+        obj = JSON.parse(text.slice(jsonStart, jsonEnd + 1));
+    }
+    catch {
+        return undefined;
+    }
+    const keys = [
+        'title',
+        'body',
+        'approveLabel',
+        'approveBusyLabel',
+        'denyLabel',
+        'denyBusyLabel',
+        'approvedPill',
+        'deniedPill',
+        'readOnlyHint',
+        'blockedTitle',
+        'blockedBody',
+        'expiresPrefix',
+    ];
+    const out = {};
+    for (const k of keys) {
+        const v = obj[k];
+        if (typeof v !== 'string' || !v.trim())
+            return undefined;
+        out[k] = v.trim();
+    }
+    return out;
+}

package/dist/services/index.d.ts

@@ -5,6 +5,7 @@ export { PreparedStreamService, PreparedStreamError, } from './prepared-stream.s
 export { InMemoryPreparedStreamStore } from './in-memory-prepared-stream.store';
 export { ConversationService, ConversationNotFoundError, } from './conversation.service';
 export { AgentService, AgentForbiddenError, type AgentNotFoundError, } from './agent.service';
+export { ApprovalCopywriterService, type ApprovalCopyBundle as ApprovalCopywriterBundle, type ApprovalCopywriterInput, } from './approval-copywriter.service';
 export { OrchestratorService, OrchestratorError, type OrchestratorServiceOptions, } from './orchestrator.service';
 export { AgentJobWorker } from './agent-job.worker';
 export { ChatTokenService, ChatTokenError, type CreateChatTokenInput, } from './chat-token.service';

package/dist/services/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.InMemoryAuthorizeStateStore = exports.ConnectorError = exports.ConnectorRegistryService = exports.OAuth2Service = exports.McpServerError = exports.McpServerService = exports.McpClientError = exports.McpClientService = exports.ChatTokenError = exports.ChatTokenService = exports.AgentJobWorker = exports.OrchestratorError = exports.OrchestratorService = exports.AgentForbiddenError = exports.AgentService = exports.ConversationNotFoundError = exports.ConversationService = exports.InMemoryPreparedStreamStore = exports.PreparedStreamError = exports.PreparedStreamService = exports.isToolBlockedError = exports.isToolApprovalRequired = exports.ToolBlockedError = exports.ToolApprovalRequired = exports.AgentRunnerService = exports.ToolRegistryService = void 0;
+exports.InMemoryAuthorizeStateStore = exports.ConnectorError = exports.ConnectorRegistryService = exports.OAuth2Service = exports.McpServerError = exports.McpServerService = exports.McpClientError = exports.McpClientService = exports.ChatTokenError = exports.ChatTokenService = exports.AgentJobWorker = exports.OrchestratorError = exports.OrchestratorService = exports.ApprovalCopywriterService = exports.AgentForbiddenError = exports.AgentService = exports.ConversationNotFoundError = exports.ConversationService = exports.InMemoryPreparedStreamStore = exports.PreparedStreamError = exports.PreparedStreamService = exports.isToolBlockedError = exports.isToolApprovalRequired = exports.ToolBlockedError = exports.ToolApprovalRequired = exports.AgentRunnerService = exports.ToolRegistryService = void 0;
 // Public service surface of @agentforge-io/core. AI runtime only — auth,
 // identity, billing, infra, etc. have all moved to the host server.
 var tool_registry_service_1 = require("./tool-registry.service");
@@ -27,6 +27,8 @@ Object.defineProperty(exports, "ConversationNotFoundError", { enumerable: true,
 var agent_service_1 = require("./agent.service");
 Object.defineProperty(exports, "AgentService", { enumerable: true, get: function () { return agent_service_1.AgentService; } });
 Object.defineProperty(exports, "AgentForbiddenError", { enumerable: true, get: function () { return agent_service_1.AgentForbiddenError; } });
+var approval_copywriter_service_1 = require("./approval-copywriter.service");
+Object.defineProperty(exports, "ApprovalCopywriterService", { enumerable: true, get: function () { return approval_copywriter_service_1.ApprovalCopywriterService; } });
 var orchestrator_service_1 = require("./orchestrator.service");
 Object.defineProperty(exports, "OrchestratorService", { enumerable: true, get: function () { return orchestrator_service_1.OrchestratorService; } });
 Object.defineProperty(exports, "OrchestratorError", { enumerable: true, get: function () { return orchestrator_service_1.OrchestratorError; } });

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

@@ -151,6 +151,20 @@ export interface ToolExecutionContext {
 export type AnthropicMessage = Anthropic.MessageParam;
 export type AnthropicTool = Anthropic.Tool;
 export type AnthropicContentBlock = Anthropic.ContentBlock;
+export interface ApprovalCopyBundle {
+    title: string;
+    body: string;
+    approveLabel: string;
+    approveBusyLabel: string;
+    denyLabel: string;
+    denyBusyLabel: string;
+    approvedPill: string;
+    deniedPill: string;
+    readOnlyHint: string;
+    blockedTitle: string;
+    blockedBody: string;
+    expiresPrefix: string;
+}
 export type StreamChunk = {
     type: 'text_delta';
     delta: string;
@@ -187,13 +201,21 @@ export type StreamChunk = {
     approvalId: string;
     toolName: string;
     expiresAt: string;
+    connectorName?: string;
+    toolDescription?: string;
+    /** AI-generated microcopy for the bubble. Built server-side by
+     *  the approval copywriter (a small Haiku call) so the language,
+     *  tone and register match the conversation. Optional — when
+     *  absent the client falls back to a minimal render derived from
+     *  `connectorName` / `toolName`. */
+    copy?: ApprovalCopyBundle;
 } | {
-    /** 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;
+    copy?: ApprovalCopyBundle;
 } | {
     type: 'done';
     messageId: string;

package/package.json

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