@gt-fe/eap-runtime 0.0.8

package/dist/api/routes/task.routes.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Task API — Route Handlers（dev-only HTTP 适配层）
+ *
+ * 生产环境 Task 状态 / HITL 由 Hosting 提供；本模块供 `EAP_DEV_HTTP=1` 本地调试。
+ */
+import type { TaskStatus } from '../../common/types.js';
+import type { ITaskManager } from '../../task/task.service.js';
+/**
+ * 任务状态查询请求 — GET /api/v1/tasks/:taskId/status
+ */
+export interface GetTaskStatusRequest {
+    /** Task ID（从路径参数获取） */
+    taskId: string;
+}
+/**
+ * 任务状态查询响应数据
+ */
+export interface GetTaskStatusResponseData {
+    /** 当前状态 */
+    status: TaskStatus;
+    /** 执行进度（0-100） */
+    progress: number;
+    /** 开始执行时间 (ISO 8601) */
+    startedAt: string | null;
+    /** 已运行时长（毫秒） */
+    duration: number;
+    /** 错误信息（如果失败） */
+    error?: string;
+}
+/**
+ * 任务状态查询完整响应
+ */
+export interface GetTaskStatusResponse {
+    /** 业务状态码，0 表示成功 */
+    code: string;
+    /** 响应数据 */
+    data: GetTaskStatusResponseData;
+}
+/**
+ * HITL 人工介入确认请求 — POST /api/v1/tasks/:taskId/hitl
+ */
+export interface PostHitlRequest {
+    /** Task ID（从路径参数获取） */
+    taskId: string;
+    /** 用户选择（确认/拒绝/其他选项） */
+    choice: string;
+    /** 操作用户 ID */
+    userId: string;
+}
+/**
+ * HITL 人工介入确认响应数据
+ */
+export interface PostHitlResponseData {
+    /** 是否已确认接收 */
+    acknowledged: boolean;
+}
+/**
+ * HITL 人工介入确认完整响应
+ */
+export interface PostHitlResponse {
+    /** 业务状态码，0 表示成功 */
+    code: string;
+    /** 响应数据 */
+    data: PostHitlResponseData;
+}
+/**
+ * 创建 Task 路由处理器
+ *
+ * @param taskManager - Task 管理器实例
+ * @returns 路由处理器函数
+ */
+export declare function createTaskRouteHandlers(taskManager: ITaskManager): {
+    getTaskStatusHandler: (req: GetTaskStatusRequest) => Promise<GetTaskStatusResponse>;
+    postHitlHandler: (req: PostHitlRequest) => Promise<PostHitlResponse>;
+};

package/dist/api/routes/task.routes.js

@@ -0,0 +1,108 @@
+/**
+ * Task API — Route Handlers（dev-only HTTP 适配层）
+ *
+ * 生产环境 Task 状态 / HITL 由 Hosting 提供；本模块供 `EAP_DEV_HTTP=1` 本地调试。
+ */
+// ─────────────────────────────────────────────
+// Route Handlers
+// ─────────────────────────────────────────────
+/**
+ * 创建 Task 路由处理器
+ *
+ * @param taskManager - Task 管理器实例
+ * @returns 路由处理器函数
+ */
+export function createTaskRouteHandlers(taskManager) {
+    /**
+     * 查询任务状态（轮询长任务进度）
+     *
+     * 客户端通过此接口轮询分钟级/小时级长任务的执行进度。
+     * SSE 断连后可降级为轮询模式。
+     */
+    async function getTaskStatusHandler(req) {
+        const { taskId } = req;
+        try {
+            // 获取任务状态
+            const task = await taskManager.getStatus(taskId);
+            if (!task) {
+                return {
+                    code: 'runtime.task.not_found',
+                    data: {
+                        status: 'failed',
+                        progress: 0,
+                        startedAt: null,
+                        duration: 0,
+                        error: `Task not found: ${taskId}`,
+                    },
+                };
+            }
+            // 计算已运行时长
+            const now = Date.now();
+            const startTime = task.startedAt ? new Date(task.startedAt).getTime() : now;
+            const duration = task.status === 'running' ? now - startTime : (task.duration ?? 0);
+            return {
+                code: 'ok',
+                data: {
+                    status: task.status,
+                    progress: task.progress ?? 0,
+                    startedAt: task.startedAt ?? null,
+                    duration,
+                    error: task.status,
+                },
+            };
+        }
+        catch (error) {
+            return {
+                code: 'runtime.graph.execution_error',
+                data: {
+                    status: 'failed',
+                    progress: 0,
+                    startedAt: null,
+                    duration: 0,
+                    error: error instanceof Error ? error.message : 'Unknown error',
+                },
+            };
+        }
+    }
+    /**
+     * 提交人工介入确认（HITL）
+     *
+     * 当 Agent 执行遇到需要人工确认的节点时（如危险操作、require_confirmation Tool），
+     * Graph 暂停并推送 hitl.waiting 事件，客户端通过此接口提交用户的确认/拒绝决定。
+     */
+    async function postHitlHandler(req) {
+        const { taskId, choice, userId } = req;
+        try {
+            // 验证任务存在且处于 HITL 等待状态
+            const task = await taskManager.getStatus(taskId);
+            if (!task) {
+                return {
+                    code: 'runtime.task.not_found',
+                    data: { acknowledged: false },
+                };
+            }
+            if (task.status !== 'waiting_hitl' && task.status !== 'running') {
+                return {
+                    code: 'runtime.task.hitl_invalid_state',
+                    data: { acknowledged: false },
+                };
+            }
+            // 恢复 HITL 执行：waiting_hitl → running
+            await taskManager.updateStatus(taskId, 'running');
+            return {
+                code: 'ok',
+                data: { acknowledged: true },
+            };
+        }
+        catch (error) {
+            return {
+                code: 'runtime.graph.execution_error',
+                data: { acknowledged: false },
+            };
+        }
+    }
+    return {
+        getTaskStatusHandler,
+        postHitlHandler,
+    };
+}

