hyacinth-ai 0.9.6

package/dist/tools/http-request.js

@@ -0,0 +1,126 @@
+/**
+ * HttpRequestTool — HTTP 客户端，支持 GET/POST/PUT/DELETE。
+ * 轻量爬虫 + API 调试。
+ */
+export class HttpRequestTool {
+    name = 'http_request';
+    description = 'Make HTTP requests. Supports GET, POST, PUT, DELETE with custom headers, body, timeout, and cookies. ' +
+        'Default User-Agent mimics a browser. Use for light web scraping, API debugging, and data fetching. ' +
+        'Returns status code, headers, and response body (truncated at 50KB).';
+    inputSchema = {
+        type: 'object',
+        properties: {
+            url: { type: 'string', description: 'The URL to request (http:// or https://)' },
+            method: {
+                type: 'string',
+                description: 'HTTP method. Default: GET',
+                enum: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS'],
+            },
+            headers: {
+                type: 'string',
+                description: 'JSON string of custom headers. Overrides defaults.',
+            },
+            body: {
+                type: 'string',
+                description: 'Request body as string. For JSON, set Content-Type header or use the json flag.',
+            },
+            timeout: {
+                type: 'number',
+                description: 'Timeout in milliseconds. Default: 30000 (30s). Max: 120000 (2 min).',
+            },
+            json: {
+                type: 'boolean',
+                description: 'If true, body is treated as JSON and Content-Type is set to application/json. Default: false.',
+            },
+        },
+        required: ['url'],
+    };
+    static DEFAULT_UA = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Safari/537.36';
+    static MAX_RESPONSE_BYTES = 50 * 1024; // 50KB
+    async execute(args) {
+        const url = args.url;
+        if (!url)
+            return 'Error: url is required.';
+        const method = (args.method ?? 'GET').toUpperCase();
+        const body = args.body;
+        const isJson = args.json === true;
+        const timeoutMs = Math.min(args.timeout ?? 30000, 120000);
+        // Parse custom headers
+        let customHeaders = {};
+        if (typeof args.headers === 'string' && args.headers.trim()) {
+            try {
+                customHeaders = JSON.parse(args.headers);
+            }
+            catch {
+                return 'Error: headers must be a valid JSON string.';
+            }
+        }
+        // Build final headers
+        const headers = {
+            'User-Agent': HttpRequestTool.DEFAULT_UA,
+            Accept: '*/*',
+        };
+        if (isJson) {
+            headers['Content-Type'] = 'application/json';
+        }
+        else if (body !== undefined && !customHeaders['Content-Type']) {
+            headers['Content-Type'] = 'text/plain';
+        }
+        Object.assign(headers, customHeaders);
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const fetchInit = {
+                method,
+                headers,
+                signal: controller.signal,
+            };
+            if (body !== undefined && method !== 'GET' && method !== 'HEAD') {
+                fetchInit.body = body;
+            }
+            const response = await fetch(url, fetchInit);
+            clearTimeout(timer);
+            const respHeaders = {};
+            response.headers.forEach((v, k) => { respHeaders[k] = v; });
+            let respBody = '';
+            if (response.body) {
+                const reader = response.body.getReader();
+                const decoder = new TextDecoder();
+                let totalBytes = 0;
+                while (true) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    totalBytes += value.length;
+                    respBody += decoder.decode(value, { stream: true });
+                    if (totalBytes > HttpRequestTool.MAX_RESPONSE_BYTES) {
+                        respBody += '\n... (response truncated at 50KB)';
+                        reader.cancel();
+                        break;
+                    }
+                }
+            }
+            const summary = [
+                `HTTP ${response.status} ${response.statusText}`,
+                `URL: ${url}`,
+                respHeaders['content-type']
+                    ? `Content-Type: ${respHeaders['content-type']}`
+                    : '',
+                respHeaders['content-length']
+                    ? `Content-Length: ${respHeaders['content-length']} bytes`
+                    : `Body: ${respBody.length} bytes`,
+                '',
+                respBody || '(empty response)',
+            ].filter(l => l !== '').join('\n');
+            return summary;
+        }
+        catch (err) {
+            clearTimeout(timer);
+            if (err.name === 'AbortError') {
+                return `Error: Request timed out after ${timeoutMs}ms`;
+            }
+            return `Error: ${err.message}`;
+        }
+    }
+}
+//# sourceMappingURL=http-request.js.map

