@amodalai/runtime 0.1.26 → 0.2.0

package/dist/src/tools/admin-file-tools.js

@@ -0,0 +1,200 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * Admin file tools rewritten for the new ToolRegistry.
+ *
+ * Four tools for managing agent repo files:
+ * - read_repo_file    — read a file from the agent repo
+ * - write_repo_file   — create or update a file
+ * - delete_repo_file  — delete a file
+ * - internal_api      — query the runtime's own API
+ *
+ * Path validation enforces allowed directories and blocks sensitive files.
+ */
+import { readFile, writeFile, unlink, mkdir } from 'node:fs/promises';
+import * as path from 'node:path';
+import { z } from 'zod';
+import { ConfigError } from '../errors.js';
+// ---------------------------------------------------------------------------
+// Path validation
+// ---------------------------------------------------------------------------
+const ALLOWED_REPO_DIRS = [
+    'skills/',
+    'knowledge/',
+    'connections/',
+    'stores/',
+    'pages/',
+    'automations/',
+    'evals/',
+    'agents/',
+    'tools/',
+    'amodal_packages/',
+];
+const BLOCKED_FILENAMES = [
+    '.env',
+    'amodal.json',
+    'package.json',
+    'pnpm-lock.yaml',
+    'tsconfig.json',
+];
+const READ_ONLY_DIRS = [
+    'amodal_packages/',
+];
+/** @internal Exported for testing */
+export function isAllowedRepoPath(relPath) {
+    const basename = path.basename(relPath);
+    if (BLOCKED_FILENAMES.includes(basename))
+        return false;
+    return ALLOWED_REPO_DIRS.some((dir) => relPath.startsWith(dir));
+}
+function isReadOnlyPath(relPath) {
+    return READ_ONLY_DIRS.some((dir) => relPath.startsWith(dir));
+}
+function validatePath(repoRoot, rawPath) {
+    if (!rawPath || rawPath.startsWith('/')) {
+        return { error: 'Path must be relative to the repo root (no leading /)' };
+    }
+    if (rawPath.includes('..')) {
+        return { error: 'Path traversal (..) is not allowed' };
+    }
+    const normalized = path.normalize(rawPath);
+    if (!isAllowedRepoPath(normalized)) {
+        return { error: `Path "${normalized}" is not in an allowed directory. Allowed: ${ALLOWED_REPO_DIRS.join(', ')}. Blocked files: ${BLOCKED_FILENAMES.join(', ')}` };
+    }
+    const resolved = path.resolve(repoRoot, normalized);
+    if (!resolved.startsWith(repoRoot)) {
+        return { error: 'Resolved path escapes the repo directory' };
+    }
+    return { resolved, relative: normalized };
+}
+// ---------------------------------------------------------------------------
+// read_repo_file
+// ---------------------------------------------------------------------------
+export function createReadRepoFileTool(repoRoot) {
+    return {
+        description: 'Read a file from the agent repo. Path is relative to repo root. Allowed directories: skills/, knowledge/, connections/, stores/, pages/, automations/, evals/, agents/, tools/.',
+        parameters: z.object({
+            path: z.string().min(1).describe('File path relative to repo root (e.g. "knowledge/formatting-rules.md")'),
+        }),
+        readOnly: true,
+        metadata: { category: 'admin' },
+        async execute(params, _ctx) {
+            const validation = validatePath(repoRoot, params.path);
+            if ('error' in validation) {
+                return { error: validation.error };
+            }
+            try {
+                const content = await readFile(validation.resolved, 'utf-8');
+                return { content, path: validation.relative };
+            }
+            catch (err) {
+                // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- guarded by instanceof + 'code' in err
+                const isNotFound = err instanceof Error && 'code' in err && err.code === 'ENOENT';
+                const msg = isNotFound ? `File not found: ${validation.relative}` : (err instanceof Error ? err.message : String(err));
+                return { error: msg };
+            }
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// write_repo_file
+// ---------------------------------------------------------------------------
+export function createWriteRepoFileTool(repoRoot) {
+    return {
+        description: 'Create or update a file in the agent repo. Allowed directories: skills/, knowledge/, connections/, stores/, pages/, automations/, evals/, agents/, tools/.',
+        parameters: z.object({
+            path: z.string().min(1).describe('File path relative to repo root'),
+            content: z.string().min(1).describe('Full file content to write'),
+        }),
+        readOnly: false,
+        metadata: { category: 'admin' },
+        async execute(params, _ctx) {
+            const validation = validatePath(repoRoot, params.path);
+            if ('error' in validation) {
+                return { error: validation.error };
+            }
+            if (isReadOnlyPath(validation.relative)) {
+                return { error: `${validation.relative} is read-only (installed package)` };
+            }
+            await mkdir(path.dirname(validation.resolved), { recursive: true });
+            await writeFile(validation.resolved, params.content, 'utf-8');
+            return { written: validation.relative, bytes: params.content.length };
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// delete_repo_file
+// ---------------------------------------------------------------------------
+export function createDeleteRepoFileTool(repoRoot) {
+    return {
+        description: 'Delete a file from the agent repo. Always confirm with the user before deleting. Same directory restrictions as write_repo_file.',
+        parameters: z.object({
+            path: z.string().min(1).describe('File path relative to repo root'),
+        }),
+        readOnly: false,
+        metadata: { category: 'admin' },
+        async execute(params, _ctx) {
+            const validation = validatePath(repoRoot, params.path);
+            if ('error' in validation) {
+                return { error: validation.error };
+            }
+            if (isReadOnlyPath(validation.relative)) {
+                return { error: `${validation.relative} is read-only (installed package)` };
+            }
+            try {
+                await unlink(validation.resolved);
+                return { deleted: validation.relative };
+            }
+            catch (err) {
+                // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- guarded by instanceof + 'code' in err
+                const isNotFound = err instanceof Error && 'code' in err && err.code === 'ENOENT';
+                const msg = isNotFound ? `File not found: ${validation.relative}` : (err instanceof Error ? err.message : String(err));
+                return { error: msg };
+            }
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// internal_api
+// ---------------------------------------------------------------------------
+export function createInternalApiTool(getPort) {
+    return {
+        description: "Query the amodal runtime's internal API. Use this to check eval results, connection health, agent context, store data, and automation status. Only GET requests.",
+        parameters: z.object({
+            endpoint: z.string().min(1).describe('API path (e.g. "/api/evals/runs", "/inspect/health")'),
+        }),
+        readOnly: true,
+        metadata: { category: 'admin' },
+        async execute(params, ctx) {
+            const port = getPort();
+            if (!port) {
+                throw new ConfigError('Server not ready — cannot query internal API', {
+                    key: 'server.port',
+                });
+            }
+            const resp = await fetch(`http://127.0.0.1:${String(port)}${params.endpoint}`, {
+                signal: ctx.signal ?? AbortSignal.timeout(10_000),
+            });
+            const text = await resp.text();
+            try {
+                return { status: resp.status, data: JSON.parse(text) };
+            }
+            catch {
+                return { status: resp.status, data: text };
+            }
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Register all admin tools
+// ---------------------------------------------------------------------------
+export function registerAdminFileTools(registry, repoRoot, getPort) {
+    registry.register('read_repo_file', createReadRepoFileTool(repoRoot));
+    registry.register('write_repo_file', createWriteRepoFileTool(repoRoot));
+    registry.register('delete_repo_file', createDeleteRepoFileTool(repoRoot));
+    registry.register('internal_api', createInternalApiTool(getPort));
+}
+//# sourceMappingURL=admin-file-tools.js.map

package/dist/src/tools/admin-file-tools.js.map

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

package/dist/src/tools/admin-file-tools.test.d.ts

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

package/dist/src/tools/admin-file-tools.test.js

@@ -0,0 +1,152 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, mkdirSync, writeFileSync, existsSync, readFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { createReadRepoFileTool, createWriteRepoFileTool, createDeleteRepoFileTool, createInternalApiTool, registerAdminFileTools, isAllowedRepoPath, } from './admin-file-tools.js';
+import { createToolRegistry } from './registry.js';
+import { ConfigError } from '../errors.js';
+const mockCtx = {
+    request: vi.fn(),
+    store: vi.fn(),
+    env: vi.fn(),
+    log: vi.fn(),
+    user: { roles: ['admin'] },
+    signal: AbortSignal.timeout(5000),
+    sessionId: 'test-session',
+    tenantId: 'test-tenant',
+};
+let repoRoot;
+beforeEach(() => {
+    repoRoot = mkdtempSync(join(tmpdir(), 'admin-tools-test-'));
+    mkdirSync(join(repoRoot, 'skills'), { recursive: true });
+    mkdirSync(join(repoRoot, 'knowledge'), { recursive: true });
+    mkdirSync(join(repoRoot, 'evals'), { recursive: true });
+    mkdirSync(join(repoRoot, 'amodal_packages', 'test-pkg'), { recursive: true });
+});
+afterEach(() => {
+    rmSync(repoRoot, { recursive: true, force: true });
+});
+describe('isAllowedRepoPath', () => {
+    it('allows paths in permitted directories', () => {
+        expect(isAllowedRepoPath('skills/triage.md')).toBe(true);
+        expect(isAllowedRepoPath('knowledge/rules.md')).toBe(true);
+        expect(isAllowedRepoPath('connections/typefully/spec.json')).toBe(true);
+        expect(isAllowedRepoPath('stores/alerts.json')).toBe(true);
+        expect(isAllowedRepoPath('tools/my_tool/handler.ts')).toBe(true);
+    });
+    it('blocks sensitive files', () => {
+        expect(isAllowedRepoPath('.env')).toBe(false);
+        expect(isAllowedRepoPath('amodal.json')).toBe(false);
+        expect(isAllowedRepoPath('package.json')).toBe(false);
+    });
+    it('blocks paths outside allowed directories', () => {
+        expect(isAllowedRepoPath('src/index.ts')).toBe(false);
+        expect(isAllowedRepoPath('node_modules/foo')).toBe(false);
+    });
+});
+describe('createReadRepoFileTool', () => {
+    it('reads an existing file', async () => {
+        writeFileSync(join(repoRoot, 'skills', 'triage.md'), '# Triage Skill');
+        const tool = createReadRepoFileTool(repoRoot);
+        const result = await tool.execute({ path: 'skills/triage.md' }, mockCtx);
+        expect(result['content']).toBe('# Triage Skill');
+        expect(result['path']).toBe('skills/triage.md');
+    });
+    it('returns error for missing file', async () => {
+        const tool = createReadRepoFileTool(repoRoot);
+        const result = await tool.execute({ path: 'skills/nonexistent.md' }, mockCtx);
+        expect(result['error']).toContain('File not found');
+    });
+    it('rejects path traversal', async () => {
+        const tool = createReadRepoFileTool(repoRoot);
+        const result = await tool.execute({ path: '../../../etc/passwd' }, mockCtx);
+        expect(result['error']).toContain('traversal');
+    });
+    it('rejects absolute paths', async () => {
+        const tool = createReadRepoFileTool(repoRoot);
+        const result = await tool.execute({ path: '/etc/passwd' }, mockCtx);
+        expect(result['error']).toContain('relative');
+    });
+    it('rejects blocked filenames', async () => {
+        const tool = createReadRepoFileTool(repoRoot);
+        const result = await tool.execute({ path: 'skills/.env' }, mockCtx);
+        expect(result['error']).toContain('not in an allowed directory');
+    });
+    it('is readOnly', () => {
+        const tool = createReadRepoFileTool(repoRoot);
+        expect(tool.readOnly).toBe(true);
+        expect(tool.metadata?.category).toBe('admin');
+    });
+});
+describe('createWriteRepoFileTool', () => {
+    it('writes a new file', async () => {
+        const tool = createWriteRepoFileTool(repoRoot);
+        const result = await tool.execute({ path: 'knowledge/rules.md', content: '# Rules' }, mockCtx);
+        expect(result['written']).toBe('knowledge/rules.md');
+        expect(result['bytes']).toBe(7);
+        expect(readFileSync(join(repoRoot, 'knowledge', 'rules.md'), 'utf-8')).toBe('# Rules');
+    });
+    it('creates parent directories', async () => {
+        const tool = createWriteRepoFileTool(repoRoot);
+        await tool.execute({ path: 'connections/new-api/spec.json', content: '{}' }, mockCtx);
+        expect(existsSync(join(repoRoot, 'connections', 'new-api', 'spec.json'))).toBe(true);
+    });
+    it('rejects writes to read-only directories', async () => {
+        const tool = createWriteRepoFileTool(repoRoot);
+        const result = await tool.execute({ path: 'amodal_packages/test-pkg/file.ts', content: 'code' }, mockCtx);
+        expect(result['error']).toContain('read-only');
+    });
+    it('is not readOnly', () => {
+        const tool = createWriteRepoFileTool(repoRoot);
+        expect(tool.readOnly).toBe(false);
+    });
+});
+describe('createDeleteRepoFileTool', () => {
+    it('deletes an existing file', async () => {
+        writeFileSync(join(repoRoot, 'evals', 'old-test.md'), 'old');
+        const tool = createDeleteRepoFileTool(repoRoot);
+        const result = await tool.execute({ path: 'evals/old-test.md' }, mockCtx);
+        expect(result['deleted']).toBe('evals/old-test.md');
+        expect(existsSync(join(repoRoot, 'evals', 'old-test.md'))).toBe(false);
+    });
+    it('returns error for missing file', async () => {
+        const tool = createDeleteRepoFileTool(repoRoot);
+        const result = await tool.execute({ path: 'evals/nonexistent.md' }, mockCtx);
+        expect(result['error']).toContain('File not found');
+    });
+    it('rejects deletes in read-only directories', async () => {
+        const tool = createDeleteRepoFileTool(repoRoot);
+        const result = await tool.execute({ path: 'amodal_packages/test-pkg/file.ts' }, mockCtx);
+        expect(result['error']).toContain('read-only');
+    });
+});
+describe('createInternalApiTool', () => {
+    it('throws ConfigError when server not ready', async () => {
+        const tool = createInternalApiTool(() => null);
+        await expect(tool.execute({ endpoint: '/inspect/health' }, mockCtx)).rejects.toThrow(ConfigError);
+    });
+    it('is readOnly', () => {
+        const tool = createInternalApiTool(() => 3000);
+        expect(tool.readOnly).toBe(true);
+        expect(tool.metadata?.category).toBe('admin');
+    });
+});
+describe('registerAdminFileTools', () => {
+    it('registers all 4 admin tools', () => {
+        const registry = createToolRegistry();
+        registerAdminFileTools(registry, repoRoot, () => 3000);
+        expect(registry.names()).toEqual([
+            'read_repo_file',
+            'write_repo_file',
+            'delete_repo_file',
+            'internal_api',
+        ]);
+        expect(registry.size).toBe(4);
+    });
+});
+//# sourceMappingURL=admin-file-tools.test.js.map

package/dist/src/tools/admin-file-tools.test.js.map

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

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

@@ -0,0 +1,41 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+import type { LoadedTool, CustomToolExecutor } from '@amodalai/types';
+import type { ToolDefinition } from './types.js';
+export interface CustomToolSessionContext {
+    config: {
+        getConnections(): Record<string, unknown>;
+        getStores(): Array<{
+            name: string;
+            entity: {
+                key: string;
+                schema: Record<string, unknown>;
+            };
+        }>;
+    };
+    storeBackend?: {
+        put(appId: string, store: string, key: string, payload: Record<string, unknown>, meta: Record<string, unknown>): Promise<void>;
+    };
+    appId?: string;
+    shellExecutor?: {
+        exec(command: string, options?: {
+            cwd?: string;
+            timeout?: number;
+        }): Promise<{
+            stdout: string;
+            stderr: string;
+            exitCode: number;
+        }>;
+    };
+}
+/**
+ * Create a ToolDefinition from a LoadedTool.
+ *
+ * The returned definition can be registered on the ToolRegistry. When the
+ * LLM calls the tool, the executor compiles the handler (if needed) and
+ * runs it with the full CustomToolContext.
+ */
+export declare function createCustomToolDefinition(tool: LoadedTool, executor: CustomToolExecutor, sessionCtx: CustomToolSessionContext): ToolDefinition;

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

@@ -0,0 +1,190 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * Adapts custom tools (handler.ts → esbuild → dynamic import) to
+ * ToolDefinition objects for the new ToolRegistry.
+ *
+ * The compiled handler exports `default async function(params, ctx)`.
+ * This adapter wraps it with:
+ * - A Zod schema derived from the tool's JSON Schema parameters
+ * - A ToolContext that provides request(), store(), exec(), env(), log()
+ * - Timeout + abort signal handling
+ * - Read-only enforcement (confirm: false → GET only)
+ */
+import { jsonSchema } from 'ai';
+import { ToolExecutionError } from '../errors.js';
+import { log } from '../logger.js';
+import { resolveKey } from '../stores/key-resolver.js';
+import { LOCAL_APP_ID } from '../constants.js';
+function buildCustomToolContext(tool, sessionCtx, runtimeCtx) {
+    const timeoutSignal = AbortSignal.timeout(tool.timeout);
+    const combinedSignal = AbortSignal.any([runtimeCtx.signal, timeoutSignal]);
+    return {
+        async request(connection, endpoint, params) {
+            const connections = sessionCtx.config.getConnections();
+            const connConfig = connections[connection];
+            if (!connConfig) {
+                throw new ToolExecutionError(`Connection "${connection}" not found`, {
+                    toolName: tool.name,
+                    callId: '',
+                    context: { connection },
+                });
+            }
+            const method = params?.method ?? 'GET';
+            if (tool.confirm === false && method !== 'GET') {
+                throw new ToolExecutionError(`Tool "${tool.name}" has confirm: false — only GET requests are allowed.`, { toolName: tool.name, callId: '', context: { method } });
+            }
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- connection config shape from buildConnectionsMap
+            const conn = connConfig;
+            const baseUrl = String(conn['base_url'] ?? '');
+            if (!baseUrl) {
+                throw new ToolExecutionError(`Connection "${connection}" has no base_url`, {
+                    toolName: tool.name,
+                    callId: '',
+                    context: { connection },
+                });
+            }
+            // Build headers — start with defaults, apply auth from _request_config
+            const headers = { 'Content-Type': 'application/json' };
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- internal config shape
+            const reqConfig = conn['_request_config'];
+            if (reqConfig?.default_headers) {
+                Object.assign(headers, reqConfig.default_headers);
+            }
+            if (reqConfig?.auth) {
+                for (const authEntry of reqConfig.auth) {
+                    // value_template is pre-resolved by buildConnectionsMap
+                    headers[authEntry.header] = authEntry.value_template;
+                }
+            }
+            const url = `${baseUrl}${endpoint}`;
+            const fetchOpts = {
+                method,
+                signal: combinedSignal,
+                headers,
+            };
+            if (params?.data) {
+                fetchOpts.body = JSON.stringify(params.data);
+            }
+            const res = await fetch(url, fetchOpts);
+            const body = await res.text();
+            if (!res.ok) {
+                throw new ToolExecutionError(`${method} ${url} returned ${String(res.status)}: ${body.slice(0, 500)}`, { toolName: tool.name, callId: '', context: { connection, endpoint, status: res.status } });
+            }
+            try {
+                return JSON.parse(body);
+            }
+            catch {
+                return { text: body, status: res.status };
+            }
+        },
+        async store(storeName, payload) {
+            if (!sessionCtx.storeBackend) {
+                throw new ToolExecutionError('Store backend not available', {
+                    toolName: tool.name,
+                    callId: '',
+                    context: { storeName },
+                });
+            }
+            const stores = sessionCtx.config.getStores();
+            const storeDef = stores.find((s) => s.name === storeName);
+            if (!storeDef) {
+                throw new ToolExecutionError(`Store "${storeName}" not found`, {
+                    toolName: tool.name,
+                    callId: '',
+                    context: { storeName },
+                });
+            }
+            const key = resolveKey(storeDef.entity.key, payload);
+            const appId = sessionCtx.appId ?? LOCAL_APP_ID;
+            await sessionCtx.storeBackend.put(appId, storeName, key, payload, {});
+            return { key };
+        },
+        async exec(command, options) {
+            if (sessionCtx.shellExecutor) {
+                return sessionCtx.shellExecutor.exec(command, options);
+            }
+            const { exec: execCb } = await import('node:child_process');
+            const { promisify } = await import('node:util');
+            const execAsync = promisify(execCb);
+            try {
+                const { stdout, stderr } = await execAsync(command, {
+                    signal: combinedSignal,
+                    timeout: options?.timeout ?? tool.timeout,
+                    cwd: options?.cwd,
+                });
+                return { stdout: stdout ?? '', stderr: stderr ?? '', exitCode: 0 };
+            }
+            catch (err) {
+                // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- exec error shape
+                const e = err;
+                return { stdout: e.stdout ?? '', stderr: e.stderr ?? '', exitCode: e.code ?? 1 };
+            }
+        },
+        env(name) {
+            if (!tool.env.includes(name))
+                return undefined;
+            return process.env[name];
+        },
+        log(message) {
+            runtimeCtx.log(message);
+        },
+        user: runtimeCtx.user,
+        signal: combinedSignal,
+    };
+}
+// ---------------------------------------------------------------------------
+// Public factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a ToolDefinition from a LoadedTool.
+ *
+ * The returned definition can be registered on the ToolRegistry. When the
+ * LLM calls the tool, the executor compiles the handler (if needed) and
+ * runs it with the full CustomToolContext.
+ */
+export function createCustomToolDefinition(tool, executor, sessionCtx) {
+    // Pass the tool's JSON Schema directly to the AI SDK so the LLM sees
+    // the full parameter descriptions, types, and required fields from tool.json.
+    const schema = jsonSchema(tool.parameters);
+    return {
+        description: tool.description,
+        parameters: schema,
+        readOnly: tool.confirm === false,
+        metadata: {
+            category: 'custom',
+        },
+        async execute(params, ctx) {
+            const customCtx = buildCustomToolContext(tool, sessionCtx, ctx);
+            const validatedParams = typeof params === 'object' && params !== null
+                // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- params validated by Zod schema before reaching execute
+                ? params
+                : {};
+            log.debug('custom_tool_execute', {
+                tool: tool.name,
+                tag: 'tool',
+            });
+            try {
+                const result = await executor.execute(tool, validatedParams, customCtx);
+                return result;
+            }
+            catch (err) {
+                if (err instanceof Error && err.name === 'AbortError') {
+                    throw new ToolExecutionError(`Tool "${tool.name}" was aborted`, {
+                        toolName: tool.name,
+                        callId: '',
+                    });
+                }
+                throw new ToolExecutionError(`Tool "${tool.name}" failed: ${err instanceof Error ? err.message : String(err)}`, {
+                    toolName: tool.name,
+                    callId: '',
+                    cause: err instanceof Error ? err : undefined,
+                });
+            }
+        },
+    };
+}
+//# sourceMappingURL=custom-tool-adapter.js.map

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

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

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

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