hyacinth-ai 0.9.6

package/dist/tools/edit.js

@@ -0,0 +1,235 @@
+import { promises as fs } from 'node:fs';
+import { computeDiff } from '../utils/diff.js';
+import { pushDiff } from './diff-channel.js';
+import { getLastReadTime, recordFileWrite } from './file-tracker.js';
+import { runDiagnostics } from './diagnostics.js';
+import { autoReferenceCheck } from './symbol-references.js';
+/**
+ * EditTool — 在文件中精确替换匹配的字符串 或 按行号替换
+ *
+ * 支持两种模式（互斥）：
+ *
+ * 模式一：字符串替换（原有逻辑）
+ * - old_string (必需): 要被替换的字符串
+ * - new_string (必需): 替换后的字符串
+ * - replace_all (可选): 是否替换所有匹配，默认 false
+ *
+ * 模式二：行号替换（新增）
+ * - line_start (必需): 替换起始行号 (1-based)
+ * - line_count (可选): 替换行数，默认 1
+ * - new_string (必需): 替换后的内容
+ */
+export class EditTool {
+    name = 'edit';
+    description = 'Performs exact string replacements in a file (' +
+        'old_string must uniquely match unless replace_all=true), ' +
+        'or replaces lines by line number using line_start/line_count. ' +
+        'line_start and old_string are mutually exclusive.';
+    companionDescription = '得改一下了。';
+    inputSchema = {
+        type: 'object',
+        properties: {
+            file_path: {
+                type: 'string',
+                description: 'The absolute path to the file to edit',
+            },
+            old_string: {
+                type: 'string',
+                description: 'The text to replace (must match exactly). Mutually exclusive with line_start.',
+            },
+            new_string: {
+                type: 'string',
+                description: 'The text to replace it with',
+            },
+            replace_all: {
+                type: 'boolean',
+                description: 'Replace all occurrences of old_string. Defaults to false.',
+            },
+            line_start: {
+                type: 'number',
+                description: 'Starting line number for replacement (1-based). Mutually exclusive with old_string.',
+            },
+            line_count: {
+                type: 'number',
+                description: 'Number of lines to replace. Defaults to 1.',
+            },
+        },
+        required: ['file_path', 'new_string'],
+    };
+    async execute(args) {
+        const filePath = args.file_path;
+        const newString = args.new_string;
+        const lineStart = args.line_start;
+        const oldString = args.old_string;
+        if (!filePath)
+            return '错误：缺少 file_path 参数。请提供文件的绝对路径。';
+        if (newString === undefined || newString === null)
+            return '错误：缺少 new_string 参数。请提供替换后的内容。';
+        if (lineStart === undefined && oldString === undefined)
+            return '错误：请提供 line_start（按行编辑）或 old_string（字符串替换）。';
+        if (lineStart !== undefined && lineStart < 1)
+            return '错误：line_start 必须 >= 1。';
+        if (lineStart !== undefined && oldString !== undefined) {
+            throw new Error('line_start and old_string are mutually exclusive. Use one mode or the other.');
+        }
+        // 拒绝编辑图片文件
+        const IMG_SIGS = [
+            [0xFF, 0xD8], // JPEG
+            [0x89, 0x50, 0x4E, 0x47], // PNG
+            [0x47, 0x49, 0x46], // GIF
+            [0x42, 0x4D], // BMP
+            [0x52, 0x49, 0x46, 0x46], // WEBP (RIFF)
+        ];
+        try {
+            const fh = await fs.open(filePath, 'r');
+            const sniff = Buffer.alloc(12);
+            await fh.read(sniff, 0, 12, 0);
+            await fh.close();
+            for (const sig of IMG_SIGS) {
+                if (sig.every((b, i) => sniff[i] === b)) {
+                    return `Error: Cannot edit image files (${filePath}). Use specialized image tools instead.`;
+                }
+            }
+        }
+        catch {
+            throw new Error(`File not found: ${filePath}`);
+        }
+        let content;
+        try {
+            content = await fs.readFile(filePath, 'utf-8');
+        }
+        catch {
+            throw new Error(`File not found: ${filePath}`);
+        }
+        // ── Read-before-write 门控 ──
+        const lastRead = getLastReadTime(filePath);
+        if (lastRead === null) {
+            return 'Error: You must read the file before editing it. Use the read tool first.';
+        }
+        try {
+            const stat = await fs.stat(filePath);
+            if (stat.mtimeMs > lastRead) {
+                return 'Error: File has been modified on disk since it was last read. Please re-read it first.';
+            }
+        }
+        catch { }
+        let result;
+        if (lineStart !== undefined) {
+            result = await this.executeLineReplace(filePath, content, newString, lineStart, args);
+        }
+        else {
+            result = await this.executeStringReplace(filePath, content, oldString, newString, args);
+        }
+        // 记录写入
+        recordFileWrite(filePath);
+        // ── 自动诊断：修改后运行类型检查/编译检查 ──
+        try {
+            const diag = await runDiagnostics(process.cwd(), 15000);
+            if (diag)
+                result += '\n\n' + diag;
+        }
+        catch { /* 诊断失败不影响工具返回值 */ }
+        // ── 自动引用搜索：提取变更符号 → 项目内搜索引用 ──
+        try {
+            const effectiveOld = oldString ?? (() => {
+                const ls = args.line_start ?? 1;
+                const lc = args.line_count ?? 1;
+                return content.split('\n').slice(ls - 1, ls - 1 + lc).join('\n');
+            })();
+            const ref = autoReferenceCheck(filePath, content, effectiveOld, newString);
+            if (ref.text)
+                result += '\n\n' + ref.text;
+        }
+        catch { /* 引用搜索失败不影响工具返回值 */ }
+        return result;
+    }
+    async executeLineReplace(filePath, content, newString, lineStart, args) {
+        const lineCount = args.line_count ?? 1;
+        const lines = content.split('\n');
+        const start = lineStart - 1;
+        if (start < 0 || start >= lines.length) {
+            throw new Error(`line_start ${lineStart} is out of range. File has ${lines.length} lines.`);
+        }
+        if (lineCount < 1) {
+            throw new Error('line_count must be at least 1.');
+        }
+        const end = Math.min(start + lineCount, lines.length);
+        const before = lines.slice(0, start);
+        const after = lines.slice(end);
+        const newContent = [...before, newString, ...after].join('\n');
+        await fs.writeFile(filePath, newContent, 'utf-8');
+        try {
+            pushDiff(filePath, computeDiff(content, newContent, filePath));
+        }
+        catch { }
+        const replaced = end - start;
+        // 生成变更摘要：显示替换后的内容
+        const newLines = newString.split('\n');
+        const previewLines = newLines.slice(0, 5);
+        const preview = previewLines.join('\n');
+        const truncated = newLines.length > 5;
+        let result = `Successfully edited ${filePath} (replaced ${replaced} line${replaced > 1 ? 's' : ''} starting at line ${lineStart})`;
+        result += `\n--- New content preview ---\n${preview}`;
+        if (truncated) {
+            result += `\n... (${newLines.length - 5} more lines)`;
+        }
+        result += `\n--- End preview ---`;
+        return result;
+    }
+    async executeStringReplace(filePath, content, oldString, newString, args) {
+        const replaceAll = args.replace_all ?? false;
+        const matchCount = this.countOccurrences(content, oldString);
+        if (matchCount === 0) {
+            throw new Error(`String not found in file: ${filePath}\n` +
+                `The old_string was not found. Make sure the string matches exactly, including whitespace and indentation.`);
+        }
+        if (matchCount > 1 && !replaceAll) {
+            throw new Error(`Multiple matches found (${matchCount} occurrences) in file: ${filePath}\n` +
+                `Use replace_all=true to replace all occurrences, or provide a larger old_string that uniquely identifies the target.`);
+        }
+        let newContent;
+        if (replaceAll) {
+            newContent = content.split(oldString).join(newString);
+        }
+        else {
+            const index = content.indexOf(oldString);
+            newContent =
+                content.slice(0, index) + newString + content.slice(index + oldString.length);
+        }
+        await fs.writeFile(filePath, newContent, 'utf-8');
+        try {
+            pushDiff(filePath, computeDiff(content, newContent, filePath));
+        }
+        catch { }
+        const replacementCount = replaceAll ? matchCount : 1;
+        // 生成变更摘要：显示 old_string 和 new_string 的对比
+        const oldPreview = oldString.split('\n').slice(0, 3).join('\n');
+        const newPreview = newString.split('\n').slice(0, 3).join('\n');
+        const oldTruncated = oldString.split('\n').length > 3;
+        const newTruncated = newString.split('\n').length > 3;
+        let result = `Successfully edited ${filePath} (${replacementCount} replacement${replacementCount > 1 ? 's' : ''})`;
+        result += `\n--- Replaced ---\n${oldPreview}`;
+        if (oldTruncated)
+            result += '\n...';
+        result += `\n--- With ---\n${newPreview}`;
+        if (newTruncated)
+            result += '\n...';
+        result += '\n--- End diff ---';
+        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=edit.js.map

package/dist/tools/executor.d.ts

@@ -0,0 +1,32 @@
+import type { ToolCall, ToolResult } from '../types.js';
+import type { ToolRegistry } from './registry.js';
+/**
+ * ToolExecutor — 调度工具执行
+ *
+ * 职责：
+ * - 根据工具调用请求查找并执行对应工具
+ * - 处理超时和错误
+ * - 返回结构化结果（ToolResult）
+ */
+export declare class ToolExecutor {
+    private registry;
+    private defaultTimeout;
+    /**
+     * @param registry  工具注册表
+     * @param defaultTimeout  默认超时时间（毫秒），默认 300000 (5 分钟)
+     */
+    constructor(registry: ToolRegistry, defaultTimeout?: number);
+    /**
+     * 执行单个工具调用
+     */
+    execute(toolCall: ToolCall): Promise<ToolResult>;
+    /**
+     * 并行执行多个工具调用
+     */
+    executeParallel(toolCalls: ToolCall[]): Promise<ToolResult[]>;
+    /**
+     * 为 Promise 添加超时控制
+     */
+    private withTimeout;
+}
+//# sourceMappingURL=executor.d.ts.map

package/dist/tools/executor.js

@@ -0,0 +1,66 @@
+/**
+ * ToolExecutor — 调度工具执行
+ *
+ * 职责：
+ * - 根据工具调用请求查找并执行对应工具
+ * - 处理超时和错误
+ * - 返回结构化结果（ToolResult）
+ */
+export class ToolExecutor {
+    registry;
+    defaultTimeout;
+    /**
+     * @param registry  工具注册表
+     * @param defaultTimeout  默认超时时间（毫秒），默认 300000 (5 分钟)
+     */
+    constructor(registry, defaultTimeout) {
+        this.registry = registry;
+        this.defaultTimeout = defaultTimeout ?? 300_000;
+    }
+    /**
+     * 执行单个工具调用
+     */
+    async execute(toolCall) {
+        // 查找工具
+        const tool = this.registry.get(toolCall.name);
+        if (!tool) {
+            return {
+                tool_use_id: toolCall.id,
+                content: `Unknown tool: ${toolCall.name}`,
+                is_error: true,
+            };
+        }
+        try {
+            // 带超时执行
+            const result = await this.withTimeout(tool.execute(toolCall.input), this.defaultTimeout);
+            return {
+                tool_use_id: toolCall.id,
+                content: result,
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                tool_use_id: toolCall.id,
+                content: message,
+                is_error: true,
+            };
+        }
+    }
+    /**
+     * 并行执行多个工具调用
+     */
+    async executeParallel(toolCalls) {
+        return Promise.all(toolCalls.map((tc) => this.execute(tc)));
+    }
+    /**
+     * 为 Promise 添加超时控制
+     */
+    withTimeout(promise, ms) {
+        return Promise.race([
+            promise,
+            new Promise((_, reject) => setTimeout(() => reject(new Error(`Tool execution timed out after ${ms / 1000} seconds`)), ms)),
+        ]);
+    }
+}
+//# sourceMappingURL=executor.js.map

package/dist/tools/file-tracker.d.ts

@@ -0,0 +1,20 @@
+/**
+ * file-tracker — 追踪文件读写时间，支撑 read-before-write 门控。
+ *
+ * 全局 in-memory 记录表：
+ *   - recordFileRead(path)    — read 工具读取文件后调用
+ *   - recordFileWrite(path)   — write/edit 修改文件后调用
+ *   - getLastReadTime(path)   — 获取上次读取时间，null = 从未读取
+ *
+ * write/edit/multi_edit 在修改文件前检查：
+ *   1. 文件存在但从未被 read → 拒绝（幻觉编辑）
+ *   2. 文件在读取后被外部修改过 → 拒绝（过期数据编辑）
+ *   3. 文件不存在 → 放行（新建文件无需读取）
+ */
+/** 记录文件被读取 */
+export declare function recordFileRead(filePath: string): void;
+/** 获取文件上次被本进程读取的时间。null = 从未读取 */
+export declare function getLastReadTime(filePath: string): number | null;
+/** 记录文件被写入（写入后自动更新 readTime，等同于 read 过） */
+export declare function recordFileWrite(filePath: string): void;
+//# sourceMappingURL=file-tracker.d.ts.map

package/dist/tools/file-tracker.js

@@ -0,0 +1,44 @@
+/**
+ * file-tracker — 追踪文件读写时间，支撑 read-before-write 门控。
+ *
+ * 全局 in-memory 记录表：
+ *   - recordFileRead(path)    — read 工具读取文件后调用
+ *   - recordFileWrite(path)   — write/edit 修改文件后调用
+ *   - getLastReadTime(path)   — 获取上次读取时间，null = 从未读取
+ *
+ * write/edit/multi_edit 在修改文件前检查：
+ *   1. 文件存在但从未被 read → 拒绝（幻觉编辑）
+ *   2. 文件在读取后被外部修改过 → 拒绝（过期数据编辑）
+ *   3. 文件不存在 → 放行（新建文件无需读取）
+ */
+import path from 'node:path';
+const records = new Map();
+/** 规范化路径为绝对路径，Windows 上统一盘符大小写 */
+function normalize(p) {
+    const resolved = path.resolve(p);
+    // Windows: 盘符统一大写，避免 c:\foo 和 C:\foo 被当成两个 key
+    if (process.platform === 'win32' && resolved.length >= 2 && resolved[1] === ':') {
+        return resolved[0].toUpperCase() + resolved.slice(1);
+    }
+    return resolved;
+}
+/** 记录文件被读取 */
+export function recordFileRead(filePath) {
+    const key = normalize(filePath);
+    const existing = records.get(key);
+    const now = Date.now();
+    records.set(key, { readTime: now, writeTime: existing?.writeTime ?? 0 });
+}
+/** 获取文件上次被本进程读取的时间。null = 从未读取 */
+export function getLastReadTime(filePath) {
+    const key = normalize(filePath);
+    const record = records.get(key);
+    return record ? record.readTime : null;
+}
+/** 记录文件被写入（写入后自动更新 readTime，等同于 read 过） */
+export function recordFileWrite(filePath) {
+    const key = normalize(filePath);
+    const now = Date.now();
+    records.set(key, { readTime: now, writeTime: now });
+}
+//# sourceMappingURL=file-tracker.js.map

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

@@ -0,0 +1,29 @@
+import type { ToolDefinition } from '../types.js';
+import type { Tool } from './interface.js';
+import { ToolRegistry } from './registry.js';
+/**
+ * FilteredToolRegistry — 包装 ToolRegistry，基于白名单过滤工具
+ * 用于子 Agent 的工具隔离：子 Agent 只能使用白名单中的工具
+ */
+export declare class FilteredToolRegistry extends ToolRegistry {
+    private parentRegistry;
+    private allowedTools;
+    constructor(parentRegistry: ToolRegistry, allowedTools: string[]);
+    /**
+     * 根据名称获取工具（仅在白名单中时返回）
+     */
+    get(name: string): Tool | undefined;
+    /**
+     * 获取所有允许的工具
+     */
+    getAll(): Tool[];
+    /**
+     * 生成 LLM 格式的工具定义数组（仅包含白名单中的工具）
+     */
+    getToolDefinitions(): ToolDefinition[];
+    /**
+     * 检查指定名称的工具是否可用
+     */
+    has(name: string): boolean;
+}
+//# sourceMappingURL=filtered-registry.d.ts.map

package/dist/tools/filtered-registry.js

@@ -0,0 +1,50 @@
+import { ToolRegistry } from './registry.js';
+/**
+ * FilteredToolRegistry — 包装 ToolRegistry，基于白名单过滤工具
+ * 用于子 Agent 的工具隔离：子 Agent 只能使用白名单中的工具
+ */
+export class FilteredToolRegistry extends ToolRegistry {
+    parentRegistry;
+    allowedTools;
+    constructor(parentRegistry, allowedTools) {
+        super(); // 父类的 Map 为空，我们不使用它
+        this.parentRegistry = parentRegistry;
+        this.allowedTools = new Set(allowedTools);
+    }
+    /**
+     * 根据名称获取工具（仅在白名单中时返回）
+     */
+    get(name) {
+        if (this.allowedTools.size > 0 && !this.allowedTools.has(name))
+            return undefined;
+        return this.parentRegistry.get(name);
+    }
+    /**
+     * 获取所有允许的工具
+     */
+    getAll() {
+        const all = this.parentRegistry.getAll();
+        if (this.allowedTools.size === 0)
+            return all;
+        return all.filter(t => this.allowedTools.has(t.name));
+    }
+    /**
+     * 生成 LLM 格式的工具定义数组（仅包含白名单中的工具）
+     */
+    getToolDefinitions() {
+        return this.getAll().map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            input_schema: tool.inputSchema,
+        }));
+    }
+    /**
+     * 检查指定名称的工具是否可用
+     */
+    has(name) {
+        if (this.allowedTools.size > 0 && !this.allowedTools.has(name))
+            return false;
+        return this.parentRegistry.has(name);
+    }
+}
+//# sourceMappingURL=filtered-registry.js.map

