@amodalai/runtime 0.1.26 → 0.2.0

package/dist/src/tools/custom-tool-adapter.test.js

@@ -0,0 +1,244 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { createCustomToolDefinition } from './custom-tool-adapter.js';
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+function makeTool(overrides) {
+    return {
+        name: 'test_tool',
+        description: 'A test tool',
+        parameters: {
+            type: 'object',
+            properties: {
+                query: { type: 'string', description: 'Search query' },
+                limit: { type: 'number', description: 'Max results' },
+            },
+            required: ['query'],
+        },
+        confirm: true,
+        timeout: 30_000,
+        env: ['TEST_KEY'],
+        handlerPath: '/fake/handler.ts',
+        location: '/fake',
+        hasPackageJson: false,
+        hasSetupScript: false,
+        hasRequirementsTxt: false,
+        hasDockerfile: false,
+        sandboxLanguage: 'node',
+        ...overrides,
+    };
+}
+function makeExecutor(result = { ok: true }) {
+    return {
+        execute: vi.fn().mockResolvedValue(result),
+    };
+}
+function makeSessionCtx(overrides) {
+    return {
+        config: {
+            getConnections: () => ({
+                typefully: {
+                    base_url: 'https://api.typefully.com',
+                    _request_config: {
+                        auth: [{ header: 'Authorization', value_template: 'Bearer tok-123' }],
+                        default_headers: { 'X-Custom': 'yes' },
+                    },
+                },
+            }),
+            getStores: () => [{
+                    name: 'alerts',
+                    entity: { key: '{alert_id}', schema: { alert_id: { type: 'string' } } },
+                }],
+        },
+        storeBackend: {
+            put: vi.fn().mockResolvedValue(undefined),
+        },
+        appId: 'test-app',
+        ...overrides,
+    };
+}
+function makeToolContext(overrides) {
+    return {
+        request: vi.fn(),
+        store: vi.fn(),
+        env: vi.fn(),
+        log: vi.fn(),
+        user: { roles: ['admin'] },
+        signal: AbortSignal.timeout(30_000),
+        sessionId: 'sess-1',
+        tenantId: 'tenant-1',
+        ...overrides,
+    };
+}
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+describe('createCustomToolDefinition', () => {
+    describe('schema', () => {
+        it('passes JSON Schema through to ToolDefinition parameters', () => {
+            const tool = makeTool();
+            const def = createCustomToolDefinition(tool, makeExecutor(), makeSessionCtx());
+            expect(def.description).toBe('A test tool');
+            // The jsonSchema() wrapper preserves the original schema
+            expect(def.parameters).toBeDefined();
+        });
+        it('sets readOnly: true when confirm is false', () => {
+            const def = createCustomToolDefinition(makeTool({ confirm: false }), makeExecutor(), makeSessionCtx());
+            expect(def.readOnly).toBe(true);
+        });
+        it('sets readOnly: false when confirm is true', () => {
+            const def = createCustomToolDefinition(makeTool({ confirm: true }), makeExecutor(), makeSessionCtx());
+            expect(def.readOnly).toBe(false);
+        });
+        it('sets metadata.category to custom', () => {
+            const def = createCustomToolDefinition(makeTool(), makeExecutor(), makeSessionCtx());
+            expect(def.metadata?.category).toBe('custom');
+        });
+    });
+    describe('execute', () => {
+        it('calls executor with tool, params, and context', async () => {
+            const executor = makeExecutor({ result: 42 });
+            const def = createCustomToolDefinition(makeTool(), executor, makeSessionCtx());
+            const ctx = makeToolContext();
+            const result = await def.execute({ query: 'test' }, ctx);
+            expect(executor.execute).toHaveBeenCalledOnce();
+            expect(result).toEqual({ result: 42 });
+        });
+        it('wraps executor errors in ToolExecutionError', async () => {
+            const executor = {
+                execute: vi.fn().mockRejectedValue(new Error('handler crashed')),
+            };
+            const def = createCustomToolDefinition(makeTool(), executor, makeSessionCtx());
+            await expect(def.execute({ query: 'test' }, makeToolContext()))
+                .rejects.toThrow('Tool "test_tool" failed: handler crashed');
+        });
+        it('wraps AbortError as abort-specific message', async () => {
+            const abortErr = new Error('aborted');
+            abortErr.name = 'AbortError';
+            const executor = {
+                execute: vi.fn().mockRejectedValue(abortErr),
+            };
+            const def = createCustomToolDefinition(makeTool(), executor, makeSessionCtx());
+            await expect(def.execute({ query: 'test' }, makeToolContext()))
+                .rejects.toThrow('Tool "test_tool" was aborted');
+        });
+    });
+    describe('ctx.request()', () => {
+        let fetchSpy;
+        beforeEach(() => {
+            fetchSpy = vi.fn().mockResolvedValue({
+                ok: true,
+                status: 200,
+                text: () => Promise.resolve('{"data": "ok"}'),
+            });
+            vi.stubGlobal('fetch', fetchSpy);
+        });
+        it('applies auth headers from connection config', async () => {
+            const executor = {
+                execute: vi.fn().mockImplementation(async (_tool, _params, ctx) => {
+                    const result = await ctx.request('typefully', '/social-sets');
+                    return result;
+                }),
+            };
+            const def = createCustomToolDefinition(makeTool(), executor, makeSessionCtx());
+            await def.execute({}, makeToolContext());
+            expect(fetchSpy).toHaveBeenCalledOnce();
+            const [url, opts] = fetchSpy.mock.calls[0];
+            expect(url).toBe('https://api.typefully.com/social-sets');
+            expect(opts.headers['Authorization']).toBe('Bearer tok-123');
+            expect(opts.headers['X-Custom']).toBe('yes');
+        });
+        it('throws on unknown connection', async () => {
+            const executor = {
+                execute: vi.fn().mockImplementation(async (_tool, _params, ctx) => {
+                    await ctx.request('nonexistent', '/foo');
+                }),
+            };
+            const def = createCustomToolDefinition(makeTool(), executor, makeSessionCtx());
+            await expect(def.execute({}, makeToolContext()))
+                .rejects.toThrow('Connection "nonexistent" not found');
+        });
+        it('rejects non-GET when confirm is false', async () => {
+            const executor = {
+                execute: vi.fn().mockImplementation(async (_tool, _params, ctx) => {
+                    await ctx
+                        .request('typefully', '/post', { method: 'POST' });
+                }),
+            };
+            const def = createCustomToolDefinition(makeTool({ confirm: false }), executor, makeSessionCtx());
+            await expect(def.execute({}, makeToolContext()))
+                .rejects.toThrow('only GET requests are allowed');
+        });
+        it('throws on non-2xx responses', async () => {
+            fetchSpy.mockResolvedValue({
+                ok: false,
+                status: 401,
+                text: () => Promise.resolve('Unauthorized'),
+            });
+            const executor = {
+                execute: vi.fn().mockImplementation(async (_tool, _params, ctx) => {
+                    await ctx.request('typefully', '/social-sets');
+                }),
+            };
+            const def = createCustomToolDefinition(makeTool(), executor, makeSessionCtx());
+            await expect(def.execute({}, makeToolContext()))
+                .rejects.toThrow('returned 401');
+        });
+    });
+    describe('ctx.store()', () => {
+        it('writes to store backend with resolved key', async () => {
+            const sessionCtx = makeSessionCtx();
+            const executor = {
+                execute: vi.fn().mockImplementation(async (_tool, _params, ctx) => ctx
+                    .store('alerts', { alert_id: 'a-1', severity: 'high' })),
+            };
+            const def = createCustomToolDefinition(makeTool(), executor, sessionCtx);
+            const result = await def.execute({}, makeToolContext());
+            expect(sessionCtx.storeBackend?.put).toHaveBeenCalledWith('test-app', 'alerts', 'a-1', { alert_id: 'a-1', severity: 'high' }, {});
+            expect(result).toEqual({ key: 'a-1' });
+        });
+        it('throws when store backend is not available', async () => {
+            const executor = {
+                execute: vi.fn().mockImplementation(async (_tool, _params, ctx) => ctx
+                    .store('alerts', { alert_id: 'a-1' })),
+            };
+            const def = createCustomToolDefinition(makeTool(), executor, makeSessionCtx({ storeBackend: undefined }));
+            await expect(def.execute({}, makeToolContext()))
+                .rejects.toThrow('Store backend not available');
+        });
+    });
+    describe('ctx.env()', () => {
+        it('returns env var when in allowlist', async () => {
+            vi.stubEnv('TEST_KEY', 'secret-value');
+            let envResult;
+            const executor = {
+                execute: vi.fn().mockImplementation(async (_tool, _params, ctx) => {
+                    envResult = ctx.env('TEST_KEY');
+                    return { ok: true };
+                }),
+            };
+            const def = createCustomToolDefinition(makeTool(), executor, makeSessionCtx());
+            await def.execute({}, makeToolContext());
+            expect(envResult).toBe('secret-value');
+            vi.unstubAllEnvs();
+        });
+        it('returns undefined for non-allowlisted env var', async () => {
+            let envResult = 'should-be-overwritten';
+            const executor = {
+                execute: vi.fn().mockImplementation(async (_tool, _params, ctx) => {
+                    envResult = ctx.env('HOME');
+                    return { ok: true };
+                }),
+            };
+            const def = createCustomToolDefinition(makeTool(), executor, makeSessionCtx());
+            await def.execute({}, makeToolContext());
+            expect(envResult).toBeUndefined();
+        });
+    });
+});
+//# sourceMappingURL=custom-tool-adapter.test.js.map

