@mickorz/opencode-agentic-workflow 0.3.0

package/dist/state/recorder.js

@@ -0,0 +1,138 @@
+/**
+ * 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 { createRun, toErrorRecord, } from "./journal.js";
+export class RunJournal {
+    store;
+    run;
+    constructor(store, run) {
+        this.store = store;
+        this.run = run;
+    }
+    /** 创建新 run 并持久化初始状态 */
+    static async start(store, input) {
+        const run = createRun(input);
+        await store.createRun(run);
+        return new RunJournal(store, run);
+    }
+    /** 附加到已有 run（resume 场景：读取历史 journal 继续记录）；不存在返回 undefined */
+    static async attach(store, runId) {
+        const run = await store.getRun(runId);
+        return run ? new RunJournal(store, run) : undefined;
+    }
+    assertOpen() {
+        if (this.run.status !== "running") {
+            throw new Error(`journal closed (status=${this.run.status}): run ${this.run.runId}`);
+        }
+    }
+    step(index) {
+        const step = this.run.steps[index];
+        if (!step) {
+            throw new Error(`step index out of range: ${index} (run ${this.run.runId})`);
+        }
+        return step;
+    }
+    async stepStarted(index, input) {
+        this.assertOpen();
+        const step = this.step(index);
+        step.status = "running";
+        step.input = input;
+        step.startedAt = Date.now();
+        this.run.currentStep = index;
+        await this.store.saveRun(this.run);
+    }
+    async stepCompleted(index, output) {
+        this.assertOpen();
+        const step = this.step(index);
+        step.status = "completed";
+        step.output = output;
+        step.completedAt = Date.now();
+        await this.store.saveRun(this.run);
+    }
+    async stepFailed(index, error) {
+        this.assertOpen();
+        const step = this.step(index);
+        step.status = "failed";
+        step.error = toErrorRecord(error);
+        step.completedAt = Date.now();
+        await this.store.saveRun(this.run);
+    }
+    /** run 成功收口 */
+    async complete() {
+        this.assertOpen();
+        this.run.status = "completed";
+        this.run.completedAt = Date.now();
+        await this.store.saveRun(this.run);
+    }
+    /** run 失败收口：仍为 pending 的步骤标记 skipped（fail-fast 下它们不会被执行） */
+    async fail(error) {
+        this.assertOpen();
+        this.run.status = "failed";
+        this.run.completedAt = Date.now();
+        this.run.failure = toErrorRecord(error);
+        for (const step of this.run.steps) {
+            if (step.status === "pending")
+                step.status = "skipped";
+        }
+        await this.store.saveRun(this.run);
+    }
+    /**
+     * 记录 workspace 身份（P2.7 隔离启用时，resume attach 的依据）。
+     * 仅限 run 进行中（收口后不可再写）。
+     */
+    async setWorkspace(identity) {
+        this.assertOpen();
+        this.run.workspace = identity;
+        await this.store.saveRun(this.run);
+    }
+    /**
+     * 清除 workspace 身份（清理完成后调用）。
+     * 维护性操作：允许在 run 收口后执行——否则已清理的 run
+     * 在幂等 resume 时会试图 attach 一个已删除的 worktree。
+     */
+    async clearWorkspace() {
+        if (this.run.workspace === undefined)
+            return;
+        this.run.workspace = undefined;
+        await this.store.saveRun(this.run);
+    }
+    /**
+     * 重新打开已收口的 run（resume 场景）：
+     * failed/aborted -> running；未完成步骤重置 pending（连同 input/output/时间戳/错误），
+     * completed 步骤原样保留（resume 的续跑依据）。
+     */
+    async reopen() {
+        if (this.run.status === "running")
+            return;
+        if (this.run.status === "completed") {
+            throw new Error(`cannot reopen completed run: ${this.run.runId}`);
+        }
+        this.run.status = "running";
+        this.run.completedAt = undefined;
+        this.run.failure = undefined;
+        for (const step of this.run.steps) {
+            if (step.status !== "completed") {
+                step.status = "pending";
+                step.error = undefined;
+                step.input = undefined;
+                step.output = undefined;
+                step.startedAt = undefined;
+                step.completedAt = undefined;
+            }
+        }
+        await this.store.saveRun(this.run);
+    }
+}
+//# sourceMappingURL=recorder.js.map

package/dist/state/recorder.js.map

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

package/dist/state/store.d.ts