package/dist/tools/flow.d.ts

@@ -0,0 +1,10 @@
+import type { Tool } from './interface.js';
+import type { MachineRegistry } from '../machine/registry.js';
+/** Flow 框架工具名称集合 — 这些工具不记入对话历史 */
+export declare const FLOW_TOOL_NAMES: Set<string>;
+/** 判断给定工具名是否为 Flow 框架工具 */
+export declare function isFlowTool(name: string): boolean;
+export declare function createFlowStartTool(registry: MachineRegistry): Tool;
+export declare function createFlowAddTool(registry: MachineRegistry): Tool;
+export declare function createFlowCompleteTool(registry: MachineRegistry): Tool;
+//# sourceMappingURL=flow.d.ts.map

package/dist/tools/flow.js

@@ -0,0 +1,180 @@
+// ============================================================
+// Flow Tools — 通用流程控制工具
+// ============================================================
+//
+// flow_start    — 激活指定模式（todo / plan / spec / ...）
+// flow_add      — 向当前活跃 Flow 追加定义项（仅 definition 阶段有效）
+// flow_complete — 完成当前步骤/阶段，触发 guard → 状态转移
+//
+// 这三个工具以 flow_ 为前缀，自成体系。新增模式时只需扩展
+// flow_start 的 mode 枚举，不新增工具。
+//
+// Flow 工具不记入对话历史——状态由 Zone 5 注入体现。
+// ============================================================
+// ── 元数据 ──────────────────────────────────────────────────
+/** Flow 框架工具名称集合 — 这些工具不记入对话历史 */
+export const FLOW_TOOL_NAMES = new Set([
+    'flow_start',
+    'flow_add',
+    'flow_complete',
+]);
+/** 已注册的 Flow mode → 描述映射 */
+const MODE_DESCRIPTIONS = {
+    todo: '任务拆分与逐步执行 — 分析任务 → 拆解步骤 → 逐个执行',
+    spec: '需求规格撰写 — spec.md → tasks.md → checklist.md 三阶段推进',
+};
+/** 判断给定工具名是否为 Flow 框架工具 */
+export function isFlowTool(name) {
+    return FLOW_TOOL_NAMES.has(name);
+}
+// ── flow_start ──────────────────────────────────────────────
+export function createFlowStartTool(registry) {
+    return {
+        name: 'flow_start',
+        description: 'Activate a guided workflow mode. Available modes:\n' +
+            Object.entries(MODE_DESCRIPTIONS)
+                .map(([k, v]) => `  - "${k}": ${v}`)
+                .join('\n') +
+            '\n\nAfter activation, use flow_add to define items and flow_complete to advance.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                mode: {
+                    type: 'string',
+                    description: `The workflow mode to activate. One of: ${Object.keys(MODE_DESCRIPTIONS).join(', ')}.`,
+                    enum: Object.keys(MODE_DESCRIPTIONS),
+                },
+                task: {
+                    type: 'string',
+                    description: 'A concise description of the overall task (for todo mode).',
+                },
+            },
+            required: ['mode'],
+        },
+        async execute(args) {
+            const mode = args.mode ?? '';
+            const task = args.task ?? '';
+            if (!MODE_DESCRIPTIONS[mode]) {
+                return `Unknown mode "${mode}". Available: ${Object.keys(MODE_DESCRIPTIONS).join(', ')}.`;
+            }
+            const flow = registry.get(mode);
+            if (!flow) {
+                return `Flow for mode "${mode}" is not registered.`;
+            }
+            // 检查是否同一 Flow 已经处于活跃状态
+            const currentActive = registry.getActive();
+            if (currentActive?.id === mode) {
+                const snap = currentActive.getSnapshot();
+                const steps = snap.context.steps ?? [];
+                if (steps.length > 0) {
+                    return `Flow "${mode}" is already active with ${steps.length} step(s). Use flow_add to add more steps, or flow_complete to advance. To restart with a fresh plan, destroy the current flow first (wait for it to complete or be deactivated).`;
+                }
+                return `Flow "${mode}" is already active (no steps yet). Add steps with flow_add, then call flow_complete.`;
+            }
+            // 激活 Flow（自动停用当前活跃 Flow）
+            registry.activate(mode, { task });
+            return `Flow "${mode}" activated${task ? ` for task: "${task}"` : ''}. Follow the instructions in context, then call flow_complete to advance.`;
+        },
+    };
+}
+// ── flow_add ────────────────────────────────────────────────
+export function createFlowAddTool(registry) {
+    return {
+        name: 'flow_add',
+        description: 'Add steps to the current active flow. In todo mode, each step is an execution state. Submit ALL steps at once — do not add them one by one. Steps will be executed in order.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                steps: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'ALL step descriptions at once. Each string is one step — a clear, actionable description of what to do and what success looks like. Submit the COMPLETE list in one call.',
+                },
+            },
+            required: ['steps'],
+        },
+        async execute(args) {
+            const active = registry.getActive();
+            if (!active) {
+                return 'No active flow. Use flow_start first.';
+            }
+            const stepDescs = args.steps ?? [];
+            if (!active.addItem) {
+                return `Flow "${active.id}" does not support adding items.`;
+            }
+            if (stepDescs.length === 0) {
+                return 'No steps provided. Pass at least one step description in the steps array.';
+            }
+            const added = [];
+            for (const desc of stepDescs) {
+                const item = active.addItem(desc);
+                added.push(`${item.id}: ${item.label}`);
+            }
+            // 规划阶段：写入步骤后自动转移到执行阶段
+            // 模型只需提交步骤，状态机自己推进，无需模型额外调 flow_complete
+            const snapAfter = active.getSnapshot();
+            if (snapAfter.currentState === 'planning') {
+                const advanceResult = active.advance('flow_complete');
+                if (advanceResult.ok) {
+                    registry.onAdvanceSucceeded(active.id, advanceResult.isTerminal ?? false);
+                    const newSnap = active.getSnapshot();
+                    const newSteps = newSnap.context.steps ?? [];
+                    const newIdx = newSnap.context.stepIndex ?? 0;
+                    const firstStep = newSteps[newIdx];
+                    if (firstStep) {
+                        return `${added.length} step(s) added. Auto-advanced to execution.\n\n${'-'.repeat(40)}\n${added.map((a, i) => `  ${i + 1}. ${a}`).join('\n')}\n${'-'.repeat(40)}\n\nNow executing step ${newIdx + 1}/${newSteps.length}: "${firstStep.label}"`;
+                    }
+                    return `${added.length} step(s) added:\n${added.map((a, i) => `  ${i + 1}. ${a}`).join('\n')}\n\nAuto-advanced to execution.`;
+                }
+                // guard 失败（比如步骤数为0），不自动转移，让模型知道
+                return `${added.length} step(s) added:\n${added.map((a, i) => `  ${i + 1}. ${a}`).join('\n')}\n\nWarning: could not auto-advance — ${advanceResult.reason ?? 'unknown guard failure'}. Call flow_complete manually.`;
+            }
+            return `${added.length} step(s) added:\n${added.map((a, i) => `  ${i + 1}. ${a}`).join('\n')}\n\nAll steps defined. Call flow_complete to begin execution.`;
+        },
+    };
+}
+// ── flow_complete ───────────────────────────────────────────
+export function createFlowCompleteTool(registry) {
+    return {
+        name: 'flow_complete',
+        description: 'Complete the current flow step or phase and advance. In definition phase (todo planning), this finishes defining and starts execution. In execution phase, this advances to the next step. On the final step, the flow ends.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+        },
+        async execute(_args) {
+            const active = registry.getActive();
+            if (!active) {
+                return 'No active flow. Nothing to complete.';
+            }
+            const snap = active.getSnapshot();
+            const steps = snap.context.steps ?? [];
+            const idx = snap.context.stepIndex ?? 0;
+            // 执行实际的状态转移（guard 检查在此发生）
+            const result = active.advance('flow_complete');
+            if (!result.ok) {
+                // Guard 失败：返回失败原因给模型
+                return `Cannot advance: ${result.reason ?? 'unknown guard failure'}`;
+            }
+            // 转移成功：更新 registry（terminal 则清理）
+            registry.onAdvanceSucceeded(active.id, result.isTerminal ?? false);
+            if (result.isTerminal) {
+                return 'All steps completed. Flow finished.';
+            }
+            // 查找下一步
+            const newSnap = active.getSnapshot();
+            const newSteps = newSnap.context.steps ?? [];
+            const newIdx = newSnap.context.stepIndex ?? 0;
+            const nextStep = newSteps[newIdx];
+            if (newSnap.currentState === 'executing' && nextStep) {
+                return `Planning complete (${newSteps.length} steps). Now executing step ${newIdx + 1}/${newSteps.length}: "${nextStep.label}"`;
+            }
+            if (nextStep) {
+                return `Step "${nextStep.id}" (${newIdx + 1}/${newSteps.length}) acknowledged. Advancing to: "${nextStep.label}"`;
+            }
+            return `${newSteps.length} items defined — transitioning to execution.`;
+        },
+    };
+}
+//# sourceMappingURL=flow.js.map