package/dist/checkpoint/checkpoint-serializer.d.ts

@@ -0,0 +1,58 @@
+/**
+ * CheckpointSerializer — Checkpoint 序列化/反序列化与工厂函数
+ *
+ * 提供：
+ * 1. createCheckpointData 工厂函数 — 自动生成 checkpointId + createdAt 时间戳
+ * 2. serializeCheckpoint / deserializeCheckpoint — 处理序列化边界情况
+ *    （Date 对象 → ISO 字符串、undefined 清除、循环引用检测）
+ *
+ * @see design.md §1.3 Checkpoint 数据模型
+ * @see requirements.md Requirement 2 AC3
+ */
+import type { CheckpointData, GraphState } from '../graph/contracts/executable-graph.js';
+/**
+ * createCheckpointData 参数 — checkpointId 和 createdAt 可选（自动生成）
+ */
+export interface CreateCheckpointParams {
+    /** Checkpoint ID（可选，默认自动生成 UUID） */
+    checkpointId?: string;
+    /** 线程 ID */
+    threadId: string;
+    /** 当前执行节点 ID */
+    currentNodeId: string;
+    /** 已执行的节点历史路径 */
+    historyPath: string[];
+    /** 完整 Graph State 快照 */
+    state: GraphState;
+    /** 创建人（可选，默认 'system'） */
+    createdBy?: string;
+    /** 创建时间（可选，默认当前时间 ISO 字符串） */
+    createdAt?: string;
+    /** 最后更新人（可选，默认 'system'） */
+    updatedBy?: string;
+    /** 最后更新时间（可选，默认当前时间 ISO 字符串） */
+    updatedAt?: string;
+}
+/**
+ * 创建 CheckpointData 实例
+ *
+ * 自动生成 checkpointId（UUID v4）和 createdAt（ISO 8601）。
+ * 确保所有必要字段的一致性。
+ */
+export declare function createCheckpointData(params: CreateCheckpointParams): CheckpointData;
+/**
+ * 序列化 CheckpointData 为 JSON 字符串
+ *
+ * 处理边界情况：
+ * - Date 对象 → ISO 字符串
+ * - undefined 值自动剔除（JSON.stringify 默认行为）
+ * - 循环引用检测（抛出明确错误而非默认 TypeError）
+ */
+export declare function serializeCheckpoint(data: CheckpointData): string;
+/**
+ * 反序列化 JSON 字符串为 CheckpointData
+ *
+ * 基本 JSON.parse，附加类型断言和基础字段校验。
+ * @throws Error 如果 JSON 无效或缺少必填字段
+ */
+export declare function deserializeCheckpoint(json: string): CheckpointData;

package/dist/checkpoint/checkpoint-serializer.js

