@mickorz/opencode-agentic-workflow 0.3.0

package/dist/runtime/executor.d.ts

@@ -0,0 +1,46 @@
+/**
+ * AgentExecutor —— Workflow Core 与宿主（OpenCode V2）之间唯一的边界抽象
+ *
+ * Workflow Core 只认识本文件中的接口：
+ *   workflow -> AgentExecutor -> OpenCodeV2Executor -> ctx.session
+ *
+ * 架构约束：本文件禁止 import 任何 OpenCode API。
+ * 未来可新增 ClaudeCodeExecutor / CodexExecutor 等实现，Core 不感知。
+ */
+export interface AgentTask {
+    /** 发给子 agent 的提示词 */
+    prompt: string;
+    /**
+     * 子 agent 的工作目录（P2.7 隔离）：启用 workspace 时为 worktree 根，
+     * executor 应将其绑定为子会话 cwd；未启用时不传。
+     */
+    cwd?: string;
+}
+/** token 用量（结构对齐宿主 API 的 usage 形状，但为 Core 自有类型） */
+export interface TokenUsage {
+    input: number;
+    output: number;
+    reasoning: number;
+    /** 思维链 token 已含在 output 中时为 0 */
+    cache: {
+        read: number;
+        write: number;
+    };
+}
+export interface AgentResult {
+    /** 子 agent 的最终文本输出 */
+    output: string;
+    /** token 用量（宿主能提供时；如 OpenCode V2 的 assistant 消息 tokens 字段） */
+    usage?: TokenUsage;
+    /** 本次调用的美元成本（宿主直接给出时；如 V2 的 cost 字段） */
+    costUSD?: number;
+    /** 实际使用的模型 "providerID/id"（宿主能提供时） */
+    model?: string;
+}
+export interface AgentExecutor {
+    execute(task: AgentTask): Promise<AgentResult>;
+}
+/** MockExecutor：完全脱离 OpenCode，用于测试 Workflow Core 本身 */
+export declare class MockExecutor implements AgentExecutor {
+    execute(task: AgentTask): Promise<AgentResult>;
+}

package/dist/runtime/executor.js

@@ -0,0 +1,16 @@
+/**
+ * AgentExecutor —— Workflow Core 与宿主（OpenCode V2）之间唯一的边界抽象
+ *
+ * Workflow Core 只认识本文件中的接口：
+ *   workflow -> AgentExecutor -> OpenCodeV2Executor -> ctx.session
+ *
+ * 架构约束：本文件禁止 import 任何 OpenCode API。
+ * 未来可新增 ClaudeCodeExecutor / CodexExecutor 等实现，Core 不感知。
+ */
+/** MockExecutor：完全脱离 OpenCode，用于测试 Workflow Core 本身 */
+export class MockExecutor {
+    async execute(task) {
+        return { output: `[mock] ${task.prompt}` };
+    }
+}
+//# sourceMappingURL=executor.js.map

package/dist/runtime/executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../src/runtime/executor.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAoCH,uDAAuD;AACvD,MAAM,OAAO,YAAY;IACvB,KAAK,CAAC,OAAO,CAAC,IAAe;QAC3B,OAAO,EAAE,MAAM,EAAE,UAAU,IAAI,CAAC,MAAM,EAAE,EAAE,CAAA;IAC5C,CAAC;CACF"}

package/dist/runtime/semaphore.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Semaphore —— 并发上限控制
+ *
+ * 环境约束：模型 API 最多支持 3 个并发请求。
+ * parallel() 本身不限流（保持 Core 语义纯净），限流在执行器包装层完成：
+ *   withConcurrencyLimit(executor, 3)
+ */
+import type { AgentExecutor } from "./executor.js";
+export declare class Semaphore {
+    private readonly limit;
+    private active;
+    private readonly queue;
+    constructor(limit: number);
+    run<T>(fn: () => Promise<T>): Promise<T>;
+    private acquire;
+    private release;
+}
+/** 默认并发上限：模型 API 最多支持 3 个并发 */
+export declare const DEFAULT_MAX_CONCURRENCY = 3;
+/**
+ * 包装一个 AgentExecutor，限制同时执行的 agent 任务数。
+ * 超出上限的任务排队等待（FIFO），不拒绝。
+ */
+export declare function withConcurrencyLimit(executor: AgentExecutor, limit?: number): AgentExecutor;

