@agentforge-io/core 2.0.17 → 2.0.19

package/dist/domain/connector.d.ts

@@ -28,6 +28,24 @@ export interface ConnectorToolFactory {
     definition: Omit<AgentToolDefinition, 'execute'>;
     build: (ctx: ConnectorToolContext) => AgentToolDefinition['execute'];
 }
+/**
+ * Recommended initial state for a single connector tool when the tenant
+ * has no override yet.
+ *
+ * Same shape as the platform's `ToolPermission` (which is the canonical
+ * type stored on `agent.tools` / `automation.tools` / `skill.tools`
+ * JSONB). We redeclare it here so `@agentforge-io/core` stays free of any
+ * dependency on the host's `platform/` module — connectors are core's
+ * concern, ToolPermission is the host's. The shape must stay in sync;
+ * platform-side `hydrateToolList` accepts either.
+ */
+export type ConnectorToolMode = 'allow' | 'approval' | 'blocked';
+export interface ConnectorToolDefault {
+    /** Tool name as it appears in the connector's `tools[]` factory. */
+    name: string;
+    /** What the runtime should do by default when the LLM invokes this. */
+    mode: ConnectorToolMode;
+}
 /**
  * UI hints for connectors that authenticate via a user-pasted API key
  * instead of the OAuth2 dance (Granola — and any future provider whose
@@ -86,4 +104,17 @@ export interface ConnectorDefinition {
     /** Tools this connector contributes to the agent's toolbelt once a user
      *  has authorized. */
     tools: ConnectorToolFactory[];
+    /**
+     * Connector-author's recommended initial mode for each tool. The
+     * platform uses this as the fallback when the tenant has not saved a
+     * per-tool override yet (no row in `af_connector_tool_defaults`). It
+     * also seeds the `/connectors/:id` admin page on first visit.
+     *
+     * Tools not listed here are assumed `allow`. Tools listed that don't
+     * match any `tools[i].definition.name` are ignored by the resolver.
+     *
+     * Optional. When omitted, every tool defaults to `allow` (matches the
+     * historical whitelist semantics).
+     */
+    defaultToolPermissions?: ConnectorToolDefault[];
 }

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.17",
+  "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",