hyacinth-ai 0.9.6

package/dist/tools/multi-edit.js

@@ -0,0 +1,146 @@
+import { promises as fs } from 'node:fs';
+import { GlobTool } from './glob.js';
+import { getLastReadTime, recordFileWrite } from './file-tracker.js';
+import { runDiagnostics } from './diagnostics.js';
+export class MultiEditTool {
+    name = 'multi_edit';
+    description = 'Performs search-and-replace across multiple files matching a glob pattern. ' +
+        'Supports dry_run preview mode. Default maximum 10 files. ' +
+        'Use replace_all=true to allow multiple replacements per file.';
+    inputSchema = {
+        type: 'object',
+        properties: {
+            glob: {
+                type: 'string',
+                description: 'File matching pattern (e.g., "src/**/*.ts")',
+            },
+            old_string: {
+                type: 'string',
+                description: 'The text to replace (must match exactly)',
+            },
+            new_string: {
+                type: 'string',
+                description: 'The text to replace it with',
+            },
+            max_files: {
+                type: 'number',
+                description: 'Maximum number of files to match. Defaults to 10.',
+            },
+            dry_run: {
+                type: 'boolean',
+                description: 'Preview mode — show what would be changed without writing. Defaults to false.',
+            },
+            replace_all: {
+                type: 'boolean',
+                description: 'Allow multiple replacements per file. Defaults to false.',
+            },
+        },
+        required: ['glob', 'old_string', 'new_string'],
+    };
+    async execute(args) {
+        const pattern = args.glob;
+        const oldString = args.old_string;
+        const newString = args.new_string;
+        const maxFiles = args.max_files ?? 10;
+        const dryRun = args.dry_run ?? false;
+        const replaceAll = args.replace_all ?? false;
+        const globTool = new GlobTool();
+        const globResult = await globTool.execute({ pattern });
+        const filePaths = globResult
+            .split('\n')
+            .map((p) => p.trim())
+            .filter((p) => p.length > 0);
+        if (filePaths.length === 0) {
+            return `No files matched the pattern "${pattern}".`;
+        }
+        if (filePaths.length > maxFiles) {
+            throw new Error(`Matched ${filePaths.length} files (${">"} ${maxFiles}). ` +
+                `Narrow your glob or increase max_files.`);
+        }
+        const plans = [];
+        for (const filePath of filePaths) {
+            let content;
+            try {
+                content = await fs.readFile(filePath, 'utf-8');
+            }
+            catch {
+                continue;
+            }
+            // ── Read-before-write 门控 ──
+            const lastRead = getLastReadTime(filePath);
+            if (lastRead === null) {
+                return `Error: You must read "${filePath}" before editing it. Use the read tool first.`;
+            }
+            try {
+                const stat = await fs.stat(filePath);
+                if (stat.mtimeMs > lastRead) {
+                    return `Error: "${filePath}" has been modified on disk since it was last read. Please re-read it first.`;
+                }
+            }
+            catch { }
+            const matchCount = this.countOccurrences(content, oldString);
+            if (matchCount === 0)
+                continue;
+            if (matchCount > 1 && !replaceAll) {
+                const basename = filePath.replace(/\\/g, '/').split('/').pop() || filePath;
+                throw new Error(`File "${basename}" has ${matchCount} matches. ` +
+                    `Use replace_all=true to replace all, or narrow your glob scope.`);
+            }
+            plans.push({ path: filePath, matchCount });
+        }
+        if (plans.length === 0) {
+            return `"${oldString}" was not found in any matched file.`;
+        }
+        if (dryRun) {
+            let preview = `Preview — ${plans.length} file${plans.length > 1 ? 's' : ''} would be modified:\n`;
+            let totalReplacements = 0;
+            for (const plan of plans) {
+                const basename = plan.path.replace(/\\/g, '/').split('/').pop() || plan.path;
+                preview += `${basename}: ${plan.matchCount} replacement${plan.matchCount > 1 ? 's' : ''}\n`;
+                totalReplacements += plan.matchCount;
+            }
+            preview += `---\nRun without dry_run to apply.`;
+            return preview;
+        }
+        let totalReplacements = 0;
+        for (const plan of plans) {
+            let content = await fs.readFile(plan.path, 'utf-8');
+            if (replaceAll) {
+                content = content.split(oldString).join(newString);
+            }
+            else {
+                const index = content.indexOf(oldString);
+                content =
+                    content.slice(0, index) + newString + content.slice(index + oldString.length);
+            }
+            await fs.writeFile(plan.path, content, 'utf-8');
+            recordFileWrite(plan.path);
+            totalReplacements += plan.matchCount;
+        }
+        let result = `Modified ${plans.length} file${plans.length > 1 ? 's' : ''} (${totalReplacements} replacement${totalReplacements > 1 ? 's' : ''} total):\n`;
+        for (const plan of plans) {
+            const basename = plan.path.replace(/\\/g, '/').split('/').pop() || plan.path;
+            result += `${basename}: ${plan.matchCount} replacement${plan.matchCount > 1 ? 's' : ''}\n`;
+        }
+        // ── 自动诊断：修改后运行类型检查/编译检查 ──
+        try {
+            const diag = await runDiagnostics(process.cwd(), 15000);
+            if (diag)
+                result += '\n\n' + diag;
+        }
+        catch { /* 诊断失败不影响工具返回值 */ }
+        return result;
+    }
+    countOccurrences(text, search) {
+        if (search.length === 0)
+            return 0;
+        let count = 0;
+        let pos = 0;
+        while ((pos = text.indexOf(search, pos)) !== -1) {
+            count++;
+            pos += search.length;
+        }
+        return count;
+    }
+}
+//# sourceMappingURL=multi-edit.js.map

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