@@ -0,0 +1,81 @@
+/**
+ * CheckpointSerializer — Checkpoint 序列化/反序列化与工厂函数
+ *
+ * 提供：
+ * 1. createCheckpointData 工厂函数 — 自动生成 checkpointId + createdAt 时间戳
+ * 2. serializeCheckpoint / deserializeCheckpoint — 处理序列化边界情况
+ *    （Date 对象 → ISO 字符串、undefined 清除、循环引用检测）
+ *
+ * @see design.md §1.3 Checkpoint 数据模型
+ * @see requirements.md Requirement 2 AC3
+ */
+import { randomUUID } from 'node:crypto';
+// ─────────────────────────────────────────────
+// 工厂函数
+// ─────────────────────────────────────────────
+/**
+ * 创建 CheckpointData 实例
+ *
+ * 自动生成 checkpointId（UUID v4）和 createdAt（ISO 8601）。
+ * 确保所有必要字段的一致性。
+ */
+export function createCheckpointData(params) {
+    const now = new Date().toISOString();
+    return {
+        checkpointId: params.checkpointId ?? randomUUID(),
+        threadId: params.threadId,
+        currentNodeId: params.currentNodeId,
+        historyPath: [...params.historyPath],
+        state: params.state,
+        createdBy: params.createdBy ?? 'system',
+        createdAt: params.createdAt ?? now,
+        updatedBy: params.updatedBy ?? 'system',
+        updatedAt: params.updatedAt ?? now,
+        isDeleted: false,
+    };
+}
+// ─────────────────────────────────────────────
+// 序列化 / 反序列化
+// ─────────────────────────────────────────────
+/**
+ * 序列化 CheckpointData 为 JSON 字符串
+ *
+ * 处理边界情况：
+ * - Date 对象 → ISO 字符串
+ * - undefined 值自动剔除（JSON.stringify 默认行为）
+ * - 循环引用检测（抛出明确错误而非默认 TypeError）
+ */
+export function serializeCheckpoint(data) {
+    const seen = new WeakSet();
+    return JSON.stringify(data, (_key, value) => {
+        // Date → ISO 字符串
+        if (value instanceof Date) {
+            return value.toISOString();
+        }
+        // 循环引用检测
+        if (typeof value === 'object' && value !== null) {
+            if (seen.has(value)) {
+                throw new Error(`[CheckpointSerializer] Circular reference detected during serialization`);
+            }
+            seen.add(value);
+        }
+        return value;
+    });
+}
+/**
+ * 反序列化 JSON 字符串为 CheckpointData
+ *
+ * 基本 JSON.parse，附加类型断言和基础字段校验。
+ * @throws Error 如果 JSON 无效或缺少必填字段
+ */
+export function deserializeCheckpoint(json) {
+    const parsed = JSON.parse(json);
+    // 基础字段校验
+    const requiredFields = ['checkpointId', 'threadId', 'currentNodeId', 'historyPath', 'state', 'createdAt'];
+    for (const field of requiredFields) {
+        if (!(field in parsed) || parsed[field] === undefined || parsed[field] === null) {
+            throw new Error(`[CheckpointSerializer] Missing required field: ${field}`);
+        }
+    }
+    return parsed;
+}

package/dist/checkpoint/composite-checkpoint-saver.d.ts

@@ -0,0 +1,42 @@
+/**
+ * CompositeCheckpointSaver — 组合式 Checkpoint 持久化实现
+ *
+ * 写入策略：同步写 DB（主存储），异步写 Redis 缓存（可选）
+ * 读取策略：优先 Redis 缓存（如存在），失败或 null 时 fallback 到 DB
+ *
+ * @see design.md §1.3 checkpoints 数据模型
+ * @see checkpoint-saver.contract.ts ICheckpointSaver 接口定义
+ */
+import type { ICheckpointSaver } from './contracts/checkpoint-saver.contract.js';
+import type { CheckpointData } from '../graph/contracts/executable-graph.js';
+/**
+ * CompositeCheckpointSaver — DB 主存储 + Redis 可选缓存
+ *
+ * - save: await DB → fire-and-forget Redis 缓存（错误静默记录）
+ * - load / loadByCheckpointId / list: try Redis 缓存 → fallback DB
+ */
+export declare class CompositeCheckpointSaver implements ICheckpointSaver {
+    private readonly db;
+    private readonly cache?;
+    constructor(db: ICheckpointSaver, cache?: ICheckpointSaver | undefined);
+    /**
+     * 写入 Checkpoint：同步写 DB，异步写 Redis 缓存（不 await，错误静默）
+     */
+    save(threadId: string, data: CheckpointData): Promise<void>;
+    /**
+     * 加载最新 Checkpoint：优先 Redis 缓存，失败或 null 时 fallback DB
+     */
+    load(threadId: string): Promise<CheckpointData | null>;
+    /**
+     * 按 checkpointId 加载：优先 Redis 缓存，失败或 null 时 fallback DB
+     */
+    loadByCheckpointId(checkpointId: string): Promise<CheckpointData | null>;
+    /**
+     * 列出 thread 所有 Checkpoint：优先 Redis 缓存，失败时 fallback DB
+     */
+    list(threadId: string): Promise<CheckpointData[]>;
+    /**
+     * Fork: 从指定 Checkpoint 创建新的执行线程
+     */
+    fork(sourceCheckpointId: string, newThreadId: string, overrides?: Record<string, unknown>): Promise<import('../graph/contracts/executable-graph.js').CheckpointData>;
+}

