@mickorz/opencode-agentic-workflow 0.3.0

package/dist/registry/runner.js

@@ -0,0 +1,199 @@
+/**
+ * Registry Runner（P2.5 journal 集成）
+ *
+ * 把 Definition / Registry / Journal / Resume 正式串起来：
+ *
+ *   startWorkflow:  registry.resolve(id)[@version] -> args 校验 -> journal 落盘
+ *                   -> definition.run(args, ctx{mode:"start"})
+ *                   -> ctx.runSteps = sequence + journal 记录
+ *
+ *   resumeWorkflow: store.getRun(runId) -> workflow {id, version}
+ *                   -> registry.resolve(id, version)  ← 精确版本，绝不取最新
+ *                   -> definition.run(journal.args, ctx{mode:"resume"})
+ *                   -> ctx.runSteps = resumeSequence（跳过 completed 前缀）
+ *
+ * definition 只感知 ctx.runSteps——start/resume 差异被完全封装；
+ * 失败统一抛 WorkflowExecutionError（携带 runId，供工具层提示恢复入口）。
+ */
+import { RunJournal } from "../state/recorder.js";
+import { setCurrentWorkspace, } from "../workspace/index.js";
+import { resumeSequence, sequence, } from "../workflow/sequence.js";
+import { WorkflowArgsError, WorkflowExecutionError } from "./errors.js";
+import { validateArgs } from "./schema.js";
+function toOutput(result) {
+    if (typeof result === "string")
+        return result;
+    if (result &&
+        typeof result === "object" &&
+        typeof result.output === "string") {
+        return result.output;
+    }
+    return JSON.stringify(result) ?? "";
+}
+function createContext(input) {
+    return {
+        runId: input.runId,
+        mode: input.mode,
+        // resume 模式的 journal 由 resumeSequence 内部管理（attach/reopen/收口），
+        // ctx 不直接暴露，避免双写
+        journal: input.mode === "start" ? input.journal : undefined,
+        // P2.7：隔离工作区根目录（未启用隔离时为 undefined）
+        workspaceRoot: input.workspaceRoot,
+        runSteps(steps, options) {
+            if (input.mode === "resume" && input.store) {
+                return resumeSequence(input.store, input.runId, steps, options);
+            }
+            return sequence(steps, {
+                ...options,
+                journal: input.journal,
+            });
+        },
+    };
+}
+/**
+ * 无持久化直跑（插件未配置 journalDir 时的兼容路径）：
+ * 经注册表解析 + args 校验，但不落 journal、不可恢复。
+ */
+export async function runWorkflowInline(registry, id, args) {
+    const definition = registry.resolve(id);
+    const problems = validateArgs(definition.argsSchema, args);
+    if (problems.length > 0) {
+        throw new WorkflowArgsError(definition.id, problems);
+    }
+    const result = await definition.run(args, {
+        runId: `inline_${Date.now()}`,
+        mode: "start",
+        runSteps: (steps, options) => sequence(steps, options),
+    });
+    return { output: toOutput(result) };
+}
+/** 收口辅助：成功路径把仍为 running 的 journal 置 completed（step-less 工作流兜底） */
+async function settleAfterSuccess(store, runId) {
+    const journal = await RunJournal.attach(store, runId);
+    if (!journal)
+        return;
+    if (journal.run.status === "running") {
+        await journal.complete();
+    }
+    else if (journal.run.status === "failed") {
+        // resume 成功但 definition 未走 runSteps（step-less）：failed -> completed
+        await journal.reopen();
+        await journal.complete();
+    }
+}
+async function settleAfterFailure(store, runId, error) {
+    const journal = await RunJournal.attach(store, runId);
+    if (journal && journal.run.status === "running") {
+        await journal.fail(error);
+    }
+}
+/**
+ * 按策略清理 workspace；清理后清除 journal 中的 workspace 身份
+ * （否则已清理的 run 在幂等 resume 时会 attach 一个已删除的目录）。
+ * 清理失败只记录——观测/基础设施不能成为主链路故障源。
+ */
+async function cleanupWorkspace(store, runId, handle, policy, success) {
+    if (!handle)
+        return;
+    if (policy === "never")
+        return;
+    if (policy === "on-success" && !success)
+        return;
+    try {
+        await handle.dispose({ force: true });
+        const journal = await RunJournal.attach(store, runId);
+        await journal?.clearWorkspace();
+    }
+    catch (error) {
+        console.log(`[agentic-workflow] workspace cleanup failed for ${runId}: ` +
+            `${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/** 启动新 run（默认最新版本；可用 options.version 精确指定） */
+export async function startWorkflow(registry, store, id, args, options) {
+    const definition = registry.resolve(id, options?.version);
+    const problems = validateArgs(definition.argsSchema, args);
+    if (problems.length > 0) {
+        throw new WorkflowArgsError(definition.id, problems);
+    }
+    const identity = { id: definition.id, version: definition.version };
+    const journal = await RunJournal.start(store, {
+        workflow: identity,
+        args,
+        stepNames: definition.stepNames,
+        stepCount: definition.stepNames?.length ?? 0,
+    });
+    const runId = journal.run.runId;
+    const cleanupPolicy = options?.workspace?.cleanup ?? "on-success";
+    let workspace;
+    try {
+        // P2.7：创建隔离工作区并把身份落 journal（resume attach 依据）
+        if (options?.workspace) {
+            workspace = await options.workspace.provider.create(runId, options.workspace.options);
+            await journal.setWorkspace(workspace.identity);
+        }
+        setCurrentWorkspace(workspace);
+        try {
+            const result = await definition.run(args, createContext({ runId, mode: "start", journal, workspaceRoot: workspace?.root }));
+            // 顺序纪律：先收口 journal 再清理 workspace——cleanupWorkspace 会经
+            // attach 重读持久化状态并清除 workspace 字段，若 complete() 在其后，
+            // 内存 journal 会把已删除的 worktree 身份复活写回（幂等 resume 即坏）
+            if (journal.run.status === "running") {
+                await journal.complete();
+            }
+            await cleanupWorkspace(store, runId, workspace, cleanupPolicy, true);
+            return { runId, workflow: identity, output: toOutput(result) };
+        }
+        finally {
+            setCurrentWorkspace(undefined);
+        }
+    }
+    catch (error) {
+        if (journal.run.status === "running") {
+            await journal.fail(error);
+        }
+        await cleanupWorkspace(store, runId, workspace, cleanupPolicy, false);
+        throw new WorkflowExecutionError({ runId, ...identity }, error);
+    }
+}
+/**
+ * 从 journal 恢复 run：
+ *   - workflow {id, version} 来自 journal，registry 精确版本解析（找不到即报错并列版本）
+ *   - args 取 journal 记录（无需调用方重新提供）
+ *   - journal 记录了 workspace 身份时，**重新附着原工作区**（绝不重建——
+ *     durable resume = journal 状态 + 文件系统状态同时恢复；缺失即报错）
+ *   - 已完成的 run 幂等重放（不执行任何步骤，仅重建最终报告）
+ */
+export async function resumeWorkflow(registry, store, runId, options) {
+    const run = await store.getRun(runId);
+    if (!run) {
+        throw new Error(`[agentic-workflow] cannot resume: run not found: ${runId}`);
+    }
+    const identity = run.workflow;
+    const definition = registry.resolve(identity.id, identity.version);
+    const cleanupPolicy = options?.workspace?.cleanup ?? "on-success";
+    let workspace;
+    try {
+        if (options?.workspace && run.workspace) {
+            workspace = await options.workspace.provider.attach(run.workspace);
+        }
+        setCurrentWorkspace(workspace);
+        try {
+            const result = await definition.run(run.args, createContext({ runId, mode: "resume", store, workspaceRoot: workspace?.root }));
+            // 同 start：先收口 journal（settle），再清理 workspace（clearWorkspace
+            // 允许在收口后执行——幂等 resume 依赖清理后字段被清掉）
+            await settleAfterSuccess(store, runId);
+            await cleanupWorkspace(store, runId, workspace, cleanupPolicy, true);
+            return { runId, workflow: identity, output: toOutput(result) };
+        }
+        finally {
+            setCurrentWorkspace(undefined);
+        }
+    }
+    catch (error) {
+        await settleAfterFailure(store, runId, error);
+        await cleanupWorkspace(store, runId, workspace, cleanupPolicy, false);
+        throw new WorkflowExecutionError({ runId, ...identity }, error);
+    }
+}
+//# sourceMappingURL=runner.js.map

package/dist/registry/runner.js.map

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

package/dist/registry/schema.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Args JSON Schema 子集（P2.5）
+ *
+ * 项目保持零依赖：不引入 Zod，实现最小 JSON Schema 校验
+ * （type/properties/required/enum/items/description，支持嵌套与联合类型）。
+ * 该契约同时用于：tool schema 生成、args 校验、未来 TUI 表单 / Hub 展示。
+ */
+/** 最小 JSON Schema 子集（声明 args 契约用） */
+export interface ArgsSchema {
+    type?: string | string[];
+    properties?: Record<string, ArgsSchema>;
+    required?: string[];
+    enum?: unknown[];
+    items?: ArgsSchema;
+    description?: string;
+}
+/** args 校验：返回问题列表（空数组 = 合法） */
+export declare function validateArgs(schema: ArgsSchema | undefined, args: unknown): string[];

package/dist/registry/schema.js

@@ -0,0 +1,73 @@
+/**
+ * Args JSON Schema 子集（P2.5）
+ *
+ * 项目保持零依赖：不引入 Zod，实现最小 JSON Schema 校验
+ * （type/properties/required/enum/items/description，支持嵌套与联合类型）。
+ * 该契约同时用于：tool schema 生成、args 校验、未来 TUI 表单 / Hub 展示。
+ */
+/** args 校验：返回问题列表（空数组 = 合法） */
+export function validateArgs(schema, args) {
+    if (!schema)
+        return [];
+    return validateValue(schema, args, "args");
+}
+function validateValue(schema, value, path) {
+    const problems = [];
+    if (schema.type) {
+        const expected = Array.isArray(schema.type) ? schema.type : [schema.type];
+        if (!expected.some((t) => matchesType(t, value))) {
+            problems.push(`${path}: expected type ${expected.join("|")}, got ${typeName(value)}`);
+            return problems; // 类型不对，后续检查无意义
+        }
+    }
+    if (schema.enum && !schema.enum.some((candidate) => candidate === value)) {
+        problems.push(`${path}: expected one of ${JSON.stringify(schema.enum)}`);
+    }
+    if (typeof value === "object" && value !== null && schema.properties) {
+        const record = value;
+        for (const key of schema.required ?? []) {
+            if (!(key in record) || record[key] === undefined) {
+                problems.push(`${path}: missing required property "${key}"`);
+            }
+        }
+        for (const [key, childSchema] of Object.entries(schema.properties)) {
+            if (key in record && record[key] !== undefined) {
+                problems.push(...validateValue(childSchema, record[key], `${path}.${key}`));
+            }
+        }
+    }
+    if (Array.isArray(value) && schema.items) {
+        value.forEach((item, index) => {
+            problems.push(...validateValue(schema.items, item, `${path}[${index}]`));
+        });
+    }
+    return problems;
+}
+function matchesType(expected, value) {
+    switch (expected) {
+        case "string":
+            return typeof value === "string";
+        case "number":
+            return typeof value === "number" && !Number.isNaN(value);
+        case "integer":
+            return typeof value === "number" && Number.isInteger(value);
+        case "boolean":
+            return typeof value === "boolean";
+        case "array":
+            return Array.isArray(value);
+        case "object":
+            return typeof value === "object" && value !== null && !Array.isArray(value);
+        case "null":
+            return value === null;
+        default:
+            return true; // 未知类型名不设限（前向兼容）
+    }
+}
+function typeName(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    return typeof value;
+}
+//# sourceMappingURL=schema.js.map

package/dist/registry/schema.js.map

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

package/dist/runtime/command.d.ts

@@ -0,0 +1,38 @@
+/**
+ * CommandRunner —— 命令执行抽象（Workflow Core 内的宿主无关原语）
+ *
+ * 注意：这不是 OpenCode 依赖。Core 只依赖 Node 内建能力（child_process），
+ * 默认实现 NodeCommandRunner 可直接在单测/本地使用；plugin 层如需
+ * 经由 OpenCode shell 域执行，可用 setCommandRunner() 注入替代实现。
+ *
+ * 纪律（来自经验沉淀 opencode-run-hang-watchdog.md）：
+ *   命令一律带超时，禁止无限等待。默认 120s。
+ */
+export interface CommandOptions {
+    /** 工作目录 */
+    cwd?: string;
+    /** 超时毫秒数，默认 120000；超时后进程被终止并返回 timedOut: true */
+    timeoutMs?: number;
+    /** 附加环境变量（在 process.env 之上合并） */
+    env?: Record<string, string>;
+}
+export interface CommandResult {
+    command: string;
+    /** 退出码；进程被信号杀死或启动失败时为 null */
+    code: number | null;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+}
+export interface CommandRunner {
+    run(command: string, options?: CommandOptions): Promise<CommandResult>;
+}
+export declare const DEFAULT_COMMAND_TIMEOUT_MS = 120000;
+/** 基于 node:child_process 的默认实现 */
+export declare class NodeCommandRunner implements CommandRunner {
+    run(command: string, options?: CommandOptions): Promise<CommandResult>;
+}
+/** 注入自定义 CommandRunner（测试替身 / plugin 层替代实现） */
+export declare function setCommandRunner(value: CommandRunner): void;
+/** 获取当前 CommandRunner */
+export declare function getCommandRunner(): CommandRunner;

package/dist/runtime/command.js

@@ -0,0 +1,61 @@
+/**
+ * CommandRunner —— 命令执行抽象（Workflow Core 内的宿主无关原语）
+ *
+ * 注意：这不是 OpenCode 依赖。Core 只依赖 Node 内建能力（child_process），
+ * 默认实现 NodeCommandRunner 可直接在单测/本地使用；plugin 层如需
+ * 经由 OpenCode shell 域执行，可用 setCommandRunner() 注入替代实现。
+ *
+ * 纪律（来自经验沉淀 opencode-run-hang-watchdog.md）：
+ *   命令一律带超时，禁止无限等待。默认 120s。
+ */
+import { spawn } from "node:child_process";
+export const DEFAULT_COMMAND_TIMEOUT_MS = 120_000;
+/** 基于 node:child_process 的默认实现 */
+export class NodeCommandRunner {
+    async run(command, options) {
+        const timeoutMs = options?.timeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS;
+        return new Promise((resolve) => {
+            const child = spawn(command, {
+                shell: true,
+                cwd: options?.cwd,
+                env: options?.env ? { ...process.env, ...options.env } : process.env,
+            });
+            let stdout = "";
+            let stderr = "";
+            let timedOut = false;
+            let settled = false;
+            const timer = setTimeout(() => {
+                timedOut = true;
+                child.kill("SIGKILL");
+            }, timeoutMs);
+            child.stdout?.on("data", (chunk) => {
+                stdout += chunk.toString();
+            });
+            child.stderr?.on("data", (chunk) => {
+                stderr += chunk.toString();
+            });
+            const finish = (code) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                resolve({ command, code, stdout, stderr, timedOut });
+            };
+            child.on("error", (error) => {
+                stderr += String(error.message);
+                finish(null);
+            });
+            child.on("close", (code) => finish(code));
+        });
+    }
+}
+let runner = new NodeCommandRunner();
+/** 注入自定义 CommandRunner（测试替身 / plugin 层替代实现） */
+export function setCommandRunner(value) {
+    runner = value;
+}
+/** 获取当前 CommandRunner */
+export function getCommandRunner() {
+    return runner;
+}
+//# sourceMappingURL=command.js.map

package/dist/runtime/command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.js","sourceRoot":"","sources":["../../src/runtime/command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAA;AAwB1C,MAAM,CAAC,MAAM,0BAA0B,GAAG,OAAO,CAAA;AAEjD,kCAAkC;AAClC,MAAM,OAAO,iBAAiB;IAC5B,KAAK,CAAC,GAAG,CAAC,OAAe,EAAE,OAAwB;QACjD,MAAM,SAAS,GAAG,OAAO,EAAE,SAAS,IAAI,0BAA0B,CAAA;QAElE,OAAO,IAAI,OAAO,CAAgB,CAAC,OAAO,EAAE,EAAE;YAC5C,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,EAAE;gBAC3B,KAAK,EAAE,IAAI;gBACX,GAAG,EAAE,OAAO,EAAE,GAAG;gBACjB,GAAG,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG;aACrE,CAAC,CAAA;YAEF,IAAI,MAAM,GAAG,EAAE,CAAA;YACf,IAAI,MAAM,GAAG,EAAE,CAAA;YACf,IAAI,QAAQ,GAAG,KAAK,CAAA;YACpB,IAAI,OAAO,GAAG,KAAK,CAAA;YAEnB,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;gBAC5B,QAAQ,GAAG,IAAI,CAAA;gBACf,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;YACvB,CAAC,EAAE,SAAS,CAAC,CAAA;YAEb,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE;gBACzC,MAAM,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAA;YAC5B,CAAC,CAAC,CAAA;YACF,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE;gBACzC,MAAM,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAA;YAC5B,CAAC,CAAC,CAAA;YAEF,MAAM,MAAM,GAAG,CAAC,IAAmB,EAAE,EAAE;gBACrC,IAAI,OAAO;oBAAE,OAAM;gBACnB,OAAO,GAAG,IAAI,CAAA;gBACd,YAAY,CAAC,KAAK,CAAC,CAAA;gBACnB,OAAO,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAA;YACtD,CAAC,CAAA;YAED,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAY,EAAE,EAAE;gBACjC,MAAM,IAAI,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;gBAC/B,MAAM,CAAC,IAAI,CAAC,CAAA;YACd,CAAC,CAAC,CAAA;YACF,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAA;QAC3C,CAAC,CAAC,CAAA;IACJ,CAAC;CACF;AAED,IAAI,MAAM,GAAkB,IAAI,iBAAiB,EAAE,CAAA;AAEnD,+CAA+C;AAC/C,MAAM,UAAU,gBAAgB,CAAC,KAAoB;IACnD,MAAM,GAAG,KAAK,CAAA;AAChB,CAAC;AAED,yBAAyB;AACzB,MAAM,UAAU,gBAAgB;IAC9B,OAAO,MAAM,CAAA;AACf,CAAC"}

package/dist/runtime/engine.d.ts

@@ -0,0 +1,17 @@
+/**
+ * WorkflowEngine —— 绑定 executor 并执行 workflow 函数
+ *
+ * P0 语义：
+ *   engine.run(workflowFn)
+ *     -> 绑定当前 executor（模块级）
+ *     -> 执行 workflowFn（内部调用 agent()/parallel()/sequence()/phase()）
+ *     -> 恢复原 executor，返回 workflowFn 的返回值
+ *
+ * P0 不做：retry / timeout / verify / checkpoint / journal。
+ */
+import type { AgentExecutor } from "./executor.js";
+/** 显式设置全局 executor（供 plugin 初始化时注入 OpenCodeV2Executor） */
+export declare function setExecutor(executor: AgentExecutor): void;
+/** 获取当前 executor；未绑定时抛错（workflow 必须在 engine.run 内执行） */
+export declare function requireExecutor(): AgentExecutor;
+export declare function runWorkflow<T>(workflow: () => Promise<T>): Promise<T>;

package/dist/runtime/engine.js

@@ -0,0 +1,31 @@
+/**
+ * WorkflowEngine —— 绑定 executor 并执行 workflow 函数
+ *
+ * P0 语义：
+ *   engine.run(workflowFn)
+ *     -> 绑定当前 executor（模块级）
+ *     -> 执行 workflowFn（内部调用 agent()/parallel()/sequence()/phase()）
+ *     -> 恢复原 executor，返回 workflowFn 的返回值
+ *
+ * P0 不做：retry / timeout / verify / checkpoint / journal。
+ */
+/** 当前绑定的 executor（模块级；P0 不处理并发嵌套引擎） */
+let currentExecutor;
+/** 显式设置全局 executor（供 plugin 初始化时注入 OpenCodeV2Executor） */
+export function setExecutor(executor) {
+    currentExecutor = executor;
+}
+/** 获取当前 executor；未绑定时抛错（workflow 必须在 engine.run 内执行） */
+export function requireExecutor() {
+    if (!currentExecutor) {
+        throw new Error("[agentic-workflow] no executor bound: run workflows inside engine.run() or call setExecutor() first");
+    }
+    return currentExecutor;
+}
+export async function runWorkflow(workflow) {
+    if (!currentExecutor) {
+        throw new Error("[agentic-workflow] engine has no executor: call setExecutor() before runWorkflow()");
+    }
+    return workflow();
+}
+//# sourceMappingURL=engine.js.map

package/dist/runtime/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../../src/runtime/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,uCAAuC;AACvC,IAAI,eAA0C,CAAA;AAE9C,0DAA0D;AAC1D,MAAM,UAAU,WAAW,CAAC,QAAuB;IACjD,eAAe,GAAG,QAAQ,CAAA;AAC5B,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,eAAe;IAC7B,IAAI,CAAC,eAAe,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CACb,qGAAqG,CACtG,CAAA;IACH,CAAC;IACD,OAAO,eAAe,CAAA;AACxB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,WAAW,CAAI,QAA0B;IAC7D,IAAI,CAAC,eAAe,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CAAC,oFAAoF,CAAC,CAAA;IACvG,CAAC;IACD,OAAO,QAAQ,EAAE,CAAA;AACnB,CAAC"}

package/dist/runtime/errors.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Workflow 错误分类法（P1.3 失败语义的基础）
+ *
+ * 统一家族：所有「workflow 层」的失败都继承 WorkflowError，
+ * 后续 retry / fallback（P1.4）只捕获该家族，业务异常经 cause 链保留。
+ */
+/** workflow 层失败信号的基类 */
+export declare class WorkflowError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** 单个步骤失败：携带步骤位置与原始异常 */
+export declare class WorkflowStepError extends WorkflowError {
+    readonly stepIndex: number;
+    readonly stepName?: string;
+    constructor(stepIndex: number, cause: unknown, stepName?: string);
+}
+/** sequence 整体失败：fail-fast（1 条）或 continue（累积多条） */
+export declare class WorkflowSequenceError extends WorkflowError {
+    /** 按发生顺序排列的步骤失败 */
+    readonly errors: WorkflowStepError[];
+    /** 最后一次成功步骤的返回值（失败后仍可取已产出结果） */
+    readonly lastValue: unknown;
+    constructor(errors: WorkflowStepError[], lastValue: unknown);
+}
+/** parallel 任务失败：fail-fast（首个）或 collect（全部） */
+export interface ParallelFailure {
+    /** 失败任务的序号（0 起） */
+    index: number;
+    error: unknown;
+}
+/** parallel 整体失败 */
+export declare class WorkflowParallelError extends WorkflowError {
+    readonly failures: ParallelFailure[];
+    /** 成功任务的结果（失败槽位为 undefined）；fail-fast 下可能不完整 */
+    readonly results: ReadonlyArray<unknown>;
+    readonly mode: string;
+    constructor(failures: ParallelFailure[], results: ReadonlyArray<unknown>, mode: string);
+}
+/** retry 重试耗尽 */
+export declare class WorkflowRetryError extends WorkflowError {
+    /** 已尝试次数（含首次） */
+    readonly attempts: number;
+    /** 最后一次失败的原始异常（通常为 WorkflowError 家族成员） */
+    readonly lastError: unknown;
+    readonly label: string;
+    constructor(attempts: number, lastError: unknown, label: string);
+}
+/** fallback 全部候选失败 */
+export declare class WorkflowFallbackError extends WorkflowError {
+    /** 按尝试顺序排列的各候选失败 */
+    readonly errors: unknown[];
+    readonly label: string;
+    constructor(errors: unknown[], label: string);
+}

package/dist/runtime/errors.js

@@ -0,0 +1,88 @@
+/**
+ * Workflow 错误分类法（P1.3 失败语义的基础）
+ *
+ * 统一家族：所有「workflow 层」的失败都继承 WorkflowError，
+ * 后续 retry / fallback（P1.4）只捕获该家族，业务异常经 cause 链保留。
+ */
+/** workflow 层失败信号的基类 */
+export class WorkflowError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "WorkflowError";
+    }
+}
+/** 单个步骤失败：携带步骤位置与原始异常 */
+export class WorkflowStepError extends WorkflowError {
+    stepIndex;
+    stepName;
+    constructor(stepIndex, cause, stepName) {
+        const message = cause instanceof Error ? cause.message : String(cause);
+        super(`step #${stepIndex}${stepName ? ` (${stepName})` : ""} failed: ${message}`, { cause });
+        this.name = "WorkflowStepError";
+        this.stepIndex = stepIndex;
+        this.stepName = stepName;
+    }
+}
+/** sequence 整体失败：fail-fast（1 条）或 continue（累积多条） */
+export class WorkflowSequenceError extends WorkflowError {
+    /** 按发生顺序排列的步骤失败 */
+    errors;
+    /** 最后一次成功步骤的返回值（失败后仍可取已产出结果） */
+    lastValue;
+    constructor(errors, lastValue) {
+        super(`sequence failed (${errors.length} step${errors.length > 1 ? "s" : ""}): ` +
+            errors.map((e) => e.message).join("; "));
+        this.name = "WorkflowSequenceError";
+        this.errors = errors;
+        this.lastValue = lastValue;
+    }
+}
+/** parallel 整体失败 */
+export class WorkflowParallelError extends WorkflowError {
+    failures;
+    /** 成功任务的结果（失败槽位为 undefined）；fail-fast 下可能不完整 */
+    results;
+    mode;
+    constructor(failures, results, mode) {
+        super(`parallel failed (${failures.length} task${failures.length > 1 ? "s" : ""}, mode=${mode}): ` +
+            failures
+                .map((f) => `#${f.index}: ${f.error instanceof Error ? f.error.message : String(f.error)}`)
+                .join("; "));
+        this.name = "WorkflowParallelError";
+        this.failures = failures;
+        this.results = results;
+        this.mode = mode;
+    }
+}
+/** retry 重试耗尽 */
+export class WorkflowRetryError extends WorkflowError {
+    /** 已尝试次数（含首次） */
+    attempts;
+    /** 最后一次失败的原始异常（通常为 WorkflowError 家族成员） */
+    lastError;
+    label;
+    constructor(attempts, lastError, label) {
+        const message = lastError instanceof Error ? lastError.message : String(lastError);
+        super(`retry exhausted (${attempts} attempts${label ? `, ${label}` : ""}): ${message}`, {
+            cause: lastError,
+        });
+        this.name = "WorkflowRetryError";
+        this.attempts = attempts;
+        this.lastError = lastError;
+        this.label = label;
+    }
+}
+/** fallback 全部候选失败 */
+export class WorkflowFallbackError extends WorkflowError {
+    /** 按尝试顺序排列的各候选失败 */
+    errors;
+    label;
+    constructor(errors, label) {
+        super(`fallback exhausted (${errors.length} candidate${errors.length > 1 ? "s" : ""}${label ? `, ${label}` : ""}): ` +
+            errors.map((e) => (e instanceof Error ? e.message : String(e))).join("; "));
+        this.name = "WorkflowFallbackError";
+        this.errors = errors;
+        this.label = label;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/runtime/errors.js.map

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