@@ -0,0 +1,23 @@
+/**
+ * ExecutionStore —— 持久化执行记录的存储抽象（P2.1）
+ *
+ * 依赖倒置（与 AgentExecutor / CheckpointGate 同思路）：
+ *   Workflow Core 只依赖本接口；实现可以是
+ *   FileExecutionStore（本地 JSON）/ SQLiteExecutionStore /
+ *   OpenCodeStorageAdapter（P2 后期，经 ctx.storage）。
+ *
+ * 写入契约：
+ *   - saveRun 为全量覆写（journal 每次状态变更后整体落盘）
+ *   - 实现必须保证单个 run 文件的写入原子性（读不到半截 JSON）
+ */
+import type { WorkflowRun } from "./journal.js";
+export interface ExecutionStore {
+    /** 新建 run（已存在同 runId 时抛错，防止覆盖历史记录） */
+    createRun(run: WorkflowRun): Promise<void>;
+    /** 全量覆写保存 run */
+    saveRun(run: WorkflowRun): Promise<void>;
+    /** 读取 run；不存在返回 undefined */
+    getRun(runId: string): Promise<WorkflowRun | undefined>;
+    /** 列出 runs；可选按 workflow id 过滤（不区分版本），按 startedAt 倒序 */
+    listRuns(workflowId?: string): Promise<WorkflowRun[]>;
+}

package/dist/state/store.js

@@ -0,0 +1,14 @@
+/**
+ * ExecutionStore —— 持久化执行记录的存储抽象（P2.1）
+ *
+ * 依赖倒置（与 AgentExecutor / CheckpointGate 同思路）：
+ *   Workflow Core 只依赖本接口；实现可以是
+ *   FileExecutionStore（本地 JSON）/ SQLiteExecutionStore /
+ *   OpenCodeStorageAdapter（P2 后期，经 ctx.storage）。
+ *
+ * 写入契约：
+ *   - saveRun 为全量覆写（journal 每次状态变更后整体落盘）
+ *   - 实现必须保证单个 run 文件的写入原子性（读不到半截 JSON）
+ */
+export {};
+//# sourceMappingURL=store.js.map

package/dist/state/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/state/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/workflow/agent.d.ts

@@ -0,0 +1,8 @@
+/**
+ * agent() —— 提交单个子 agent 任务
+ *
+ * 不感知 ctx / OpenCode：只经由 requireExecutor() 拿到当前绑定的
+ * AgentExecutor 并执行。P2.4 起派发 agent.started / completed / failed 事件。
+ */
+import type { AgentResult } from "../runtime/executor.js";
+export declare function agent(prompt: string): Promise<AgentResult>;

package/dist/workflow/agent.js

