hyacinth-ai 0.9.6

package/dist/rollback/rollback-tool.js

@@ -0,0 +1,167 @@
+/**
+ * 回滚工具 — rollback_status + rollback
+ *
+ * 两个独立工具，通过工厂函数创建：
+ *   - createRollbackStatusTool: 查看可回滚的回合列表
+ *   - createRollbackTool: 执行回滚操作
+ */
+import { createLogger } from '../logging/logger.js';
+const logger = createLogger('rollback-tool');
+// ── rollback_status ──────────────────────────────────────────────────
+export function createRollbackStatusTool(turnStore, getCurrentTurn) {
+    return {
+        name: 'rollback_status',
+        description: 'View the list of turns available for rollback. Each turn shows its ID, timestamp, ' +
+            'number of changed files, and executed commands. Use this before calling rollback to ' +
+            'decide how many turns to roll back.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+        },
+        async execute(_args) {
+            try {
+                const records = await turnStore.list();
+                const currentTurn = getCurrentTurn();
+                if (records.length === 0) {
+                    return 'No turns available for rollback. Turns are recorded as you interact with the agent.';
+                }
+                const entries = records.map(r => {
+                    const fileNames = r.changedFiles.slice(0, 3).map(f => f.path);
+                    const extra = r.changedFiles.length > 3 ? ` (+${r.changedFiles.length - 3} more)` : '';
+                    return {
+                        turnId: r.turnId,
+                        timestamp: r.timestamp,
+                        fileCount: r.changedFiles.length,
+                        commandCount: r.commands.length,
+                        fileSummary: fileNames.join(', ') + extra,
+                    };
+                });
+                const lines = [
+                    `Current turn: ${currentTurn} | Stored turns: ${records.length} (max 20)`,
+                    '',
+                    'Available rollback points:',
+                ];
+                for (const e of entries) {
+                    const marker = e.turnId === currentTurn ? ' ← current' : '';
+                    lines.push(`  Turn ${e.turnId}${marker}`);
+                    lines.push(`    ${e.timestamp}`);
+                    lines.push(`    Files: ${e.fileCount} (${e.fileSummary || 'none'})`);
+                    if (e.commandCount > 0) {
+                        lines.push(`    Commands: ${e.commandCount}`);
+                    }
+                    lines.push('');
+                }
+                lines.push('Use rollback({turns: N}) to roll back N turns.');
+                return lines.join('\n');
+            }
+            catch (err) {
+                return `Error reading rollback status: ${err instanceof Error ? err.message : String(err)}`;
+            }
+        },
+    };
+}
+// ── rollback ─────────────────────────────────────────────────────────
+export function createRollbackTool(turnStore, gitManager, getCurrentTurn) {
+    return {
+        name: 'rollback',
+        description: 'Roll back file changes made in the last N turns. ' +
+            'Uses git to restore files to their state before the target turn. ' +
+            'Only file changes are reverted; configuration changes may need manual review. ' +
+            'Use rollback_status first to see available turns.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                turns: {
+                    type: 'number',
+                    description: 'Number of turns to roll back (default: 1, range: 1-10). ' +
+                        'Rollback(1) reverts the most recent turn.',
+                },
+            },
+            required: [],
+        },
+        async execute(args) {
+            const turns = args.turns ?? 1;
+            if (turns < 1 || turns > 10) {
+                return 'Error: "turns" must be between 1 and 10.';
+            }
+            try {
+                const currentTurn = getCurrentTurn();
+                const records = await turnStore.list();
+                if (records.length === 0) {
+                    return 'No turns available to roll back.';
+                }
+                // 找到目标回合：回退 N 回合 → currentTurn - N + 1
+                const targetTurnId = currentTurn - turns + 1;
+                // 找到最近的 ≤ targetTurnId 的已存储回合
+                const targetRecord = records
+                    .filter(r => r.turnId <= targetTurnId)
+                    .sort((a, b) => b.turnId - a.turnId)[0];
+                if (!targetRecord) {
+                    // 如果目标回合未存储，回退到最早的已存储回合
+                    const earliest = records.sort((a, b) => a.turnId - b.turnId)[0];
+                    return `Target turn ${targetTurnId} is not stored (oldest available: ${earliest.turnId}). ` +
+                        `Use rollback_status to see available turns.`;
+                }
+                // 收集将要被回滚的回合信息（用于报告）
+                const rolledBackTurns = records.filter(r => r.turnId > targetRecord.turnId);
+                // ── 执行回滚 ──
+                if (targetRecord.preCommit) {
+                    // 有 git commit → 精确恢复
+                    try {
+                        await gitManager.resetHard(targetRecord.preCommit);
+                        logger.info(`Rolled back to turn ${targetRecord.turnId} (preCommit: ${targetRecord.preCommit.slice(0, 8)})`);
+                    }
+                    catch (err) {
+                        return `Git rollback failed: ${err instanceof Error ? err.message : String(err)}\n` +
+                            `Try manually: git reset --hard ${targetRecord.preCommit.slice(0, 8)}`;
+                    }
+                    // 清理 tag
+                    for (const r of rolledBackTurns) {
+                        try {
+                            await gitManager.git(['tag', '-d', `rollback-turn-${r.turnId}`]);
+                        }
+                        catch {
+                            // tag 可能不存在，忽略
+                        }
+                    }
+                }
+                else {
+                    return 'Cannot roll back: no git repository detected. ' +
+                        'Git-based rollback requires a git repository in the project directory.';
+                }
+                // ── 清理缓存 ──
+                await turnStore.deleteRange(targetRecord.turnId + 1);
+                // ── 构建报告 ──
+                const totalFiles = rolledBackTurns.reduce((sum, r) => sum + r.changedFiles.length, 0);
+                const allFiles = rolledBackTurns.flatMap(r => r.changedFiles.map(f => f.path));
+                const uniqueFiles = [...new Set(allFiles)];
+                const fileList = uniqueFiles.slice(0, 10)
+                    .map(f => `  • ${f}`)
+                    .join('\n');
+                const extraFiles = uniqueFiles.length > 10
+                    ? `\n  ... and ${uniqueFiles.length - 10} more files`
+                    : '';
+                const allCommands = rolledBackTurns.flatMap(r => r.commands);
+                const cmdLines = allCommands.length > 0
+                    ? `\n\n💡 ${rolledBackTurns.length} rolled-back turn(s) executed these commands — please check for side effects:\n` +
+                        allCommands.map(c => `  • ${c}`).join('\n')
+                    : '';
+                const lines = [
+                    `🔄 Rolled back ${turns} turn(s) to turn ${targetRecord.turnId} (before the reverted changes).`,
+                    '',
+                    `✅ ${uniqueFiles.length} file(s) restored across ${rolledBackTurns.length} turn(s):`,
+                    fileList + extraFiles,
+                    cmdLines,
+                    '',
+                    `💡 If there were config changes (channels, settings, etc.), please check and fix them manually.`,
+                ];
+                return lines.join('\n');
+            }
+            catch (err) {
+                return `Rollback error: ${err instanceof Error ? err.message : String(err)}`;
+            }
+        },
+    };
+}
+//# sourceMappingURL=rollback-tool.js.map

