c0de-agent 0.0.0 → 1.0.0

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;

package/dist/tools/builtin/edit.js

@@ -0,0 +1,151 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { safeResolve } from '../../shared/utils/path.js';
+import { applyPatch, parsePatch } from '../hashline/index.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 const editTool = {
+    name: 'edit',
+    description: 'Edit a file. Two modes: (1) diff — provide oldText+newText for fuzzy search-and-replace; (2) hashline — provide `patch`, a content-hash-anchored patch that fails safely if the file changed since the patch was generated.',
+    parameters: {
+        type: 'object',
+        properties: {
+            path: { type: 'string', description: 'File path (relative to cwd or absolute).' },
+            oldText: {
+                type: 'string',
+                description: 'diff mode: text to find in the file (fuzzy whitespace matching).',
+            },
+            newText: { type: 'string', description: 'diff mode: replacement text.' },
+            patch: {
+                type: 'string',
+                description: 'hashline mode: a patch block like `[path#hash]\\nSWAP start-end\\nnew content\\n---`. Generate the hash from the CURRENT file content; a stale hash is rejected.',
+            },
+        },
+        required: ['path'],
+    },
+    permission: 'ask',
+    execute: async (input, ctx) => {
+        const raw = input;
+        const path = raw.path;
+        const fullPath = safeResolve(ctx.cwd, path);
+        if (fullPath === null) {
+            return { _tag: 'error', error: `Path "${path}" escapes the working directory` };
+        }
+        try {
+            // ── hashline 模式 ──────────────────────────────────
+            if ('patch' in raw && typeof raw.patch === 'string') {
+                const patches = parsePatch(raw.patch);
+                if (patches.length === 0) {
+                    return { _tag: 'error', error: `hashline: empty patch for "${path}"` };
+                }
+                let current = await readFile(fullPath, 'utf-8');
+                for (const p of patches) {
+                    const r = applyPatch(current, p);
+                    if (r._tag !== 'success') {
+                        return { _tag: 'error', error: formatHashlineError(path, r) };
+                    }
+                    current = r.content;
+                }
+                await writeFile(fullPath, current, 'utf-8');
+                return {
+                    _tag: 'success',
+                    output: `Edited "${path}" via hashline patch (${patches.length} block(s))`,
+                };
+            }
+            // ── diff 模式 ──────────────────────────────────────
+            if (!('oldText' in raw) || !('newText' in raw)) {
+                return {
+                    _tag: 'error',
+                    error: `edit: provide either 'patch' (hashline) or 'oldText'+'newText' (diff) for "${path}"`,
+                };
+            }
+            const oldText = raw.oldText;
+            const newText = raw.newText;
+            const content = await readFile(fullPath, 'utf-8');
+            // Fuzzy whitespace matching: normalize whitespace runs
+            const normalize = (s) => s.replace(/[ \t]+/g, ' ');
+            const normalizedContent = normalize(content);
+            const normalizedOld = normalize(oldText);
+            // Find all match positions
+            const matches = [];
+            let searchFrom = 0;
+            while (true) {
+                const idx = normalizedContent.indexOf(normalizedOld, searchFrom);
+                if (idx === -1)
+                    break;
+                matches.push(idx);
+                searchFrom = idx + normalizedOld.length;
+            }
+            if (matches.length === 0) {
+                return { _tag: 'error', error: `oldText not found in "${path}"` };
+            }
+            if (matches.length > 1) {
+                return {
+                    _tag: 'error',
+                    error: `oldText matches ${matches.length} times in "${path}" — multiple matches found, provide more context to disambiguate`,
+                };
+            }
+            // Map normalized match back to original content
+            const matchIdx = matches[0] ?? 0;
+            const prefix = normalizedContent.slice(0, matchIdx);
+            const charCount = prefix.length;
+            const mapping = buildPositionMapping(content, normalizedContent);
+            const origStart = mapping.get(charCount) ?? charCount;
+            const origEnd = mapping.get(charCount + normalizedOld.length) ?? charCount + normalizedOld.length;
+            const newContent = content.slice(0, origStart) + newText + content.slice(origEnd);
+            await writeFile(fullPath, newContent, 'utf-8');
+            return {
+                _tag: 'success',
+                output: `Edited "${path}": replaced ${origEnd - origStart} chars with ${newText.length} chars`,
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return { _tag: 'error', error: `Failed to edit "${path}": ${message}` };
+        }
+    },
+};
+/** 把 hashline ApplyResult 失败分支格式化为对 agent 有指导意义的错误信息。 */
+function formatHashlineError(path, result) {
+    if (result._tag === 'hash_mismatch') {
+        return `"${path}": hashline hash mismatch — the file changed since this patch was generated (expected ${result.expected}, actual ${result.actual}). Re-read the file and regenerate the patch with the current hash.`;
+    }
+    const op = result.operation;
+    const range = 'start' in op ? `${op.start}${op.end !== op.start ? `-${op.end}` : ''}` : '';
+    return `"${path}": hashline line range ${range} out of bounds for ${op._tag} operation.`;
+}
+/**
+ * Build a mapping from normalized string positions to original string positions.
+ * Used to map fuzzy match results back to the original content.
+ */
+function buildPositionMapping(original, normalized) {
+    const map = new Map();
+    let origIdx = 0;
+    let normIdx = 0;
+    while (origIdx < original.length && normIdx < normalized.length) {
+        map.set(normIdx, origIdx);
+        if (original[origIdx] === normalized[normIdx]) {
+            origIdx++;
+            normIdx++;
+        }
+        else if (original[origIdx] === ' ' || original[origIdx] === '\t') {
+            // Original has whitespace that was collapsed
+            origIdx++;
+        }
+        else {
+            // Shouldn't happen with proper normalization
+            origIdx++;
+            normIdx++;
+        }
+    }
+    // Map the end position
+    map.set(normIdx, origIdx);
+    return map;
+}

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

@@ -0,0 +1,11 @@
+import type { ToolDef } from '../../shared/types/tool.js';
+/**
+ * Convert a glob pattern to a RegExp.
+ * Supports: * (single segment), ** (across segments), ? (single char), {a,b} (alternation), [abc] (char class).
+ */
+export declare function globToRegex(pattern: string): RegExp;
+/**
+ * glob tool: find files matching a glob pattern.
+ * Permission: auto (read-only).
+ */
+export declare const globTool: ToolDef;