c0de-agent 0.0.0 → 1.0.0

package/dist/tools/builtin/glob.js

@@ -0,0 +1,120 @@
+import { readdir } from 'node:fs/promises';
+import { join, relative, resolve } from 'node:path';
+/** Directories always skipped during glob traversal. */
+const IGNORE_DIRS = new Set(['node_modules', '.git', 'dist', '.next', 'build', '.turbo']);
+/**
+ * Convert a glob pattern to a RegExp.
+ * Supports: * (single segment), ** (across segments), ? (single char), {a,b} (alternation), [abc] (char class).
+ */
+export function globToRegex(pattern) {
+    let re = '';
+    let i = 0;
+    while (i < pattern.length) {
+        const c = pattern[i] ?? '';
+        if (c === '*') {
+            if (pattern[i + 1] === '*') {
+                re += '.*';
+                i += 2;
+                if (pattern[i] === '/')
+                    i++; // skip separator after **
+            }
+            else {
+                re += '[^/]*';
+                i++;
+            }
+        }
+        else if (c === '?') {
+            re += '[^/]';
+            i++;
+        }
+        else if (c === '{') {
+            const end = pattern.indexOf('}', i);
+            if (end === -1) {
+                re += '\\{';
+                i++;
+            }
+            else {
+                const inner = pattern.slice(i + 1, end);
+                re += `(?:${inner.split(',').map(escapeRegex).join('|')})`;
+                i = end + 1;
+            }
+        }
+        else if (c === '[') {
+            const end = pattern.indexOf(']', i);
+            if (end === -1) {
+                re += '\\[';
+                i++;
+            }
+            else {
+                re += pattern.slice(i, end + 1);
+                i = end + 1;
+            }
+        }
+        else if ('.+^$()|\\'.includes(c)) {
+            re += `\\${c}`;
+            i++;
+        }
+        else {
+            re += c;
+            i++;
+        }
+    }
+    return new RegExp(`^${re}$`);
+}
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** Recursively walk a directory, skipping IGNORE_DIRS. Returns relative file paths. */
+async function walkDir(dir, base) {
+    const results = [];
+    const entries = await readdir(dir, { withFileTypes: true }).catch(() => null);
+    if (!entries)
+        return [];
+    for (const entry of entries) {
+        if (entry.isDirectory()) {
+            if (IGNORE_DIRS.has(entry.name))
+                continue;
+            const sub = await walkDir(join(dir, entry.name), base);
+            results.push(...sub);
+        }
+        else {
+            results.push(relative(base, join(dir, entry.name)));
+        }
+    }
+    return results;
+}
+/**
+ * glob tool: find files matching a glob pattern.
+ * Permission: auto (read-only).
+ */
+export const globTool = {
+    name: 'glob',
+    description: 'Find files matching a glob pattern. Supports *, **, ?, {a,b}. Searches recursively, skipping node_modules/.git/dist.',
+    parameters: {
+        type: 'object',
+        properties: {
+            pattern: { type: 'string', description: 'Glob pattern (e.g. "src/**/*.ts").' },
+            path: { type: 'string', description: 'Base directory to search (default: cwd).' },
+        },
+        required: ['pattern'],
+    },
+    permission: 'auto',
+    execute: async (input, ctx) => {
+        const { pattern, path } = input;
+        const basePath = path ? resolve(ctx.cwd, path) : ctx.cwd;
+        try {
+            const regex = globToRegex(pattern);
+            const files = await walkDir(basePath, basePath);
+            const matched = files.filter((f) => regex.test(f)).sort();
+            return {
+                _tag: 'success',
+                output: matched.join('\n'),
+                metadata: { count: matched.length },
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return { _tag: 'error', error: `Glob failed: ${message}` };
+        }
+    },
+};

package/dist/tools/builtin/grep.d.ts

@@ -0,0 +1,6 @@
+import type { ToolDef } from '../../shared/types/tool.js';
+/**
+ * grep tool: search file contents with regex.
+ * Permission: auto (read-only).
+ */
+export declare const grepTool: ToolDef;

package/dist/tools/builtin/grep.js

@@ -0,0 +1,141 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join, relative, resolve } from 'node:path';
+/** Directories always skipped during search. */
+const IGNORE_DIRS = new Set(['node_modules', '.git', 'dist', '.next', 'build', '.turbo']);
+/** File extensions treated as text (skip binary files). */
+const TEXT_EXTENSIONS = new Set([
+    '.ts',
+    '.tsx',
+    '.js',
+    '.jsx',
+    '.mjs',
+    '.cjs',
+    '.json',
+    '.md',
+    '.mdx',
+    '.txt',
+    '.css',
+    '.scss',
+    '.html',
+    '.htm',
+    '.xml',
+    '.yaml',
+    '.yml',
+    '.toml',
+    '.ini',
+    '.env',
+    '.sh',
+    '.bash',
+    '.zsh',
+    '.py',
+    '.rb',
+    '.go',
+    '.rs',
+    '.java',
+    '.kt',
+    '.c',
+    '.cpp',
+    '.h',
+    '.hpp',
+    '.cs',
+    '.php',
+    '.swift',
+    '.sql',
+    '.graphql',
+    '.gql',
+    '.vue',
+    '.svelte',
+    '.astro',
+]);
+/** Maximum file size to search (skip files > 1MB). */
+const MAX_FILE_SIZE = 1024 * 1024;
+/** Recursively walk a directory for text files. */
+async function walkForFiles(dir, base) {
+    const results = [];
+    const entries = await readdir(dir, { withFileTypes: true }).catch(() => null);
+    if (!entries)
+        return [];
+    for (const entry of entries) {
+        if (entry.isDirectory()) {
+            if (IGNORE_DIRS.has(entry.name))
+                continue;
+            const sub = await walkForFiles(join(dir, entry.name), base);
+            results.push(...sub);
+        }
+        else {
+            const ext = entry.name.slice(entry.name.lastIndexOf('.'));
+            if (TEXT_EXTENSIONS.has(ext) || ext === '') {
+                results.push(join(dir, entry.name));
+            }
+        }
+    }
+    return results;
+}
+/**
+ * grep tool: search file contents with regex.
+ * Permission: auto (read-only).
+ */
+export const grepTool = {
+    name: 'grep',
+    description: 'Search file contents using regex. Searches recursively across text files, skipping node_modules/.git. Returns matching lines with file and line number.',
+    parameters: {
+        type: 'object',
+        properties: {
+            pattern: { type: 'string', description: 'Regular expression pattern.' },
+            path: { type: 'string', description: 'Base directory to search (default: cwd).' },
+            caseSensitive: { type: 'boolean', description: 'Case-sensitive search (default: true).' },
+            maxResults: { type: 'number', description: 'Maximum number of matches to return.' },
+        },
+        required: ['pattern'],
+    },
+    permission: 'auto',
+    execute: async (input, ctx) => {
+        const { pattern, path, caseSensitive = true, maxResults = 200 } = input;
+        const basePath = path ? resolve(ctx.cwd, path) : ctx.cwd;
+        let regex;
+        try {
+            regex = new RegExp(pattern, caseSensitive ? '' : 'i');
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return { _tag: 'error', error: `Invalid regex pattern: ${message}` };
+        }
+        try {
+            const files = await walkForFiles(basePath, basePath);
+            const matches = [];
+            const max = maxResults;
+            outer: for (const filePath of files) {
+                const stat = await readFile(filePath);
+                if (stat.length > MAX_FILE_SIZE)
+                    continue;
+                const content = stat.toString('utf-8');
+                const lines = content.split('\n');
+                const relPath = relative(basePath, filePath);
+                for (let i = 0; i < lines.length; i++) {
+                    const line = lines[i] ?? '';
+                    const match = line.match(regex);
+                    if (match) {
+                        matches.push({
+                            file: relPath,
+                            line: i + 1,
+                            text: line.trim(),
+                            match: match[0] ?? '',
+                        });
+                        if (matches.length >= max)
+                            break outer;
+                    }
+                }
+            }
+            const output = matches.map((m) => `${m.file}:${m.line}: ${m.text}`).join('\n');
+            return {
+                _tag: 'success',
+                output,
+                metadata: { count: matches.length, truncated: matches.length >= max },
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return { _tag: 'error', error: `Grep failed: ${message}` };
+        }
+    },
+};

package/dist/tools/builtin/read.d.ts

@@ -0,0 +1,6 @@
+import type { ToolDef } from '../../shared/types/tool.js';
+/**
+ * read tool: read file content with optional line range.
+ * Permission: auto (read-only).
+ */
+export declare const readTool: ToolDef;

package/dist/tools/builtin/read.js

@@ -0,0 +1,73 @@
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { safeResolve } from '../../shared/utils/path.js';
+import { isURLPath, resolveURL } from '../resolver.js';
+/** Apply optional offset/limit (1-indexed) to text content. */
+function applyRange(content, offset, limit) {
+    if (offset === undefined && limit === undefined)
+        return content;
+    const lines = content.split('\n');
+    const start = (offset ?? 1) - 1; // convert to 0-indexed
+    const end = limit !== undefined ? start + limit : lines.length;
+    return lines.slice(start, end).join('\n');
+}
+/**
+ * read tool: read file content with optional line range.
+ * Permission: auto (read-only).
+ */
+export const readTool = {
+    name: 'read',
+    description: 'Read file content, or list a directory (entries with trailing `/` on subdirectories). Supports optional offset (1-indexed line number) and limit (number of lines) for files. Also resolves internal URL schemes (skill://, agent://, pr://, issue://) when a resolver registry is configured.',
+    parameters: {
+        type: 'object',
+        properties: {
+            path: { type: 'string', description: 'File path (relative to cwd or absolute).' },
+            offset: { type: 'number', description: 'Starting line number (1-indexed). Default: 1.' },
+            limit: { type: 'number', description: 'Maximum number of lines to read.' },
+        },
+        required: ['path'],
+    },
+    permission: 'auto',
+    execute: async (input, ctx) => {
+        const { path, offset, limit } = input;
+        // 内部 URL scheme（spec §3.10）：skill://, agent://, pr:// 等。
+        // 命中时走 resolver 拿到文本内容，再统一应用 offset/limit；目录列举对 URL 无意义。
+        if (isURLPath(path)) {
+            if (!ctx.urlRegistry) {
+                return {
+                    _tag: 'error',
+                    error: `Cannot resolve URL "${path}": no resolver registry available`,
+                };
+            }
+            const res = await resolveURL(ctx.urlRegistry, path, { cwd: ctx.cwd, session: ctx.session });
+            if (res._tag === 'error')
+                return { _tag: 'error', error: res.error };
+            return { _tag: 'success', output: applyRange(res.content, offset, limit) };
+        }
+        const fullPath = safeResolve(ctx.cwd, path);
+        if (fullPath === null) {
+            return { _tag: 'error', error: `Path "${path}" escapes the working directory` };
+        }
+        try {
+            // 目录：列出条目（子目录加 `/` 后缀），与 system prompt 的「listing a
+            // directory → read」契约一致。否则 readFile 遇到目录会抛 EISDIR,
+            // 而 prompt 却告诉模型 read 能列目录——模型拿到这个矛盾的错误信号后
+            // 会在 glob/read/bash 之间反复试探，最终放弃调用工具而提前 stop。
+            const info = await stat(fullPath);
+            if (info.isDirectory()) {
+                const entries = await readdir(fullPath, { withFileTypes: true });
+                if (entries.length === 0) {
+                    return { _tag: 'success', output: `(empty directory) ${path}` };
+                }
+                entries.sort((a, b) => a.name.localeCompare(b.name));
+                const lines = entries.map((e) => (e.isDirectory() ? `${e.name}/` : e.name));
+                return { _tag: 'success', output: lines.join('\n') };
+            }
+            const content = await readFile(fullPath, 'utf-8');
+            return { _tag: 'success', output: applyRange(content, offset, limit) };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return { _tag: 'error', error: `Failed to read "${path}": ${message}` };
+        }
+    },
+};

package/dist/tools/builtin/resolvers.d.ts

@@ -0,0 +1,12 @@
+import type { URLRegistry, URLResolver } from '../../shared/types/tool.js';
+/** file:// 解析器：`file://rel/path` 相对 cwd；`file:///abs/path` 用绝对路径。 */
+declare function createFileResolver(): URLResolver;
+/** skill:// 解析器：技能文件候选路径（项目优先于全局）。 */
+declare function createSkillResolver(opts?: {
+    homeDir?: string;
+}): URLResolver;
+/** 内置 URL 解析器注册表：预装 file + skill。 */
+declare function createDefaultURLRegistry(opts?: {
+    homeDir?: string;
+}): URLRegistry;
+export { createDefaultURLRegistry, createFileResolver, createSkillResolver };

package/dist/tools/builtin/resolvers.js

@@ -0,0 +1,79 @@
+// 内置 URL 解析器（spec §3.10）。
+//
+// registry 框架（createURLRegistry / registerURLResolver / resolveURL 分发）见
+// ../resolver.ts。这里实现具体 scheme 的内容来源：
+//   - file://  → 本地文件（相对 ctx.cwd 或绝对路径）
+//   - skill:// → 技能文件，项目 .c0de/skills/<name>(.md|/SKILL.md) 优先于
+//                全局 ~/.c0de/skills/<name>(.md|/SKILL.md)
+//
+// agent:// pr:// issue:// 依赖未实现的子 agent 输出与 GitHub 访问，暂不内置。
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { resolve as resolvePath } from 'node:path';
+import { createURLRegistry, registerURLResolver } from '../resolver.js';
+/** 从 `scheme://rest` 中取出 rest（scheme 已校验过，直接切首个 `://`）。 */
+function stripScheme(url) {
+    const idx = url.indexOf('://');
+    return idx < 0 ? url : url.slice(idx + 3);
+}
+/** 读文件，读不到抛错（由 resolveURL 包装成 error result）。 */
+async function readOrFail(path) {
+    return readFile(path, 'utf-8');
+}
+/** file:// 解析器：`file://rel/path` 相对 cwd；`file:///abs/path` 用绝对路径。 */
+function createFileResolver() {
+    return {
+        scheme: 'file',
+        resolve: async (url, ctx) => {
+            const rest = stripScheme(url);
+            // file:///abs → rest 形如 /abs（已含前导斜杠）；file://rel → rest 形如 rel。
+            const path = resolvePath(ctx.cwd, rest);
+            return readOrFail(path);
+        },
+    };
+}
+/** 按优先级返回第一个可读候选文件的路径，全部缺失时返回 null。 */
+async function firstExistingFile(candidates) {
+    for (const c of candidates) {
+        try {
+            // 用 readFile 探测：能读到即返回。失败的候选静默跳过（ENOENT 等）。
+            await readFile(c, 'utf-8');
+            return c;
+        }
+        catch {
+            // 继续尝试下一个候选路径
+        }
+    }
+    return null;
+}
+/** skill:// 解析器：技能文件候选路径（项目优先于全局）。 */
+function createSkillResolver(opts) {
+    const home = opts?.homeDir ?? homedir();
+    return {
+        scheme: 'skill',
+        resolve: async (url, ctx) => {
+            const name = stripScheme(url);
+            if (!name)
+                throw new Error('skill URL requires a name, e.g. skill://brainstorming');
+            const candidates = [
+                resolvePath(ctx.cwd, '.c0de', 'skills', `${name}.md`),
+                resolvePath(ctx.cwd, '.c0de', 'skills', name, 'SKILL.md'),
+                resolvePath(home, '.c0de', 'skills', `${name}.md`),
+                resolvePath(home, '.c0de', 'skills', name, 'SKILL.md'),
+            ];
+            const found = await firstExistingFile(candidates);
+            if (!found) {
+                throw new Error(`Skill "${name}" not found. Looked in:\n${candidates.map((c) => `  - ${c}`).join('\n')}`);
+            }
+            return readOrFail(found);
+        },
+    };
+}
+/** 内置 URL 解析器注册表：预装 file + skill。 */
+function createDefaultURLRegistry(opts) {
+    const reg = createURLRegistry();
+    registerURLResolver(reg, createFileResolver());
+    registerURLResolver(reg, createSkillResolver(opts));
+    return reg;
+}
+export { createDefaultURLRegistry, createFileResolver, createSkillResolver };

package/dist/tools/builtin/task.d.ts

@@ -0,0 +1,9 @@
+import type { ToolDef } from '../../shared/types/tool.js';
+/**
+ * task 工具：按 agent 类型派发子 agent。
+ *
+ * 两种形态：单任务（subagent_type + prompt）或批量并行（subagent_type + context + tasks[]）。
+ * 依赖反转：实际子 agent 运行由 host（core loop 的 runSubAgent）通过 ctx.runSubAgent 执行。
+ * permission: auto（子 agent 是隔离 session，不扩宽父权限）。
+ */
+export declare const taskTool: ToolDef;

package/dist/tools/builtin/task.js

@@ -0,0 +1,100 @@
+/**
+ * task 工具：按 agent 类型派发子 agent。
+ *
+ * 两种形态：单任务（subagent_type + prompt）或批量并行（subagent_type + context + tasks[]）。
+ * 依赖反转：实际子 agent 运行由 host（core loop 的 runSubAgent）通过 ctx.runSubAgent 执行。
+ * permission: auto（子 agent 是隔离 session，不扩宽父权限）。
+ */
+export const taskTool = {
+    name: 'task',
+    description: 'Launch specialized sub-agents to handle delegated tasks. Specify subagent_type to select a specialist (e.g. researcher for read-only investigation, coder for implementation, reviewer for code review). Launch multiple agents concurrently by using the batch form with tasks[]. The sub-agent runs in an isolated session with its own context. When done, the sub-agent returns its result via the yield tool.',
+    parameters: {
+        type: 'object',
+        properties: {
+            subagent_type: {
+                type: 'string',
+                description: "The specialist agent type (e.g. researcher, coder, reviewer). Defaults to 'general'.",
+            },
+            description: { type: 'string', description: 'Short label for the task (display only).' },
+            prompt: { type: 'string', description: 'Self-contained assignment (single-task mode).' },
+            model: { type: 'string', description: 'Optional model override.' },
+            background: { type: 'boolean', description: 'Run in background (default false).' },
+            context: { type: 'string', description: 'Shared context (batch mode).' },
+            tasks: {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    properties: {
+                        description: { type: 'string' },
+                        role: { type: 'string', description: 'Specialist role for this sub-task.' },
+                        assignment: { type: 'string' },
+                    },
+                },
+                description: 'Parallel sub-tasks (batch mode).',
+            },
+        },
+        required: ['prompt'],
+        anyOf: [{ required: ['prompt'] }, { required: ['context', 'tasks'] }],
+    },
+    permission: 'auto',
+    execute: async (input, ctx) => {
+        if (!ctx.runSubAgent) {
+            return {
+                _tag: 'error',
+                error: 'task tool unavailable: no sub-agent runner is wired into this context',
+            };
+        }
+        const inp = input;
+        // 批量模式
+        if ('tasks' in inp && Array.isArray(inp.tasks) && inp.tasks.length > 0) {
+            const agentType = inp.subagent_type ?? 'general';
+            const results = [];
+            for (const item of inp.tasks) {
+                const req = {
+                    agentType,
+                    prompt: item.assignment,
+                    ...(item.description ? { description: item.description } : {}),
+                    ...(item.role ? { role: item.role } : {}),
+                    ...(inp.context ? { context: inp.context } : {}),
+                };
+                const res = await ctx.runSubAgent(req);
+                if (res._tag === 'error') {
+                    return { _tag: 'error', error: `Sub-agent failed: ${res.error}` };
+                }
+                const label = item.description ?? item.role ?? 'task';
+                if (res._tag === 'running') {
+                    results.push(`[${label}] background started (jobId: ${res.jobId})`);
+                }
+                else {
+                    results.push(`[${label}] ${res.output}`);
+                }
+            }
+            return { _tag: 'success', output: results.join('\n\n') };
+        }
+        // 单任务模式
+        const single = inp;
+        const req = {
+            agentType: single.subagent_type ?? 'general',
+            prompt: single.prompt,
+            ...(single.description ? { description: single.description } : {}),
+            ...(single.model ? { model: single.model } : {}),
+            ...(single.background ? { background: true } : {}),
+        };
+        const result = await ctx.runSubAgent(req);
+        if (result._tag === 'error') {
+            return { _tag: 'error', error: `Sub-agent failed: ${result.error}` };
+        }
+        if (result._tag === 'running') {
+            return {
+                _tag: 'success',
+                output: `Background task started (jobId: ${result.jobId}). You will be notified on completion.`,
+                metadata: { sessionId: result.sessionId, background: true, jobId: result.jobId },
+            };
+        }
+        return {
+            _tag: 'success',
+            output: result.output,
+            metadata: { sessionId: result.sessionId, ...(result.data ? { data: result.data } : {}) },
+        };
+    },
+};