@@ -0,0 +1,14 @@
+import type { Tool } from './interface.js';
+/**
+ * 为工具创建路径沙箱包装。
+ * 对 read/write/edit/grep/glob: 校验并解析路径参数到 sandboxRoot 下。
+ * 对 bash: 直接拒绝（沙箱模式下不允许执行任意命令）。
+ * 其他工具: 原样透传。
+ */
+export declare function createSandboxedTool(tool: Tool, sandboxRoot: string): Tool;
+/**
+ * 批量包装工具注册表中的路径敏感工具。
+ * 返回一个新 Map（不修改原 registry）。
+ */
+export declare function wrapSandboxedTools(tools: Tool[], sandboxRoot: string): Tool[];
+//# sourceMappingURL=path-sandbox.d.ts.map

package/dist/tools/path-sandbox.js

@@ -0,0 +1,60 @@
+import path from 'node:path';
+/** 各工具类型对应的路径参数名 */
+const PATH_PARAMS = {
+    read: ['file_path'],
+    write: ['file_path'],
+    edit: ['file_path'],
+    grep: ['path'],
+    glob: ['path'],
+};
+/**
+ * 为工具创建路径沙箱包装。
+ * 对 read/write/edit/grep/glob: 校验并解析路径参数到 sandboxRoot 下。
+ * 对 bash: 直接拒绝（沙箱模式下不允许执行任意命令）。
+ * 其他工具: 原样透传。
+ */
+export function createSandboxedTool(tool, sandboxRoot) {
+    const normalizedRoot = path.resolve(sandboxRoot);
+    const pathParams = PATH_PARAMS[tool.name];
+    // 沙箱模式下禁止 bash
+    if (tool.name === 'bash') {
+        return {
+            ...tool,
+            async execute(args) {
+                return 'Error: bash tool is not allowed in sub-agent sandbox mode. Use read/write/edit/grep/glob for file operations restricted to the sandbox directory.';
+            },
+        };
+    }
+    // 非路径敏感工具，原样返回
+    if (!pathParams || pathParams.length === 0) {
+        return tool;
+    }
+    return {
+        ...tool,
+        async execute(args) {
+            // 校验每个路径参数
+            for (const param of pathParams) {
+                const value = args[param];
+                if (value !== undefined && typeof value === 'string') {
+                    const resolved = path.resolve(normalizedRoot, value);
+                    // 检查是否在 sandboxRoot 内
+                    const rel = path.relative(normalizedRoot, resolved);
+                    if (rel.startsWith('..') || path.isAbsolute(rel)) {
+                        return `Error: path "${value}" resolves to "${resolved}" which is outside the sandbox directory "${normalizedRoot}". All file access must be within the project directory.`;
+                    }
+                    // 将相对路径替换为沙箱内的绝对路径
+                    args[param] = resolved;
+                }
+            }
+            return tool.execute(args);
+        },
+    };
+}
+/**
+ * 批量包装工具注册表中的路径敏感工具。
+ * 返回一个新 Map（不修改原 registry）。
+ */
+export function wrapSandboxedTools(tools, sandboxRoot) {
+    return tools.map(t => createSandboxedTool(t, sandboxRoot));
+}
+//# sourceMappingURL=path-sandbox.js.map

