@esankhan3/anvil-agent-core 0.1.0

package/dist/tools/builtin.js

@@ -0,0 +1,367 @@
+/**
+ * Built-in tool executor used by non-Claude adapters (Ollama, future
+ * OpenAI/Gemini agentic paths). Mirrors the minimum subset of Claude
+ * CLI's tools that the pipeline build/validate/ship stages need.
+ *
+ * Permission model:
+ *   - Construction takes an `allowedTools: Set<string>` that comes from
+ *     the stage policy (see core-pipeline/src/routing/stage-permissions).
+ *   - `listSchemas()` filters BEFORE returning so the model never even
+ *     learns about denied tools.
+ *   - `execute()` re-checks (defense in depth) and rejects denied calls
+ *     with `isError: true` rather than throwing — the adapter feeds the
+ *     rejection back to the model so it can recover.
+ */
+import { spawn } from 'node:child_process';
+import { mkdirSync, readFileSync, statSync, writeFileSync, readdirSync, existsSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { PathEscapeError, resolveSafe } from './path-guard.js';
+// Read truncation cap — keeps a stray `read_file` of a 50 MB log from
+// blowing context. The model gets a clear marker; it can re-read with
+// offset/limit if it needs more.
+const MAX_READ_BYTES = 256 * 1024;
+const DEFAULT_BASH_TIMEOUT_MS = 60_000;
+const MAX_BASH_TIMEOUT_MS = 300_000;
+// ───────────────────────────────────────────────────────────────────────
+// Schema definitions — OpenAI-tools-compatible JSON Schema
+// ───────────────────────────────────────────────────────────────────────
+const SCHEMAS = {
+    read_file: {
+        class: 'read',
+        schema: {
+            name: 'read_file',
+            description: 'Read a file from the working directory. Optionally specify offset (1-indexed start line) and limit (max lines) to page through large files.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    path: { type: 'string', description: 'Relative or absolute path inside the working directory' },
+                    offset: { type: 'integer', description: '1-indexed starting line (optional)' },
+                    limit: { type: 'integer', description: 'Max number of lines to return (optional)' },
+                },
+                required: ['path'],
+            },
+        },
+    },
+    write_file: {
+        class: 'write',
+        schema: {
+            name: 'write_file',
+            description: 'Write content to a file (creating it if needed). Overwrites existing content. Parent directory is auto-created.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    path: { type: 'string' },
+                    content: { type: 'string' },
+                },
+                required: ['path', 'content'],
+            },
+        },
+    },
+    edit: {
+        class: 'write',
+        schema: {
+            name: 'edit',
+            description: 'Replace exact text in an existing file. old_string MUST match exactly (whitespace included). Set replace_all to replace every occurrence.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    path: { type: 'string' },
+                    old_string: { type: 'string' },
+                    new_string: { type: 'string' },
+                    replace_all: { type: 'boolean' },
+                },
+                required: ['path', 'old_string', 'new_string'],
+            },
+        },
+    },
+    bash: {
+        class: 'exec',
+        schema: {
+            name: 'bash',
+            description: 'Run a shell command in the working directory. Capped to 60s default, 300s max. Returns stdout, stderr, and exit code.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    command: { type: 'string', description: 'The command to execute' },
+                    timeout_ms: { type: 'integer', description: 'Milliseconds before forced kill (max 300000)' },
+                },
+                required: ['command'],
+            },
+        },
+    },
+    grep: {
+        class: 'read',
+        schema: {
+            name: 'grep',
+            description: 'Search file contents using ripgrep-compatible regex. Returns matching lines with file:line prefixes.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    pattern: { type: 'string' },
+                    path: { type: 'string', description: 'File or directory to search; defaults to working directory' },
+                    glob: { type: 'string', description: 'File glob filter (e.g. "*.ts")' },
+                },
+                required: ['pattern'],
+            },
+        },
+    },
+    glob: {
+        class: 'read',
+        schema: {
+            name: 'glob',
+            description: 'List files matching a glob pattern. Returns absolute paths sorted by modification time (newest first).',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    pattern: { type: 'string', description: 'Glob like "**/*.ts"' },
+                    path: { type: 'string', description: 'Root to glob under; defaults to working directory' },
+                },
+                required: ['pattern'],
+            },
+        },
+    },
+    list: {
+        class: 'read',
+        schema: {
+            name: 'list',
+            description: 'List the contents of a directory (non-recursive). Returns one entry per line: kind size name.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    path: { type: 'string', description: 'Directory to list; defaults to working directory' },
+                },
+            },
+        },
+    },
+};
+export const TOOL_CLASS = Object.fromEntries(Object.entries(SCHEMAS).map(([name, { class: cls }]) => [name, cls]));
+export class BuiltinToolExecutor {
+    allowed;
+    constructor(opts) {
+        this.allowed = new Set(opts.allowedTools);
+    }
+    listSchemas() {
+        const out = [];
+        for (const [name, def] of Object.entries(SCHEMAS)) {
+            if (this.allowed.has(name))
+                out.push(def.schema);
+        }
+        return out;
+    }
+    async execute(call, ctx) {
+        if (!this.allowed.has(call.name)) {
+            return { isError: true, content: `Tool "${call.name}" is not permitted in this stage.` };
+        }
+        const handler = HANDLERS[call.name];
+        if (!handler) {
+            return { isError: true, content: `Unknown tool "${call.name}".` };
+        }
+        try {
+            return await handler(call.arguments ?? {}, ctx);
+        }
+        catch (err) {
+            return { isError: true, content: errorMessage(err) };
+        }
+    }
+}
+const HANDLERS = {
+    read_file: async (args, ctx) => {
+        const path = requireString(args.path, 'path');
+        const safe = resolveSafe(path, ctx.workingDir);
+        const stat = statSync(safe);
+        if (!stat.isFile())
+            return { isError: true, content: `"${path}" is not a regular file.` };
+        if (stat.size > MAX_READ_BYTES * 16) {
+            return { isError: true, content: `"${path}" is ${stat.size} bytes — too large to read in one call. Use offset/limit.` };
+        }
+        const raw = readFileSync(safe, 'utf8');
+        const offset = optionalInteger(args.offset, 'offset');
+        const limit = optionalInteger(args.limit, 'limit');
+        let content;
+        if (offset !== undefined || limit !== undefined) {
+            const lines = raw.split('\n');
+            const start = Math.max(0, (offset ?? 1) - 1);
+            const end = limit !== undefined ? start + limit : lines.length;
+            content = lines.slice(start, end).join('\n');
+        }
+        else if (raw.length > MAX_READ_BYTES) {
+            content = raw.slice(0, MAX_READ_BYTES) + `\n\n[truncated — ${raw.length - MAX_READ_BYTES} more bytes]`;
+        }
+        else {
+            content = raw;
+        }
+        return { isError: false, content };
+    },
+    write_file: async (args, ctx) => {
+        const path = requireString(args.path, 'path');
+        const content = requireString(args.content, 'content', { allowEmpty: true });
+        const safe = resolveSafe(path, ctx.workingDir);
+        mkdirSync(dirname(safe), { recursive: true });
+        writeFileSync(safe, content, 'utf8');
+        return { isError: false, content: `Wrote ${content.length} bytes to ${safe}` };
+    },
+    edit: async (args, ctx) => {
+        const path = requireString(args.path, 'path');
+        const oldString = requireString(args.old_string, 'old_string', { allowEmpty: true });
+        const newString = requireString(args.new_string, 'new_string', { allowEmpty: true });
+        const replaceAll = args.replace_all === true;
+        const safe = resolveSafe(path, ctx.workingDir);
+        if (!existsSync(safe))
+            return { isError: true, content: `File not found: ${path}` };
+        const original = readFileSync(safe, 'utf8');
+        if (oldString === '') {
+            return { isError: true, content: 'old_string must not be empty for edit; use write_file to create new content.' };
+        }
+        if (!original.includes(oldString)) {
+            return { isError: true, content: `old_string not found in ${path}.` };
+        }
+        let updated;
+        if (replaceAll) {
+            updated = original.split(oldString).join(newString);
+        }
+        else {
+            const occurrences = original.split(oldString).length - 1;
+            if (occurrences > 1) {
+                return { isError: true, content: `old_string matched ${occurrences} times in ${path} — set replace_all:true or pick a more unique anchor.` };
+            }
+            updated = original.replace(oldString, newString);
+        }
+        writeFileSync(safe, updated, 'utf8');
+        return { isError: false, content: `Edited ${path} (${updated.length - original.length >= 0 ? '+' : ''}${updated.length - original.length} bytes)` };
+    },
+    bash: async (args, ctx) => {
+        const command = requireString(args.command, 'command');
+        const timeoutMs = clampInteger(optionalInteger(args.timeout_ms, 'timeout_ms') ?? DEFAULT_BASH_TIMEOUT_MS, 1, MAX_BASH_TIMEOUT_MS);
+        return runBash(command, ctx, timeoutMs);
+    },
+    grep: async (args, ctx) => {
+        const pattern = requireString(args.pattern, 'pattern');
+        const target = args.path !== undefined ? resolveSafe(requireString(args.path, 'path'), ctx.workingDir) : ctx.workingDir;
+        const globArg = optionalString(args.glob, 'glob');
+        const argv = ['--no-heading', '--line-number', '--color=never', '-e', pattern];
+        if (globArg)
+            argv.push('--glob', globArg);
+        argv.push(target);
+        return runProcess('rg', argv, ctx, DEFAULT_BASH_TIMEOUT_MS);
+    },
+    glob: async (args, ctx) => {
+        const pattern = requireString(args.pattern, 'pattern');
+        const target = args.path !== undefined ? resolveSafe(requireString(args.path, 'path'), ctx.workingDir) : ctx.workingDir;
+        // ripgrep's `--files --glob` is a portable globber that respects .gitignore.
+        return runProcess('rg', ['--files', '--glob', pattern, target], ctx, DEFAULT_BASH_TIMEOUT_MS);
+    },
+    list: async (args, ctx) => {
+        const target = args.path !== undefined ? resolveSafe(requireString(args.path, 'path'), ctx.workingDir) : ctx.workingDir;
+        const stat = statSync(target);
+        if (!stat.isDirectory())
+            return { isError: true, content: `"${target}" is not a directory.` };
+        const entries = readdirSync(target, { withFileTypes: true });
+        const lines = entries
+            .map((e) => {
+            try {
+                const full = `${target}/${e.name}`;
+                const s = statSync(full);
+                const kind = e.isDirectory() ? 'dir' : e.isSymbolicLink() ? 'symlink' : 'file';
+                return `${kind}\t${s.size}\t${e.name}`;
+            }
+            catch {
+                return `unknown\t0\t${e.name}`;
+            }
+        })
+            .sort();
+        return { isError: false, content: lines.join('\n') || '(empty)' };
+    },
+};
+// ───────────────────────────────────────────────────────────────────────
+// Process runners
+// ───────────────────────────────────────────────────────────────────────
+async function runBash(command, ctx, timeoutMs) {
+    // Use `sh -c` so the model can pipe + redirect, but never invoke an
+    // interactive shell. Args are NOT interpolated by the agent — the
+    // entire command string comes from the model in one piece.
+    return runProcess('sh', ['-c', command], ctx, timeoutMs);
+}
+async function runProcess(cmd, argv, ctx, timeoutMs) {
+    return new Promise((resolve) => {
+        const child = spawn(cmd, argv, {
+            cwd: ctx.workingDir,
+            env: process.env,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            shell: false, // never re-interpret cmd via /bin/sh
+        });
+        let stdout = '';
+        let stderr = '';
+        let finished = false;
+        const STDIO_CAP = 64 * 1024;
+        const finish = (content, isError) => {
+            if (finished)
+                return;
+            finished = true;
+            try {
+                child.kill('SIGKILL');
+            }
+            catch { /* already exited */ }
+            resolve({ isError, content });
+        };
+        const timer = setTimeout(() => finish(stdout + stderr + `\n\n[timed out after ${timeoutMs}ms]`, true), timeoutMs);
+        const onAbort = () => finish(stdout + stderr + '\n\n[aborted]', true);
+        if (ctx.abortSignal.aborted) {
+            clearTimeout(timer);
+            onAbort();
+            return;
+        }
+        ctx.abortSignal.addEventListener('abort', onAbort, { once: true });
+        child.stdout?.on('data', (b) => {
+            if (stdout.length < STDIO_CAP)
+                stdout += b.toString('utf8').slice(0, STDIO_CAP - stdout.length);
+        });
+        child.stderr?.on('data', (b) => {
+            if (stderr.length < STDIO_CAP)
+                stderr += b.toString('utf8').slice(0, STDIO_CAP - stderr.length);
+        });
+        child.on('error', (err) => {
+            clearTimeout(timer);
+            ctx.abortSignal.removeEventListener('abort', onAbort);
+            finish(`spawn error: ${err.message}`, true);
+        });
+        child.on('exit', (code, signal) => {
+            clearTimeout(timer);
+            ctx.abortSignal.removeEventListener('abort', onAbort);
+            const tail = stdout + (stderr ? `\n\n[stderr]\n${stderr}` : '');
+            const body = tail || '(no output)';
+            const exitLine = signal ? `\n\n[killed by ${signal}]` : code !== 0 ? `\n\n[exit ${code}]` : '';
+            finish(body + exitLine, code !== 0 || signal !== null);
+        });
+    });
+}
+// ───────────────────────────────────────────────────────────────────────
+// Argument validation helpers
+// ───────────────────────────────────────────────────────────────────────
+function requireString(v, name, opts = {}) {
+    if (typeof v !== 'string')
+        throw new Error(`Argument "${name}" must be a string`);
+    if (!opts.allowEmpty && v.length === 0)
+        throw new Error(`Argument "${name}" must not be empty`);
+    return v;
+}
+function optionalString(v, name) {
+    if (v === undefined || v === null)
+        return undefined;
+    return requireString(v, name);
+}
+function optionalInteger(v, name) {
+    if (v === undefined || v === null)
+        return undefined;
+    if (typeof v !== 'number' || !Number.isInteger(v))
+        throw new Error(`Argument "${name}" must be an integer`);
+    return v;
+}
+function clampInteger(v, lo, hi) {
+    return Math.min(hi, Math.max(lo, v));
+}
+function errorMessage(err) {
+    if (err instanceof PathEscapeError)
+        return err.message;
+    return err instanceof Error ? err.message : String(err);
+}
+//# sourceMappingURL=builtin.js.map