package/dist/tools/index.d.ts

@@ -0,0 +1,43 @@
+export type { Tool } from './interface.js';
+export type { SandboxConfig } from './bash.js';
+export { ToolRegistry } from './registry.js';
+export { ReadTool } from './read.js';
+export { WriteTool } from './write.js';
+export { EditTool } from './edit.js';
+export { BashTool } from './bash.js';
+export { GlobTool } from './glob.js';
+export { GrepTool } from './grep.js';
+export { GitTool } from './git-tool.js';
+export { MultiEditTool } from './multi-edit.js';
+export { InsertTool } from './insert.js';
+export { RestartTool } from './restart.js';
+export { DiffFilesTool } from './diff-files.js';
+export { JsonEditTool } from './json-edit.js';
+export { HttpRequestTool } from './http-request.js';
+export { ArchiveTool } from './archive.js';
+export { DbQueryTool } from './db-query.js';
+export { DiskUsageTool } from './disk-usage.js';
+export { XrefManager, XrefBuildTool, XrefQueryTool, XrefGraphTool } from './xref/index.js';
+export { PythonToolBridge } from './python-bridge/index.js';
+export type { PythonToolMeta } from './python-bridge/index.js';
+export { ToolExecutor } from './executor.js';
+export { ToolResultBuffer } from './result-buffer.js';
+export type { ResultBufferConfig } from './result-buffer.js';
+import { ToolRegistry } from './registry.js';
+import type { SandboxConfig } from './bash.js';
+import type { GitManager } from '../evolution/git-manager.js';
+/**
+ * 创建包含所有内置工具的默认注册表（不包含 GitTool，需要 GitManager 实例）
+ * @param cwd BashTool 的工作目录，默认为 process.cwd()
+ * @param sandboxConfig 可选沙箱配置，传入后 BashTool 将启用命令拦截
+ */
+export declare function createDefaultRegistry(cwd?: string, sandboxConfig?: SandboxConfig): ToolRegistry;
+/**
+ * 创建包含所有内置工具的注册表（含 GitTool）
+ * @param gitManager GitManager 实例
+ * @param sessionId 可选 sessionId，用于 commit message 追溯
+ * @param cwd BashTool 的工作目录，默认为 process.cwd()
+ * @param sandboxConfig 可选沙箱配置
+ */
+export declare function createBuiltInTools(gitManager: GitManager, sessionId?: string, cwd?: string, sandboxConfig?: SandboxConfig): ToolRegistry;
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/index.js