package/dist/checkpoint/composite-checkpoint-saver.js

@@ -0,0 +1,118 @@
+/**
+ * CompositeCheckpointSaver — 组合式 Checkpoint 持久化实现
+ *
+ * 写入策略：同步写 DB（主存储），异步写 Redis 缓存（可选）
+ * 读取策略：优先 Redis 缓存（如存在），失败或 null 时 fallback 到 DB
+ *
+ * @see design.md §1.3 checkpoints 数据模型
+ * @see checkpoint-saver.contract.ts ICheckpointSaver 接口定义
+ */
+/**
+ * CompositeCheckpointSaver — DB 主存储 + Redis 可选缓存
+ *
+ * - save: await DB → fire-and-forget Redis 缓存（错误静默记录）
+ * - load / loadByCheckpointId / list: try Redis 缓存 → fallback DB
+ */
+export class CompositeCheckpointSaver {
+    db;
+    cache;
+    constructor(db, cache) {
+        this.db = db;
+        this.cache = cache;
+    }
+    /**
+     * 写入 Checkpoint：同步写 DB，异步写 Redis 缓存（不 await，错误静默）
+     */
+    async save(threadId, data) {
+        // 主存储：DB
+        await this.db.save(threadId, data);
+        // 可选缓存：Redis（fire-and-forget）
+        if (this.cache) {
+            this.cache.save(threadId, data).catch((err) => {
+                console.error('[CompositeCheckpointSaver] Cache save failed:', err);
+            });
+        }
+    }
+    /**
+     * 加载最新 Checkpoint：优先 Redis 缓存，失败或 null 时 fallback DB
+     */
+    async load(threadId) {
+        // 尝试从缓存加载
+        if (this.cache) {
+            try {
+                const result = await this.cache.load(threadId);
+                if (result !== null) {
+                    return result;
+                }
+            }
+            catch (err) {
+                console.error('[CompositeCheckpointSaver] Cache load failed, falling back to DB:', err);
+            }
+        }
+        // Fallback: 从 DB 加载
+        return this.db.load(threadId);
+    }
+    /**
+     * 按 checkpointId 加载：优先 Redis 缓存，失败或 null 时 fallback DB
+     */
+    async loadByCheckpointId(checkpointId) {
+        // 尝试从缓存加载
+        if (this.cache) {
+            try {
+                const result = await this.cache.loadByCheckpointId(checkpointId);
+                if (result !== null) {
+                    return result;
+                }
+            }
+            catch (err) {
+                console.error('[CompositeCheckpointSaver] Cache loadByCheckpointId failed, falling back to DB:', err);
+            }
+        }
+        // Fallback: 从 DB 加载
+        return this.db.loadByCheckpointId(checkpointId);
+    }
+    /**
+     * 列出 thread 所有 Checkpoint：优先 Redis 缓存，失败时 fallback DB
+     */
+    async list(threadId) {
+        // 尝试从缓存加载
+        if (this.cache) {
+            try {
+                const results = await this.cache.list(threadId);
+                if (results.length > 0) {
+                    return results;
+                }
+            }
+            catch (err) {
+                console.error('[CompositeCheckpointSaver] Cache list failed, falling back to DB:', err);
+            }
+        }
+        // Fallback: 从 DB 加载
+        return this.db.list(threadId);
+    }
+    /**
+     * Fork: 从指定 Checkpoint 创建新的执行线程
+     */
+    async fork(sourceCheckpointId, newThreadId, overrides) {
+        const source = await this.loadByCheckpointId(sourceCheckpointId);
+        if (!source) {
+            throw new Error(`Source checkpoint not found: ${sourceCheckpointId}`);
+        }
+        const now = new Date().toISOString();
+        const { randomUUID } = await import('node:crypto');
+        const newData = {
+            checkpointId: randomUUID(),
+            threadId: newThreadId,
+            currentNodeId: source.currentNodeId,
+            historyPath: source.historyPath,
+            state: overrides ? { ...source.state, ...overrides } : source.state,
+            createdBy: 'fork',
+            createdAt: now,
+            updatedBy: 'fork',
+            updatedAt: now,
+            isDeleted: false,
+        };
+        await this.save(newThreadId, newData);
+        return newData;
+    }
+}