package/dist/tools/builtin.js.map

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

package/dist/tools/index.d.ts

@@ -0,0 +1,4 @@
+export { BuiltinToolExecutor, TOOL_CLASS } from './builtin.js';
+export { PathEscapeError, resolveSafe } from './path-guard.js';
+export type { ExecCtx, ToolClass, ToolExecutor, ToolResult } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC/D,YAAY,EAAE,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}

package/dist/tools/index.js

@@ -0,0 +1,3 @@
+export { BuiltinToolExecutor, TOOL_CLASS } from './builtin.js';
+export { PathEscapeError, resolveSafe } from './path-guard.js';
+//# sourceMappingURL=index.js.map

package/dist/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/tools/path-guard.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Path guard — rejects any path argument that escapes the agent's
+ * working directory. Symlink resolution happens before the comparison so
+ * `cwd/link-to-/etc/passwd` can't slip past.
+ *
+ * SECURITY CRITICAL: every built-in tool that touches the filesystem
+ * MUST go through `resolveSafe`. A bug here means the agent can read or
+ * write arbitrary files on the host. Tests cover the known escape
+ * vectors (`..`, absolute paths outside cwd, symlinks).
+ */
+export declare class PathEscapeError extends Error {
+    readonly attempted: string;
+    readonly workingDir: string;
+    constructor(attempted: string, workingDir: string);
+}
+/**
+ * Resolve `input` to an absolute, real path that is guaranteed to live
+ * inside `workingDir` (or be `workingDir` itself). Throws PathEscapeError
+ * otherwise. The path doesn't have to exist — for write_file/edit we
+ * resolve the parent and append the leaf.
+ */
+export declare function resolveSafe(input: string, workingDir: string): string;
+//# sourceMappingURL=path-guard.d.ts.map