package/dist/src/tools/custom-tool-adapter.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom-tool-adapter.test.js","sourceRoot":"","sources":["../../../src/tools/custom-tool-adapter.test.ts"],"names":[],"mappings":"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"}

package/dist/src/tools/dispatch-tool.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * Dispatch tool.
+ *
+ * Allows the model to delegate a sub-task to a child agent with a
+ * subset of tools. The EXECUTING state handler intercepts this tool
+ * by name and transitions to DISPATCHING — the execute() function
+ * here is a safety net that should never be reached.
+ *
+ * Circular dependency avoidance: this file does NOT import from
+ * the agent loop. The dispatch tool is just a schema definition.
+ * The actual child agent execution lives in states/dispatching.ts.
+ */
+import { z } from 'zod';
+import type { ToolDefinition } from './types.js';
+export declare const DISPATCH_TOOL_NAME = "dispatch_task";
+declare const DEFAULT_CHILD_MAX_TURNS = 10;
+declare const DispatchParamsSchema: z.ZodObject<{
+    /** Name for the child agent (used in SSE events and logging) */
+    agent_name: z.ZodString;
+    /** Which tools the child agent can use (must be a subset of available tools) */
+    tools: z.ZodArray<z.ZodString, "many">;
+    /** The task prompt for the child agent */
+    prompt: z.ZodString;
+    /** Max turns for the child agent (default: 10) */
+    max_turns: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    agent_name: string;
+    tools: string[];
+    prompt: string;
+    max_turns?: number | undefined;
+}, {
+    agent_name: string;
+    tools: string[];
+    prompt: string;
+    max_turns?: number | undefined;
+}>;
+export type DispatchParams = z.infer<typeof DispatchParamsSchema>;
+/**
+ * Create the dispatch_task tool definition.
+ *
+ * The tool is intercepted by the EXECUTING state handler before execute()
+ * is called. The EXECUTING handler reads the args, strips dispatch_task
+ * from the child's tool list (preventing recursion), and transitions to
+ * DISPATCHING state.
+ */
+export declare function createDispatchTool(): ToolDefinition;
+export { DEFAULT_CHILD_MAX_TURNS };