package/dist/runtime/semaphore.js

@@ -0,0 +1,57 @@
+/**
+ * Semaphore —— 并发上限控制
+ *
+ * 环境约束：模型 API 最多支持 3 个并发请求。
+ * parallel() 本身不限流（保持 Core 语义纯净），限流在执行器包装层完成：
+ *   withConcurrencyLimit(executor, 3)
+ */
+export class Semaphore {
+    limit;
+    active = 0;
+    queue = [];
+    constructor(limit) {
+        this.limit = limit;
+        if (limit < 1)
+            throw new Error(`Semaphore limit must be >= 1, got ${limit}`);
+    }
+    async run(fn) {
+        await this.acquire();
+        try {
+            return await fn();
+        }
+        finally {
+            this.release();
+        }
+    }
+    acquire() {
+        if (this.active < this.limit) {
+            this.active += 1;
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => this.queue.push(resolve));
+    }
+    release() {
+        const next = this.queue.shift();
+        if (next) {
+            next(); // 保持 active 不变：槽位直接移交给下一个等待者
+        }
+        else {
+            this.active -= 1;
+        }
+    }
+}
+/** 默认并发上限：模型 API 最多支持 3 个并发 */
+export const DEFAULT_MAX_CONCURRENCY = 3;
+/**
+ * 包装一个 AgentExecutor，限制同时执行的 agent 任务数。
+ * 超出上限的任务排队等待（FIFO），不拒绝。
+ */
+export function withConcurrencyLimit(executor, limit = DEFAULT_MAX_CONCURRENCY) {
+    const semaphore = new Semaphore(limit);
+    return {
+        async execute(task) {
+            return semaphore.run(() => executor.execute(task));
+        },
+    };
+}
+//# sourceMappingURL=semaphore.js.map