package/dist/tools/path-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-guard.d.ts","sourceRoot":"","sources":["../../src/tools/path-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,qBAAa,eAAgB,SAAQ,KAAK;aACZ,SAAS,EAAE,MAAM;aAAkB,UAAU,EAAE,MAAM;gBAArD,SAAS,EAAE,MAAM,EAAkB,UAAU,EAAE,MAAM;CAIlF;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAerE"}

package/dist/tools/path-guard.js

@@ -0,0 +1,66 @@
+/**
+ * Path guard — rejects any path argument that escapes the agent's
+ * working directory. Symlink resolution happens before the comparison so
+ * `cwd/link-to-/etc/passwd` can't slip past.
+ *
+ * SECURITY CRITICAL: every built-in tool that touches the filesystem
+ * MUST go through `resolveSafe`. A bug here means the agent can read or
+ * write arbitrary files on the host. Tests cover the known escape
+ * vectors (`..`, absolute paths outside cwd, symlinks).
+ */
+import { realpathSync } from 'node:fs';
+import { isAbsolute, resolve, sep } from 'node:path';
+export class PathEscapeError extends Error {
+    attempted;
+    workingDir;
+    constructor(attempted, workingDir) {
+        super(`Path "${attempted}" escapes workingDir "${workingDir}".`);
+        this.attempted = attempted;
+        this.workingDir = workingDir;
+        this.name = 'PathEscapeError';
+    }
+}
+/**
+ * Resolve `input` to an absolute, real path that is guaranteed to live
+ * inside `workingDir` (or be `workingDir` itself). Throws PathEscapeError
+ * otherwise. The path doesn't have to exist — for write_file/edit we
+ * resolve the parent and append the leaf.
+ */
+export function resolveSafe(input, workingDir) {
+    if (typeof input !== 'string' || input.length === 0) {
+        throw new PathEscapeError(String(input), workingDir);
+    }
+    const wd = canonicalize(workingDir);
+    const candidate = isAbsolute(input) ? input : resolve(wd, input);
+    // For non-existent paths, walk up until we find an existing ancestor
+    // and canonicalize that, then re-attach the leaf segments.
+    const real = canonicalizeExistingPrefix(candidate);
+    if (real !== wd && !real.startsWith(wd + sep)) {
+        throw new PathEscapeError(input, workingDir);
+    }
+    return real;
+}
+function canonicalize(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return resolve(p);
+    }
+}
+function canonicalizeExistingPrefix(p) {
+    const parts = p.split(sep);
+    for (let i = parts.length; i > 0; i--) {
+        const ancestor = parts.slice(0, i).join(sep) || sep;
+        try {
+            const real = realpathSync(ancestor);
+            const tail = parts.slice(i).join(sep);
+            return tail ? resolve(real, tail) : real;
+        }
+        catch {
+            continue;
+        }
+    }
+    return p;
+}
+//# sourceMappingURL=path-guard.js.map