@@ -0,0 +1,76 @@
+export { ToolRegistry } from './registry.js';
+export { ReadTool } from './read.js';
+export { WriteTool } from './write.js';
+export { EditTool } from './edit.js';
+export { BashTool } from './bash.js';
+export { GlobTool } from './glob.js';
+export { GrepTool } from './grep.js';
+export { GitTool } from './git-tool.js';
+export { MultiEditTool } from './multi-edit.js';
+export { InsertTool } from './insert.js';
+export { RestartTool } from './restart.js';
+export { DiffFilesTool } from './diff-files.js';
+export { JsonEditTool } from './json-edit.js';
+export { HttpRequestTool } from './http-request.js';
+export { ArchiveTool } from './archive.js';
+export { DbQueryTool } from './db-query.js';
+export { DiskUsageTool } from './disk-usage.js';
+export { XrefManager, XrefBuildTool, XrefQueryTool, XrefGraphTool } from './xref/index.js';
+export { PythonToolBridge } from './python-bridge/index.js';
+export { ToolExecutor } from './executor.js';
+export { ToolResultBuffer } from './result-buffer.js';
+// === 创建默认工具注册表 ===
+import { ToolRegistry } from './registry.js';
+import { ReadTool } from './read.js';
+import { WriteTool } from './write.js';
+import { EditTool } from './edit.js';
+import { BashTool } from './bash.js';
+import { GlobTool } from './glob.js';
+import { GrepTool } from './grep.js';
+import { GitTool } from './git-tool.js';
+import { MultiEditTool } from './multi-edit.js';
+import { InsertTool } from './insert.js';
+import { RestartTool } from './restart.js';
+import { DiffFilesTool } from './diff-files.js';
+import { JsonEditTool } from './json-edit.js';
+import { HttpRequestTool } from './http-request.js';
+import { ArchiveTool } from './archive.js';
+import { DbQueryTool } from './db-query.js';
+import { DiskUsageTool } from './disk-usage.js';
+/**
+ * 创建包含所有内置工具的默认注册表（不包含 GitTool，需要 GitManager 实例）
+ * @param cwd BashTool 的工作目录，默认为 process.cwd()
+ * @param sandboxConfig 可选沙箱配置，传入后 BashTool 将启用命令拦截
+ */
+export function createDefaultRegistry(cwd, sandboxConfig) {
+    const registry = new ToolRegistry();
+    registry.register(new ReadTool());
+    registry.register(new WriteTool());
+    registry.register(new EditTool());
+    registry.register(new BashTool(cwd, sandboxConfig));
+    registry.register(new GlobTool());
+    registry.register(new GrepTool());
+    registry.register(new MultiEditTool());
+    registry.register(new InsertTool());
+    registry.register(new RestartTool(cwd ?? process.cwd()));
+    registry.register(new DiffFilesTool());
+    registry.register(new JsonEditTool());
+    registry.register(new HttpRequestTool());
+    registry.register(new ArchiveTool());
+    registry.register(new DbQueryTool());
+    registry.register(new DiskUsageTool(cwd));
+    return registry;
+}
+/**
+ * 创建包含所有内置工具的注册表（含 GitTool）
+ * @param gitManager GitManager 实例
+ * @param sessionId 可选 sessionId，用于 commit message 追溯
+ * @param cwd BashTool 的工作目录，默认为 process.cwd()
+ * @param sandboxConfig 可选沙箱配置
+ */
+export function createBuiltInTools(gitManager, sessionId, cwd, sandboxConfig) {
+    const registry = createDefaultRegistry(cwd, sandboxConfig);
+    registry.register(new GitTool(gitManager, sessionId));
+    return registry;
+}
+//# sourceMappingURL=index.js.map

package/dist/tools/injection-filter.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 清洗工具返回结果中的提示词注入内容。
+ * 在工具结果进入对话上下文之前调用，从源头阻断外部注入。
+ */
+export declare function sanitizeToolResult(content: string): string;
+//# sourceMappingURL=injection-filter.d.ts.map

package/dist/tools/injection-filter.js

@@ -0,0 +1,71 @@
+import { createLogger } from '../logging/logger.js';
+const logger = createLogger('injection-filter');
+/** 提示词注入检测模式 */
+const PATTERNS = [
+    // 英文
+    'ignore previous instructions',
+    'ignore all previous',
+    'disregard all',
+    'forget your instructions',
+    'you are now',
+    'new instructions:',
+    'your new task is',
+    'do not follow',
+    'do not obey',
+    'override your',
+    'bypass your',
+    // 中文
+    '忽略之前的指令',
+    '忽略之前的所有',
+    '忘记你的指令',
+    '你现在是',
+    '新的指令',
+    '不要按照',
+    '不要遵守',
+    '覆盖你的',
+    '绕过你的',
+    '你现在的任务是',
+];
+const SYSTEM_TAG_RE = /<system>[\s\S]*?<\/system>/gi;
+const IM_START_RE = /<\|im_start\|>system[\s\S]*?<\|im_end\|>/gi;
+const BRACKET_SYSTEM_RE = /^\s*\[(SYSTEM(?:\s+INSTRUCTION)?)\]\s*/gim;
+/**
+ * 清洗工具返回结果中的提示词注入内容。
+ * 在工具结果进入对话上下文之前调用，从源头阻断外部注入。
+ */
+export function sanitizeToolResult(content) {
+    if (!content || content.length === 0)
+        return content;
+    let text = content;
+    let stripped = false;
+    // 移除 XML/标记风格的 system 标签
+    const afterSystemTag = text.replace(SYSTEM_TAG_RE, '');
+    if (afterSystemTag !== text) {
+        text = afterSystemTag;
+        stripped = true;
+    }
+    const afterImStart = text.replace(IM_START_RE, '');
+    if (afterImStart !== text) {
+        text = afterImStart;
+        stripped = true;
+    }
+    const afterBracket = text.replace(BRACKET_SYSTEM_RE, '');
+    if (afterBracket !== text) {
+        text = afterBracket;
+        stripped = true;
+    }
+    // 移除已知注入模式
+    const lower = text.toLowerCase();
+    for (const pattern of PATTERNS) {
+        if (lower.includes(pattern.toLowerCase())) {
+            const re = new RegExp(pattern, 'gi');
+            text = text.replace(re, '');
+            stripped = true;
+        }
+    }
+    if (stripped) {
+        logger.warn('[Security] Stripped injection pattern from tool result');
+    }
+    return text;
+}
+//# sourceMappingURL=injection-filter.js.map

