hyacinth-ai 0.9.6

package/dist/tools/archive.js

@@ -0,0 +1,131 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * ArchiveTool — 解压/压缩 zip、tar.gz、tar.bz2 归档。
+ *
+ * 解压时使用系统自带命令（Windows tar / Unix tar+unzip）。
+ * 压缩时创建 tar.gz 或 zip。
+ */
+export class ArchiveTool {
+    name = 'archive';
+    description = 'Compress or extract archives (zip, tar.gz, tar.bz2). ' +
+        'Action "extract" unpacks to a target directory. ' +
+        'Action "compress" creates an archive from a source directory or file list. ' +
+        'Uses system tools (tar, zip) for reliable operation.';
+    inputSchema = {
+        type: 'object',
+        properties: {
+            action: {
+                type: 'string',
+                description: 'extract (unpack an archive) or compress (create an archive)',
+                enum: ['extract', 'compress'],
+            },
+            file: {
+                type: 'string',
+                description: 'Path to the archive file. For extract: the file to unpack. For compress: the output archive path.',
+            },
+            target: {
+                type: 'string',
+                description: 'For extract: directory to extract into (default: same dir as archive). For compress: source file/directory to compress.',
+            },
+        },
+        required: ['action', 'file'],
+    };
+    async execute(args) {
+        const action = args.action;
+        const file = args.file;
+        const target = args.target;
+        if (!action || !file)
+            return 'Error: action and file are required.';
+        const cwd = process.cwd();
+        const absFile = path.isAbsolute(file) ? file : path.resolve(cwd, file);
+        const absTarget = target ? (path.isAbsolute(target) ? target : path.resolve(cwd, target)) : undefined;
+        if (action === 'extract') {
+            return this.extract(absFile, absTarget);
+        }
+        else if (action === 'compress') {
+            if (!absTarget)
+                return 'Error: target is required for compress action.';
+            return this.compress(absFile, absTarget);
+        }
+        return `Error: Unknown action "${action}". Use extract or compress.`;
+    }
+    async extract(archiveFile, targetDir) {
+        if (!fs.existsSync(archiveFile)) {
+            return `Error: Archive file not found: ${archiveFile}`;
+        }
+        const destDir = targetDir ?? path.join(path.dirname(archiveFile), path.basename(archiveFile).replace(/\.(tar\.gz|tar\.bz2|tgz|tbz2|tar|zip)$/i, ''));
+        if (!fs.existsSync(destDir)) {
+            fs.mkdirSync(destDir, { recursive: true });
+        }
+        const ext = path.basename(archiveFile).toLowerCase();
+        if (ext.endsWith('.tar.gz') || ext.endsWith('.tgz') || ext.endsWith('.tar.bz2') || ext.endsWith('.tbz2') || ext.endsWith('.tar')) {
+            return this.execCommand('tar', ['-xf', archiveFile, '-C', destDir], `Extracted to ${destDir}`);
+        }
+        else if (ext.endsWith('.zip')) {
+            // Try PowerShell on Windows, unzip on Unix
+            if (process.platform === 'win32') {
+                return this.execCommand('powershell', [
+                    '-Command',
+                    `Expand-Archive -Path "${archiveFile}" -DestinationPath "${destDir}" -Force`,
+                ], `Extracted to ${destDir}`);
+            }
+            return this.execCommand('unzip', ['-o', archiveFile, '-d', destDir], `Extracted to ${destDir}`);
+        }
+        return `Error: Unsupported archive format. Use .zip, .tar.gz, .tar.bz2, or .tar`;
+    }
+    async compress(outputFile, source) {
+        if (!fs.existsSync(source)) {
+            return `Error: Source not found: ${source}`;
+        }
+        const parentDir = path.dirname(outputFile);
+        if (!fs.existsSync(parentDir)) {
+            fs.mkdirSync(parentDir, { recursive: true });
+        }
+        const sourceName = path.basename(source);
+        const sourceDir = path.dirname(source);
+        const ext = outputFile.toLowerCase();
+        if (ext.endsWith('.tar.gz') || ext.endsWith('.tgz')) {
+            return this.execCommand('tar', ['-czf', outputFile, '-C', sourceDir, sourceName], `Created ${outputFile}`);
+        }
+        else if (ext.endsWith('.tar.bz2') || ext.endsWith('.tbz2')) {
+            return this.execCommand('tar', ['-cjf', outputFile, '-C', sourceDir, sourceName], `Created ${outputFile}`);
+        }
+        else if (ext.endsWith('.tar')) {
+            return this.execCommand('tar', ['-cf', outputFile, '-C', sourceDir, sourceName], `Created ${outputFile}`);
+        }
+        else if (ext.endsWith('.zip')) {
+            if (process.platform === 'win32') {
+                return this.execCommand('powershell', [
+                    '-Command',
+                    `Compress-Archive -Path "${source}" -DestinationPath "${outputFile}" -Force`,
+                ], `Created ${outputFile}`);
+            }
+            return this.execCommand('zip', ['-r', outputFile, sourceName], `Created ${outputFile}`);
+        }
+        return `Error: Unsupported archive format. Use .zip, .tar.gz, .tar.bz2, or .tar`;
+    }
+    execCommand(cmd, args, okPrefix) {
+        return new Promise((resolve) => {
+            const child = spawn(cmd, args, {
+                shell: process.platform === 'win32',
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+            let stderr = '';
+            child.stderr.on('data', (d) => { stderr += d.toString(); });
+            child.on('close', (code) => {
+                if (code === 0) {
+                    resolve(okPrefix);
+                }
+                else {
+                    resolve(`Error: ${cmd} exited with code ${code}. ${stderr.slice(0, 500)}`);
+                }
+            });
+            child.on('error', (err) => {
+                resolve(`Error: Cannot run ${cmd}: ${err.message}. Is it installed?`);
+            });
+        });
+    }
+}
+//# sourceMappingURL=archive.js.map

package/dist/tools/ask-user.d.ts

@@ -0,0 +1,9 @@
+import type { Tool } from './interface.js';
+import type { AskUserQuestion } from '../orchestrator/loop.js';
+export type { AskUserQuestion } from '../orchestrator/loop.js';
+/** 工具依赖：调用 OutputHandler.onAskUser 的函数 */
+export type AskUserFn = (questions: AskUserQuestion[]) => Promise<string>;
+/** TUI 启动后由 tui.ts 调用，将 onAskUser 的实现注入到工具中 */
+export declare function setAskUserHandler(handler: AskUserFn): void;
+export declare function createAskUserTool(): Tool;
+//# sourceMappingURL=ask-user.d.ts.map

package/dist/tools/ask-user.js

@@ -0,0 +1,62 @@
+// ============================================================
+// ask_user — 向用户展示交互式多问题表单
+// ============================================================
+let askUserHandler = null;
+/** TUI 启动后由 tui.ts 调用，将 onAskUser 的实现注入到工具中 */
+export function setAskUserHandler(handler) {
+    askUserHandler = handler;
+}
+export function createAskUserTool() {
+    return {
+        name: 'ask_user',
+        description: 'Pause execution to ask the user structured questions. Shows an interactive form with multiple questions, multi-select options, and custom text input. Use this when you need to clarify requirements, gather preferences, or confirm choices before proceeding.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                questions: {
+                    type: 'array',
+                    description: 'Questions to ask the user',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            question: {
+                                type: 'string',
+                                description: 'The question text to display',
+                            },
+                            header: {
+                                type: 'string',
+                                description: 'Optional short label for the tab (max 12 chars)',
+                            },
+                            options: {
+                                type: 'array',
+                                items: { type: 'string' },
+                                description: 'Available choices (empty = custom text input only)',
+                            },
+                            multiSelect: {
+                                type: 'boolean',
+                                description: 'Allow selecting multiple options (default: false = single choice)',
+                            },
+                            customInput: {
+                                type: 'boolean',
+                                description: 'Show a free-text input below the options',
+                            },
+                        },
+                        required: ['question'],
+                    },
+                },
+            },
+            required: ['questions'],
+        },
+        async execute(args) {
+            const questions = args.questions ?? [];
+            if (!questions || questions.length === 0) {
+                return JSON.stringify({ error: 'No questions provided.' });
+            }
+            if (!askUserHandler) {
+                return JSON.stringify({ error: 'Ask user handler not connected (TUI not active).' });
+            }
+            return askUserHandler(questions);
+        },
+    };
+}
+//# sourceMappingURL=ask-user.js.map