package/dist/src/tools/dispatch-tool.js

@@ -0,0 +1,71 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * Dispatch tool.
+ *
+ * Allows the model to delegate a sub-task to a child agent with a
+ * subset of tools. The EXECUTING state handler intercepts this tool
+ * by name and transitions to DISPATCHING — the execute() function
+ * here is a safety net that should never be reached.
+ *
+ * Circular dependency avoidance: this file does NOT import from
+ * the agent loop. The dispatch tool is just a schema definition.
+ * The actual child agent execution lives in states/dispatching.ts.
+ */
+import { z } from 'zod';
+import { ToolExecutionError } from '../errors.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+export const DISPATCH_TOOL_NAME = 'dispatch_task';
+const DEFAULT_CHILD_MAX_TURNS = 10;
+// ---------------------------------------------------------------------------
+// Schema
+// ---------------------------------------------------------------------------
+const DispatchParamsSchema = z.object({
+    /** Name for the child agent (used in SSE events and logging) */
+    agent_name: z.string().describe('A short descriptive name for the sub-agent (e.g. "data-fetcher", "entity-profiler")'),
+    /** Which tools the child agent can use (must be a subset of available tools) */
+    tools: z.array(z.string()).describe('List of tool names the child agent can use'),
+    /** The task prompt for the child agent */
+    prompt: z.string().describe('The task description for the child agent to complete'),
+    /** Max turns for the child agent (default: 10) */
+    max_turns: z.number().int().positive().optional().describe('Maximum number of LLM turns the child agent can take'),
+});
+// ---------------------------------------------------------------------------
+// Tool definition
+// ---------------------------------------------------------------------------
+/**
+ * Create the dispatch_task tool definition.
+ *
+ * The tool is intercepted by the EXECUTING state handler before execute()
+ * is called. The EXECUTING handler reads the args, strips dispatch_task
+ * from the child's tool list (preventing recursion), and transitions to
+ * DISPATCHING state.
+ */
+export function createDispatchTool() {
+    return {
+        description: `Delegate a sub-task to a child agent that runs independently with its own tool set. Use this when a task can be broken into parallel or sequential sub-tasks, each requiring specific tools. The child agent completes its task and returns a text summary.
+
+The child agent has access only to the tools you specify — choose the minimum set needed. The child cannot dispatch further sub-agents.
+
+Use dispatch_task when:
+- A task involves multiple independent data-gathering steps
+- You need to query different connections in parallel
+- A sub-task is self-contained and doesn't need conversation context`,
+        parameters: DispatchParamsSchema,
+        readOnly: false,
+        metadata: { category: 'system' },
+        async execute() {
+            // The EXECUTING state handler intercepts dispatch_task by name and
+            // transitions to DISPATCHING. If execute() is called directly, the
+            // interception was bypassed — this is a bug.
+            throw new ToolExecutionError('dispatch_task must be intercepted by the EXECUTING state handler — direct execution is not supported', { toolName: DISPATCH_TOOL_NAME, callId: 'unknown', context: {} });
+        },
+    };
+}
+export { DEFAULT_CHILD_MAX_TURNS };
+//# sourceMappingURL=dispatch-tool.js.map