package/dist/tools/insert.d.ts

@@ -0,0 +1,13 @@
+import type { Tool } from './interface.js';
+/**
+ * InsertTool — 在文件指定行号处插入内容。
+ * line_number=0 或 "end" = 追加到末尾，line_number=1 = 开头，line_number=N = 第 N 行之前。
+ * 配合 grep（查找目标行号）使用。
+ */
+export declare class InsertTool implements Tool {
+    readonly name = "insert";
+    readonly description: string;
+    readonly inputSchema: Record<string, unknown>;
+    execute(args: Record<string, unknown>): Promise<string>;
+}
+//# sourceMappingURL=insert.d.ts.map

package/dist/tools/insert.js

@@ -0,0 +1,61 @@
+import { promises as fs } from 'node:fs';
+/**
+ * InsertTool — 在文件指定行号处插入内容。
+ * line_number=0 或 "end" = 追加到末尾，line_number=1 = 开头，line_number=N = 第 N 行之前。
+ * 配合 grep（查找目标行号）使用。
+ */
+export class InsertTool {
+    name = 'insert';
+    description = 'Insert content into a file at a specific line number. ' +
+        'line_number=1 inserts at the beginning. line_number=0 or "end" appends to the end (no need to read the file first). ' +
+        'Use grep to find the target line number for mid-file insertion.';
+    inputSchema = {
+        type: 'object',
+        properties: {
+            file_path: { type: 'string', description: 'The absolute path to the file' },
+            line_number: { oneOf: [
+                    { type: 'number', description: 'Line number (1-based). 0 or -1 = append to end.' },
+                    { type: 'string', enum: ['end'], description: '"end" = append to end' },
+                ] },
+            content: { type: 'string', description: 'Content to insert (can be multiple lines)' },
+        },
+        required: ['file_path', 'line_number', 'content'],
+    };
+    async execute(args) {
+        const filePath = args.file_path;
+        const content = args.content;
+        const lineNum = args.line_number;
+        // 末尾追加
+        const isAppend = lineNum === 0 || lineNum === -1 || lineNum === 'end';
+        if (isAppend) {
+            const fh = await fs.open(filePath, 'a');
+            await fh.write(content);
+            await fh.close();
+            const lines = content.split('\n').length;
+            return `Appended ${lines} line(s) to end of ${filePath}`;
+        }
+        const lineNumber = typeof lineNum === 'string' ? parseInt(lineNum, 10) : lineNum;
+        if (isNaN(lineNumber) || lineNumber < 1) {
+            throw new Error(`line_number must be ≥ 1 for insertion, or 0/"end" for append. Got: ${lineNum}`);
+        }
+        let text;
+        try {
+            text = await fs.readFile(filePath, 'utf-8');
+        }
+        catch {
+            throw new Error(`File not found: ${filePath}`);
+        }
+        const lines = text.split('\n');
+        if (lines.length > 0 && lines[lines.length - 1] === '')
+            lines.pop();
+        if (lineNumber > lines.length + 1) {
+            throw new Error(`line_number ${lineNumber} is out of range. File has ${lines.length} lines. ` +
+                `Valid range: 1-${lines.length + 1} (use 0 or "end" to append).`);
+        }
+        const insertLines = content.split('\n');
+        lines.splice(lineNumber - 1, 0, ...insertLines);
+        await fs.writeFile(filePath, lines.join('\n') + '\n', 'utf-8');
+        return `Inserted ${insertLines.length} line(s) at line ${lineNumber} in ${filePath}`;
+    }
+}
+//# sourceMappingURL=insert.js.map

