c0de-agent 0.0.0 → 1.1.0

package/dist/shared/types/tool.d.ts

@@ -0,0 +1,137 @@
+import type { JSONSchema, SessionRef } from './base.js';
+/** Permission level for tool execution. */
+type ToolPermission = 'auto' | 'ask' | 'deny';
+/** Result of a tool execution. Discriminated by `_tag`. */
+type ToolResult = {
+    _tag: 'success';
+    output: string;
+    metadata?: Record<string, unknown>;
+    shakenAt?: number;
+} | {
+    _tag: 'error';
+    error: string;
+    shakenAt?: number;
+} | {
+    _tag: 'permission_required';
+    reason: string;
+} | {
+    _tag: 'truncated';
+    output: string;
+    truncated: boolean;
+    totalLines: number;
+    shakenAt?: number;
+};
+/** Context passed to a URL resolver (skill://, agent://, pr://, …). */
+type URLResolveContext = {
+    cwd: string;
+    session: SessionRef;
+};
+/** A resolver for one URL scheme (e.g. `skill`, `agent`, `pr`). */
+type URLResolver = {
+    scheme: string;
+    resolve: (url: string, ctx: URLResolveContext) => Promise<string>;
+};
+/** Mutable registry of URL resolvers, keyed by scheme. */
+type URLRegistry = {
+    resolvers: Map<string, URLResolver>;
+};
+/** Result of resolving a URL. */
+type ResolveResult = {
+    _tag: 'ok';
+    content: string;
+} | {
+    _tag: 'error';
+    error: string;
+};
+/** Transport shape for a debug adapter process stdio (DAP). Host-injected. */
+type DebugTransport = {
+    write: (chunk: string | Uint8Array) => void;
+    onData: (handler: (chunk: Uint8Array | string) => void) => void;
+    onClose: (handler: () => void) => void;
+    close: () => void;
+};
+/** Context passed to every tool executor. */
+type ToolContext = {
+    cwd: string;
+    session: SessionRef;
+    abort: AbortSignal;
+    mode?: string;
+    /** URL resolver registry; present when the host wires up internal URL schemes. */
+    urlRegistry?: URLRegistry;
+    /** Spawn a sub-agent and return its final text output (dependency-reversal hook
+     *  for the `task` tool; avoids tools→core circular import). */
+    runSubAgent?: (input: SubAgentRequest) => Promise<SubAgentResult>;
+    /** Spawn a debug adapter and return its stdio transport (dependency-reversal
+     *  hook for the `debug_*` tools; host wires real child_process spawn). */
+    debugSpawn?: (config: unknown) => DebugTransport;
+    /** 子 agent 专用：yield 工具调用时收集结构化结果（runSubAgent 注入）。 */
+    collectYield?: (data: unknown) => void;
+};
+/** 单个并行子任务项（批量模式）。 */
+type TaskItem = {
+    description?: string;
+    /** 角色细分（注入子 prompt）。 */
+    role?: string;
+    assignment: string;
+};
+/** Request to run a sub-agent (the `task` tool's payload to the host). */
+type SubAgentRequest = {
+    /** agent 类型名（必填）。 */
+    agentType: string;
+    prompt: string;
+    description?: string;
+    /** 批量模式的角色细分。 */
+    role?: string;
+    /** 批量模式的共享上下文。 */
+    context?: string;
+    model?: string;
+    /** 后台异步运行（默认 false）。 */
+    background?: boolean;
+};
+/** Result of a sub-agent run. */
+type SubAgentResult = {
+    _tag: 'success';
+    output: string;
+    sessionId: string;
+    data?: unknown;
+    patchPath?: string;
+} | {
+    _tag: 'error';
+    error: string;
+    sessionId?: string;
+} | {
+    _tag: 'running';
+    jobId: string;
+    sessionId: string;
+};
+/** Function signature for tool execution. */
+type ToolExecutor = (input: unknown, ctx: ToolContext) => Promise<ToolResult>;
+/** Optional execution mode for tools with multiple implementations. */
+type ToolMode = {
+    name: string;
+    description: string;
+    isAvailable: (ctx: ToolContext) => boolean;
+};
+/** Complete tool definition registered with the tool registry. */
+type ToolDef = {
+    name: string;
+    description: string;
+    parameters: JSONSchema;
+    permission: ToolPermission;
+    execute: ToolExecutor;
+    timeout?: number;
+    modes?: ToolMode[];
+};
+/** Per-(model, tool, mode) success/latency record used to auto-select the
+ *  best tool mode (spec §16.5). Persisted in the `tool_metrics` table. */
+type ModelToolMetrics = {
+    model: string;
+    tool: string;
+    mode: string;
+    attempts: number;
+    successes: number;
+    failures: number;
+    avgLatencyMs: number;
+    lastUsed: number;
+};
+export type { DebugTransport, ModelToolMetrics, ResolveResult, SubAgentRequest, SubAgentResult, TaskItem, ToolContext, ToolDef, ToolExecutor, ToolMode, ToolPermission, ToolResult, URLRegistry, URLResolveContext, URLResolver, };