package/dist/checkpoint/contracts/checkpoint-saver.contract.d.ts

@@ -0,0 +1,65 @@
+/**
+ * ICheckpointSaver — Checkpoint 持久化服务接口
+ *
+ * 定义 Checkpoint 的存储/加载/列表操作。
+ * 实现架构：DB 为主存储，Redis 为可选缓存。
+ *
+ * 支持 Fork 功能：从指定 Checkpoint 恢复执行。
+ *
+ * @see design.md §1.3 checkpoints 数据模型
+ * @see requirements.md Requirement 2 AC1-AC4
+ */
+import type { CheckpointData } from '../../graph/contracts/executable-graph.js';
+/**
+ * ICheckpointSaver — Checkpoint 持久化接口
+ *
+ * 由 PostgreSQL/MySQL/Redis/Composite 实现，提供 Graph 状态快照的 CRUD 能力。
+ * - save: 持久化 Checkpoint（DB 主写 + Redis 可选缓存）
+ * - load: 加载指定 thread 最新的 Checkpoint（用于断点恢复）
+ * - loadByCheckpointId: 按 checkpointId 加载特定快照（供 05-Trace/Replay 模块使用）
+ * - list: 列出指定 thread 的所有 Checkpoint 历史
+ * - fork: 从指定 Checkpoint 创建新的执行线程
+ */
+export interface ICheckpointSaver {
+    /**
+     * 持久化一个 Checkpoint
+     *
+     * @param threadId - 线程 ID（一个 Task 对应一个 thread）
+     * @param data - 完整的 Checkpoint 数据（含 state 快照）
+     */
+    save(threadId: string, data: CheckpointData): Promise<void>;
+    /**
+     * 加载指定 thread 的最新 Checkpoint
+     *
+     * @param threadId - 线程 ID
+     * @returns 最新的 CheckpointData，不存在时返回 null
+     */
+    load(threadId: string): Promise<CheckpointData | null>;
+    /**
+     * 按 checkpointId 加载特定 Checkpoint
+     *
+     * 供 05-Trace/Replay 模块调用，实现 Replay/Fork 功能。
+     *
+     * @param checkpointId - Checkpoint 唯一 ID
+     * @returns 对应的 CheckpointData，不存在时返回 null
+     */
+    loadByCheckpointId(checkpointId: string): Promise<CheckpointData | null>;
+    /**
+     * 列出指定 thread 的所有 Checkpoint
+     *
+     * @param threadId - 线程 ID
+     * @returns 按时间排序的 CheckpointData 数组
+     */
+    list(threadId: string): Promise<CheckpointData[]>;
+    /**
+     * Fork：从指定 Checkpoint 创建新的执行线程
+     *
+     * 用于用户调试场景，从某个 Checkpoint 恢复执行，支持修改参数后重新执行。
+     *
+     * @param sourceCheckpointId - 源 Checkpoint ID
+     * @param newThreadId - 新线程 ID
+     * @param overrides - 覆盖的参数（可选）
+     * @returns 新的 CheckpointData
+     */
+    fork(sourceCheckpointId: string, newThreadId: string, overrides?: Record<string, unknown>): Promise<CheckpointData>;
+}

package/dist/checkpoint/contracts/checkpoint-saver.contract.js

@@ -0,0 +1,12 @@
+/**
+ * ICheckpointSaver — Checkpoint 持久化服务接口
+ *
+ * 定义 Checkpoint 的存储/加载/列表操作。
+ * 实现架构：DB 为主存储，Redis 为可选缓存。
+ *
+ * 支持 Fork 功能：从指定 Checkpoint 恢复执行。
+ *
+ * @see design.md §1.3 checkpoints 数据模型
+ * @see requirements.md Requirement 2 AC1-AC4
+ */
+export {};

package/dist/checkpoint/contracts/index.d.ts

@@ -0,0 +1 @@
+export type { ICheckpointSaver } from './checkpoint-saver.contract.js';