package/dist/tools/interface.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Tool 接口定义
+ * 所有内置工具和自定义工具都必须实现此接口
+ */
+export interface Tool {
+    /** 工具名称，全局唯一标识 */
+    name: string;
+    /** 工具描述，供 LLM 理解工具用途 */
+    description: string;
+    /** 陪伴模式下的工具描述（可选）。未提供时沿用 description。
+     *  用于将工具调用包装为自然行为（如「向朋友道别」而非「退出陪伴模式」）。 */
+    companionDescription?: string;
+    /** 输入参数的 JSON Schema 定义 */
+    inputSchema: Record<string, unknown>;
+    /** 执行工具，返回结果文本。signal 可用于中断长时间运行的工具 */
+    execute(args: Record<string, unknown>, signal?: AbortSignal): Promise<string>;
+    /**
+     * 执行模式：
+     * - 'sync'（默认）: 阻塞等待工具完成，结果返回后继续
+     * - 'asyncable': 工具支持异步执行（通过 input 中的 async 参数控制），
+     *   异步模式下立即返回 handle，不阻塞后续工具和 LLM 轮次
+     */
+    executionMode?: 'sync' | 'asyncable';
+    /**
+     * 注入后台进程注册表（仅 asyncable 工具需要）。
+     * 由 factory 在组装阶段调用，工具实现方负责类型转换。
+     */
+    setBackgroundRegistry?(registry: unknown): void;
+}
+//# sourceMappingURL=interface.d.ts.map

package/dist/tools/interface.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=interface.js.map

package/dist/tools/json-edit.d.ts

@@ -0,0 +1,15 @@
+import type { Tool } from './interface.js';
+/**
+ * JsonEditTool — 读写 JSON/YAML/TOML 文件，按路径修改字段。
+ *
+ * 支持 JSON（原生）和 YAML/TOML（需 Node.js 解析）。
+ * 路径用点号分隔，如 "compilerOptions.target"。
+ * 写回时保留原始缩进格式。
+ */
+export declare class JsonEditTool implements Tool {
+    readonly name = "json_edit";
+    readonly description: string;
+    readonly inputSchema: Record<string, unknown>;
+    execute(args: Record<string, unknown>): Promise<string>;
+}
+//# sourceMappingURL=json-edit.d.ts.map

package/dist/tools/json-edit.js