package/dist/shared/types/tool.js

@@ -0,0 +1 @@
+export {};

package/dist/shared/utils/path.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 安全路径解析：确保 requestPath 解析后落在 root 内，防止路径穿越
+ * （如 `../etc/passwd`、绝对路径 `/etc/passwd`）。
+ *
+ * - `resolve(root, requestPath)` 解析后，若结果不在 root 子树内则返回 null。
+ * - 判定逻辑：`relative(root, resolved)` 以 `..` 开头即越界；
+ *   再用 `resolve(root, rel) === resolved` 兜底，防止相对段恰好名为 root 的边角情况。
+ *
+ * 返回解析后的绝对路径；越界返回 null。
+ *
+ * 注意：本函数基于 `relative`，不解析符号链接（symlink）。若 root 内存在指向
+ * root 外的符号链接，本函数无法阻止经由该链接的逃逸——symlink 逃逸不在本次范围内。
+ */
+declare function safeResolve(root: string, requestPath: string): string | null;
+export { safeResolve };

package/dist/shared/utils/path.js

@@ -0,0 +1,23 @@
+import { relative, resolve } from 'node:path';
+/**
+ * 安全路径解析：确保 requestPath 解析后落在 root 内，防止路径穿越
+ * （如 `../etc/passwd`、绝对路径 `/etc/passwd`）。
+ *
+ * - `resolve(root, requestPath)` 解析后，若结果不在 root 子树内则返回 null。
+ * - 判定逻辑：`relative(root, resolved)` 以 `..` 开头即越界；
+ *   再用 `resolve(root, rel) === resolved` 兜底，防止相对段恰好名为 root 的边角情况。
+ *
+ * 返回解析后的绝对路径；越界返回 null。
+ *
+ * 注意：本函数基于 `relative`，不解析符号链接（symlink）。若 root 内存在指向
+ * root 外的符号链接，本函数无法阻止经由该链接的逃逸——symlink 逃逸不在本次范围内。
+ */
+function safeResolve(root, requestPath) {
+    const resolved = resolve(root, requestPath);
+    const rel = relative(root, resolved);
+    if (rel.startsWith('..') || resolve(root, rel) !== resolved) {
+        return null;
+    }
+    return resolved;
+}
+export { safeResolve };

package/dist/shared/utils.d.ts

@@ -0,0 +1,5 @@
+/** Generate a UUID v4 string. */
+declare function generateId(): string;
+/** Current timestamp in milliseconds since epoch. */
+declare function now(): number;
+export { generateId, now };

package/dist/shared/utils.js

@@ -0,0 +1,10 @@
+import { randomUUID } from 'node:crypto';
+/** Generate a UUID v4 string. */
+function generateId() {
+    return randomUUID();
+}
+/** Current timestamp in milliseconds since epoch. */
+function now() {
+    return Date.now();
+}
+export { generateId, now };

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

@@ -0,0 +1,12 @@
+import type { ToolDef } from '../../shared/types/tool.js';
+/**
+ * bash tool: execute a shell command synchronously.
+ * Permission: ask (can modify filesystem, run arbitrary code).
+ *
+ * Features:
+ * - Merges stdout + stderr
+ * - Process tree kill on abort
+ * - Timeout kills the process tree
+ * - Returns exit code in metadata
+ */
+export declare const bashTool: ToolDef;

package/dist/tools/builtin/bash.js