package/dist/tools/process-tools.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 后台进程管理工具 — process_list / process_kill / process_output
+ *
+ * 这些工具供模型控制由 bash(async: true) 启动的后台进程。
+ * 所有工具通过 BackgroundProcessRegistry 操作，保持安全管理。
+ */
+import type { Tool } from './interface.js';
+import type { BackgroundProcessRegistry } from './background-registry.js';
+/** 创建 process_list 工具：列出所有后台进程 */
+export declare function createProcessListTool(registry: BackgroundProcessRegistry): Tool;
+/** 创建 process_kill 工具：停止指定后台进程 */
+export declare function createProcessKillTool(registry: BackgroundProcessRegistry): Tool;
+/** 创建 process_output 工具：读取后台进程输出 */
+export declare function createProcessOutputTool(registry: BackgroundProcessRegistry): Tool;
+//# sourceMappingURL=process-tools.d.ts.map

package/dist/tools/process-tools.js

@@ -0,0 +1,95 @@
+/** 创建 process_list 工具：列出所有后台进程 */
+export function createProcessListTool(registry) {
+    return {
+        name: 'process_list',
+        description: 'List all background processes started with bash(async:true). ' +
+            'Returns handle, command, PID, status (running/stopped/crashed), start time, and output buffer size for each.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+        },
+        async execute() {
+            const processes = registry.list();
+            if (processes.length === 0)
+                return '(no background processes)';
+            const lines = [];
+            lines.push(`${'HANDLE'.padEnd(8)} ${'PID'.padEnd(8)} ${'STATUS'.padEnd(8)} ${'OUTPUT'.padEnd(8)} COMMAND`);
+            lines.push('-'.repeat(80));
+            for (const p of processes) {
+                const handle = p.handle.padEnd(8);
+                const pid = String(p.pid ?? '?').padEnd(8);
+                const status = p.status.padEnd(8);
+                const output = `${p.outputSize} lines`.padEnd(8);
+                lines.push(`${handle} ${pid} ${status} ${output} ${p.command}`);
+            }
+            return lines.join('\n');
+        },
+    };
+}
+/** 创建 process_kill 工具：停止指定后台进程 */
+export function createProcessKillTool(registry) {
+    return {
+        name: 'process_kill',
+        description: 'Stop a background process by its handle (e.g. "bg_001"). ' +
+            'Kills the process tree. Use process_list to see available handles.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                handle: {
+                    type: 'string',
+                    description: 'The background process handle (e.g. "bg_001"). Get from process_list.',
+                },
+            },
+            required: ['handle'],
+        },
+        async execute(args) {
+            const handle = args.handle;
+            if (!handle)
+                return 'Error: "handle" parameter is required.';
+            const killed = await registry.kill(handle);
+            if (killed)
+                return `Process ${handle} stopped.`;
+            return `No process found for handle: ${handle}`;
+        },
+    };
+}
+/** 创建 process_output 工具：读取后台进程输出 */
+export function createProcessOutputTool(registry) {
+    return {
+        name: 'process_output',
+        description: 'Read the captured stdout/stderr output of a background process. ' +
+            'Returns up to 1000 lines of buffered output. Use process_list to see available handles.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                handle: {
+                    type: 'string',
+                    description: 'The background process handle (e.g. "bg_001"). Get from process_list.',
+                },
+            },
+            required: ['handle'],
+        },
+        async execute(args) {
+            const handle = args.handle;
+            if (!handle)
+                return 'Error: "handle" parameter is required.';
+            const status = registry.getStatus(handle);
+            if (!status) {
+                return `No process found for handle: ${handle}. Use process_list to see running processes.`;
+            }
+            const output = registry.getOutput(handle);
+            const header = `[${handle}] PID ${status.pid ?? '?'} | ${status.status} | started ${status.startTime}`;
+            if (!output || output === '(no output yet)') {
+                return `${header}\n(no output captured yet — process may still be starting)`;
+            }
+            // 截断过长的输出
+            const maxChars = 200_000; // ToolResultBuffer handles context protection
+            if (output.length > maxChars) {
+                return `${header}\n${output.slice(0, maxChars)}\n\n[Output truncated: ${output.length - maxChars} more characters]`;
+            }
+            return `${header}\n${output}`;
+        },
+    };
+}
+//# sourceMappingURL=process-tools.js.map