@@ -0,0 +1,38 @@
+/**
+ * agent() —— 提交单个子 agent 任务
+ *
+ * 不感知 ctx / OpenCode：只经由 requireExecutor() 拿到当前绑定的
+ * AgentExecutor 并执行。P2.4 起派发 agent.started / completed / failed 事件。
+ */
+import { requireExecutor } from "../runtime/engine.js";
+import { emitEvent, preview } from "../observability/events.js";
+import { currentWorkspace } from "../workspace/ambient.js";
+export async function agent(prompt) {
+    const workspace = currentWorkspace();
+    emitEvent({ type: "agent.started", promptPreview: preview(prompt) });
+    const startedAt = Date.now();
+    try {
+        const result = await requireExecutor().execute({
+            prompt,
+            ...(workspace ? { cwd: workspace.root } : {}),
+        });
+        emitEvent({
+            type: "agent.completed",
+            durationMs: Date.now() - startedAt,
+            outputLength: result.output.length,
+            usage: result.usage,
+            costUSD: result.costUSD,
+            model: result.model,
+        });
+        return result;
+    }
+    catch (error) {
+        emitEvent({
+            type: "agent.failed",
+            durationMs: Date.now() - startedAt,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        throw error;
+    }
+}
+//# sourceMappingURL=agent.js.map

package/dist/workflow/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../src/workflow/agent.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAA;AAC/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAA;AAE1D,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,MAAc;IACxC,MAAM,SAAS,GAAG,gBAAgB,EAAE,CAAA;IACpC,SAAS,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,aAAa,EAAE,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;IACpE,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;IAC5B,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,eAAe,EAAE,CAAC,OAAO,CAAC;YAC7C,MAAM;YACN,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC9C,CAAC,CAAA;QACF,SAAS,CAAC;YACR,IAAI,EAAE,iBAAiB;YACvB,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;YAClC,YAAY,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM;YAClC,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,KAAK,EAAE,MAAM,CAAC,KAAK;SACpB,CAAC,CAAA;QACF,OAAO,MAAM,CAAA;IACf,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,SAAS,CAAC;YACR,IAAI,EAAE,cAAc;YACpB,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;YAClC,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;SAC9D,CAAC,CAAA;QACF,MAAM,KAAK,CAAA;IACb,CAAC;AACH,CAAC"}

package/dist/workflow/fallback.d.ts

@@ -0,0 +1,15 @@
+/**
+ * fallback() —— 降级候选组合子（P1.4）
+ *
+ * 依序尝试候选任务，第一个成功者胜出；全部失败抛 WorkflowFallbackError
+ * （errors 按尝试顺序排列，保留每个候选的失败原因）。
+ *
+ * 与 retry 的组合即用户链路：
+ *   agent -> check fail -> retry -> still fail -> fallback
+ *   fallback([() => retry(primary), () => degraded])
+ */
+export interface FallbackOptions {
+    /** 日志标签 */
+    label?: string;
+}
+export declare function fallback<T>(candidates: Array<() => Promise<T>>, options?: FallbackOptions): Promise<T>;

package/dist/workflow/fallback.js

@@ -0,0 +1,32 @@
+/**
+ * fallback() —— 降级候选组合子（P1.4）
+ *
+ * 依序尝试候选任务，第一个成功者胜出；全部失败抛 WorkflowFallbackError
+ * （errors 按尝试顺序排列，保留每个候选的失败原因）。
+ *
+ * 与 retry 的组合即用户链路：
+ *   agent -> check fail -> retry -> still fail -> fallback
+ *   fallback([() => retry(primary), () => degraded])
+ */
+import { WorkflowFallbackError } from "../runtime/errors.js";
+export async function fallback(candidates, options) {
+    const label = options?.label ?? "";
+    const errors = [];
+    for (let i = 0; i < candidates.length; i++) {
+        const candidate = candidates[i];
+        if (!candidate)
+            continue;
+        try {
+            const value = await candidate();
+            console.log(`[agentic-workflow] fallback resolved by candidate #${i}${label ? ` (${label})` : ""}`);
+            return value;
+        }
+        catch (cause) {
+            errors.push(cause);
+            const message = cause instanceof Error ? cause.message : String(cause);
+            console.log(`[agentic-workflow] fallback candidate #${i} failed${label ? ` (${label})` : ""}: ${message}`);
+        }
+    }
+    throw new WorkflowFallbackError(errors, label);
+}
+//# sourceMappingURL=fallback.js.map

package/dist/workflow/fallback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fallback.js","sourceRoot":"","sources":["../../src/workflow/fallback.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AAO5D,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,UAAmC,EACnC,OAAyB;IAEzB,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,IAAI,EAAE,CAAA;IAClC,MAAM,MAAM,GAAc,EAAE,CAAA;IAE5B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,UAAU,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3C,MAAM,SAAS,GAAG,UAAU,CAAC,CAAC,CAAC,CAAA;QAC/B,IAAI,CAAC,SAAS;YAAE,SAAQ;QACxB,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,MAAM,SAAS,EAAE,CAAA;YAC/B,OAAO,CAAC,GAAG,CACT,sDAAsD,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,KAAK,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CACvF,CAAA;YACD,OAAO,KAAK,CAAA;QACd,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;YAClB,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;YACtE,OAAO,CAAC,GAAG,CACT,0CAA0C,CAAC,UAAU,KAAK,CAAC,CAAC,CAAC,KAAK,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK,OAAO,EAAE,CAC9F,CAAA;QACH,CAAC;IACH,CAAC;IAED,MAAM,IAAI,qBAAqB,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;AAChD,CAAC"}

package/dist/workflow/parallel.d.ts

@@ -0,0 +1,14 @@
+/**
+ * parallel() —— 并行执行多个任务（P1.3 失败语义）
+ *
+ * onFailure 三种模式：
+ *   "fail-fast"（默认）：第一个失败即抛 WorkflowParallelError；
+ *                        其余任务不再影响结果（已附加吞错处理，不会产生 unhandled rejection）。
+ *   "collect"          ：等全部任务落定；任一失败则抛错，携带全部失败与成功结果（完整可观测）。
+ *   "partial"          ：等全部任务落定；返回结果数组，失败槽位为 undefined，不抛错（尽力而为）。
+ */
+export interface ParallelOptions {
+    /** 失败模式，默认 "fail-fast" */
+    onFailure?: "fail-fast" | "collect" | "partial";
+}
+export declare function parallel<T>(tasks: Array<() => Promise<T>>, options?: ParallelOptions): Promise<T[]>;

package/dist/workflow/parallel.js

@@ -0,0 +1,62 @@
+/**
+ * parallel() —— 并行执行多个任务（P1.3 失败语义）
+ *
+ * onFailure 三种模式：
+ *   "fail-fast"（默认）：第一个失败即抛 WorkflowParallelError；
+ *                        其余任务不再影响结果（已附加吞错处理，不会产生 unhandled rejection）。
+ *   "collect"          ：等全部任务落定；任一失败则抛错，携带全部失败与成功结果（完整可观测）。
+ *   "partial"          ：等全部任务落定；返回结果数组，失败槽位为 undefined，不抛错（尽力而为）。
+ */
+import { WorkflowParallelError } from "../runtime/errors.js";
+export async function parallel(tasks, options) {
+    const onFailure = options?.onFailure ?? "fail-fast";
+    if (tasks.length === 0)
+        return [];
+    if (onFailure === "fail-fast") {
+        return new Promise((resolve, reject) => {
+            const results = new Array(tasks.length).fill(undefined);
+            let rejected = false;
+            let pending = tasks.length;
+            tasks.forEach((task, index) => {
+                Promise.resolve()
+                    .then(task)
+                    .then((value) => {
+                    if (rejected)
+                        return;
+                    results[index] = value;
+                    pending -= 1;
+                    if (pending === 0)
+                        resolve(results);
+                })
+                    .catch((cause) => {
+                    if (rejected)
+                        return; // 已失败：吞掉后续错误，避免 unhandled rejection
+                    rejected = true;
+                    reject(new WorkflowParallelError([{ index, error: cause }], results, "fail-fast"));
+                });
+            });
+        });
+    }
+    // collect / partial：等全部落定
+    const settled = await Promise.allSettled(tasks.map((task) => task()));
+    const results = new Array(tasks.length).fill(undefined);
+    const failures = [];
+    settled.forEach((outcome, index) => {
+        if (outcome.status === "fulfilled") {
+            results[index] = outcome.value;
+        }
+        else {
+            failures.push({ index, error: outcome.reason });
+        }
+    });
+    if (onFailure === "collect" && failures.length > 0) {
+        throw new WorkflowParallelError(failures, results, "collect");
+    }
+    // partial：失败槽位保持 undefined，仅记录日志
+    for (const failure of failures) {
+        const message = failure.error instanceof Error ? failure.error.message : String(failure.error);
+        console.log(`[agentic-workflow] parallel task #${failure.index} failed (partial): ${message}`);
+    }
+    return results;
+}
+//# sourceMappingURL=parallel.js.map

package/dist/workflow/parallel.js.map

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

package/dist/workflow/phase.d.ts

@@ -0,0 +1,7 @@
+/**
+ * phase() —— 标记当前工作流阶段
+ *
+ * P0: metadata + log；P2.4 起升级为事件源（phase.started 派发到事件总线），
+ * TUI / metrics / trace / journal 均可消费。
+ */
+export declare function phase(name: string): void;

package/dist/workflow/phase.js

@@ -0,0 +1,12 @@
+/**
+ * phase() —— 标记当前工作流阶段
+ *
+ * P0: metadata + log；P2.4 起升级为事件源（phase.started 派发到事件总线），
+ * TUI / metrics / trace / journal 均可消费。
+ */
+import { emitEvent } from "../observability/events.js";
+export function phase(name) {
+    console.log(`[agentic-workflow] phase: ${name}`);
+    emitEvent({ type: "phase.started", name });
+}
+//# sourceMappingURL=phase.js.map

package/dist/workflow/phase.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"phase.js","sourceRoot":"","sources":["../../src/workflow/phase.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAA;AAEtD,MAAM,UAAU,KAAK,CAAC,IAAY;IAChC,OAAO,CAAC,GAAG,CAAC,6BAA6B,IAAI,EAAE,CAAC,CAAA;IAChD,SAAS,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,CAAC,CAAA;AAC5C,CAAC"}

package/dist/workflow/reliable.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Reliable Workflow —— P1 完整可靠执行链（用户验收 Demo 的落地）
+ *
+ * 链路：执行 -> 确定性检查 -> 语义验证（N reviewer）-> 人工审批
+ *
+ *   agent(分析主题)           —— 做事
+ *     -> check(commandSuccess) —— 确定性验证（环境命令真实执行）
+ *     -> verify(artifact)      —— 语义质量验证（reviewer 子会话并行）
+ *     -> checkpoint(审批)      —— Human-in-the-loop（P1 策略门 / P2.3 交互门）
+ *
+ * 默认 fail-fast：任一环节失败即中断（WorkflowError 家族）。
+ *
+ * P2.5 resume 关键设计：步骤状态经 prev 链**累积**（不再闭包捕获）——
+ * resume 跳过 completed 步骤时，后续步骤与最终报告仍能从
+ * journal 记录的累积状态完整重建。
+ */
+import { type ReviewVerdict } from "../quality/verify.js";
+import { type RunStepsFn } from "./sequence.js";
+export interface ReliableWorkflowOptions {
+    /** check 步骤执行的命令，默认 "node --version" */
+    checkCommand?: string;
+    /** verify 的 reviewer 数，默认 2 */
+    reviewers?: number;
+    /** checkpoint 节点标签 */
+    checkpointLabel?: string;
+    /**
+     * 注入的步骤编排入口（registry ctx.runSteps）；缺省 sequence 直跑。
+     * 传入后 start/resume 由其内部封装（journal 记录 / completed 前缀跳过）。
+     */
+    runSteps?: RunStepsFn;
+}
+/** 链路累积状态：每一步返回 {...prev, 新字段}，journal 逐步落盘 */
+export interface ReliableState {
+    artifact?: string;
+    checkLabel?: string;
+    checkOk?: boolean;
+    verdicts?: ReviewVerdict[];
+    checkpointApproved?: boolean;
+}
+export interface ReliableWorkflowReport {
+    topic: string;
+    artifact: string;
+    checkLabel: string;
+    checkOk: boolean;
+    verdicts: ReviewVerdict[];
+    verified: boolean;
+    checkpointApproved: boolean;
+    output: string;
+}
+export declare function runReliableWorkflow(topic: string, options?: ReliableWorkflowOptions): Promise<ReliableWorkflowReport>;

package/dist/workflow/reliable.js

@@ -0,0 +1,92 @@
+/**
+ * Reliable Workflow —— P1 完整可靠执行链（用户验收 Demo 的落地）
+ *
+ * 链路：执行 -> 确定性检查 -> 语义验证（N reviewer）-> 人工审批
+ *
+ *   agent(分析主题)           —— 做事
+ *     -> check(commandSuccess) —— 确定性验证（环境命令真实执行）
+ *     -> verify(artifact)      —— 语义质量验证（reviewer 子会话并行）
+ *     -> checkpoint(审批)      —— Human-in-the-loop（P1 策略门 / P2.3 交互门）
+ *
+ * 默认 fail-fast：任一环节失败即中断（WorkflowError 家族）。
+ *
+ * P2.5 resume 关键设计：步骤状态经 prev 链**累积**（不再闭包捕获）——
+ * resume 跳过 completed 步骤时，后续步骤与最终报告仍能从
+ * journal 记录的累积状态完整重建。
+ */
+import { assert } from "../quality/check.js";
+import { checkpoint } from "../quality/checkpoint.js";
+import { commandSuccess } from "../quality/predicates.js";
+import { assertVerify } from "../quality/verify.js";
+import { observeWorkflow } from "../observability/observe.js";
+import { agent } from "./agent.js";
+import { phase } from "./phase.js";
+import { sequence } from "./sequence.js";
+export async function runReliableWorkflow(topic, options) {
+    const checkCommand = options?.checkCommand ?? "node --version";
+    const reviewers = options?.reviewers ?? 2;
+    const runSteps = options?.runSteps ?? ((steps, stepOptions) => sequence(steps, stepOptions));
+    return observeWorkflow("reliable", async () => {
+        phase("Execute");
+        const state = await runSteps([
+            // 1. 执行：分析主题
+            async () => {
+                const result = await agent(`针对主题「${topic}」写一份简明分析（3-5 个要点）。` +
+                    "直接用你自己的知识回答，禁止调用 workflow 或其他任何工具。");
+                return { artifact: result.output };
+            },
+            // 2. 确定性检查：环境命令真实执行（失败即中断：assert 严格版）
+            async (prev) => {
+                const label = `check: ${checkCommand} must succeed`;
+                const result = await assert(() => commandSuccess(checkCommand), label);
+                return { ...prev, checkLabel: label, checkOk: result.ok };
+            },
+            // 3. 语义验证：N reviewer 并行评审 agent 产物（任一 fail 即中断：assertVerify 严格版）
+            async (prev) => {
+                const result = await assertVerify(prev?.artifact ?? "", {
+                    reviewers,
+                    label: `verify: ${topic}`,
+                    criteria: "分析切题、要点清晰、无事实性错误",
+                });
+                return { ...prev, verdicts: result.verdicts };
+            },
+            // 4. 人工审批（P1 策略门 / P2.3 交互门，经 CheckpointGate 注入）
+            async (prev) => {
+                await checkpoint("验证完成，是否继续？", {
+                    label: options?.checkpointLabel ?? "final-review",
+                });
+                return { ...prev, checkpointApproved: true };
+            },
+        ], { stepNames: ["execute", "check", "verify", "checkpoint"] });
+        phase("Done");
+        const artifact = state?.artifact ?? "";
+        const checkLabel = state?.checkLabel ?? "";
+        const checkOk = state?.checkOk ?? false;
+        const verdicts = state?.verdicts ?? [];
+        const checkpointApproved = state?.checkpointApproved ?? false;
+        const passed = verdicts.filter((v) => v.verdict === "pass").length;
+        const output = [
+            `# Reliable Workflow 报告：${topic}`,
+            "",
+            `1. 执行：agent 已产出分析（${artifact.length} 字符）`,
+            `2. 确定性检查 ${checkOk ? "通过" : "失败"}：${checkLabel}`,
+            `3. 语义验证 ${passed}/${verdicts.length} reviewer 通过`,
+            `4. 审批：${checkpointApproved ? "已批准" : "未批准"}`,
+            "",
+            "## 分析产物",
+            "",
+            artifact,
+        ].join("\n");
+        return {
+            topic,
+            artifact,
+            checkLabel,
+            checkOk,
+            verdicts,
+            verified: passed === verdicts.length,
+            checkpointApproved,
+            output,
+        };
+    }, { topic, reviewers, checkCommand });
+}
+//# sourceMappingURL=reliable.js.map

package/dist/workflow/reliable.js.map

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

package/dist/workflow/retry.d.ts

@@ -0,0 +1,28 @@
+/**
+ * retry() —— 失败重试组合子（P1.4）
+ *
+ * 基于统一失败模型（WorkflowError 家族）：默认重试一切失败，
+ * 可用 retryOn 过滤（例如对配额类错误不重试，防重试风暴——见经验沉淀）。
+ *
+ * 防锤击默认值（经验教训 tool-throw-retry-storm-and-concurrency.md）：
+ *   attempts=3 / delayMs=1000 / exponential backoff / maxDelayMs=30s
+ *
+ * 拒绝契约：
+ *   - 重试耗尽 -> WorkflowRetryError（attempts + lastError cause 链）
+ *   - retryOn 判定不可重试 -> 原样抛出原始异常（调用方自行分类）
+ */
+export interface RetryOptions {
+    /** 总尝试次数（含首次），默认 3 */
+    attempts?: number;
+    /** 首次重试前等待毫秒，默认 1000；0 表示立即重试 */
+    delayMs?: number;
+    /** 退避策略：fixed 固定间隔 / exponential 指数退避（默认） */
+    backoff?: "fixed" | "exponential";
+    /** exponential 模式下的单次等待上限，默认 30000 */
+    maxDelayMs?: number;
+    /** 重试过滤器：返回 false 的异常不重试、原样抛出 */
+    retryOn?: (error: unknown) => boolean;
+    /** 日志标签 */
+    label?: string;
+}
+export declare function retry<T>(task: () => Promise<T>, options?: RetryOptions): Promise<T>;

package/dist/workflow/retry.js

@@ -0,0 +1,53 @@
+/**
+ * retry() —— 失败重试组合子（P1.4）
+ *
+ * 基于统一失败模型（WorkflowError 家族）：默认重试一切失败，
+ * 可用 retryOn 过滤（例如对配额类错误不重试，防重试风暴——见经验沉淀）。
+ *
+ * 防锤击默认值（经验教训 tool-throw-retry-storm-and-concurrency.md）：
+ *   attempts=3 / delayMs=1000 / exponential backoff / maxDelayMs=30s
+ *
+ * 拒绝契约：
+ *   - 重试耗尽 -> WorkflowRetryError（attempts + lastError cause 链）
+ *   - retryOn 判定不可重试 -> 原样抛出原始异常（调用方自行分类）
+ */
+import { WorkflowRetryError } from "../runtime/errors.js";
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export async function retry(task, options) {
+    const attempts = Math.max(1, Math.floor(options?.attempts ?? 3));
+    const delayMs = options?.delayMs ?? 1000;
+    const backoff = options?.backoff ?? "exponential";
+    const maxDelayMs = options?.maxDelayMs ?? 30_000;
+    const retryOn = options?.retryOn ?? (() => true);
+    const label = options?.label ?? "";
+    let lastError;
+    for (let attempt = 1; attempt <= attempts; attempt++) {
+        try {
+            return await task();
+        }
+        catch (cause) {
+            lastError = cause;
+            if (attempt === attempts) {
+                throw new WorkflowRetryError(attempts, lastError, label);
+            }
+            if (!retryOn(cause)) {
+                // 不可重试：原样抛出，让调用方的失败策略接手
+                throw cause;
+            }
+            const wait = backoff === "exponential"
+                ? Math.min(delayMs * 2 ** (attempt - 1), maxDelayMs)
+                : delayMs;
+            if (wait > 0) {
+                const message = cause instanceof Error ? cause.message : String(cause);
+                console.log(`[agentic-workflow] retry ${attempt}/${attempts - 1}${label ? ` (${label})` : ""} ` +
+                    `in ${wait}ms after: ${message}`);
+                await sleep(wait);
+            }
+        }
+    }
+    /* istanbul ignore next -- 循环必然 return/throw，不可达 */
+    throw new WorkflowRetryError(attempts, lastError, label);
+}
+//# sourceMappingURL=retry.js.map

package/dist/workflow/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/workflow/retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAA;AAiBzD,SAAS,KAAK,CAAC,EAAU;IACvB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAA;AAC1D,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,KAAK,CACzB,IAAsB,EACtB,OAAsB;IAEtB,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,QAAQ,IAAI,CAAC,CAAC,CAAC,CAAA;IAChE,MAAM,OAAO,GAAG,OAAO,EAAE,OAAO,IAAI,IAAI,CAAA;IACxC,MAAM,OAAO,GAAG,OAAO,EAAE,OAAO,IAAI,aAAa,CAAA;IACjD,MAAM,UAAU,GAAG,OAAO,EAAE,UAAU,IAAI,MAAM,CAAA;IAChD,MAAM,OAAO,GAAG,OAAO,EAAE,OAAO,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAA;IAChD,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,IAAI,EAAE,CAAA;IAElC,IAAI,SAAkB,CAAA;IAEtB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,QAAQ,EAAE,OAAO,EAAE,EAAE,CAAC;QACrD,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,EAAE,CAAA;QACrB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,SAAS,GAAG,KAAK,CAAA;YAEjB,IAAI,OAAO,KAAK,QAAQ,EAAE,CAAC;gBACzB,MAAM,IAAI,kBAAkB,CAAC,QAAQ,EAAE,SAAS,EAAE,KAAK,CAAC,CAAA;YAC1D,CAAC;YACD,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;gBACpB,wBAAwB;gBACxB,MAAM,KAAK,CAAA;YACb,CAAC;YAED,MAAM,IAAI,GACR,OAAO,KAAK,aAAa;gBACvB,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,GAAG,CAAC,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC,EAAE,UAAU,CAAC;gBACpD,CAAC,CAAC,OAAO,CAAA;YACb,IAAI,IAAI,GAAG,CAAC,EAAE,CAAC;gBACb,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;gBACtE,OAAO,CAAC,GAAG,CACT,4BAA4B,OAAO,IAAI,QAAQ,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,KAAK,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG;oBACjF,MAAM,IAAI,aAAa,OAAO,EAAE,CACnC,CAAA;gBACD,MAAM,KAAK,CAAC,IAAI,CAAC,CAAA;YACnB,CAAC;QACH,CAAC;IACH,CAAC;IAED,mDAAmD;IACnD,MAAM,IAAI,kBAAkB,CAAC,QAAQ,EAAE,SAAS,EAAE,KAAK,CAAC,CAAA;AAC1D,CAAC"}