package/dist/tools/builtin/write.d.ts

@@ -0,0 +1,6 @@
+import type { ToolDef } from '../../shared/types/tool.js';
+/**
+ * write tool: create or overwrite a file.
+ * Permission: ask (modifies filesystem).
+ */
+export declare const writeTool: ToolDef;

package/dist/tools/builtin/write.js

@@ -0,0 +1,36 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { safeResolve } from '../../shared/utils/path.js';
+/**
+ * write tool: create or overwrite a file.
+ * Permission: ask (modifies filesystem).
+ */
+export const writeTool = {
+    name: 'write',
+    description: 'Create or overwrite a file with the given content. Creates parent directories.',
+    parameters: {
+        type: 'object',
+        properties: {
+            path: { type: 'string', description: 'File path (relative to cwd or absolute).' },
+            content: { type: 'string', description: 'Content to write.' },
+        },
+        required: ['path', 'content'],
+    },
+    permission: 'ask',
+    execute: async (input, ctx) => {
+        const { path, content } = input;
+        const fullPath = safeResolve(ctx.cwd, path);
+        if (fullPath === null) {
+            return { _tag: 'error', error: `Path "${path}" escapes the working directory` };
+        }
+        try {
+            await mkdir(dirname(fullPath), { recursive: true });
+            await writeFile(fullPath, content, 'utf-8');
+            return { _tag: 'success', output: `Wrote ${content.length} bytes to ${path}` };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return { _tag: 'error', error: `Failed to write "${path}": ${message}` };
+        }
+    },
+};