@@ -0,0 +1,121 @@
+import { spawn } from 'node:child_process';
+import { resolve } from 'node:path';
+/** Default timeout: 120 seconds. */
+const DEFAULT_TIMEOUT = 120_000;
+/** Kill an entire process tree (the child and all its descendants). */
+function killProcessTree(child) {
+    try {
+        // On Linux/macOS, negative PID kills the process group.
+        // We use `detached: true` at spawn to create a new process group.
+        if (child.pid) {
+            process.kill(-child.pid, 'SIGKILL');
+        }
+    }
+    catch {
+        // Process may have already exited — ignore
+    }
+}
+/**
+ * bash tool: execute a shell command synchronously.
+ * Permission: ask (can modify filesystem, run arbitrary code).
+ *
+ * Features:
+ * - Merges stdout + stderr
+ * - Process tree kill on abort
+ * - Timeout kills the process tree
+ * - Returns exit code in metadata
+ */
+export const bashTool = {
+    name: 'bash',
+    description: 'Execute a shell command. Merges stdout+stderr. Supports custom cwd, env, and timeout (default 120s). Returns exit code in metadata.',
+    parameters: {
+        type: 'object',
+        properties: {
+            command: { type: 'string', description: 'Shell command to execute.' },
+            cwd: { type: 'string', description: 'Working directory (default: ctx.cwd).' },
+            timeout: { type: 'number', description: 'Timeout in milliseconds (default: 120000).' },
+            env: {
+                type: 'object',
+                description: 'Additional environment variables.',
+                additionalProperties: { type: 'string' },
+            },
+        },
+        required: ['command'],
+    },
+    permission: 'ask',
+    execute: async (input, ctx) => {
+        const { command, cwd, timeout = DEFAULT_TIMEOUT, env } = input;
+        const workDir = cwd ? resolve(ctx.cwd, cwd) : ctx.cwd;
+        return new Promise((resolvePromise) => {
+            const childEnv = { ...process.env, ...env };
+            const child = spawn(command, {
+                cwd: workDir,
+                shell: true,
+                env: childEnv,
+                detached: true,
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            let stdout = '';
+            let stderr = '';
+            let timedOut = false;
+            child.stdout?.on('data', (data) => {
+                stdout += data.toString();
+            });
+            child.stderr?.on('data', (data) => {
+                stderr += data.toString();
+            });
+            // Timeout handler
+            const timer = setTimeout(() => {
+                timedOut = true;
+                killProcessTree(child);
+            }, timeout);
+            // Abort handler
+            const onAbort = () => {
+                clearTimeout(timer);
+                killProcessTree(child);
+            };
+            if (ctx.abort.aborted) {
+                killProcessTree(child);
+                resolvePromise({ _tag: 'error', error: 'Operation aborted before execution' });
+                return;
+            }
+            ctx.abort.addEventListener('abort', onAbort, { once: true });
+            child.on('close', (code) => {
+                clearTimeout(timer);
+                ctx.abort.removeEventListener('abort', onAbort);
+                if (ctx.abort.aborted) {
+                    resolvePromise({ _tag: 'error', error: 'Command aborted by user' });
+                    return;
+                }
+                if (timedOut) {
+                    resolvePromise({
+                        _tag: 'error',
+                        error: `Command timeout after ${timeout}ms\nPartial output:\n${stdout}${stderr}`,
+                    });
+                    return;
+                }
+                const output = stdout + (stderr ? `\n${stderr}` : '');
+                if (code !== null && code !== 0) {
+                    resolvePromise({
+                        _tag: 'error',
+                        error: `Command failed with exit code: ${code}\n${output}`,
+                    });
+                    return;
+                }
+                resolvePromise({
+                    _tag: 'success',
+                    output: output || '(no output)',
+                    metadata: { exitCode: code ?? 0 },
+                });
+            });
+            child.on('error', (err) => {
+                clearTimeout(timer);
+                ctx.abort.removeEventListener('abort', onAbort);
+                resolvePromise({
+                    _tag: 'error',
+                    error: `Failed to spawn command: ${err.message}`,
+                });
+            });
+        });
+    },
+};

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

@@ -0,0 +1,23 @@
+import { encodeMessage } from '../../dap/protocol.js';
+import type { ToolDef } from '../../shared/types/tool.js';
+/**
+ * debug_* 工具（spec §21）：暴露调试器能力给 agent。
+ *
+ * 依赖反转（同 task 工具）：调试适配器的 spawn 由 host 通过
+ * `ctx.debugSpawn` 注入，本包不依赖 child_process，也不依赖 core。
+ * 无注入时 debug_start 返回 error。
+ *
+ * 模块级 manager 持有活跃会话；sessionId 由 debug_start 返回，agent
+ * 将其传给后续工具。
+ */
+declare const manager: import("../../dap/session.js").DebugSessionManager;
+declare const debugStartTool: ToolDef;
+declare const debugBreakpointTool: ToolDef;
+declare const debugContinueTool: ToolDef;
+declare const debugStepTool: ToolDef;
+declare const debugStackTool: ToolDef;
+declare const debugVarsTool: ToolDef;
+declare const debugEvalTool: ToolDef;
+declare const debugStopTool: ToolDef;
+declare const dapTools: ToolDef[];
+export { dapTools, debugBreakpointTool, debugContinueTool, debugEvalTool, debugStackTool, debugStartTool, debugStepTool, debugStopTool, debugVarsTool, encodeMessage, manager, };

package/dist/tools/builtin/dap.js

@@ -0,0 +1,231 @@
+import { encodeMessage } from '../../dap/protocol.js';
+import { createDebugSessionManager } from '../../dap/session.js';
+/**
+ * debug_* 工具（spec §21）：暴露调试器能力给 agent。
+ *
+ * 依赖反转（同 task 工具）：调试适配器的 spawn 由 host 通过
+ * `ctx.debugSpawn` 注入，本包不依赖 child_process，也不依赖 core。
+ * 无注入时 debug_start 返回 error。
+ *
+ * 模块级 manager 持有活跃会话；sessionId 由 debug_start 返回，agent
+ * 将其传给后续工具。
+ */
+const manager = createDebugSessionManager();
+function ok(output) {
+    return {
+        _tag: 'success',
+        output: typeof output === 'string' ? output : JSON.stringify(output, null, 2),
+    };
+}
+function fail(message) {
+    return { _tag: 'error', error: message };
+}
+// debug_start — 启动调试会话（权限 ask：启动调试器是重操作）
+const debugStartTool = {
+    name: 'debug_start',
+    description: 'Start a debug session by launching a debug adapter and the target program. Returns { sessionId, threadId }. Other debug_* tools take the sessionId.',
+    parameters: {
+        type: 'object',
+        properties: {
+            adapter: { type: 'string', description: 'Debug adapter id, e.g. "node", "python".' },
+            program: { type: 'string', description: 'Path to the program to debug.' },
+            args: { type: 'array', items: { type: 'string' }, description: 'Program arguments.' },
+            cwd: { type: 'string', description: 'Working directory for the program.' },
+            stopOnEntry: { type: 'boolean', description: 'Break on entry (default false).' },
+        },
+        required: ['adapter', 'program'],
+    },
+    permission: 'ask',
+    execute: async (input, ctx) => {
+        if (!ctx.debugSpawn) {
+            return fail('debug_start unavailable: no debug adapter spawn is wired into this context');
+        }
+        const i = input;
+        const config = {
+            adapter: i.adapter,
+            program: i.program,
+            args: i.args,
+            cwd: i.cwd,
+            launchArgs: { stopOnEntry: i.stopOnEntry ?? false },
+        };
+        try {
+            const spawn = ctx.debugSpawn;
+            const result = await manager.start(spawn, config);
+            return ok(result);
+        }
+        catch (error) {
+            return fail(`debug_start failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    },
+};
+// debug_breakpoint — 设置断点（auto）
+const debugBreakpointTool = {
+    name: 'debug_breakpoint',
+    description: 'Set a breakpoint at a file:line (optional condition).',
+    parameters: {
+        type: 'object',
+        properties: {
+            sessionId: { type: 'string' },
+            file: { type: 'string' },
+            line: { type: 'number' },
+            condition: { type: 'string', description: 'Optional hit condition expression.' },
+        },
+        required: ['sessionId', 'file', 'line'],
+    },
+    permission: 'auto',
+    execute: async (input) => {
+        const { sessionId, file, line, condition } = input;
+        const bp = { file, line, ...(condition ? { condition } : {}) };
+        try {
+            const result = await manager.setBreakpoint(sessionId, bp);
+            return ok(result);
+        }
+        catch (error) {
+            return fail(`debug_breakpoint failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    },
+};
+// debug_continue — 继续执行（auto）
+const debugContinueTool = {
+    name: 'debug_continue',
+    description: 'Continue execution of the given thread until the next stop.',
+    parameters: {
+        type: 'object',
+        properties: { sessionId: { type: 'string' }, threadId: { type: 'number' } },
+        required: ['sessionId', 'threadId'],
+    },
+    permission: 'auto',
+    execute: async (input) => {
+        const { sessionId, threadId } = input;
+        try {
+            return ok(await manager.continue(sessionId, threadId));
+        }
+        catch (error) {
+            return fail(`debug_continue failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    },
+};
+// debug_step — 单步 over/in/out（auto）
+const debugStepTool = {
+    name: 'debug_step',
+    description: 'Step execution: kind = "over" | "in" | "out".',
+    parameters: {
+        type: 'object',
+        properties: {
+            sessionId: { type: 'string' },
+            threadId: { type: 'number' },
+            kind: { type: 'string', enum: ['over', 'in', 'out'] },
+        },
+        required: ['sessionId', 'threadId', 'kind'],
+    },
+    permission: 'auto',
+    execute: async (input) => {
+        const { sessionId, threadId, kind } = input;
+        try {
+            return ok(await manager.step(sessionId, threadId, kind));
+        }
+        catch (error) {
+            return fail(`debug_step failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    },
+};
+// debug_stack — 调用栈（auto）
+const debugStackTool = {
+    name: 'debug_stack',
+    description: 'Get the stack trace of a thread. Returns StackFrame[].',
+    parameters: {
+        type: 'object',
+        properties: { sessionId: { type: 'string' }, threadId: { type: 'number' } },
+        required: ['sessionId', 'threadId'],
+    },
+    permission: 'auto',
+    execute: async (input) => {
+        const { sessionId, threadId } = input;
+        try {
+            const frames = await manager.stack(sessionId, threadId);
+            return ok(frames);
+        }
+        catch (error) {
+            return fail(`debug_stack failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    },
+};
+// debug_vars — 查看变量（auto）
+const debugVarsTool = {
+    name: 'debug_vars',
+    description: 'Get variables visible in a stack frame (frameId from debug_stack). Returns Variable[].',
+    parameters: {
+        type: 'object',
+        properties: { sessionId: { type: 'string' }, frameId: { type: 'number' } },
+        required: ['sessionId', 'frameId'],
+    },
+    permission: 'auto',
+    execute: async (input) => {
+        const { sessionId, frameId } = input;
+        try {
+            const vars = await manager.variables(sessionId, frameId);
+            return ok(vars);
+        }
+        catch (error) {
+            return fail(`debug_vars failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    },
+};
+// debug_eval — 求值表达式（auto）
+const debugEvalTool = {
+    name: 'debug_eval',
+    description: 'Evaluate an expression in the context of a stack frame. Returns the result string.',
+    parameters: {
+        type: 'object',
+        properties: {
+            sessionId: { type: 'string' },
+            frameId: { type: 'number' },
+            expression: { type: 'string' },
+        },
+        required: ['sessionId', 'frameId', 'expression'],
+    },
+    permission: 'auto',
+    execute: async (input) => {
+        const { sessionId, frameId, expression } = input;
+        try {
+            const result = await manager.evaluate(sessionId, frameId, expression);
+            return ok(result);
+        }
+        catch (error) {
+            return fail(`debug_eval failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    },
+};
+// debug_stop — 停止调试（auto）
+const debugStopTool = {
+    name: 'debug_stop',
+    description: 'Stop the debug session and disconnect the adapter.',
+    parameters: {
+        type: 'object',
+        properties: { sessionId: { type: 'string' } },
+        required: ['sessionId'],
+    },
+    permission: 'auto',
+    execute: async (input) => {
+        const { sessionId } = input;
+        try {
+            await manager.stop(sessionId);
+            return ok(`debug session ${sessionId} stopped`);
+        }
+        catch (error) {
+            return fail(`debug_stop failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    },
+};
+const dapTools = [
+    debugStartTool,
+    debugBreakpointTool,
+    debugContinueTool,
+    debugStepTool,
+    debugStackTool,
+    debugVarsTool,
+    debugEvalTool,
+    debugStopTool,
+];
+// re-export for tests/host wiring
+export { dapTools, debugBreakpointTool, debugContinueTool, debugEvalTool, debugStackTool, debugStartTool, debugStepTool, debugStopTool, debugVarsTool, encodeMessage, manager, };

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

@@ -0,0 +1,12 @@
+import type { ToolDef } from '../../shared/types/tool.js';
+/**
+ * edit tool: file editing in two modes (spec §16.4).
+ * - diff mode: search-and-replace with fuzzy whitespace matching. Provide
+ *   `oldText` + `newText`. Returns error if oldText is absent or ambiguous.
+ * - hashline mode: content-hash-anchored patch language (spec §16). Provide
+ *   `patch`. If the file changed since the patch was generated, the hash
+ *   mismatch is rejected rather than misapplied.
+ *
+ * Permission: ask (modifies filesystem).
+ */
+export declare const editTool: ToolDef;