package/dist/tools/path-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-guard.js","sourceRoot":"","sources":["../../src/tools/path-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAErD,MAAM,OAAO,eAAgB,SAAQ,KAAK;IACZ;IAAmC;IAA/D,YAA4B,SAAiB,EAAkB,UAAkB;QAC/E,KAAK,CAAC,SAAS,SAAS,yBAAyB,UAAU,IAAI,CAAC,CAAC;QADvC,cAAS,GAAT,SAAS,CAAQ;QAAkB,eAAU,GAAV,UAAU,CAAQ;QAE/E,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,KAAa,EAAE,UAAkB;IAC3D,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,eAAe,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC,CAAC;IACvD,CAAC;IACD,MAAM,EAAE,GAAG,YAAY,CAAC,UAAU,CAAC,CAAC;IAEpC,MAAM,SAAS,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;IACjE,qEAAqE;IACrE,2DAA2D;IAC3D,MAAM,IAAI,GAAG,0BAA0B,CAAC,SAAS,CAAC,CAAC;IAEnD,IAAI,IAAI,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,GAAG,GAAG,CAAC,EAAE,CAAC;QAC9C,MAAM,IAAI,eAAe,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;IAC/C,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,YAAY,CAAC,CAAS;IAC7B,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,CAAC,CAAC,CAAC;IACzB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC;IACpB,CAAC;AACH,CAAC;AAED,SAAS,0BAA0B,CAAC,CAAS;IAC3C,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,KAAK,IAAI,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,QAAQ,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC;QACpD,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;YACpC,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACtC,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAC3C,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;IACH,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC"}