@@ -0,0 +1,122 @@
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * JsonEditTool — 读写 JSON/YAML/TOML 文件，按路径修改字段。
+ *
+ * 支持 JSON（原生）和 YAML/TOML（需 Node.js 解析）。
+ * 路径用点号分隔，如 "compilerOptions.target"。
+ * 写回时保留原始缩进格式。
+ */
+export class JsonEditTool {
+    name = 'json_edit';
+    description = 'Read or modify a key in a JSON, YAML, or TOML file by path. ' +
+        'Path uses dot notation (e.g. "compilerOptions.target"). ' +
+        'Without a value, reads the current value at the path. ' +
+        'With a value, sets the key and writes the file back preserving formatting. ' +
+        'Supports nested objects, array elements, and deep paths.';
+    inputSchema = {
+        type: 'object',
+        properties: {
+            file: { type: 'string', description: 'Path to the JSON/YAML/TOML file (absolute or relative to cwd)' },
+            path: { type: 'string', description: 'Dot-separated key path (e.g. "dependencies.express")' },
+            value: { type: 'string', description: 'New value to set. If omitted, returns current value. JSON values allowed.' },
+        },
+        required: ['file', 'path'],
+    };
+    async execute(args) {
+        const filePath = args.file;
+        const keyPath = args.path;
+        const rawValue = args.value;
+        const isRead = rawValue === undefined;
+        if (!filePath || !keyPath)
+            return 'Error: Both file and path are required.';
+        const cwd = process.cwd();
+        const absPath = path.isAbsolute(filePath) ? filePath : path.resolve(cwd, filePath);
+        let content;
+        try {
+            content = fs.readFileSync(absPath, 'utf-8');
+        }
+        catch {
+            return `Error: Cannot read file: ${absPath}`;
+        }
+        const ext = path.extname(absPath).toLowerCase();
+        const isJson = ext === '.json';
+        const isYaml = ext === '.yaml' || ext === '.yml';
+        const isToml = ext === '.toml';
+        // Parse
+        let parsed;
+        try {
+            if (isJson) {
+                parsed = JSON.parse(content);
+            }
+            else if (isYaml || isToml) {
+                return 'Error: YAML/TOML support requires Node.js YAML/TOML parsers. ' +
+                    'Install yaml/toml packages or convert to JSON.';
+            }
+            else {
+                // Try JSON as fallback
+                try {
+                    parsed = JSON.parse(content);
+                }
+                catch {
+                    return `Error: Unsupported file format "${ext}". Use .json, .yaml, or .toml.`;
+                }
+            }
+        }
+        catch (e) {
+            return `Error: Failed to parse file: ${e.message}`;
+        }
+        // Navigate to path
+        const keys = keyPath.split('.');
+        let current = parsed;
+        for (let i = 0; i < keys.length - 1; i++) {
+            const k = keys[i];
+            if (current[k] === undefined) {
+                if (isRead)
+                    return `Key "${keys.slice(0, i + 1).join('.')}" not found.`;
+                current[k] = {};
+            }
+            if (typeof current[k] !== 'object' || current[k] === null) {
+                return `Error: "${keys.slice(0, i + 1).join('.')}" is not an object (got ${typeof current[k]}).`;
+            }
+            current = current[k];
+        }
+        const leafKey = keys[keys.length - 1];
+        if (isRead) {
+            const val = current[leafKey];
+            if (val === undefined)
+                return `Key "${keyPath}" not found.`;
+            return JSON.stringify(val, null, 2);
+        }
+        // Write: parse value (try JSON, fallback to string)
+        let newValue = rawValue;
+        try {
+            newValue = JSON.parse(rawValue);
+        }
+        catch { /* use raw string */ }
+        // If the new value starts with { or [, try to parse as JSON inline
+        if (typeof rawValue === 'string') {
+            const trimmed = rawValue.trim();
+            if ((trimmed.startsWith('{') && trimmed.endsWith('}')) ||
+                (trimmed.startsWith('[') && trimmed.endsWith(']'))) {
+                try {
+                    newValue = JSON.parse(trimmed);
+                }
+                catch { /* keep as string */ }
+            }
+        }
+        current[leafKey] = newValue;
+        // Write back with minimal diff: detect original indent
+        const indentMatch = content.match(/\n(\s+)/);
+        const indent = indentMatch ? indentMatch[1].length : 2;
+        const newContent = JSON.stringify(parsed, null, indent) + '\n';
+        try {
+            fs.writeFileSync(absPath, newContent, 'utf-8');
+        }
+        catch (e) {
+            return `Error: Cannot write file: ${e.message}`;
+        }
+        return `Set "${keyPath}" to ${JSON.stringify(newValue)} in ${absPath}`;
+    }
+}
+//# sourceMappingURL=json-edit.js.map

package/dist/tools/multi-edit.d.ts

@@ -0,0 +1,9 @@
+import type { Tool } from './interface.js';
+export declare class MultiEditTool implements Tool {
+    readonly name = "multi_edit";
+    readonly description: string;
+    readonly inputSchema: Record<string, unknown>;
+    execute(args: Record<string, unknown>): Promise<string>;
+    private countOccurrences;
+}
+//# sourceMappingURL=multi-edit.d.ts.map