package/dist/checkpoint/contracts/index.js

@@ -0,0 +1 @@
+export {};

package/dist/checkpoint/file-checkpoint-saver.d.ts

@@ -0,0 +1,19 @@
+/**
+ * FileCheckpointSaver — 本地 JSON 文件存储
+ * 适用场景：本地开发、单机部署
+ */
+import type { ICheckpointSaver } from './contracts/checkpoint-saver.contract.js';
+import type { CheckpointData } from '../graph/contracts/executable-graph.js';
+export declare class FileCheckpointSaver implements ICheckpointSaver {
+    private readonly baseDir;
+    constructor(baseDir: string);
+    save(threadId: string, data: CheckpointData): Promise<void>;
+    load(threadId: string): Promise<CheckpointData | null>;
+    loadByCheckpointId(checkpointId: string, threadId?: string): Promise<CheckpointData | null>;
+    list(threadId: string): Promise<CheckpointData[]>;
+    private readCheckpoint;
+    /**
+     * Fork: 从指定 Checkpoint 创建新的执行线程
+     */
+    fork(sourceCheckpointId: string, newThreadId: string, overrides?: Record<string, unknown>): Promise<import('../graph/contracts/executable-graph.js').CheckpointData>;
+}

package/dist/checkpoint/file-checkpoint-saver.js

@@ -0,0 +1,98 @@
+/**
+ * FileCheckpointSaver — 本地 JSON 文件存储
+ * 适用场景：本地开发、单机部署
+ */
+import { readdir, readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+export class FileCheckpointSaver {
+    baseDir;
+    constructor(baseDir) {
+        this.baseDir = baseDir;
+    }
+    async save(threadId, data) {
+        const dir = join(this.baseDir, threadId);
+        await mkdir(dir, { recursive: true });
+        await writeFile(join(dir, `${data.checkpointId}.json`), JSON.stringify(data));
+        // 更新 latest 指针
+        await writeFile(join(dir, 'latest.json'), JSON.stringify({ checkpointId: data.checkpointId }));
+    }
+    async load(threadId) {
+        try {
+            const latestRaw = await readFile(join(this.baseDir, threadId, 'latest.json'), 'utf-8');
+            const { checkpointId } = JSON.parse(latestRaw);
+            return this.loadByCheckpointId(checkpointId, threadId);
+        }
+        catch {
+            return null;
+        }
+    }
+    async loadByCheckpointId(checkpointId, threadId) {
+        // If threadId provided, look directly; otherwise scan all thread dirs
+        if (threadId) {
+            return this.readCheckpoint(join(this.baseDir, threadId, `${checkpointId}.json`));
+        }
+        // ponytail: brute scan — upgrade to index file if perf matters
+        try {
+            const threads = await readdir(this.baseDir);
+            for (const t of threads) {
+                const result = await this.readCheckpoint(join(this.baseDir, t, `${checkpointId}.json`));
+                if (result)
+                    return result;
+            }
+        }
+        catch { /* dir doesn't exist */ }
+        return null;
+    }
+    async list(threadId) {
+        const dir = join(this.baseDir, threadId);
+        try {
+            const files = await readdir(dir);
+            const results = [];
+            for (const f of files) {
+                if (f === 'latest.json' || !f.endsWith('.json'))
+                    continue;
+                const data = await this.readCheckpoint(join(dir, f));
+                if (data)
+                    results.push(data);
+            }
+            return results.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+        }
+        catch {
+            return [];
+        }
+    }
+    async readCheckpoint(filePath) {
+        try {
+            const raw = await readFile(filePath, 'utf-8');
+            return JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Fork: 从指定 Checkpoint 创建新的执行线程
+     */
+    async fork(sourceCheckpointId, newThreadId, overrides) {
+        const source = await this.loadByCheckpointId(sourceCheckpointId);
+        if (!source) {
+            throw new Error(`Source checkpoint not found: ${sourceCheckpointId}`);
+        }
+        const now = new Date().toISOString();
+        const { randomUUID } = await import('node:crypto');
+        const newData = {
+            checkpointId: randomUUID(),
+            threadId: newThreadId,
+            currentNodeId: source.currentNodeId,
+            historyPath: source.historyPath,
+            state: overrides ? { ...source.state, ...overrides } : source.state,
+            createdBy: 'fork',
+            createdAt: now,
+            updatedBy: 'fork',
+            updatedAt: now,
+            isDeleted: false,
+        };
+        await this.save(newThreadId, newData);
+        return newData;
+    }
+}