package/dist/src/tools/dispatch-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch-tool.js","sourceRoot":"","sources":["../../../src/tools/dispatch-tool.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;GAWG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,OAAO,EAAC,kBAAkB,EAAC,MAAM,cAAc,CAAC;AAEhD,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E,MAAM,CAAC,MAAM,kBAAkB,GAAG,eAAe,CAAC;AAElD,MAAM,uBAAuB,GAAG,EAAE,CAAC;AAEnC,8EAA8E;AAC9E,SAAS;AACT,8EAA8E;AAE9E,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IACpC,gEAAgE;IAChE,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,qFAAqF,CAAC;IACtH,gFAAgF;IAChF,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC,4CAA4C,CAAC;IACjF,0CAA0C;IAC1C,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,sDAAsD,CAAC;IACnF,kDAAkD;IAClD,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,sDAAsD,CAAC;CACnH,CAAC,CAAC;AAIH,8EAA8E;AAC9E,kBAAkB;AAClB,8EAA8E;AAE9E;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB;IAChC,OAAO;QACL,WAAW,EAAE;;;;;;;qEAOoD;QAEjE,UAAU,EAAE,oBAAoB;QAEhC,QAAQ,EAAE,KAAK;QACf,QAAQ,EAAE,EAAC,QAAQ,EAAE,QAAQ,EAAC;QAE9B,KAAK,CAAC,OAAO;YACX,mEAAmE;YACnE,mEAAmE;YACnE,6CAA6C;YAC7C,MAAM,IAAI,kBAAkB,CAC1B,sGAAsG,EACtG,EAAC,QAAQ,EAAE,kBAAkB,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,EAAE,EAAC,CAC/D,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC;AAED,OAAO,EAAC,uBAAuB,EAAC,CAAC"}

package/dist/src/tools/dispatch-tool.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+export {};

package/dist/src/tools/dispatch-tool.test.js