package/dist/tools/python-bridge/bridge.d.ts

@@ -0,0 +1,24 @@
+import type { Tool } from '../interface.js';
+import { type PythonToolMeta } from './parser.js';
+/**
+ * PythonToolBridge — 将 Python 脚本桥接为 Tool 接口。
+ *
+ * 解析阶段（tool-watcher 触发）:
+ *   → parsePythonToolMeta(filePath) → PythonToolMeta
+ *   → new PythonToolBridge(filePath, meta)
+ *   → ToolRegistry.register(bridge)
+ *
+ * 执行阶段（Agent 调用时）:
+ *   → bridge.execute(args) → executePython(filePath, args) → 返回 stdout
+ */
+export declare class PythonToolBridge implements Tool {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: Record<string, unknown>;
+    private filePath;
+    constructor(filePath: string, meta: PythonToolMeta);
+    /** 工厂：从文件路径创建 Bridge（含解析） */
+    static fromFile(filePath: string): PythonToolBridge | null;
+    execute(args: Record<string, unknown>): Promise<string>;
+}
+//# sourceMappingURL=bridge.d.ts.map

package/dist/tools/python-bridge/bridge.js

@@ -0,0 +1,39 @@
+import { executePython } from './executor.js';
+import { parsePythonToolMeta } from './parser.js';
+import { createLogger } from '../../logging/logger.js';
+const logger = createLogger('python-bridge');
+/**
+ * PythonToolBridge — 将 Python 脚本桥接为 Tool 接口。
+ *
+ * 解析阶段（tool-watcher 触发）:
+ *   → parsePythonToolMeta(filePath) → PythonToolMeta
+ *   → new PythonToolBridge(filePath, meta)
+ *   → ToolRegistry.register(bridge)
+ *
+ * 执行阶段（Agent 调用时）:
+ *   → bridge.execute(args) → executePython(filePath, args) → 返回 stdout
+ */
+export class PythonToolBridge {
+    name;
+    description;
+    inputSchema;
+    filePath;
+    constructor(filePath, meta) {
+        this.filePath = filePath;
+        this.name = meta.name;
+        this.description = meta.description;
+        this.inputSchema = meta.inputSchema;
+    }
+    /** 工厂：从文件路径创建 Bridge（含解析） */
+    static fromFile(filePath) {
+        const meta = parsePythonToolMeta(filePath);
+        if (!meta)
+            return null;
+        return new PythonToolBridge(filePath, meta);
+    }
+    async execute(args) {
+        logger.debug(`Executing Python tool: ${this.name} (${this.filePath})`);
+        return executePython(this.filePath, args);
+    }
+}
+//# sourceMappingURL=bridge.js.map

