@zhushanwen/pi-subagent-workflow 8.6.0 → 8.7.0

package/src/orchestration/lifecycle.ts

@@ -1,399 +0,0 @@
-/**
- * Workflow Extension — lifecycle
- *
- * Workflow run 生命周期 free functions（D-12）。
- *
- * 5 个导出函数：
- * - runWorkflow(spec, deps, signal?) → Promise<runId>
- * - abortRun(runId, deps, reason?, doneReason?) → Promise<void>（done no-op）
- * - terminateRunningRuns(deps, reason) → Promise<void>（session 切换/关闭终止）
- * - evictDoneRunsBeyondCap(runs, keepDone) → number（done run 内存淘汰）
- * - scheduleTimeBudget(runId, deps, budgetTimeMs) → timer（C.7 时间预算）
- *
- * 私有 makeHandlers(run, deps) → WorkerHandlers：
- * - onMessage → handleWorkerMessage(run, raw, deps, handlers)
- * - onError → handleWorkerError(run, err, deps, handlers) + workerErrorCount++
- * - onExit(code, handle) → handleWorkerExit(run, code, handle, deps, handlers)
- * （G-025：handle.isCurrent 检查内化在 handleWorkerExit 内）
- *
- * **A4 原子性**：abort/terminate 内部 transition 先 releaseRuntime（cleanup before
- * mutate），失败时 status 不变。transition("done") 在 WorkflowRun.transition 内已实现
- * 「releaseRuntime → 改 status」原子顺序。
- *
- * **G3-001**（run 一次性生命周期）：AbortController 一次性无法复用，runtime 释放后
- * 只有两类重建——rebuildRuntime（error-recovery，崩溃重试路径，run 保持 running、
- * replaceRuntime 原子换新）与 abort/terminate 的终态释放（transition("done") 内
- * releaseRuntime，run 不再恢复）。
- * （旧并发门闩 gate 抽象已删——no-op 无生产语义，实际并发由 SubagentService
- * ConcurrencyPool 管理；原 D-13 maxConcurrency=4 无消费方。）
- *
- * 层归属：Engine。依赖 LifecycleDeps + WorkerHost via port +
- * WorkflowRun + handleWorker* 函数。
- *
- * 参考：domain-models.md §1（聚合根状态机）。
- */
-
-import { getLogger } from "@zhushanwen/pi-extension-logger";
-
-import { assertSafeTimerDelay } from "../shared/timer-delay.ts";
-import { validateRunArgs } from "./args-validator.ts";
-import {
-  handleWorkerError,
-  handleWorkerExit,
-  handleWorkerMessage,
-} from "./error-recovery.ts";
-import { Budget } from "./models/budget.ts";
-import type { LifecycleDeps, WorkerHandlers } from "./models/ports.ts";
-import { RunRuntime } from "./models/run-runtime.ts";
-import type { RunSpec } from "./models/run-spec.ts";
-import { Trace } from "./models/trace.ts";
-import type { DoneReason } from "./models/types.ts";
-import { WorkflowRun } from "./models/workflow-run.ts";
-import type { WorkerHandle } from "./worker-handle.ts";
-
-const logger = getLogger("subagents");
-
-// ── 常量 ─────────────────────────────────────────────────────
-
-/** runId 生成：wf-<timestamp>-<base36 random 6 chars>。 */
-const RUNID_RADIX = 36;
-const RUNID_SLICE_START = 2;
-const RUNID_SLICE_END = 8;
-
-/**
- * done run 内存保留窗口（K=20）。
- *
- * 本淘汰是 done run 内存有界性的唯一来源：calls.result 不裁、单聚合大小不随 wave1
- * 裁剪缩小，故内存上限 = K × 实际聚合大小。同时定义 actionStatus 可查刚完成 run
- * 的窗口（超出窗口的 done run 不再出现在列表中——已接受的用户可见变化）。
- */
-export const MAX_RETAINED_DONE_RUNS = 20;
-
-function generateRunId(): string {
-  return `wf-${Date.now()}-${Math.random().toString(RUNID_RADIX).slice(RUNID_SLICE_START, RUNID_SLICE_END)}`;
-}
-
-// ── makeHandlers（路由 worker 事件到 error-recovery handle* 函数） ──────
-
-/**
- * 构造 WorkerHandlers——将 worker 的 onMessage/onError/onExit 事件路由到
- * error-recovery 的 handleWorker* 函数。
- *
- * 闭包捕获 run + deps。runtime 重建（replaceRuntime）后 run 实例不变、deps 不变，
- * 故 handlers 对新 worker 仍有效（lifecycle 与 error-recovery 共用 handlers）。
- *
- * **onExit G-025**：handleWorkerExit 内部检查 handle.isCurrent（stale exit 丢弃）。
- * 本函数不在 onExit 里重复检查——error-recovery.handleWorkerExit 是单一守卫点。
- *
- * **workerErrorCount**：onError 触发时递增（C.5 跨 runtime 存活的重试计数载体）。
- * 注意 handleWorkerError 内部也会递增——这里 onError 递增是 worker 事件层面的
- * 「error 事件到达」计数，handleWorkerError 内的是「错误处理决策」计数。
- * 实际 handleWorkerError 会做最终计数（含重试上限判断），onError 不重复递增。
- */
-function makeHandlers(run: WorkflowRun, deps: LifecycleDeps): WorkerHandlers {
- // 自引用——error-recovery rebuildRuntime 需要 handlers 参数（handlers 引用自身）
-  const handlers: WorkerHandlers = {
-    async onMessage(raw: unknown): Promise<void> {
-      await handleWorkerMessage(run, raw, deps, handlers);
-    },
-    async onError(err: Error): Promise<void> {
-      await handleWorkerError(run, err, deps, handlers);
-    },
-    async onExit(code: number, handle: WorkerHandle): Promise<void> {
- // H-2：用 worker-host 传入的 handle（即真正触发 exit 的那个 handle），而非
- // run.runtime?.worker——重试竞态下 runtime.worker 可能已被 replaceRuntime 替换
- // 为新 handle，导致 handleWorkerExit 内的 isCurrent 检查误判（漏判 stale exit 或
- // 误杀新 worker）。G-025 检查仍在 handleWorkerExit 内（handle.isCurrent）。
-      await handleWorkerExit(run, code, handle, deps, handlers);
-    },
-  };
-  return handlers;
-}
-
-// ── scheduleTimeBudget（C.7 Run 级时间预算调度） ──────────
-
-/**
- * 启动 run 级墙钟时间预算计时器：到期后 abortRun(doneReason="time_limited")。
- *
- * 恢复旧 orchestrator-budget.ts 的 scheduleTimeBudgetCheck 语义——runWorkflow 启动
- * 一个 setTimeout(maxTimeMs)，到期若 run 仍未终态则转 done,time_limited。
- * 计时器存入 RunRuntime.timeBudgetTimer，release（abort/replaceRuntime）时
- * 自动清理，避免孤儿触发。worker/script 错误重试经 rebuildRuntime 重排新计时器。
- *
- * @returns 计时器句柄（未设预算时 undefined）
- * @throws budgetTimeMs 超出 Node setTimeout 上限（2^31-1）——溢出值会被 Node 置 1ms
- *   立即触发（「不限时预算」变「立即超时」），fail-fast 不静默 clamp（U1）。
- */
-export function scheduleTimeBudget(
-  runId: string,
-  deps: LifecycleDeps,
-  budgetTimeMs: number,
-): ReturnType<typeof setTimeout> {
-  // [U1] arm 入口：值流入 setTimeout 前校验安全域（>2^31-1 会变 1ms 立即触发）。
-  assertSafeTimerDelay(budgetTimeMs, "budgetTimeMs");
-  const timer = setTimeout(() => {
-    void abortRun(runId, deps, "Time budget exceeded", "time_limited").catch(
-      (err: unknown) => {
-        const msg = err instanceof Error ? err.message : String(err);
-        logger.error(`[workflow] time budget abort failed: ${msg}`);
-      },
-    );
-  }, budgetTimeMs);
- // unref：不阻止 Node 退出（workflow 是后台任务，不应因计时器持有事件循环）。
-  timer.unref();
-  return timer;
-}
-
-// ── runWorkflow ──────────────────────────────────────────────
-
-/**
- * 启动一个 workflow run。
- *
- * 流程：创建 WorkflowRun（running，I1 构造期跳过）+ makeHandlers + 构建 RunRuntime
- * （worker+gate+controller）+ assignRuntime（注入 runtime，恢复 I1）+ 注册到
- * deps.runs + store.save。
- *
- * @param spec RunSpec（scriptSource 只读；args 会被原地注入 _runId——rfl C2 契约，
- * worker 启动与崩溃重建共用同一 args 对象）
- * @param deps LifecycleDeps（store/workerHost/runner/runs）
- * @param signal 外部 abort signal（可选；abort 时调 abortRun）
- * @returns runId（wf-<timestamp>-<random>）
- * @throws signal 已 abort（pre-abort fail fast）
- */
-export async function runWorkflow(
-  spec: RunSpec,
-  deps: LifecycleDeps,
-  signal?: AbortSignal,
-): Promise<string> {
-  // m3 E9：参数校验单一 chokepoint，钉在所有副作用前（generateRunId/log/signal
-  // listener/runs.set/workerHost.start/store.save/pending:register）。校验失败时
-  // zero side effects。coerceTypes 原地规范化 spec.args——worker 启动与崩溃重建
-  // 共用同一对象（run.spec === spec），恢复路径参数一致。
-  validateRunArgs(spec);
-
-  const runId = generateRunId();
-  // rfl 仪表（tier-1 §7.1）：注入稳定 _runId。runAndWait 与 executeNestedWorkflow
-  // 两个 args 入口都经本 choke point；rebuildRuntime 复用 run.spec.args 同一对象
-  // （error-recovery.ts），worker rebuild 后脚本侧 $ARGS._runId 不漂移——修复
-  // 「rebuild 回退 run-<Date.now()> 导致同一逻辑 run 碎裂到多个 state 目录」。
-  // 注入在 validateRunArgs 之后，不参与脚本参数 schema 校验（引擎内部字段）。
-  if (spec.args && typeof spec.args === "object") {
-    spec.args._runId = runId;
-  }
-  deps.log?.("debug", "workflow:lifecycle", "runWorkflow start", { runId, scriptName: spec.scriptName });
-
- // P1-2: pre-aborted signal → fail fast
-  if (signal?.aborted) {
-    throw new Error("Workflow run aborted before start");
-  }
-
-  const run = new WorkflowRun(
-    runId,
-    spec,
-    {
-      status: "running",
-      budget: spec.budgetRef ?? new Budget({
-        maxTokens: spec.budgetTokens,
-        maxTimeMs: spec.budgetTimeMs,
-      }),
-      calls: new Map(),
-      trace: new Trace(),
-      errorLogs: [],
-    },
-    { startedAt: new Date().toISOString() },
-  );
-
- // signal abort → abortRun（一次性监听）
-  if (signal) {
-    signal.addEventListener(
-      "abort",
-      () => {
-        void abortRun(runId, deps, "External signal aborted").catch((err: unknown) => {
-          const msg = err instanceof Error ? err.message : String(err);
-          logger.error(`[workflow] abortRun on signal failed: ${msg}`);
-        });
-      },
-      { once: true },
-    );
-  }
-
- // 构造 handlers + runtime（worker + controller）
-  const handlers = makeHandlers(run, deps);
-  const controller = new AbortController();
-  const worker = deps.workerHost.start(spec, spec.args, handlers);
- // C.7：run 级时间预算计时器（spec.budgetTimeMs > 0 时启用，到期 abortRun time_limited）。
-  const timeBudgetTimer =
-    spec.budgetTimeMs && spec.budgetTimeMs > 0
-      ? scheduleTimeBudget(runId, deps, spec.budgetTimeMs)
-      : undefined;
-  const runtime = new RunRuntime(worker, controller, timeBudgetTimer);
-
- // assignRuntime（注入 runtime，恢复 I1：running ⟺ runtime!==undefined）
-  run.assignRuntime(runtime);
-
- // 注册到 deps.runs（assignRuntime 之后——构造到 assignRuntime 之间 run 处于
- // I1 跳过窗口（running 而 runtime undefined），后移保证窗口对外不可见；
- // worker.start 抛错时 run 未注册，无孤儿 run 残留）
-  deps.runs.set(runId, run);
-
-  await deps.store.save(run);
-  deps.log?.("debug", "workflow:lifecycle", "run saved", { runId, status: run.state.status });
-
- // pending-notifications: run 启动 → 注册（所有 workflow 启动路径的单一汇聚点：
- // runAndWait / actionRun / 未来入口全覆盖）
-  deps.log?.("debug", "workflow:lifecycle", "emit pending:register", { runId });
-  deps.eventBus?.emit("pending:register", {
-    id: runId,
-    type: "workflow",
-    name: spec.slug || spec.scriptName || runId,
-  });
-  deps.log?.("debug", "workflow:lifecycle", "emit pending:register done", { runId });
-
-  return runId;
-}
-
-// ── abortRun ─────────────────────────────────────────────────
-
-/**
- * 中止 workflow（running）。
- *
- * **done 状态 no-op**：已终态的 run 不重复 abort。
- * **A4 原子性**：transition("done", doneReason) 内部先 releaseRuntime。
- *
- * @param runId
- * @param deps
- * @param reason 可选中止原因（存 run.state.error）
- * @param doneReason 终态原因（默认 "aborted"；超时场景传 "time_limited"，C.7）
- * @throws runId 不存在
- */
-export async function abortRun(
-  runId: string,
-  deps: LifecycleDeps,
-  reason?: string,
-  doneReason: DoneReason = "aborted",
-): Promise<void> {
-  const run = deps.runs.get(runId);
-  if (!run) {
-    throw new Error(`Workflow '${runId}' not found`);
-  }
-
-  deps.log?.("debug", "workflow:lifecycle", "abortRun", { runId, status: run.state.status, reason, doneReason });
-
- // done 状态 no-op
-  if (run.state.status === "done") {
-    deps.log?.("debug", "workflow:lifecycle", "abortRun no-op: already done", { runId });
-    return;
-  }
-
- // 记录中止原因
-  if (reason) {
-    run.state.error = reason;
-  }
- // A4: transition 内部 releaseRuntime（cleanup before mutate）
-  run.transition("done", doneReason);
-  await deps.store.save(run);
-  deps.log?.("debug", "workflow:lifecycle", "abortRun transition done", { runId, reason: run.state.reason });
- // C-4: run 到达 done 终态 → 注销 pending-notification + 通知 Interface 层
-  deps.log?.("debug", "workflow:lifecycle", "emit pending:unregister", { runId, reason: run.state.reason });
-  deps.eventBus?.emit("pending:unregister", { id: run.runId, reason: run.state.reason ?? "completed" });
-  deps.log?.("debug", "workflow:lifecycle", "emit pending:unregister done", { runId });
-  deps.onRunDone?.(run);
-}
-
-// ── terminateRunningRuns（session 切换/关闭：终止全部 running run） ────────
-
-/**
- * 终止 deps.runs 中全部 running run（session 切换 / session 关闭时调用）。
- *
- * 一次性生命周期（D-2）：session 离开当刻，running run 的 token 投入作废，转
- * done,failed 持久化落盘——重启后 kill-9 恢复不误判，也不再存在「挂起待恢复」
- * 的中间态。
- *
- * per-run 行为：`state.error = reason` → `transition("done","failed")`（内部先
- * releaseRuntime，A4）→ `await store.save(run)` → `eventBus.emit("pending:unregister",
- * {reason:"failed"})`。
- *
- * **不调 deps.onRunDone**：对齐 session_start 恢复先例（index.ts kill-9 恢复只发
- * unregister、不发 onRunDone）——session 切换/关闭语境下主 agent 已离开本 session，
- * 注入完成通知只会把消息发给已离开的 session。
- *
- * **不调 discardInFlightCalls**：run 已转终态不再 replay（无恢复路径），在飞 call
- * 缓存清不清都不影响结果；该清理仅 rebuildRuntime 需要（崩溃重试会重放脚本，
- * 假失败结果会污染重跑输出）。
- *
- * 单 run 失败（try/catch + log 带 runId/reason）不中断其余 run——终止是批量收尾，
- * 一个 run 落盘失败不应放走其余 run 的 failed 状态。
- *
- * @param deps LifecycleDeps（runs/store/eventBus/log）
- * @param reason 终止原因（写入 run.state.error，如 "Session switched: run terminated"）
- */
-export async function terminateRunningRuns(
-  deps: LifecycleDeps,
-  reason: string,
-): Promise<void> {
-  for (const run of deps.runs.values()) {
-    if (run.state.status !== "running") continue;
-    try {
-      deps.log?.("debug", "workflow:lifecycle", "terminateRunningRuns", { runId: run.runId, reason });
-      run.state.error = reason;
-      // A4: transition 内部先 releaseRuntime（cleanup before mutate）
-      run.transition("done", "failed");
-      await deps.store.save(run);
-      // C-4: run 到达 done 终态 → 注销 pending-notification（reason 固定 "failed"）
-      deps.eventBus?.emit("pending:unregister", { id: run.runId, reason: "failed" });
-      deps.log?.("debug", "workflow:lifecycle", "run terminated", { runId: run.runId, reason: run.state.reason });
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      logger.error(
-        `[workflow] terminateRunningRuns failed for run ${run.runId}: ${msg} (reason: ${reason})`,
-      );
-    }
-  }
-}
-
-// ── evictDoneRunsBeyondCap（done run 内存淘汰，原地裁剪函数） ────────
-
-/**
- * 淘汰 runs Map 中超出保留窗口的 done run，返回本次淘汰数量。
- *
- * 规则（契约 W3C1）：
- * 1. **状态白名单**：仅 `state.status === "done"` 可淘汰（RunStatus 封闭两态，
- *    显式白名单而非「非 running」——未来新增状态不落淘汰端）。running
- *    （活跃执行，isScriptRunning 遍历依赖）永不淘汰，即使 completedAt 缺失也
- *    绝不参与排序淘汰。
- * 2. **排序**：done 项按 `meta.completedAt` ISO 字符串字典序升序（toISOString 恒
- *    UTC 毫秒格式，字典序=时间序）。completedAt 缺失（防御旧格式/异常快照）fallback
- *    排序键为空串——字典序最小=最旧，先被淘汰。
- * 3. **tie 稳定排序**：比较器三态返回（相等返回 0），Array#sort 稳定性（Node≥12）
- *    保持元素原序——原序 = Map 插入序 = 创建序，tie 组内先创建者视为更旧先被淘汰
- *    （kill-9 批量恢复同 ms completedAt 场景的确定性保证）。
- * 4. **淘汰执行**：超限数 excess = doneCount - keepDone（<=0 时 no-op 返回 0），
- *    对升序前 excess 项逐个 `runs.delete(runId)`。
- * 5. **边界不变式**：禁止按 Map 插入序直接淘汰——嵌套 workflow 父 run 创建最早、
- *    完成最晚，插入序淘汰会在其自身 onRunDone 同步裁剪中淘汰它，runAndWait 轮询
- *    窗口内 get 不到 → 误返 "Run not found"。
- * 6. **副作用边界**：只清内存 runs Map，不动磁盘 state 文件、不删
- *    workflow-state-link 指针条目、不发任何事件。
- *
- * @param runs per-session 的 run 注册表（原地裁剪）
- * @param keepDone done run 保留数（生产传 MAX_RETAINED_DONE_RUNS）
- * @returns 本次淘汰的 run 数量
- */
-export function evictDoneRunsBeyondCap(
-  runs: Map<string, WorkflowRun>,
-  keepDone: number,
-): number {
-  // 显式白名单：仅 done 参与淘汰（running 误删即功能破坏）
-  const done = Array.from(runs.values()).filter((r) => r.state.status === "done");
-  const excess = done.length - keepDone;
-  if (excess <= 0) return 0;
-  // ISO 字典序=时间序；缺失 fallback 空串（ISO 串恒以 '2' 开头非空，空串严格最小=最旧）
-  const keyOf = (r: WorkflowRun): string => r.meta.completedAt ?? "";
-  // 三态比较器 + sort 稳定性：tie 保持 Array.from 的 Map 插入序（=创建序）——
-  // 先插入者更旧先淘汰，禁止按插入序直接 slice 淘汰（边界不变式 5）
-  done.sort((a, b) => (keyOf(a) < keyOf(b) ? -1 : keyOf(a) > keyOf(b) ? 1 : 0));
-  for (const r of done.slice(0, excess)) {
-    runs.delete(r.runId);
-  }
-  return excess;
-}