package/dist/tools/background-registry.d.ts

@@ -0,0 +1,45 @@
+/**
+ * BackgroundProcessRegistry — 后台进程注册表
+ *
+ * 管理异步工具启动的后台子进程（如 dev server），提供统一的
+ * 注册、查询、输出读取、终止和优雅关闭能力。
+ *
+ * 所有后台进程在会话结束时由 LifecycleSupervisor 统一清理。
+ */
+import { type ChildProcess } from 'node:child_process';
+export interface BackgroundProcessInfo {
+    handle: string;
+    name: string;
+    command: string;
+    pid: number | null;
+    status: 'running' | 'stopped' | 'crashed';
+    startTime: string;
+    outputSize: number;
+}
+export declare class BackgroundProcessRegistry {
+    private entries;
+    /**
+     * 注册一个后台子进程。生成唯一 handle 并开始捕获输出。
+     * @param name 工具名称（如 'bash'）
+     * @param command 原始命令（用于列表展示）
+     * @param childProcess 已 spawn 的子进程
+     * @returns handle 字符串（如 'bg_001'）
+     */
+    register(name: string, command: string, childProcess: ChildProcess): string;
+    /** 获取进程状态 */
+    getStatus(handle: string): BackgroundProcessInfo | null;
+    /** 获取进程输出 */
+    getOutput(handle: string): string;
+    /** 列出所有后台进程 */
+    list(): BackgroundProcessInfo[];
+    /** 停止指定进程 */
+    kill(handle: string): Promise<boolean>;
+    /** 停止所有后台进程（异步，用于优雅关闭） */
+    shutdownAll(): Promise<void>;
+    /**
+     * 同步强制杀死所有后台进程。
+     * 用于 exit handler（不能依赖异步），OS 最后防线。
+     */
+    forceKillAll(): void;
+}
+//# sourceMappingURL=background-registry.d.ts.map

