@agentforge-io/core 2.0.8 → 2.0.10

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

@@ -2,6 +2,7 @@ import type { AgentOverrides, AgentResponse, AnthropicMessage, StreamChunk, Tool
 import type { AgentDefinition, AnthropicConfig } from '../types/config.types';
 import type { ToolRegistryService } from './tool-registry.service';
 import type { Logger } from './tool-registry.service';
+import { type ToolApprovalGate } from './tool-approval-gate';
 /**
  * Framework-free runner for Claude. Handles the agentic loop (tool calls) for
  * sync runs and exposes streaming as an `AsyncGenerator<StreamChunk>` so any
@@ -12,8 +13,23 @@ export declare class AgentRunnerService {
     private readonly toolRegistry;
     private readonly client;
     private readonly logger;
+    /**
+     * Optional pre-dispatch gate. When supplied, every tool call passes
+     * through `check()` before the actual handler runs. The gate may:
+     *   - return `allow` → execution proceeds (identical to no-gate path)
+     *   - return `blocked` → runner throws ToolBlockedError; loop bubbles up
+     *   - return `approval` → runner throws ToolApprovalRequired; the
+     *     consumer is responsible for catching, persisting state, and
+     *     resuming later (typically by re-running the turn after the
+     *     human approves).
+     *
+     * Left undefined by default to keep deployments without an approval
+     * story behaviorally identical to the pre-gate codebase.
+     */
+    private readonly approvalGate;
     constructor(anthropicConfig: AnthropicConfig, toolRegistry: ToolRegistryService, opts?: {
         logger?: Logger;
+        approvalGate?: ToolApprovalGate;
     });
     run(agent: AgentDefinition, messages: AnthropicMessage[], context: ToolExecutionContext, overrides?: AgentOverrides): Promise<AgentResponse>;
     stream(agent: AgentDefinition, messages: AnthropicMessage[], context: ToolExecutionContext, overrides?: AgentOverrides): AsyncGenerator<StreamChunk>;

package/dist/services/agent-runner.service.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.AgentRunnerService = void 0;
 const sdk_1 = __importDefault(require("@anthropic-ai/sdk"));
 const crypto_1 = require("crypto");
+const tool_approval_gate_1 = require("./tool-approval-gate");
 const noopLogger = {
     log: () => { }, warn: () => { }, debug: () => { }, error: () => { },
 };
@@ -23,6 +24,7 @@ class AgentRunnerService {
             baseURL: anthropicConfig.baseURL,
         });
         this.logger = opts.logger ?? noopLogger;