package/dist/tools/types.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Built-in tool executor surface used by non-Claude adapters that need
+ * to drive an agentic loop themselves (Claude CLI ships its own tool
+ * runtime; everything else routes through this).
+ *
+ * Schemas are JSON Schema and OpenAI-tool-compatible — Ollama, OpenAI,
+ * Gemini, and OpenRouter all accept this shape with minor envelope
+ * differences handled by each adapter.
+ */
+import type { ToolCall, ToolSchema } from '../types.js';
+export interface ExecCtx {
+    /** Absolute workingDir; every path arg must resolve inside this directory. */
+    workingDir: string;
+    /** Cancels long-running operations (bash, large file ops) when fired. */
+    abortSignal: AbortSignal;
+}
+export interface ToolResult {
+    /** Free-form content the model sees. Truncated by the adapter if needed. */
+    content: string;
+    /** True when the call failed; the adapter still feeds it back so the
+     *  model can recover instead of getting silently stuck. */
+    isError: boolean;
+}
+export interface ToolExecutor {
+    /**
+     * Schemas the adapter MAY advertise to the model. Permission-filtered
+     * BEFORE this call returns so the model never learns about denied tools.
+     */
+    listSchemas(): ToolSchema[];
+    /**
+     * Execute a single tool call. Implementations must:
+     *   1. Re-check permissions (defense in depth).
+     *   2. Re-validate path arguments against ctx.workingDir.
+     *   3. Honor ctx.abortSignal for any long-running work.
+     *   4. NEVER throw — surface failures via { isError: true, content }.
+     */
+    execute(call: ToolCall, ctx: ExecCtx): Promise<ToolResult>;
+}
+/**
+ * Permission classes for built-in tools. Stage policy maps stage name →
+ * set of allowed classes. The executor filters schemas + rejects calls
+ * whose tool falls outside the set.
+ */
+export type ToolClass = 'read' | 'write' | 'exec';
+//# sourceMappingURL=types.d.ts.map

package/dist/tools/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/tools/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAExD,MAAM,WAAW,OAAO;IACtB,8EAA8E;IAC9E,UAAU,EAAE,MAAM,CAAC;IACnB,yEAAyE;IACzE,WAAW,EAAE,WAAW,CAAC;CAC1B;AAED,MAAM,WAAW,UAAU;IACzB,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAC;IAChB;+DAC2D;IAC3D,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,WAAW,IAAI,UAAU,EAAE,CAAC;IAE5B;;;;;;OAMG;IACH,OAAO,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CAC5D;AAED;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC"}

package/dist/tools/types.js

@@ -0,0 +1,11 @@
+/**
+ * Built-in tool executor surface used by non-Claude adapters that need
+ * to drive an agentic loop themselves (Claude CLI ships its own tool
+ * runtime; everything else routes through this).
+ *
+ * Schemas are JSON Schema and OpenAI-tool-compatible — Ollama, OpenAI,
+ * Gemini, and OpenRouter all accept this shape with minor envelope
+ * differences handled by each adapter.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/tools/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/tools/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}