package/dist/tools/builtin/yield.d.ts

@@ -0,0 +1,9 @@
+import type { ToolDef } from '../../shared/types/tool.js';
+/**
+ * yield 工具：子 agent 专用，提交结构化最终结果。
+ *
+ * 这是子 agent 返回结果的唯一方式。调用后，runSubAgent 的 collectYield
+ * 回调收集结果，子 agent loop 检测到 yield 后优雅终止。
+ * 主 agent 不注册此工具。permission: auto（纯结果收集，不改外部状态）。
+ */
+export declare const yieldTool: ToolDef;

package/dist/tools/builtin/yield.js

@@ -0,0 +1,40 @@
+/**
+ * yield 工具：子 agent 专用，提交结构化最终结果。
+ *
+ * 这是子 agent 返回结果的唯一方式。调用后，runSubAgent 的 collectYield
+ * 回调收集结果，子 agent loop 检测到 yield 后优雅终止。
+ * 主 agent 不注册此工具。permission: auto（纯结果收集，不改外部状态）。
+ */
+export const yieldTool = {
+    name: 'yield',
+    description: 'Submit your final structured result. This is the ONLY way to return a result from a sub-agent task. Call this once when your work is complete.',
+    parameters: {
+        type: 'object',
+        properties: {
+            data: {
+                type: 'object',
+                description: 'Your structured result. Must match the outputSchema if the agent declared one.',
+            },
+            type: {
+                type: 'string',
+                description: 'Optional section label for incremental yields.',
+            },
+            status: {
+                type: 'string',
+                enum: ['success', 'aborted'],
+                description: 'Outcome status. Use "aborted" if blocked.',
+            },
+            error: {
+                type: 'string',
+                description: 'If blocked (status=aborted), describe what you tried and the exact blocker.',
+            },
+        },
+        required: ['data'],
+    },
+    permission: 'auto',
+    execute: async (input, ctx) => {
+        const { data } = input;
+        ctx.collectYield?.(data);
+        return { _tag: 'success', output: 'Result submitted.' };
+    },
+};

package/dist/tools/executor.d.ts

@@ -0,0 +1,9 @@
+import type { ToolContext, ToolResult } from '../shared/types/tool.js';
+import type { PermissionChecker, ToolRegistry } from './types.js';
+/**
+ * Execute a tool by name with full pipeline:
+ * find tool → validate input → check permission → execute → truncate output.
+ *
+ * Returns the ToolResult. Never throws — all errors become { _tag: 'error' }.
+ */
+export declare function executeTool(registry: ToolRegistry, name: string, input: unknown, ctx: ToolContext, permissionChecker: PermissionChecker): Promise<ToolResult>;