@zhushanwen/subagent-core 0.2.0

package/src/orchestration/lifecycle.ts

@@ -0,0 +1,399 @@
+/**
+ * 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 "../core/logger.ts";
+
+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;
+}