package/dist/rollback/turn-recorder.d.ts

@@ -0,0 +1,37 @@
+/**
+ * TurnRecorder — 回合追踪器
+ *
+ * 在每个回合的生命周期中自动记录文件变更：
+ *   - 回合开始 → git commit（生成回滚锚点）
+ *   - 工具执行前 → 拦截 write/edit 读取旧内容
+ *   - 回合结束 → git diff 补充检测 + 写入 TurnStore
+ */
+import type { GitManager } from '../evolution/git-manager.js';
+import type { TurnStore } from './turn-store.js';
+import type { TurnRecord } from './types.js';
+export declare class TurnRecorder {
+    private gitManager;
+    private turnStore;
+    private currentRecord;
+    private projectDir;
+    /** 记录已手动捕获预状态的路径 → 避免 git diff 重复添加 */
+    private recordedPaths;
+    constructor(gitManager: GitManager, turnStore: TurnStore, projectDir: string);
+    /** 回合开始时调用。返回 preCommit hash（非 git 时为空字符串） */
+    startTurn(turnId: number): Promise<string>;
+    /**
+     * 记录文件写操作的前置状态。
+     * 在 write / edit / multi_edit 工具执行前调用。
+     * @param absolutePath 文件的绝对路径
+     */
+    recordPreState(absolutePath: string): void;
+    /** 记录 bash 命令 */
+    recordCommand(command: string): void;
+    /** 回合结束时调用。补充 git diff 检测 → 写入 TurnStore */
+    endTurn(): Promise<TurnRecord | null>;
+    /** 通过 git diff --name-status 补充检测遗漏的变更文件 */
+    private enrichFromGitDiff;
+    /** 绝对路径 → 相对于项目根目录的路径 */
+    private toRelativePath;
+}
+//# sourceMappingURL=turn-recorder.d.ts.map