@@ -0,0 +1,75 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+import { describe, it, expect } from 'vitest';
+import { createDispatchTool, DISPATCH_TOOL_NAME, DEFAULT_CHILD_MAX_TURNS } from './dispatch-tool.js';
+import { ToolExecutionError } from '../errors.js';
+describe('dispatch-tool', () => {
+    it('has the correct tool name constant', () => {
+        expect(DISPATCH_TOOL_NAME).toBe('dispatch_task');
+    });
+    it('has a sensible default child max turns', () => {
+        expect(DEFAULT_CHILD_MAX_TURNS).toBe(10);
+    });
+    it('creates a tool definition with Zod schema', () => {
+        const tool = createDispatchTool();
+        expect(tool.description).toContain('child agent');
+        expect(tool.readOnly).toBe(false);
+        expect(tool.metadata?.category).toBe('system');
+        // Zod schema should have safeParse
+        expect('safeParse' in tool.parameters).toBe(true);
+    });
+    it('validates correct parameters', () => {
+        const tool = createDispatchTool();
+        const schema = tool.parameters;
+        if ('safeParse' in schema) {
+            const result = schema.safeParse({
+                agent_name: 'data-fetcher',
+                tools: ['request', 'query_store'],
+                prompt: 'Fetch the latest metrics',
+            });
+            expect(result.success).toBe(true);
+        }
+    });
+    it('validates parameters with optional max_turns', () => {
+        const tool = createDispatchTool();
+        const schema = tool.parameters;
+        if ('safeParse' in schema) {
+            const result = schema.safeParse({
+                agent_name: 'profiler',
+                tools: ['request'],
+                prompt: 'Profile the entity',
+                max_turns: 5,
+            });
+            expect(result.success).toBe(true);
+        }
+    });
+    it('rejects missing required fields', () => {
+        const tool = createDispatchTool();
+        const schema = tool.parameters;
+        if ('safeParse' in schema) {
+            const result = schema.safeParse({ agent_name: 'test' });
+            expect(result.success).toBe(false);
+        }
+    });
+    it('rejects invalid max_turns', () => {
+        const tool = createDispatchTool();
+        const schema = tool.parameters;
+        if ('safeParse' in schema) {
+            const result = schema.safeParse({
+                agent_name: 'test',
+                tools: [],
+                prompt: 'do thing',
+                max_turns: -1,
+            });
+            expect(result.success).toBe(false);
+        }
+    });
+    it('execute throws ToolExecutionError (should never be called directly)', async () => {
+        const tool = createDispatchTool();
+        await expect(tool.execute({}, {})).rejects.toThrow(ToolExecutionError);
+    });
+});
+//# sourceMappingURL=dispatch-tool.test.js.map

package/dist/src/tools/dispatch-tool.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch-tool.test.js","sourceRoot":"","sources":["../../../src/tools/dispatch-tool.test.ts"],"names":[],"mappings":"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"}

package/dist/src/tools/mcp-tool-adapter.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+import type { McpManager, McpDiscoveredTool } from '@amodalai/core';
+import type { ToolDefinition, ToolRegistry } from './types.js';
+import type { Logger } from '@amodalai/core';
+/**
+ * Convert a single MCP discovered tool to a ToolDefinition.
+ */
+export declare function createMcpToolDefinition(tool: McpDiscoveredTool, mcpManager: McpManager, logger: Logger): ToolDefinition;
+/**
+ * Register all discovered MCP tools on a ToolRegistry.
+ *
+ * Call this after MCP servers have connected and discovered their tools.
+ */
+export declare function registerMcpTools(registry: ToolRegistry, mcpManager: McpManager, logger: Logger): number;

package/dist/src/tools/mcp-tool-adapter.js