package/dist/runtime/semaphore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"semaphore.js","sourceRoot":"","sources":["../../src/runtime/semaphore.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,MAAM,OAAO,SAAS;IAIS,KAAK;IAH1B,MAAM,GAAG,CAAC,CAAA;IACD,KAAK,GAAsB,EAAE,CAAA;IAE9C,YAA6B,KAAa;qBAAb,KAAK;QAChC,IAAI,KAAK,GAAG,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,qCAAqC,KAAK,EAAE,CAAC,CAAA;IAC9E,CAAC;IAED,KAAK,CAAC,GAAG,CAAI,EAAoB;QAC/B,MAAM,IAAI,CAAC,OAAO,EAAE,CAAA;QACpB,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,EAAE,CAAA;QACnB,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,OAAO,EAAE,CAAA;QAChB,CAAC;IACH,CAAC;IAEO,OAAO;QACb,IAAI,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;YAC7B,IAAI,CAAC,MAAM,IAAI,CAAC,CAAA;YAChB,OAAO,OAAO,CAAC,OAAO,EAAE,CAAA;QAC1B,CAAC;QACD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAA;IAC3D,CAAC;IAEO,OAAO;QACb,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAA;QAC/B,IAAI,IAAI,EAAE,CAAC;YACT,IAAI,EAAE,CAAA,CAAC,6BAA6B;QACtC,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,MAAM,IAAI,CAAC,CAAA;QAClB,CAAC;IACH,CAAC;CACF;AAED,+BAA+B;AAC/B,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAA;AAExC;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAClC,QAAuB,EACvB,KAAK,GAAW,uBAAuB;IAEvC,MAAM,SAAS,GAAG,IAAI,SAAS,CAAC,KAAK,CAAC,CAAA;IACtC,OAAO;QACL,KAAK,CAAC,OAAO,CAAC,IAAe;YAC3B,OAAO,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAA;QACpD,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/state/file-store.d.ts

@@ -0,0 +1,25 @@
+/**
+ * FileExecutionStore —— 基于 JSON 文件的执行记录存储（P2.1）
+ *
+ * 布局：<baseDir>/<runId>.json（每 run 一个文件，全量快照）
+ * 原子性：先写同目录临时文件再 rename（POSIX 同文件系统 rename 原子），
+ *          读者永远不会读到半截 JSON。
+ * 安全：runId 白名单校验（防路径穿越）。
+ * 序列化：safeSerialize 兜底处理函数/BigInt/symbol/Error/循环引用，
+ *          保证任何 in-memory run 都能落盘（占位描述代替不可 JSON 化的值）。
+ */
+import { type WorkflowRun } from "./journal.js";
+import type { ExecutionStore } from "./store.js";
+export declare class FileExecutionStore implements ExecutionStore {
+    private readonly baseDir;
+    constructor(baseDir: string);
+    private filePath;
+    private ensureDir;
+    private exists;
+    /** 原子写：同目录 tmp -> rename（隐藏名，避免被 listRuns 扫到） */
+    private writeFileAtomic;
+    createRun(run: WorkflowRun): Promise<void>;
+    saveRun(run: WorkflowRun): Promise<void>;
+    getRun(runId: string): Promise<WorkflowRun | undefined>;
+    listRuns(workflowId?: string): Promise<WorkflowRun[]>;
+}

package/dist/state/file-store.js

@@ -0,0 +1,138 @@
+/**
+ * FileExecutionStore —— 基于 JSON 文件的执行记录存储（P2.1）
+ *
+ * 布局：<baseDir>/<runId>.json（每 run 一个文件，全量快照）
+ * 原子性：先写同目录临时文件再 rename（POSIX 同文件系统 rename 原子），
+ *          读者永远不会读到半截 JSON。
+ * 安全：runId 白名单校验（防路径穿越）。
+ * 序列化：safeSerialize 兜底处理函数/BigInt/symbol/Error/循环引用，
+ *          保证任何 in-memory run 都能落盘（占位描述代替不可 JSON 化的值）。
+ */
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { isValidRunId } from "./journal.js";
+/** 不可 JSON 化的值 -> 占位描述 */
+function toPlaceholder(value) {
+    if (typeof value === "function")
+        return "[Function]";
+    if (typeof value === "bigint")
+        return value.toString();
+    if (typeof value === "symbol")
+        return String(value);
+    if (value instanceof Error)
+        return { name: value.name, message: value.message };
+    return value;
+}
+/**
+ * 安全序列化：
+ *   1) 常规路径：基础替换器（重复引用保持原语义，完整复制两份）
+ *   2) 循环引用退路：WeakSet 标记（可能把重复引用误标为 [Circular]，可接受——
+ *      只有出现真正循环时才会走到这条路）
+ */
+function safeSerialize(run) {
+    try {
+        return JSON.stringify(run, (_key, value) => toPlaceholder(value), 2) + "\n";
+    }
+    catch {
+        const seen = new WeakSet();
+        return (JSON.stringify(run, (_key, value) => {
+            if (typeof value === "object" && value !== null) {
+                if (seen.has(value))
+                    return "[Circular]";
+                seen.add(value);
+            }
+            return toPlaceholder(value);
+        }, 2) + "\n");
+    }
+}
+export class FileExecutionStore {
+    baseDir;
+    constructor(baseDir) {
+        this.baseDir = baseDir;
+    }
+    filePath(runId) {
+        if (!isValidRunId(runId)) {
+            throw new Error(`[agentic-workflow] invalid runId: ${JSON.stringify(runId)}`);
+        }
+        return path.join(this.baseDir, `${runId}.json`);
+    }
+    async ensureDir() {
+        await fs.mkdir(this.baseDir, { recursive: true });
+    }
+    async exists(file) {
+        try {
+            await fs.access(file);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** 原子写：同目录 tmp -> rename（隐藏名，避免被 listRuns 扫到） */
+    async writeFileAtomic(file, content) {
+        const tmp = path.join(path.dirname(file), `.${path.basename(file)}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}.tmp`);
+        await fs.writeFile(tmp, content, "utf8");
+        await fs.rename(tmp, file);
+    }
+    async createRun(run) {
+        const file = this.filePath(run.runId);
+        await this.ensureDir();
+        if (await this.exists(file)) {
+            throw new Error(`[agentic-workflow] run already exists: ${run.runId}`);
+        }
+        await this.writeFileAtomic(file, safeSerialize(run));
+    }
+    async saveRun(run) {
+        const file = this.filePath(run.runId);
+        await this.ensureDir();
+        await this.writeFileAtomic(file, safeSerialize(run));
+    }
+    async getRun(runId) {
+        const file = this.filePath(runId);
+        let raw;
+        try {
+            raw = await fs.readFile(file, "utf8");
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return undefined;
+            throw error;
+        }
+        try {
+            return JSON.parse(raw);
+        }
+        catch (error) {
+            throw new Error(`[agentic-workflow] corrupt run file ${file}: ` +
+                `${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    async listRuns(workflowId) {
+        let entries;
+        try {
+            entries = await fs.readdir(this.baseDir);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return [];
+            throw error;
+        }
+        const runs = [];
+        for (const entry of entries) {
+            if (!entry.endsWith(".json"))
+                continue;
+            const file = path.join(this.baseDir, entry);
+            try {
+                const run = JSON.parse(await fs.readFile(file, "utf8"));
+                if (workflowId && run.workflow?.id !== workflowId)
+                    continue;
+                runs.push(run);
+            }
+            catch {
+                console.log(`[agentic-workflow] skipping corrupt run file: ${file}`);
+            }
+        }
+        runs.sort((a, b) => b.startedAt - a.startedAt);
+        return runs;
+    }
+}
+//# sourceMappingURL=file-store.js.map

package/dist/state/file-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-store.js","sourceRoot":"","sources":["../../src/state/file-store.ts"],"names":[],"mappings":"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"}

package/dist/state/journal.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Workflow Journal 模型（P2.1，P2.5 升级版本身份）
+ *
+ * 一个 WorkflowRun 是某次 workflow 执行的持久化描述，是 P2 后续
+ * resume（P2.2）、trace（P2.4）、TUI（P2.3）、registry（P2.5）的共同基础。
+ *
+ * 形状：
+ *   WorkflowRun
+ *   ├─ runId / workflow { id, version }   ← P2.5：版本身份（安全 resume 的依据）
+ *   ├─ status / currentStep
+ *   ├─ startedAt / completedAt
+ *   └─ steps[] { input, output, status, error, timestamps }
+ *
+ * 可序列化纪律：run 及 steps 的 input/output/error 必须可 JSON 化
+ * （不可 JSON 化的值在落盘时被替换为占位描述，见 file-store 的 replacer；
+ * 需要被 resume 消费的值应保持 JSON-safe，如 AgentResult { output: string }）。
+ */
+import type { WorkspaceIdentity } from "../workspace/provider.js";
+export type RunStatus = "running" | "completed" | "failed" | "aborted";
+export type StepStatus = "pending" | "running" | "completed" | "failed" | "skipped";
+export interface StepErrorRecord {
+    /** 错误名（如 WorkflowCheckError） */
+    name: string;
+    message: string;
+}
+/** workflow 版本身份：resume 必须经 registry 解析到精确版本，绝不隐式取最新 */
+export interface WorkflowIdentity {
+    id: string;
+    /** 语义化版本（与 WorkflowDefinition.version 一致） */
+    version: string;
+}
+export interface StepRecord {
+    /** 步骤序号（0 起，对应 sequence 下标） */
+    index: number;
+    /** 步骤名（可选，便于定位） */
+    name?: string;
+    status: StepStatus;
+    /** 步骤输入（序列化后；通常是上一步 output） */
+    input?: unknown;
+    /** 步骤输出（序列化后；resume 时作为后续步骤的 prev） */
+    output?: unknown;
+    /** 失败信息 */
+    error?: StepErrorRecord;
+    startedAt?: number;
+    completedAt?: number;
+}
+export interface WorkflowRun {
+    /** 全局唯一 run 标识（run_<time>_<rand>） */
+    runId: string;
+    /** workflow 版本身份（P2.5：安全 resume 依据，见 registry.resolve） */
+    workflow: WorkflowIdentity;
+    status: RunStatus;
+    /** 当前/最后尝试的步骤序号；未开始为 -1 */
+    currentStep: number;
+    /** epoch ms（排序与耗时计算用） */
+    startedAt: number;
+    completedAt?: number;
+    /** 执行参数（重建执行所需的最小上下文，如 topic；由 argsSchema 声明契约） */
+    args?: unknown;
+    /**
+     * 隔离工作区身份（P2.7）：resume 必须附着原 workspace——
+     * durable resume = journal 状态 + 文件系统状态同时恢复。
+     * 清理完成后置 undefined（见 RunJournal.clearWorkspace）。
+     */
+    workspace?: WorkspaceIdentity;
+    /** 失败/中断原因（run 级别） */
+    failure?: StepErrorRecord;
+    steps: StepRecord[];
+}
+/** 生成 runId：run_<epochms>_<rand8>（文件名安全字符） */
+export declare function generateRunId(): string;
+/** runId 白名单（防止路径穿越；文件名安全字符集） */
+export declare function isValidRunId(runId: string): boolean;
+/** Error -> StepErrorRecord */
+export declare function toErrorRecord(error: unknown): StepErrorRecord;
+/** 创建初始 run（全部步骤 pending） */
+export declare function createRun(input: {
+    runId?: string;
+    workflow: WorkflowIdentity;
+    args?: unknown;
+    stepNames?: string[];
+    stepCount: number;
+}): WorkflowRun;

package/dist/state/journal.js

@@ -0,0 +1,59 @@
+/**
+ * Workflow Journal 模型（P2.1，P2.5 升级版本身份）
+ *
+ * 一个 WorkflowRun 是某次 workflow 执行的持久化描述，是 P2 后续
+ * resume（P2.2）、trace（P2.4）、TUI（P2.3）、registry（P2.5）的共同基础。
+ *
+ * 形状：
+ *   WorkflowRun
+ *   ├─ runId / workflow { id, version }   ← P2.5：版本身份（安全 resume 的依据）
+ *   ├─ status / currentStep
+ *   ├─ startedAt / completedAt
+ *   └─ steps[] { input, output, status, error, timestamps }
+ *
+ * 可序列化纪律：run 及 steps 的 input/output/error 必须可 JSON 化
+ * （不可 JSON 化的值在落盘时被替换为占位描述，见 file-store 的 replacer；
+ * 需要被 resume 消费的值应保持 JSON-safe，如 AgentResult { output: string }）。
+ */
+/** 生成 runId：run_<epochms>_<rand8>（文件名安全字符） */
+export function generateRunId() {
+    const rand = Math.random().toString(36).slice(2, 10);
+    return `run_${Date.now()}_${rand}`;
+}
+/** runId 白名单（防止路径穿越；文件名安全字符集） */
+export function isValidRunId(runId) {
+    return /^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/.test(runId);
+}
+/** Error -> StepErrorRecord */
+export function toErrorRecord(error) {
+    if (error instanceof Error) {
+        return { name: error.name, message: error.message };
+    }
+    return { name: "Error", message: String(error) };
+}
+/** 创建初始 run（全部步骤 pending） */
+export function createRun(input) {
+    if (!Number.isInteger(input.stepCount) || input.stepCount < 0) {
+        throw new Error(`stepCount must be a non-negative integer, got ${input.stepCount}`);
+    }
+    if (!input.workflow.id || typeof input.workflow.id !== "string") {
+        throw new Error("workflow.id must be a non-empty string");
+    }
+    if (!input.workflow.version || typeof input.workflow.version !== "string") {
+        throw new Error("workflow.version must be a non-empty string");
+    }
+    return {
+        runId: input.runId ?? generateRunId(),
+        workflow: input.workflow,
+        status: "running",
+        currentStep: -1,
+        startedAt: Date.now(),
+        args: input.args,
+        steps: Array.from({ length: input.stepCount }, (_, index) => ({
+            index,
+            name: input.stepNames?.[index],
+            status: "pending",
+        })),
+    };
+}
+//# sourceMappingURL=journal.js.map

package/dist/state/journal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal.js","sourceRoot":"","sources":["../../src/state/journal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AA2DH,8CAA8C;AAC9C,MAAM,UAAU,aAAa;IAC3B,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;IACpD,OAAO,OAAO,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,EAAE,CAAA;AACpC,CAAC;AAED,iCAAiC;AACjC,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,OAAO,oCAAoC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;AACzD,CAAC;AAED,+BAA+B;AAC/B,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAA;IACrD,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,CAAA;AAClD,CAAC;AAED,6BAA6B;AAC7B,MAAM,UAAU,SAAS,CAAC,KAMzB;IACC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,KAAK,CAAC,SAAS,GAAG,CAAC,EAAE,CAAC;QAC9D,MAAM,IAAI,KAAK,CAAC,iDAAiD,KAAK,CAAC,SAAS,EAAE,CAAC,CAAA;IACrF,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,IAAI,OAAO,KAAK,CAAC,QAAQ,CAAC,EAAE,KAAK,QAAQ,EAAE,CAAC;QAChE,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAA;IAC3D,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,IAAI,OAAO,KAAK,CAAC,QAAQ,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;QAC1E,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAA;IAChE,CAAC;IACD,OAAO;QACL,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,aAAa,EAAE;QACrC,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,MAAM,EAAE,SAAS;QACjB,WAAW,EAAE,CAAC,CAAC;QACf,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;QACrB,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;YAC5D,KAAK;YACL,IAAI,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC,KAAK,CAAC;YAC9B,MAAM,EAAE,SAAkB;SAC3B,CAAC,CAAC;KACJ,CAAA;AACH,CAAC"}

package/dist/state/recorder.d.ts

@@ -0,0 +1,63 @@
+/**
+ * RunJournal —— run 生命周期记录器（P2.1）
+ *
+ * 包装 ExecutionStore：每次状态变更后全量落盘（journal = 一串原子快照）。
+ * P2.2 的 sequence resume 将基于这些记录重建执行（attach -> 读已完成步骤 -> 续跑）。
+ *
+ * 典型生命周期：
+ *   start()            -> run 创建并落盘（全部步骤 pending）
+ *   stepStarted(i)     -> 步骤开始（input 记录）
+ *   stepCompleted(i)   -> 步骤成功（output 记录，resume 时的续跑依据）
+ *   stepFailed(i, e)   -> 步骤失败（error 记录）
+ *   complete()/fail(e) -> run 收口（fail 时仍为 pending 的步骤标记 skipped）
+ *
+ * status=aborted 预留给中断场景（交互拒绝/人工打断，P2.3+）。
+ */
+import { type WorkflowIdentity, type WorkflowRun } from "./journal.js";
+import type { ExecutionStore } from "./store.js";
+import type { WorkspaceIdentity } from "../workspace/provider.js";
+export interface JournalStartInput {
+    workflow: WorkflowIdentity;
+    /** 执行参数（重建执行所需的最小上下文） */
+    args?: unknown;
+    /** 步骤名（可选） */
+    stepNames?: string[];
+    stepCount: number;
+    /** 显式 runId（缺省自动生成） */
+    runId?: string;
+}
+export declare class RunJournal {
+    private readonly store;
+    readonly run: WorkflowRun;
+    private constructor();
+    /** 创建新 run 并持久化初始状态 */
+    static start(store: ExecutionStore, input: JournalStartInput): Promise<RunJournal>;
+    /** 附加到已有 run（resume 场景：读取历史 journal 继续记录）；不存在返回 undefined */
+    static attach(store: ExecutionStore, runId: string): Promise<RunJournal | undefined>;
+    private assertOpen;
+    private step;
+    stepStarted(index: number, input?: unknown): Promise<void>;
+    stepCompleted(index: number, output?: unknown): Promise<void>;
+    stepFailed(index: number, error: unknown): Promise<void>;
+    /** run 成功收口 */
+    complete(): Promise<void>;
+    /** run 失败收口：仍为 pending 的步骤标记 skipped（fail-fast 下它们不会被执行） */
+    fail(error: unknown): Promise<void>;
+    /**
+     * 记录 workspace 身份（P2.7 隔离启用时，resume attach 的依据）。
+     * 仅限 run 进行中（收口后不可再写）。
+     */
+    setWorkspace(identity: WorkspaceIdentity): Promise<void>;
+    /**
+     * 清除 workspace 身份（清理完成后调用）。
+     * 维护性操作：允许在 run 收口后执行——否则已清理的 run
+     * 在幂等 resume 时会试图 attach 一个已删除的 worktree。
+     */
+    clearWorkspace(): Promise<void>;
+    /**
+     * 重新打开已收口的 run（resume 场景）：
+     * failed/aborted -> running；未完成步骤重置 pending（连同 input/output/时间戳/错误），
+     * completed 步骤原样保留（resume 的续跑依据）。
+     */
+    reopen(): Promise<void>;
+}