package/dist/rollback/turn-recorder.js

@@ -0,0 +1,183 @@
+/**
+ * TurnRecorder — 回合追踪器
+ *
+ * 在每个回合的生命周期中自动记录文件变更：
+ *   - 回合开始 → git commit（生成回滚锚点）
+ *   - 工具执行前 → 拦截 write/edit 读取旧内容
+ *   - 回合结束 → git diff 补充检测 + 写入 TurnStore
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { createLogger } from '../logging/logger.js';
+const logger = createLogger('turn-recorder');
+export class TurnRecorder {
+    gitManager;
+    turnStore;
+    currentRecord = null;
+    projectDir;
+    /** 记录已手动捕获预状态的路径 → 避免 git diff 重复添加 */
+    recordedPaths = new Set();
+    constructor(gitManager, turnStore, projectDir) {
+        this.gitManager = gitManager;
+        this.turnStore = turnStore;
+        this.projectDir = projectDir;
+    }
+    // ── Public API ─────────────────────────────────────────────────────
+    /** 回合开始时调用。返回 preCommit hash（非 git 时为空字符串） */
+    async startTurn(turnId) {
+        let preCommit = '';
+        try {
+            if (await this.gitManager.isRepo()) {
+                // 先处理可能存在的未提交变更（上一回合残留）
+                const hasChanges = await this.gitManager.hasUncommittedChanges();
+                if (hasChanges) {
+                    // 先 stash，commit 干净的状态，再 pop（确保 pre-commit 只含本回合前的状态）
+                    // 实际做法：直接 commit 当前状态（包含所有未提交变更），这些变更属于上一回合
+                    logger.debug('Uncommitted changes detected before turn start, committing as previous turn state.');
+                }
+                preCommit = await this.gitManager.commit(`auto: pre-turn-${turnId}`);
+                logger.debug(`Pre-turn commit: ${preCommit.slice(0, 8)} for turn ${turnId}`);
+                // 打轻量 tag 方便 git log 查找
+                try {
+                    await this.gitManager.git(['tag', '-f', `rollback-turn-${turnId}`]);
+                }
+                catch {
+                    // tag 失败不阻塞
+                }
+            }
+        }
+        catch (err) {
+            logger.warn(`Failed to create pre-turn commit for turn ${turnId}`, {
+                error: err instanceof Error ? err.message : String(err),
+            });
+            // 不阻塞回合
+        }
+        this.currentRecord = {
+            turnId,
+            timestamp: new Date().toISOString(),
+            preCommit,
+            changedFiles: [],
+            commands: [],
+        };
+        this.recordedPaths.clear();
+        return preCommit;
+    }
+    /**
+     * 记录文件写操作的前置状态。
+     * 在 write / edit / multi_edit 工具执行前调用。
+     * @param absolutePath 文件的绝对路径
+     */
+    recordPreState(absolutePath) {
+        if (!this.currentRecord)
+            return;
+        // 转为相对于项目目录的路径
+        const relPath = this.toRelativePath(absolutePath);
+        // 去重：同一个文件可能被多次拦截（如多次 edit），只记录第一次
+        if (this.recordedPaths.has(relPath))
+            return;
+        this.recordedPaths.add(relPath);
+        const exists = fs.existsSync(absolutePath);
+        const entry = {
+            path: relPath,
+            action: exists ? 'modified' : 'created',
+        };
+        if (exists) {
+            try {
+                entry.oldContent = fs.readFileSync(absolutePath, 'utf-8');
+            }
+            catch {
+                // 二进制文件或读取失败，不存 oldContent
+            }
+        }
+        this.currentRecord.changedFiles.push(entry);
+    }
+    /** 记录 bash 命令 */
+    recordCommand(command) {
+        if (!this.currentRecord)
+            return;
+        this.currentRecord.commands.push(command);
+    }
+    /** 回合结束时调用。补充 git diff 检测 → 写入 TurnStore */
+    async endTurn() {
+        if (!this.currentRecord)
+            return null;
+        try {
+            // 通过 git diff 补充检测遗漏文件（bash rm 等未被拦截的操作）
+            await this.enrichFromGitDiff();
+        }
+        catch (err) {
+            logger.warn('Failed to enrich turn record from git diff', {
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+        const record = { ...this.currentRecord };
+        await this.turnStore.save(record);
+        logger.debug(`Turn ${record.turnId} recorded: ${record.changedFiles.length} files, ${record.commands.length} commands`);
+        this.currentRecord = null;
+        this.recordedPaths.clear();
+        return record;
+    }
+    // ── Private ────────────────────────────────────────────────────────
+    /** 通过 git diff --name-status 补充检测遗漏的变更文件 */
+    async enrichFromGitDiff() {
+        if (!this.currentRecord || !this.currentRecord.preCommit)
+            return;
+        try {
+            const isRepo = await this.gitManager.isRepo();
+            if (!isRepo)
+                return;
+            // git diff --name-status <preCommit>
+            const { stdout } = await this.gitManager.git([
+                'diff', '--name-status', this.currentRecord.preCommit,
+            ]);
+            const lines = stdout.trim().split('\n').filter(Boolean);
+            for (const line of lines) {
+                const parts = line.split('\t');
+                if (parts.length < 2)
+                    continue;
+                const statusCode = parts[0];
+                const filePath = parts.slice(1).join('\t'); // 文件名可能含空格
+                // 跳过已手动记录的路径
+                if (this.recordedPaths.has(filePath))
+                    continue;
+                const action = statusToAction(statusCode);
+                if (!action)
+                    continue;
+                this.currentRecord.changedFiles.push({
+                    path: filePath,
+                    action,
+                    // 无法获取 oldContent（文件已被修改），git reset 会直接恢复
+                });
+                this.recordedPaths.add(filePath);
+            }
+        }
+        catch {
+            // diff 失败不阻塞
+        }
+    }
+    /** 绝对路径 → 相对于项目根目录的路径 */
+    toRelativePath(absolutePath) {
+        const rel = path.relative(this.projectDir, absolutePath);
+        // 规范化路径分隔符
+        return rel.replace(/\\/g, '/');
+    }
+}
+// ── Helpers ──────────────────────────────────────────────────────────
+/** git diff --name-status 的状态码 → ChangedFile.action */
+function statusToAction(code) {
+    switch (code) {
+        case 'M':
+            return 'modified';
+        case 'A':
+            return 'created';
+        case 'D':
+            return 'deleted';
+        // R = renamed, C = copied — 当作 modified（文件内容变化）
+        case 'R':
+        case 'C':
+            return 'modified';
+        default:
+            return null;
+    }
+}
+//# sourceMappingURL=turn-recorder.js.map

package/dist/rollback/turn-store.d.ts

@@ -0,0 +1,29 @@
+/**
+ * TurnStore — 环状缓冲区 + JSON 持久化
+ *
+ * 存储回合记录到 .agent/rollback/turn-{id}.json。
+ * 最多保留 20 个回合，超出时淘汰最旧的。
+ */
+import type { TurnRecord } from './types.js';
+export declare class TurnStore {
+    private storeDir;
+    constructor(storeDir: string);
+    /** 保存回合记录，自动触发环状淘汰 */
+    save(record: TurnRecord): Promise<void>;
+    /** 按 turnId 加载单个回合记录 */
+    load(turnId: number): Promise<TurnRecord | null>;
+    /** 列出所有已存储的回合记录（按 turnId 升序） */
+    list(): Promise<TurnRecord[]>;
+    /** 删除从 fromTurnId 开始的所有记录（含 fromTurnId），用于回滚后清理 */
+    deleteRange(fromTurnId: number): Promise<void>;
+    /** 获取存储目录路径 */
+    getDir(): string;
+    private turnFilePath;
+    private indexFilePath;
+    private readIndex;
+    private writeIndex;
+    private ensureDir;
+    /** 超过上限时删除最旧的回合文件 */
+    private evictIfNeeded;
+}
+//# sourceMappingURL=turn-store.d.ts.map

package/dist/rollback/turn-store.js

@@ -0,0 +1,114 @@
+/**
+ * TurnStore — 环状缓冲区 + JSON 持久化
+ *
+ * 存储回合记录到 .agent/rollback/turn-{id}.json。
+ * 最多保留 20 个回合，超出时淘汰最旧的。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+const MAX_STORED_TURNS = 20;
+const INDEX_FILE = 'index.json';
+export class TurnStore {
+    storeDir;
+    constructor(storeDir) {
+        this.storeDir = storeDir;
+        this.ensureDir();
+    }
+    // ── Public API ─────────────────────────────────────────────────────
+    /** 保存回合记录，自动触发环状淘汰 */
+    async save(record) {
+        this.ensureDir();
+        // 写入单个回合文件
+        const filePath = this.turnFilePath(record.turnId);
+        fs.writeFileSync(filePath, JSON.stringify(record, null, 2), 'utf-8');
+        // 更新索引
+        const index = this.readIndex();
+        if (!index.turns.includes(record.turnId)) {
+            index.turns.push(record.turnId);
+            index.turns.sort((a, b) => a - b);
+        }
+        index.lastTurnId = record.turnId;
+        this.writeIndex(index);
+        // 环状淘汰
+        this.evictIfNeeded(index);
+    }
+    /** 按 turnId 加载单个回合记录 */
+    async load(turnId) {
+        const filePath = this.turnFilePath(turnId);
+        if (!fs.existsSync(filePath))
+            return null;
+        try {
+            return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+        }
+        catch {
+            return null;
+        }
+    }
+    /** 列出所有已存储的回合记录（按 turnId 升序） */
+    async list() {
+        const index = this.readIndex();
+        const records = [];
+        for (const turnId of index.turns) {
+            const record = await this.load(turnId);
+            if (record)
+                records.push(record);
+        }
+        return records;
+    }
+    /** 删除从 fromTurnId 开始的所有记录（含 fromTurnId），用于回滚后清理 */
+    async deleteRange(fromTurnId) {
+        const index = this.readIndex();
+        const toRemove = index.turns.filter(id => id >= fromTurnId);
+        for (const turnId of toRemove) {
+            const filePath = this.turnFilePath(turnId);
+            if (fs.existsSync(filePath)) {
+                fs.unlinkSync(filePath);
+            }
+        }
+        index.turns = index.turns.filter(id => id < fromTurnId);
+        this.writeIndex(index);
+    }
+    /** 获取存储目录路径 */
+    getDir() {
+        return this.storeDir;
+    }
+    // ── Private ────────────────────────────────────────────────────────
+    turnFilePath(turnId) {
+        return path.join(this.storeDir, `turn-${turnId}.json`);
+    }
+    indexFilePath() {
+        return path.join(this.storeDir, INDEX_FILE);
+    }
+    readIndex() {
+        const filePath = this.indexFilePath();
+        if (!fs.existsSync(filePath)) {
+            return { turns: [], lastTurnId: 0 };
+        }
+        try {
+            return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+        }
+        catch {
+            return { turns: [], lastTurnId: 0 };
+        }
+    }
+    writeIndex(index) {
+        fs.writeFileSync(this.indexFilePath(), JSON.stringify(index, null, 2), 'utf-8');
+    }
+    ensureDir() {
+        if (!fs.existsSync(this.storeDir)) {
+            fs.mkdirSync(this.storeDir, { recursive: true });
+        }
+    }
+    /** 超过上限时删除最旧的回合文件 */
+    evictIfNeeded(index) {
+        while (index.turns.length > MAX_STORED_TURNS) {
+            const oldest = index.turns.shift();
+            const filePath = this.turnFilePath(oldest);
+            if (fs.existsSync(filePath)) {
+                fs.unlinkSync(filePath);
+            }
+        }
+        this.writeIndex(index);
+    }
+}
+//# sourceMappingURL=turn-store.js.map

package/dist/rollback/types.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 回合回滚 — 类型定义
+ *
+ * ## 术语
+ * - **回合 (Turn)**: 用户一条消息 → 模型执行全部工具调用 → 模型回复。一个完整轮次。
+ * - **回滚 (Rollback)**: 撤销指定回合中模型所做的所有文件变更。
+ */
+/** 单个文件变更记录 */
+export interface ChangedFile {
+    /** 文件路径（相对于项目根） */
+    path: string;
+    /** 变更类型 */
+    action: 'modified' | 'created' | 'deleted';
+    /** 修改前的完整内容（modified / deleted 时记录；created 时 undefined） */
+    oldContent?: string;
+}
+/** 一个回合的完整记录 */
+export interface TurnRecord {
+    /** 回合编号（全局递增） */
+    turnId: number;
+    /** 回合开始时间 ISO 8601 */
+    timestamp: string;
+    /** 回合开始前的 git commit hash（非 git 仓库时为空字符串） */
+    preCommit: string;
+    /** 本回合变更的文件列表 */
+    changedFiles: ChangedFile[];
+    /** 本回合执行的 bash 命令列表 */
+    commands: string[];
+}
+/** rollback_status 工具返回的摘要 */
+export interface RollbackStatusResult {
+    currentTurn: number;
+    maxStored: number;
+    available: RollbackStatusEntry[];
+}
+export interface RollbackStatusEntry {
+    turnId: number;
+    timestamp: string;
+    fileCount: number;
+    commandCount: number;
+    /** 变更文件摘要，如 "src/a.ts, src/b.ts (+2 more)" */
+    fileSummary: string;
+}
+/** 环状缓冲区索引文件结构 */
+export interface RollbackIndex {
+    /** 已存储的回合 ID 列表（按 turnId 升序） */
+    turns: number[];
+    /** 下次写入的回合 ID（用于判断连续性） */
+    lastTurnId: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/rollback/types.js

@@ -0,0 +1,9 @@
+/**
+ * 回合回滚 — 类型定义
+ *
+ * ## 术语
+ * - **回合 (Turn)**: 用户一条消息 → 模型执行全部工具调用 → 模型回复。一个完整轮次。
+ * - **回滚 (Rollback)**: 撤销指定回合中模型所做的所有文件变更。
+ */
+export {};
+//# sourceMappingURL=types.js.map