@@ -0,0 +1,135 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * MCP tool adapter.
+ *
+ * Converts MCP discovered tools into ToolDefinition objects that can be
+ * registered on our ToolRegistry. Each tool's execute function delegates
+ * to the McpManager.callTool() method.
+ *
+ * MCP tools already have JSON Schema parameter definitions from the server.
+ * We pass these through to the AI SDK via jsonSchema() — no Zod conversion
+ * needed. The AI SDK sends the schema to the LLM as-is, preserving all
+ * parameter descriptions, types, and constraints the server defined.
+ */
+import { jsonSchema } from 'ai';
+import { ConnectionError } from '../errors.js';
+/** Default timeout for MCP tool calls (60 seconds). */
+const MCP_TOOL_TIMEOUT_MS = 60_000;
+// ---------------------------------------------------------------------------
+// MCP tool → ToolDefinition
+// ---------------------------------------------------------------------------
+/**
+ * Convert a single MCP discovered tool to a ToolDefinition.
+ */
+export function createMcpToolDefinition(tool, mcpManager, logger) {
+    // Pass the MCP server's JSON Schema directly to the AI SDK.
+    // No Zod conversion — the schema goes to the LLM as-is, preserving
+    // all parameter descriptions, types, and constraints.
+    const parametersSchema = jsonSchema(tool.parameters);
+    return {
+        description: tool.description,
+        parameters: parametersSchema,
+        readOnly: false, // MCP tools may have side effects — default conservative
+        metadata: {
+            category: 'mcp',
+            connection: tool.serverName,
+            originalName: tool.originalName,
+        },
+        async execute(params, ctx) {
+            logger.debug('mcp_tool_call_start', {
+                session: ctx.sessionId,
+                tool: tool.name,
+                server: tool.serverName,
+            });
+            const startTime = Date.now();
+            try {
+                // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- params validated by Zod before execute; MCP tools always have object schemas
+                const callPromise = mcpManager.callTool(tool.name, (params ?? {}));
+                // Race against timeout — McpManager.callTool doesn't accept AbortSignal
+                const timeoutSignal = ctx.signal ?? AbortSignal.timeout(MCP_TOOL_TIMEOUT_MS);
+                const result = await Promise.race([
+                    callPromise,
+                    new Promise((_resolve, reject) => {
+                        if (timeoutSignal.aborted) {
+                            reject(new ConnectionError(`MCP tool call "${tool.name}" timed out`, { connection: tool.serverName, action: `callTool(${tool.originalName})` }));
+                            return;
+                        }
+                        timeoutSignal.addEventListener('abort', () => {
+                            reject(new ConnectionError(`MCP tool call "${tool.name}" timed out`, { connection: tool.serverName, action: `callTool(${tool.originalName})` }));
+                        }, { once: true });
+                    }),
+                ]);
+                const durationMs = Date.now() - startTime;
+                logger.info('mcp_tool_call_complete', {
+                    session: ctx.sessionId,
+                    tool: tool.name,
+                    server: tool.serverName,
+                    durationMs,
+                    isError: result.isError ?? false,
+                });
+                if (result.isError) {
+                    const errorText = result.content
+                        .filter((c) => c.type === 'text' && c.text)
+                        .map((c) => c.text)
+                        .join('\n');
+                    return { error: errorText || 'MCP tool returned an error' };
+                }
+                // Format the response content
+                const output = result.content
+                    .map((c) => {
+                    if (c.type === 'text' && c.text)
+                        return c.text;
+                    if (c.type === 'image' && c.data)
+                        return `[image: ${c.mimeType ?? 'unknown'}]`;
+                    return `[${c.type}]`;
+                })
+                    .join('\n');
+                return { output };
+            }
+            catch (err) {
+                const durationMs = Date.now() - startTime;
+                const message = err instanceof Error ? err.message : String(err);
+                logger.error('mcp_tool_call_failed', {
+                    session: ctx.sessionId,
+                    tool: tool.name,
+                    server: tool.serverName,
+                    durationMs,
+                    error: message,
+                });
+                // Classify the error for a helpful message
+                if (message.includes('ECONNREFUSED') || message.includes('ENOTFOUND') || message.includes('unreachable')) {
+                    throw new ConnectionError(`MCP server for "${tool.name}" is unreachable: ${message}. The MCP server may have crashed or the URL may be wrong.`, { connection: tool.serverName, action: `callTool(${tool.originalName})`, cause: err });
+                }
+                if (message.includes('401') || message.includes('403') || message.includes('missing_token') || message.includes('invalid_token')) {
+                    throw new ConnectionError(`MCP authentication failed for "${tool.name}": ${message}. Check auth headers in amodal.json.`, { connection: tool.serverName, action: `callTool(${tool.originalName})`, cause: err });
+                }
+                throw new ConnectionError(`MCP tool call failed for "${tool.name}": ${message}`, { connection: tool.serverName, action: `callTool(${tool.originalName})`, cause: err });
+            }
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Register all MCP tools
+// ---------------------------------------------------------------------------
+/**
+ * Register all discovered MCP tools on a ToolRegistry.
+ *
+ * Call this after MCP servers have connected and discovered their tools.
+ */
+export function registerMcpTools(registry, mcpManager, logger) {
+    const tools = mcpManager.getDiscoveredTools();
+    let registered = 0;
+    for (const tool of tools) {
+        registry.register(tool.name, createMcpToolDefinition(tool, mcpManager, logger));
+        registered++;
+    }
+    if (registered > 0) {
+        logger.info('mcp_tools_registered', { count: registered, tools: tools.map((t) => t.name) });
+    }
+    return registered;
+}
+//# sourceMappingURL=mcp-tool-adapter.js.map

package/dist/src/tools/mcp-tool-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-tool-adapter.js","sourceRoot":"","sources":["../../../src/tools/mcp-tool-adapter.ts"],"names":[],"mappings":"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"}

package/dist/src/tools/mcp-tool-adapter.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+export {};