+        this.approvalGate = opts.approvalGate;
     }
     // ─── Run (non-streaming) ──────────────────────────────────────────────────
     async run(agent, messages, context, overrides) {
@@ -68,6 +70,17 @@ class AgentRunnerService {
                             output = await this.dispatchTool(block.name, block.input, context, extras);
                         }
                         catch (err) {
+                            // Approval-gate signals are NOT tool execution errors —
+                            // they ARE the surface the caller of run() branches on.
+                            // Re-throw so the loop aborts and the consumer (executor /
+                            // conversation service) can persist the pause + surface
+                            // the approvalId. Without this re-throw, the runner would
+                            // feed back a `"Error executing tool …"` to the LLM,
+                            // hiding the pause behind a regular tool failure.
+                            if (err instanceof tool_approval_gate_1.ToolApprovalRequired ||
+                                err instanceof tool_approval_gate_1.ToolBlockedError) {
+                                throw err;
+                            }
                             error = err instanceof Error ? err.message : String(err);
                             output = `Error executing tool ${block.name}: ${error}`;
                         }
@@ -165,6 +178,15 @@ class AgentRunnerService {
                             output = await this.dispatchTool(block.name, block.input, context, extras);
                         }
                         catch (err) {
+                            // Same rule as the sync path: gate signals propagate, regular
+                            // errors collapse into a `"Error: …"` tool result the LLM
+                            // can react to. The consumer of `stream()` catches the
+                            // ToolApprovalRequired and decides whether to emit a
+                            // structured chunk to the client or just end the stream.
+                            if (err instanceof tool_approval_gate_1.ToolApprovalRequired ||
+                                err instanceof tool_approval_gate_1.ToolBlockedError) {
+                                throw err;
+                            }
                             output = `Error: ${err instanceof Error ? err.message : String(err)}`;
                         }
                         yield { type: 'tool_result', toolName: block.name, result: output };
@@ -261,6 +283,27 @@ class AgentRunnerService {
         return { tools: tools.length ? tools : undefined, extras };
     }
     async dispatchTool(name, input, context, extras) {
+        // Consult the approval gate before any tool work happens. The throws
+        // here are caught and re-raised verbatim by `run()` / `stream()` —
+        // they ARE the surface the consumer branches on, not generic errors.
+        if (this.approvalGate) {
+            const decision = await this.approvalGate.check({
+                toolName: name,
+                toolInput: input,
+                context,
+            });
+            if (decision.kind === 'blocked') {
+                throw new tool_approval_gate_1.ToolBlockedError(name, decision.reason);
+            }
+            if (decision.kind === 'approval') {
+                throw new tool_approval_gate_1.ToolApprovalRequired({
+                    approvalId: decision.approvalId,
+                    toolName: name,
+                    expiresAt: decision.expiresAt,
+                });
+            }
+            // `allow` falls through to the normal dispatch path.
+        }
         const extra = extras.get(name);
         if (extra)
             return extra.execute(input, context);

package/dist/services/index.d.ts

@@ -1,5 +1,6 @@
 export { ToolRegistryService, type Logger, type ToolDescription, } from './tool-registry.service';
 export { AgentRunnerService } from './agent-runner.service';
+export { ToolApprovalRequired, ToolBlockedError, isToolApprovalRequired, isToolBlockedError, type ToolApprovalGate, type ToolApprovalCheckArgs, type ToolApprovalDecision, } from './tool-approval-gate';
 export { PreparedStreamService, PreparedStreamError, } from './prepared-stream.service';
 export { InMemoryPreparedStreamStore } from './in-memory-prepared-stream.store';
 export { ConversationService, ConversationNotFoundError, } from './conversation.service';

package/dist/services/index.js

@@ -1,12 +1,21 @@
 "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.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.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");
 Object.defineProperty(exports, "ToolRegistryService", { enumerable: true, get: function () { return tool_registry_service_1.ToolRegistryService; } });
 var agent_runner_service_1 = require("./agent-runner.service");
 Object.defineProperty(exports, "AgentRunnerService", { enumerable: true, get: function () { return agent_runner_service_1.AgentRunnerService; } });
+// Approval gate primitives. Optional dependency of the runner — hosts
+// that don't need human-in-the-loop tool calls leave it unwired and
+// nothing changes. See @agentforge-io/server's ApprovalGateAdapter for
+// a reference impl.
+var tool_approval_gate_1 = require("./tool-approval-gate");
+Object.defineProperty(exports, "ToolApprovalRequired", { enumerable: true, get: function () { return tool_approval_gate_1.ToolApprovalRequired; } });
+Object.defineProperty(exports, "ToolBlockedError", { enumerable: true, get: function () { return tool_approval_gate_1.ToolBlockedError; } });
+Object.defineProperty(exports, "isToolApprovalRequired", { enumerable: true, get: function () { return tool_approval_gate_1.isToolApprovalRequired; } });
+Object.defineProperty(exports, "isToolBlockedError", { enumerable: true, get: function () { return tool_approval_gate_1.isToolBlockedError; } });
 var prepared_stream_service_1 = require("./prepared-stream.service");
 Object.defineProperty(exports, "PreparedStreamService", { enumerable: true, get: function () { return prepared_stream_service_1.PreparedStreamService; } });
 Object.defineProperty(exports, "PreparedStreamError", { enumerable: true, get: function () { return prepared_stream_service_1.PreparedStreamError; } });

package/dist/services/tool-approval-gate.d.ts

@@ -0,0 +1,97 @@
+import type { ToolExecutionContext } from '../types/agent.types';
+/**
+ * Optional pre-dispatch gate consulted by `AgentRunnerService` before
+ * every tool call. The runner is intentionally agnostic about WHERE the
+ * decision comes from — the host (e.g. AgentForge platform) supplies a
+ * concrete implementation backed by its own DB / config.
+ *
+ * Three possible decisions:
+ *
+ *   - `allow`    → runner proceeds to invoke the tool. Identical to the
+ *                  pre-gate behavior, so a deployment without a gate
+ *                  installed is a no-op.
+ *   - `blocked`  → runner throws `ToolBlockedError`. In a healthy
+ *                  deployment a blocked tool isn't even injected into
+ *                  the LLM's tool list, so this branch is defense-in-
+ *                  depth against a stale agent definition the model
+ *                  somehow still references.
+ *   - `approval` → runner throws `ToolApprovalRequired`. The caller of
+ *                  `run()` / `stream()` is expected to catch this,
+ *                  persist whatever it needs to resume later, and
+ *                  surface the approval id to the end consumer.
+ *
+ * The async signature is deliberate — every realistic adapter will need
+ * at least one DB read (look up the tool's mode on the agent) and often
+ * one write (open the approval row).
+ */
+export interface ToolApprovalGate {
+    check(args: ToolApprovalCheckArgs): Promise<ToolApprovalDecision>;
+}
+export interface ToolApprovalCheckArgs {
+    /** The tool name as the LLM emitted it (post-prefix for connector +
+     *  MCP tools — same string the runner uses to look the tool up in
+     *  the registry). */
+    toolName: string;
+    /** Tool arguments the LLM produced. The gate may persist these on a
+     *  pending approval row so a human can inspect; the runner never
+     *  mutates them after the gate returns. */
+    toolInput: Record<string, unknown>;
+    /** Same context object passed to the tool's `execute`. Carries the
+     *  agent / conversation / user identities the adapter needs to scope
+     *  its lookups. */
+    context: ToolExecutionContext;
+}
+export type ToolApprovalDecision = {
+    kind: 'allow';
+} | {
+    kind: 'blocked';
+    reason?: string;
+} | {
+    kind: 'approval';
+    /** Opaque id of the approval row the gate just created. The
+     *  consumer surfaces this to the operator so they can find the
+     *  row in the approvals queue. */
+    approvalId: string;
+    /** ISO timestamp at which the approval will auto-expire. Useful
+     *  for the consumer to set a comparable timeout on its own
+     *  side (e.g. expire a paused conversation). */
+    expiresAt: string;
+};
+/**
+ * Thrown by the runner when the gate returns `approval`. The caller is
+ * expected to catch this exact class (not a plain `Error`) and translate
+ * it to its surface: an automation run row flips to `awaiting_approval`,
+ * a conversation appends a synthetic message, a public chat stream
+ * emits a structured chunk, etc.
+ *
+ * Carries the approval id + expiry so the surface can echo them back to
+ * the consumer without an extra DB read.
+ */
+export declare class ToolApprovalRequired extends Error {
+    readonly approvalId: string;
+    readonly toolName: string;
+    readonly expiresAt: string;
+    constructor(args: {
+        approvalId: string;
+        toolName: string;
+        expiresAt: string;
+    });
+}
+/**
+ * Thrown by the runner when the gate returns `blocked`. Different class
+ * than `ToolApprovalRequired` so callers can branch — `awaiting_approval`
+ * is a pause, `blocked` is a hard refusal.
+ */
+export declare class ToolBlockedError extends Error {
+    readonly toolName: string;
+    readonly reason?: string;
+    constructor(toolName: string, reason?: string);
+}
+/**
+ * Cheap helpers for catch-blocks that want to know whether a thrown
+ * error escaped from the gate path. Using these avoids `instanceof`
+ * realm pitfalls when the lib's compiled code is imported by both the
+ * platform's source tree and a vendored copy in tests.
+ */
+export declare function isToolApprovalRequired(err: unknown): err is ToolApprovalRequired;
+export declare function isToolBlockedError(err: unknown): err is ToolBlockedError;

package/dist/services/tool-approval-gate.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToolBlockedError = exports.ToolApprovalRequired = void 0;
+exports.isToolApprovalRequired = isToolApprovalRequired;
+exports.isToolBlockedError = isToolBlockedError;
+/**
+ * Thrown by the runner when the gate returns `approval`. The caller is
+ * expected to catch this exact class (not a plain `Error`) and translate
+ * it to its surface: an automation run row flips to `awaiting_approval`,
+ * a conversation appends a synthetic message, a public chat stream
+ * emits a structured chunk, etc.
+ *
+ * Carries the approval id + expiry so the surface can echo them back to
+ * the consumer without an extra DB read.
+ */
+class ToolApprovalRequired extends Error {
+    constructor(args) {
+        super(`Tool "${args.toolName}" requires approval (id ${args.approvalId}); ` +
+            `decision needed before ${args.expiresAt}`);
+        this.name = 'ToolApprovalRequired';
+        this.approvalId = args.approvalId;
+        this.toolName = args.toolName;
+        this.expiresAt = args.expiresAt;
+    }
+}
+exports.ToolApprovalRequired = ToolApprovalRequired;
+/**
+ * Thrown by the runner when the gate returns `blocked`. Different class
+ * than `ToolApprovalRequired` so callers can branch — `awaiting_approval`
+ * is a pause, `blocked` is a hard refusal.
+ */
+class ToolBlockedError extends Error {
+    constructor(toolName, reason) {
+        super(reason ?? `Tool "${toolName}" is blocked for this agent`);
+        this.name = 'ToolBlockedError';
+        this.toolName = toolName;
+        this.reason = reason;
+    }
+}
+exports.ToolBlockedError = ToolBlockedError;
+/**
+ * Cheap helpers for catch-blocks that want to know whether a thrown
+ * error escaped from the gate path. Using these avoids `instanceof`
+ * realm pitfalls when the lib's compiled code is imported by both the
+ * platform's source tree and a vendored copy in tests.
+ */
+function isToolApprovalRequired(err) {
+    return (err instanceof ToolApprovalRequired ||
+        (typeof err === 'object' &&
+            err !== null &&
+            err.name === 'ToolApprovalRequired'));
+}
+function isToolBlockedError(err) {
+    return (err instanceof ToolBlockedError ||
+        (typeof err === 'object' &&
+            err !== null &&
+            err.name === 'ToolBlockedError'));
+}

package/package.json

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