package/dist/tools/background-registry.js

@@ -0,0 +1,164 @@
+/**
+ * BackgroundProcessRegistry — 后台进程注册表
+ *
+ * 管理异步工具启动的后台子进程（如 dev server），提供统一的
+ * 注册、查询、输出读取、终止和优雅关闭能力。
+ *
+ * 所有后台进程在会话结束时由 LifecycleSupervisor 统一清理。
+ */
+import { execSync } from 'node:child_process';
+import os from 'node:os';
+import { createLogger } from '../logging/logger.js';
+const logger = createLogger('background-registry');
+const isWindows = os.platform() === 'win32';
+let nextId = 1;
+/** 杀死进程树（同 BashTool） */
+function killProcessTree(pid) {
+    try {
+        if (isWindows) {
+            execSync(`taskkill /T /F /PID ${pid}`, { stdio: 'ignore', windowsHide: true });
+        }
+        else {
+            process.kill(-pid, 'SIGKILL');
+        }
+    }
+    catch {
+        try {
+            process.kill(pid, 'SIGKILL');
+        }
+        catch { /* already dead */ }
+    }
+}
+export class BackgroundProcessRegistry {
+    entries = new Map();
+    /**
+     * 注册一个后台子进程。生成唯一 handle 并开始捕获输出。
+     * @param name 工具名称（如 'bash'）
+     * @param command 原始命令（用于列表展示）
+     * @param childProcess 已 spawn 的子进程
+     * @returns handle 字符串（如 'bg_001'）
+     */
+    register(name, command, childProcess) {
+        const handle = `bg_${String(nextId++).padStart(3, '0')}`;
+        const entry = {
+            handle,
+            name,
+            command: command.length > 120 ? command.slice(0, 117) + '...' : command,
+            childProcess,
+            outputBuffer: [],
+            maxOutputLines: 1000,
+            startTime: new Date(),
+        };
+        // 捕获 stdout
+        childProcess.stdout?.on('data', (data) => {
+            const lines = data.toString().split('\n');
+            for (const line of lines) {
+                if (entry.outputBuffer.length >= entry.maxOutputLines) {
+                    entry.outputBuffer.shift();
+                }
+                entry.outputBuffer.push(line);
+            }
+        });
+        // 捕获 stderr（混入 output）
+        childProcess.stderr?.on('data', (data) => {
+            const lines = data.toString().split('\n');
+            for (const line of lines) {
+                if (entry.outputBuffer.length >= entry.maxOutputLines) {
+                    entry.outputBuffer.shift();
+                }
+                entry.outputBuffer.push(`[stderr] ${line}`);
+            }
+        });
+        // 进程退出时更新状态（进程保持 running 直到显式 kill）
+        childProcess.on('exit', (code, signal) => {
+            const existing = this.entries.get(handle);
+            if (existing) {
+                logger.debug(`Background process ${handle} (PID ${childProcess.pid}) exited: code=${code}, signal=${signal}`);
+            }
+        });
+        this.entries.set(handle, entry);
+        logger.debug(`Registered background process ${handle}: ${command.slice(0, 80)}`);
+        return handle;
+    }
+    /** 获取进程状态 */
+    getStatus(handle) {
+        const entry = this.entries.get(handle);
+        if (!entry)
+            return null;
+        const exited = entry.childProcess.exitCode !== null;
+        const killed = entry.childProcess.killed;
+        let status = 'running';
+        if (killed)
+            status = 'stopped';
+        else if (exited && entry.childProcess.exitCode !== 0)
+            status = 'crashed';
+        else if (exited)
+            status = 'stopped';
+        return {
+            handle: entry.handle,
+            name: entry.name,
+            command: entry.command,
+            pid: entry.childProcess.pid ?? null,
+            status,
+            startTime: entry.startTime.toISOString(),
+            outputSize: entry.outputBuffer.length,
+        };
+    }
+    /** 获取进程输出 */
+    getOutput(handle) {
+        const entry = this.entries.get(handle);
+        if (!entry)
+            return `No process found for handle: ${handle}`;
+        if (entry.outputBuffer.length === 0)
+            return '(no output yet)';
+        return entry.outputBuffer.join('\n');
+    }
+    /** 列出所有后台进程 */
+    list() {
+        const results = [];
+        for (const entry of this.entries.values()) {
+            const info = this.getStatus(entry.handle);
+            if (info)
+                results.push(info);
+        }
+        return results;
+    }
+    /** 停止指定进程 */
+    async kill(handle) {
+        const entry = this.entries.get(handle);
+        if (!entry)
+            return false;
+        const pid = entry.childProcess.pid;
+        if (pid) {
+            killProcessTree(pid);
+        }
+        this.entries.delete(handle);
+        logger.debug(`Killed background process ${handle}`);
+        return true;
+    }
+    /** 停止所有后台进程（异步，用于优雅关闭） */
+    async shutdownAll() {
+        const handles = [...this.entries.keys()];
+        for (const handle of handles) {
+            await this.kill(handle);
+        }
+        logger.debug(`Shutdown all background processes (${handles.length} total)`);
+    }
+    /**
+     * 同步强制杀死所有后台进程。
+     * 用于 exit handler（不能依赖异步），OS 最后防线。
+     */
+    forceKillAll() {
+        for (const entry of this.entries.values()) {
+            const pid = entry.childProcess.pid;
+            if (pid) {
+                try {
+                    killProcessTree(pid);
+                }
+                catch { /* best effort */ }
+            }
+        }
+        this.entries.clear();
+    }
+}
+//# sourceMappingURL=background-registry.js.map