package/dist/tools/python-bridge/executor.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 执行 Python 脚本，传入 JSON 参数，返回 stdout。
+ * 超时或非零退出码时返回错误。
+ */
+export declare function executePython(filePath: string, args: Record<string, unknown>): Promise<string>;
+//# sourceMappingURL=executor.d.ts.map

package/dist/tools/python-bridge/executor.js

@@ -0,0 +1,69 @@
+import { spawn } from 'node:child_process';
+import { createLogger } from '../../logging/logger.js';
+const logger = createLogger('python-executor');
+const MAX_OUTPUT_BYTES = 100 * 1024; // 100KB
+const DEFAULT_TIMEOUT_MS = 60_000; // 60s
+/**
+ * 执行 Python 脚本，传入 JSON 参数，返回 stdout。
+ * 超时或非零退出码时返回错误。
+ */
+export function executePython(filePath, args) {
+    return new Promise((resolve) => {
+        const python = findPython();
+        const child = spawn(python, [filePath], {
+            env: { ...process.env, PYTHONIOENCODING: 'utf-8', PYTHONUTF8: '1' },
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        const input = JSON.stringify(args);
+        let stdout = '';
+        let stderr = '';
+        let killed = false;
+        const timer = setTimeout(() => {
+            killed = true;
+            child.kill();
+            resolve(`Error: Python tool timed out after ${DEFAULT_TIMEOUT_MS / 1000}s`);
+        }, DEFAULT_TIMEOUT_MS);
+        child.stdin.write(input);
+        child.stdin.end();
+        child.stdout.on('data', (data) => {
+            stdout += data.toString();
+            if (stdout.length > MAX_OUTPUT_BYTES) {
+                killed = true;
+                child.kill();
+            }
+        });
+        child.stderr.on('data', (data) => {
+            stderr += data.toString();
+        });
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            if (killed) {
+                if (stdout.length > MAX_OUTPUT_BYTES) {
+                    resolve(`Error: Python tool output exceeded ${MAX_OUTPUT_BYTES / 1024}KB limit`);
+                }
+                return;
+            }
+            if (code !== 0) {
+                logger.warn(`Python tool ${filePath} exited with code ${code}: ${stderr.slice(0, 500)}`);
+                resolve(`Error (exit ${code}): ${stderr.slice(0, 1000) || 'Unknown error'}`);
+                return;
+            }
+            resolve(stdout.trimEnd());
+        });
+        child.on('error', (err) => {
+            clearTimeout(timer);
+            resolve(`Error: Cannot execute python: ${err.message}`);
+        });
+    });
+}
+function findPython() {
+    // 优先虚拟环境 → python3 → python
+    if (process.platform === 'win32') {
+        const venv = process.env.VIRTUAL_ENV || process.env.CONDA_PREFIX;
+        if (venv)
+            return `${venv}/Scripts/python.exe`;
+        return 'python';
+    }
+    return 'python3';
+}
+//# sourceMappingURL=executor.js.map

package/dist/tools/python-bridge/index.d.ts

@@ -0,0 +1,5 @@
+export { PythonToolBridge } from './bridge.js';
+export { parsePythonToolMeta } from './parser.js';
+export type { PythonToolMeta } from './parser.js';
+export { executePython } from './executor.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/python-bridge/index.js

@@ -0,0 +1,4 @@
+export { PythonToolBridge } from './bridge.js';
+export { parsePythonToolMeta } from './parser.js';
+export { executePython } from './executor.js';
+//# sourceMappingURL=index.js.map

package/dist/tools/python-bridge/parser.d.ts

@@ -0,0 +1,21 @@
+export interface PythonToolMeta {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}
+/**
+ * 从 Python 文件的 docstring 中解析工具元信息。
+ *
+ * 支持格式:
+ *   """
+ *   name: my_tool
+ *   description: 工具描述
+ *   parameters:
+ *     type: object
+ *     properties:
+ *       arg1: {type: string, description: 参数1}
+ *     required: [arg1]
+ *   """
+ */
+export declare function parsePythonToolMeta(filePath: string): PythonToolMeta | null;
+//# sourceMappingURL=parser.d.ts.map