package/dist/tools/bash.d.ts

@@ -0,0 +1,56 @@
+import type { Tool } from './interface.js';
+import type { BackgroundProcessRegistry } from './background-registry.js';
+/** 沙箱配置接口 — 限制 BashTool 可执行的命令 */
+export interface SandboxConfig {
+    /** @deprecated 路径白名单已废弃，不再限制工作目录 */
+    allowedPaths?: string[];
+    /** 危险命令黑名单（大小写不敏感子串匹配） */
+    blockedCommands: string[];
+    /** 最大输出字节数，默认 1MB */
+    maxOutputBytes?: number;
+}
+/**
+ * BashTool — 在子进程中执行命令
+ *
+ * 参数：
+ * - command (必需): 要执行的命令
+ * - timeout (可选): 超时时间（秒），默认 600
+ * - env (可选): 环境变量映射，会自动持久化到后续调用
+ *
+ * 平台适配：
+ * - Windows: 命令写入临时 .ps1 文件，powershell -File 直接执行
+ * - Linux/macOS: 使用 /bin/sh 执行
+ *
+ * 返回 stdout + stderr，超时后终止进程树
+ * 工作目录为当前 Agent 的工作目录
+ */
+export declare class BashTool implements Tool {
+    readonly name = "bash";
+    readonly description = "Execute a shell command and return stdout/stderr. On Windows, commands natively run in PowerShell \u2014 do NOT prefix with \"powershell -Command\". On Linux/macOS, commands run in /bin/sh. Set async=true for background execution.";
+    readonly inputSchema: Record<string, unknown>;
+    readonly executionMode = "asyncable";
+    private cwd;
+    private sandboxConfig;
+    private persistentEnv;
+    private backgroundRegistry?;
+    private allowAsync;
+    constructor(cwd?: string, sandboxConfig?: SandboxConfig);
+    /** 更新工作目录 */
+    setCwd(cwd: string): void;
+    /** 运行时更新沙箱配置 */
+    setSandboxConfig(config: SandboxConfig): void;
+    /** 注入后台进程注册表（用于 async 模式） */
+    setBackgroundRegistry(registry: BackgroundProcessRegistry): void;
+    /** 是否允许 async 模式（默认 true，可通过 tools.allowAsync 配置关闭） */
+    setAllowAsync(allow: boolean): void;
+    /** 获取当前沙箱配置（只读） */
+    getSandboxConfig(): Readonly<SandboxConfig>;
+    /**
+     * 杀死进程树
+     * - Windows: 使用 taskkill /T /F /PID
+     * - Unix: 使用 process.kill(-pid) 杀进程组
+     */
+    private killProcessTree;
+    execute(args: Record<string, unknown>, signal?: AbortSignal): Promise<string>;
+}
+//# sourceMappingURL=bash.d.ts.map