@zhushanwen/subagent-core 0.2.0

package/src/orchestration/models/__tests__/budget.test.ts

@@ -0,0 +1,307 @@
+// 测试框架：vitest
+// 运行命令：npx vitest run src/orchestration/models/__tests__/budget.test.ts
+
+import { describe, expect, it } from "vitest";
+
+import {
+  Budget,
+  CACHE_READ_WEIGHT,
+  CACHE_WRITE_WEIGHT,
+  INPUT_WEIGHT,
+  OUTPUT_WEIGHT,
+} from "../budget.js";
+import type { AgentUsage } from "../types.js";
+
+/** 构造合法 AgentUsage，未指定字段补 0。 */
+function usage(partial: Partial<AgentUsage>): AgentUsage {
+  return {
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    cost: 0,
+    contextTokens: 0,
+    turns: 0,
+    ...partial,
+  };
+}
+
+/**
+ * 构造"有毒" usage：刻意注入 undefined / NaN / Infinity，
+ * 模拟 provider 返回脏数据或 JSON 反序列化缺字段时的运行时场景。
+ *
+ * 单层 `as AgentUsage`：AgentUsage 全部必填字段（非全可选结构），
+ * 不触发 taste/no-unsafe-cast 的 structuralCast；此处刻意绕过类型系统
+ * 以验证 consume() 的运行时 NaN 守卫。
+ */
+function poisonedUsage(
+  overrides: Partial<Record<keyof AgentUsage, number | undefined>>,
+): AgentUsage {
+  return {
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    cost: 0,
+    contextTokens: 0,
+    turns: 0,
+    ...overrides,
+  } as AgentUsage;
+}
+
+// ── consume：加权公式 ────────────────────────────────────────
+
+describe("Budget.consume 加权公式", () => {
+  it(`纯 input → usedTokens = input × ${INPUT_WEIGHT}`, () => {
+    const b = new Budget({ maxTokens: 1000 });
+    b.consume(usage({ input: 100 }));
+    expect(b.usedTokens).toBe(100);
+  });
+
+  it(`纯 output → usedTokens = output × ${OUTPUT_WEIGHT}（自回归开销最高）`, () => {
+    const b = new Budget({ maxTokens: 1000 });
+    b.consume(usage({ output: 100 }));
+    expect(b.usedTokens).toBe(200);
+  });
+
+  it(`纯 cacheRead → usedTokens = cacheRead × ${CACHE_READ_WEIGHT}（命中缓存，开销极低）`, () => {
+    const b = new Budget({ maxTokens: 1000 });
+    b.consume(usage({ cacheRead: 100 }));
+    expect(b.usedTokens).toBe(2);
+  });
+
+  it(`纯 cacheWrite → usedTokens = cacheWrite × ${CACHE_WRITE_WEIGHT}（首次写缓存不计 budget）`, () => {
+    const b = new Budget({ maxTokens: 1000 });
+    b.consume(usage({ cacheWrite: 100 }));
+    expect(b.usedTokens).toBe(0);
+  });
+
+  it("混合四项加权累加（input×1 + output×2 + cacheRead×0.02 + cacheWrite×0）", () => {
+    const b = new Budget({ maxTokens: 10000 });
+    b.consume(
+      usage({ input: 100, output: 50, cacheRead: 1000, cacheWrite: 500 }),
+    );
+    // 100×1 + 50×2 + 1000×0.02 + 500×0 = 100 + 100 + 20 + 0 = 220
+    expect(b.usedTokens).toBe(220);
+  });
+
+  it("cost 随 consume 累加", () => {
+    const b = new Budget();
+    b.consume(usage({ cost: 0.3 }));
+    expect(b.usedCost).toBe(0.3);
+  });
+
+  it("多次 consume 累加（retry 间如实记录，不减）", () => {
+    const b = new Budget();
+    b.consume(usage({ input: 100, cost: 0.1 }));
+    b.consume(usage({ input: 50, output: 50, cost: 0.2 }));
+    // tokens: 100×1 + (50×1 + 50×2) = 250
+    expect(b.usedTokens).toBe(250);
+    // 0.1 + 0.2 浮点误差，用 toBeCloseTo
+    expect(b.usedCost).toBeCloseTo(0.3);
+  });
+});
+
+// ── consume：NaN 守卫（TDD，预期主 agent 同步补源码守卫）──────
+//
+// 源码 consume() 当前无守卫：undefined/NaN/Infinity 进入加权公式会产出
+// NaN/Infinity 污染 usedTokens，导致后续 isExceeded 永远命中。
+// 以下测试断言「脏字段当 0 处理」——守卫补上前会失败，属预期临时状态。
+
+describe("Budget.consume NaN 守卫（undefined/NaN/Infinity 当 0 处理）", () => {
+  it("input=undefined → usedTokens 不变（不当 NaN）", () => {
+    const b = new Budget({ maxTokens: 1000 });
+    b.consume(poisonedUsage({ input: undefined }));
+    expect(b.usedTokens).toBe(0);
+    expect(Number.isNaN(b.usedTokens)).toBe(false);
+  });
+
+  it("output=undefined → usedTokens 不变", () => {
+    const b = new Budget({ maxTokens: 1000 });
+    b.consume(poisonedUsage({ output: undefined }));
+    expect(b.usedTokens).toBe(0);
+  });
+
+  it("input=NaN → usedTokens 不变", () => {
+    const b = new Budget({ maxTokens: 1000 });
+    b.consume(poisonedUsage({ input: Number.NaN }));
+    expect(b.usedTokens).toBe(0);
+    expect(Number.isNaN(b.usedTokens)).toBe(false);
+  });
+
+  it("output=NaN → usedTokens 不变", () => {
+    const b = new Budget({ maxTokens: 1000 });
+    b.consume(poisonedUsage({ output: Number.NaN }));
+    expect(b.usedTokens).toBe(0);
+  });
+
+  it("cacheRead=NaN / cacheWrite=NaN → usedTokens 不变", () => {
+    const b = new Budget({ maxTokens: 1000 });
+    b.consume(
+      poisonedUsage({ cacheRead: Number.NaN, cacheWrite: Number.NaN }),
+    );
+    expect(b.usedTokens).toBe(0);
+  });
+
+  it("input=Infinity → usedTokens 不变（Infinity 不烧穿预算）", () => {
+    const b = new Budget({ maxTokens: 1000 });
+    b.consume(poisonedUsage({ input: Number.POSITIVE_INFINITY }));
+    expect(b.usedTokens).toBe(0);
+    expect(Number.isFinite(b.usedTokens)).toBe(true);
+  });
+
+  it("合法字段与脏字段混合 → 仅累加合法部分（脏字段当 0）", () => {
+    const b = new Budget({ maxTokens: 1000 });
+    // input=100（合法）+ output=undefined（脏，当 0）
+    b.consume(poisonedUsage({ input: 100, output: undefined }));
+    expect(b.usedTokens).toBe(100);
+  });
+
+  it("已有累计后再遇脏数据 → usedTokens 保持原值不退化", () => {
+    const b = new Budget({ maxTokens: 1000 });
+    b.consume(usage({ input: 50 })); // usedTokens = 50
+    b.consume(poisonedUsage({ input: undefined }));
+    expect(b.usedTokens).toBe(50);
+  });
+
+  it("cost=undefined → usedCost 不当 NaN", () => {
+    const b = new Budget();
+    b.consume(poisonedUsage({ cost: undefined }));
+    expect(b.usedCost).toBe(0);
+    expect(Number.isNaN(b.usedCost)).toBe(false);
+  });
+});
+
+// ── incrementCallCount ───────────────────────────────────────
+
+describe("Budget.incrementCallCount", () => {
+  it("累加调用计数（每次 agent dispatch 后 +1）", () => {
+    const b = new Budget();
+    expect(b.totalCallCount).toBe(0);
+    b.incrementCallCount();
+    b.incrementCallCount();
+    b.incrementCallCount();
+    expect(b.totalCallCount).toBe(3);
+  });
+});
+
+// ── isExceeded ───────────────────────────────────────────────
+
+describe("Budget.isExceeded", () => {
+  it("maxTokens=1000, usedTokens=999 → 未超", () => {
+    const b = new Budget({ maxTokens: 1000 });
+    b.consume(usage({ input: 999 }));
+    expect(b.isExceeded()).toBe(false);
+  });
+
+  it("maxTokens=1000, usedTokens=1000 → 超限（边界 >=）", () => {
+    const b = new Budget({ maxTokens: 1000 });
+    b.consume(usage({ input: 1000 }));
+    expect(b.isExceeded()).toBe(true);
+  });
+
+  it("maxTokens=1000, usedTokens=1001 → 超限", () => {
+    const b = new Budget({ maxTokens: 1000 });
+    b.consume(usage({ input: 1001 }));
+    expect(b.isExceeded()).toBe(true);
+  });
+
+  it("maxTokens=0 → 视为不限制（守卫，首个 agent 完成不误判）", () => {
+    const b = new Budget({ maxTokens: 0 });
+    b.consume(usage({ input: 999999 }));
+    expect(b.isExceeded()).toBe(false);
+  });
+
+  it("maxTokens undefined → 视为不限制", () => {
+    const b = new Budget();
+    b.consume(usage({ input: 999999 }));
+    expect(b.isExceeded()).toBe(false);
+  });
+
+  it("maxCost 边界：usedCost >= maxCost → 超限", () => {
+    const b = new Budget({ maxCost: 1 });
+    b.consume(usage({ cost: 1 }));
+    expect(b.isExceeded()).toBe(true);
+  });
+
+  it("maxCost=0 → 视为不限制", () => {
+    const b = new Budget({ maxCost: 0 });
+    b.consume(usage({ cost: 999 }));
+    expect(b.isExceeded()).toBe(false);
+  });
+
+  it("maxCost undefined → 视为不限制", () => {
+    const b = new Budget();
+    b.consume(usage({ cost: 999 }));
+    expect(b.isExceeded()).toBe(false);
+  });
+
+  it("token 与 cost 均未达阈值 → 不超限", () => {
+    const b = new Budget({ maxTokens: 1000, maxCost: 10 });
+    b.consume(usage({ input: 50, cost: 0.5 }));
+    expect(b.isExceeded()).toBe(false);
+  });
+});
+
+// ── remaining ────────────────────────────────────────────────
+
+describe("Budget.remaining", () => {
+  it("正常：maxTokens - usedTokens", () => {
+    const b = new Budget({ maxTokens: 1000 });
+    b.consume(usage({ input: 300 }));
+    expect(b.remaining()).toBe(700);
+  });
+
+  it("usedTokens > maxTokens → clamp 到 0（不返回负数）", () => {
+    const b = new Budget({ maxTokens: 1000 });
+    b.consume(usage({ input: 1500 }));
+    expect(b.remaining()).toBe(0);
+  });
+
+  it("maxTokens=1000, usedTokens=1000（恰好用尽）→ 0", () => {
+    const b = new Budget({ maxTokens: 1000 });
+    b.consume(usage({ input: 1000 }));
+    expect(b.remaining()).toBe(0);
+  });
+
+  it("maxTokens undefined → undefined（视为不限制）", () => {
+    const b = new Budget();
+    expect(b.remaining()).toBeUndefined();
+  });
+
+  it("maxTokens <= 0 → undefined（视为不限制）", () => {
+    const b = new Budget({ maxTokens: 0 });
+    expect(b.remaining()).toBeUndefined();
+  });
+});
+
+// ── 构造 ─────────────────────────────────────────────────────
+
+describe("Budget 构造", () => {
+  it("默认值全 0 / undefined", () => {
+    const b = new Budget();
+    expect(b.usedTokens).toBe(0);
+    expect(b.usedCost).toBe(0);
+    expect(b.totalCallCount).toBe(0);
+    expect(b.maxTokens).toBeUndefined();
+    expect(b.maxCost).toBeUndefined();
+    expect(b.maxTimeMs).toBeUndefined();
+  });
+
+  it("从持久化数据重建（保留全部字段）", () => {
+    const b = new Budget({
+      maxTokens: 5000,
+      maxCost: 2,
+      maxTimeMs: 60000,
+      usedTokens: 100,
+      usedCost: 0.3,
+      totalCallCount: 7,
+    });
+    expect(b.maxTokens).toBe(5000);
+    expect(b.maxCost).toBe(2);
+    expect(b.maxTimeMs).toBe(60000);
+    expect(b.usedTokens).toBe(100);
+    expect(b.usedCost).toBe(0.3);
+    expect(b.totalCallCount).toBe(7);
+  });
+});

package/src/orchestration/models/agent-call.ts

@@ -0,0 +1,83 @@
+/**
+ * Workflow Extension — AgentCall 实体
+ *
+ * 单次 agent 调用的数据 + 不变式守卫（D-12）。纯数据，无 execute 上帝方法——
+ * 执行编排（重试+预算+stale 检测）在 execute-agent-call.ts 的 free function。
+ *
+ * - 状态机：pending → running → done（不可逆）
+ * - markRunning 进入 running 并 attempts++（每次 retry 前调用）
+ * - markDone(result) 进入 done 并记录结果
+ * - traceNode 持有引用，但 AgentCall 不直接改其字段——trace 同步由
+ * Trace.update 负责（D-10 单一来源），AgentCall 只持有引用供 executeAgentCall 读取
+ *
+ * 层归属：Engine。
+ *
+ * 参考：domain-models.md §5（字段/不变式/设计决策）。
+ */
+import type { AgentCallOpts, AgentResult, ExecutionTraceNode } from "./types.ts";
+
+/** AgentCall 生命周期状态。pending→running→done，不可逆。 */
+export type AgentCallStatus = "pending" | "running" | "done";
+
+/**
+ * AgentCall 实体（在 RunState.calls Map 内）。
+ *
+ * 不变式：
+ * - status 转换严格 pending→running→done，反向抛错
+ * - done 时 result 必须已设置（markDone(result) 前置保证）
+ * - attempts 反映 dispatch 次数（markRunning 累加，含首次）
+ * - **无 execute 方法**（D-12：执行编排由 Engine executeAgentCall 函数承担）
+ */
+export class AgentCall {
+  readonly id: number;
+  readonly opts: AgentCallOpts;
+  status: AgentCallStatus = "pending";
+  attempts = 0;
+  result?: AgentResult;
+ /** Pi subprocess session ID（uuidv7，G-017 归此）。 */
+  sessionId?: string;
+ /** Session JSONL 绝对路径（finalizeCall 后从 result.sessionFile 填入，对齐 sessionId 模式）。 */
+  sessionFile?: string;
+ /** 与 Trace 共享的节点引用（D-10 单源）。AgentCall 不直接改其字段。 */
+  readonly traceNode: ExecutionTraceNode;
+
+  constructor(id: number, opts: AgentCallOpts, traceNode: ExecutionTraceNode) {
+    this.id = id;
+    this.opts = opts;
+    this.traceNode = traceNode;
+  }
+
+ /**
+ * 标记进入 running 状态（dispatch 前）。attempts++（含首次）。
+ * @throws 若已 done（不可重启）
+ */
+  markRunning(): void {
+    if (this.status === "done") {
+      throw new Error(`AgentCall ${this.id} already done — cannot mark running`);
+    }
+    this.status = "running";
+    this.attempts += 1;
+  }
+
+ /**
+ * 标记完成（成功或失败均调用——result.error 区分）。
+ * @throws 若当前非 running（pending 不能直接跳 done，必须先 markRunning）
+ */
+  markDone(result: AgentResult): void {
+    if (this.status !== "running") {
+      throw new Error(`AgentCall ${this.id} must be running to mark done (was ${this.status})`);
+    }
+    this.result = result;
+    this.status = "done";
+  }
+
+ /** 记录 pi subprocess session ID（dispatch 成功后）。 */
+  setSessionId(sessionId: string): void {
+    this.sessionId = sessionId;
+  }
+
+ /** 记录 session JSONL 绝对路径（finalizeCall 后，对齐 setSessionId 模式）。 */
+  setSessionFile(sessionFile: string): void {
+    this.sessionFile = sessionFile;
+  }
+}

package/src/orchestration/models/budget.ts

@@ -0,0 +1,118 @@
+/**
+ * Workflow Extension — Budget 值对象
+ *
+ * Token / cost 预算值对象（D-12）。纯数据 + 不变式守卫，无副作用。
+ *
+ * maxTokens===0 视为不限制（守卫，避免首个 agent 完成误判 budget_limited）。
+ * （预算语义对齐 2026-08：soft-limit 常量（500 调用数预警）与 90% 阈值预警方法
+ * 已删——全库无生产消费方，仅测试锁定。）
+ *
+ * 层归属：Engine。
+ *
+ * 参考：domain-models.md §4（字段/不变式/操作）。
+ */
+import type { AgentUsage } from "./types.ts";
+
+/**
+ * Budget 加权系数（token 口径）。
+ *
+ * usedTokens 不再是四项原始 token 简单求和，而是加权后的「等效消耗」，
+ * 反映不同 token 桶的真实计费/处理开销差异：
+ * - input（非缓存新增）：首次见到、需完整处理的新内容，权重 1（基准）
+ * - cacheRead（命中缓存）：读取历史，开销极低，按 1/50 折算（权重 0.02）
+ * - cacheWrite（首次写入缓存）：本版本不计入 budget（权重 0）
+ * - output：模型自回归生成，开销最高，权重 2
+ *
+ * 这避免了长 session 中 cacheRead 随轮次单调累积导致 budget 被快速烧穿的失真
+ * （详见讨论：cacheRead 在 N 轮里被报 N 次，去重上下文只有一份）。
+ */
+export const INPUT_WEIGHT = 1;
+export const CACHE_READ_WEIGHT = 0.02;
+export const CACHE_WRITE_WEIGHT = 0;
+export const OUTPUT_WEIGHT = 2;
+
+/**
+ * Budget 值对象。
+ *
+ * 不变式（domain-models.md §4）：
+ * - maxTokens > 0 守卫：maxTokens===0 或 undefined 视为不限制
+ * - maxCost > 0 守卫：同上
+ * - consume 只累加，不减；isExceeded 只读
+ * - 无回调字段——所有副作用由调用方在 consume 后查询决定
+ */
+export class Budget {
+  readonly maxTokens?: number;
+  readonly maxCost?: number;
+  readonly maxTimeMs?: number;
+  usedTokens = 0;
+  usedCost = 0;
+ /** 总调用计数（持久化/诊断用；execute-agent-call 每次 dispatch 后 increment）。 */
+  totalCallCount = 0;
+
+  constructor(opts: {
+    maxTokens?: number;
+    maxCost?: number;
+    maxTimeMs?: number;
+    usedTokens?: number;
+    usedCost?: number;
+    totalCallCount?: number;
+  } = {}) {
+    this.maxTokens = opts.maxTokens;
+    this.maxCost = opts.maxCost;
+    this.maxTimeMs = opts.maxTimeMs;
+    this.usedTokens = opts.usedTokens ?? 0;
+    this.usedCost = opts.usedCost ?? 0;
+    this.totalCallCount = opts.totalCallCount ?? 0;
+  }
+
+ /**
+ * 累加一次 agent 调用的 usage（加权口径）。
+ *
+ * 四项 token 按各自权重（INPUT/CACHE_READ/CACHE_WRITE/OUTPUT_WEIGHT）折算后求和，
+ * 而非原始 token 数直接相加。retry 间的真实消耗如实记录，避免预算被低估。
+ * 详见上方权重常量的口径说明。
+ */
+  consume(usage: AgentUsage): void {
+    // NaN 守卫——非有限值当 0 处理，防 usedTokens 变 NaN 导致 isExceeded() 永远 false（预算限制失效）
+    const numOrZero = (v: number | undefined): number =>
+      typeof v === "number" && Number.isFinite(v) ? v : 0;
+    this.usedTokens +=
+      numOrZero(usage.input) * INPUT_WEIGHT +
+      numOrZero(usage.output) * OUTPUT_WEIGHT +
+      numOrZero(usage.cacheRead) * CACHE_READ_WEIGHT +
+      numOrZero(usage.cacheWrite) * CACHE_WRITE_WEIGHT;
+    this.usedCost += numOrZero(usage.cost);
+  }
+
+ /** 累加调用计数（每次 agent dispatch 后调用；持久化快照同步）。 */
+  incrementCallCount(): void {
+    this.totalCallCount += 1;
+  }
+
+ /**
+ * 是否超 token / cost 预算（FR-3）。
+ *
+ * maxTokens===0 或 undefined 视为不限制（守卫）；
+ * maxCost===0 或 undefined 视为不限制。
+ * 时间预算（maxTimeMs）不由本方法判断——它是 wall-clock 约束，需参照 startedAt，
+ * 由 lifecycle 层的 scheduleTimeBudget（runWorkflow 内 setTimeout）
+ * 独立调度，到期 abortRun(doneReason="time_limited")。
+ */
+  isExceeded(): boolean {
+    if (this.maxTokens !== undefined && this.maxTokens > 0 && this.usedTokens >= this.maxTokens) {
+      return true;
+    }
+    return this.maxCost !== undefined && this.maxCost > 0 && this.usedCost >= this.maxCost;
+  }
+
+ /**
+ * 剩余 token 预算。maxTokens 未设或 ≤0 时返回 undefined（视为不限制）。
+ *
+ * 嵌套 workflow() 调用时由 executeNestedWorkflow 消费：子 run 的 budgetTokens
+ * 继承父 run 的剩余预算，实现父子预算隔离下的总量约束。
+ */
+  remaining(): number | undefined {
+    if (this.maxTokens === undefined || this.maxTokens <= 0) return undefined;
+    return Math.max(0, this.maxTokens - this.usedTokens);
+  }
+}

package/src/orchestration/models/ports.ts

@@ -0,0 +1,164 @@
+/**
+ * Workflow Extension — Engine Ports + 编排层共享类型
+ *
+ * 3 个注入 Port（AgentRunner / RunStore / WorkerHost）——Engine 定义、Infra 实现，
+ * 是真需要 mock 测试的依赖（子进程/文件系统/线程）。
+ *
+ * 编排层共享类型（WorkerHandlers / LifecycleDeps）——打破 lifecycle ↔
+ * error-recovery 循环依赖：2 个 engine 函数文件各自独立，共用同一组
+ * 依赖签名（D-12）。
+ *
+ * 层归属：Engine。零 infra 依赖（AC-1）。
+ */
+import type { StreamSink, SubagentStream } from "../../execution/stream-sink.ts";
+import type { AgentEvent } from "../../shared/agent-event.ts";
+import type { WorkerHandle } from "../worker-handle.ts";
+import type { RunSpec } from "./run-spec.ts";
+import type { AgentCallOpts, AgentResult } from "./types.ts";
+import type { WorkflowRun } from "./workflow-run.ts";
+
+// ── Port 1: AgentRunner ───────────────────────────────────────
+
+/**
+ * Agent 子进程执行 port。Infra 实现：SubprocessAgentRunner。
+ *
+ * run 执行单次 agent 调用（委托 SubagentService.executeAndAwait），返回结构化结果。
+ * signal 用于 abort 传播。
+ *
+ * onEvent（可选）：强类型 AgentEvent 回调，供调用方实时更新 live record 供 TUI 展示进度。
+ * 不传则不回调（向后兼容；现有调用点不传不受影响）。
+ *
+ * D-005: onEvent 签名从 raw Record<string,unknown> 升级为 AgentEvent——委托后不再有
+ * raw JSONL 中间层（executeAndAwait 直接出 AgentEvent，session-runner handleSdkEvent 出口）。
+ */
+export interface AgentRunner {
+  run(opts: AgentCallOpts, signal: AbortSignal, onEvent?: (event: AgentEvent) => void, stream?: SubagentStream): Promise<AgentResult>;
+}
+
+// ── Port 2: RunStore ──────────────────────────────────────────
+
+/**
+ * WorkflowRun 持久化 port。Infra 实现：JsonlRunStore。
+ *
+ * save 在每次状态变更后持久化整个 WorkflowRun（聚合根）；
+ * loadAll 在 session_start 时重水合（D-5：JSONL 不向后兼容旧 session，旧格式返回空）。
+ * stateFilePath 返回 run 状态文件的绝对路径（供 overlay/GUI 暴露给用户）。
+ */
+export interface RunStore {
+  save(run: WorkflowRun): Promise<void>;
+  loadAll(): Promise<WorkflowRun[]>;
+  /** 返回 run 状态快照文件的绝对路径：<sessionDir>/workflow-state/<runId>.jsonl */
+  stateFilePath(runId: string): string;
+}
+
+// ── Port 3: WorkerHost ────────────────────────────────────────
+
+/**
+ * Worker 线程启动 port。Infra 实现：WorkerHostImpl。
+ *
+ * start 创建一个 Worker thread 运行 workflow 脚本，返回 WorkerHandle。
+ * handlers 绑定 message/error/exit 回调（见 WorkerHandlers）。
+ */
+export interface WorkerHost {
+  start(
+    spec: RunSpec,
+    args: Record<string, unknown>,
+    handlers: WorkerHandlers,
+  ): WorkerHandle;
+}
+
+// ── 编排层共享类型 1: WorkerHandlers ───────────────────────────
+
+/**
+ * Worker 线程事件回调集合——WorkerHost.start 的入参，由 lifecycle
+ * 构造并注入。2 个 engine 文件（lifecycle / error-recovery）共用此签名，
+ * 避免各自定义形状不一致的 handler bag（打破循环依赖）。
+ *
+ * 所有回调返回 Promise——允许 engine 层在回调内做 await persistState 等异步操作。
+ */
+export interface WorkerHandlers {
+ /** Worker → Main 的业务消息（agent-call / return / error / log）。 */
+  onMessage(raw: unknown): Promise<void>;
+ /** Worker 线程 uncaught error。 */
+  onError(err: Error): Promise<void>;
+ /** Worker 线程 exit（含 code，用于区分正常退出 vs 崩溃）。handle 用于竞态防护 G-025。 */
+  onExit(code: number, handle: WorkerHandle): Promise<void>;
+}
+
+// ── 编排层共享类型 2: LifecycleDeps ────────────────────────────
+
+/**
+ * lifecycle / error-recovery 2 个 engine 函数文件的共同依赖 bag。
+ *
+ * 取代旧 4 个 Context factory（errorHandlerContext / agentCallContext /
+ * budgetCallbacks / 旧 terminate bag，AC-2 目标）。函数签名 `(deps: LifecycleDeps, ...)`
+ * 让每个 free function 自包含依赖，无需 God Facade 中介。
+ *
+ * - store: 持久化（RunStore port）
+ * - workerHost: 启动 worker（WorkerHost port）
+ * - runner: 执行 agent（AgentRunner port）
+ * - runs: 内存中的活动 run 聚合根索引（runId → WorkflowRun），替代旧 6 张并行 map
+ * - onRunDone?: run 到达 done 终态时的回调（C-4 修复，可选）。由 Interface 层
+ * factory 注入（notifyDone —— 唤醒 parent agent 消费结果）。Engine 层不依赖
+ * Pi SDK，通过 callback 把完成信号外推到 Interface 层。所有 transition("done", ...)
+ * 路径（handleReturn / handleWorkerError / handleScriptError / abortRun /
+ * dispatchAgentCall budget 终止）调完 transition + save 后触发本回调。
+ */
+export interface LifecycleDeps {
+  store: RunStore;
+  workerHost: WorkerHost;
+  runner: AgentRunner;
+  runs: Map<string, WorkflowRun>;
+ /** run 到达 done 终态时的回调（C-4 修复，可选）。Interface 层注入 notifyDone。 */
+  onRunDone?: (run: WorkflowRun) => void;
+ /**
+ * 跨扩展事件总线（pending-notifications register/unregister 信号灯）。
+ *
+ * runWorkflow 启动时 emit pending:register；所有 transition("done") 路径 emit
+ * pending:unregister。两处均通过本端口（Engine 不直接依赖 Pi SDK）。可选——
+ * 无 pending-notifications 扩展时 no-op（向后兼容）。
+ */
+  eventBus?: { emit(channel: string, data: unknown): void };
+ /**
+ * 调试日志端口（Engine 不直接依赖 Pi SDK）。Interface 层注入实现。
+ * 关键路径记录 run 启动、保存、pending 注册/注销，便于排查异步操作状态。
+ */
+  log?: (level: "debug" | "info" | "warn" | "error", component: string, message: string, data?: unknown) => void;
+ /**
+ * D-12 regression fix (round-2 #2)：rebuildRuntime 重新调度 run 级墙钟预算计时器。
+ *
+ * worker/script 错误重试走 replaceRuntime，旧 RunRuntime 的 release 会 clearTimeout
+ * 旧计时器（run-runtime.release）。新 runtime 必须重排 scheduleTimeBudget，否则带
+ * budgetTimeMs 的 run 命中一次错误重试后时间预算静默失效（直到下次 pause/resume 才重排）。
+ * 由 Interface 层 factory 注入——闭包捕获 deps，内部调 lifecycle.scheduleTimeBudget。
+ *
+ * 可选——旧测试 deps 不注入时 rebuildRuntime 不重排计时器（兼容，不影响无时间预算的 run）。
+ */
+  scheduleTimeBudget?: (
+    runId: string,
+    budgetTimeMs: number,
+  ) => ReturnType<typeof setTimeout> | undefined;
+ /**
+ * workflow() 嵌套调用回调（可选）。Worker 脚本内调 workflow(name, args) 时触发。
+ *
+ * 由 Interface 层 makeDeps 注入（闭包捕获 registry + deps）。Engine 层的
+ * error-recovery.handleWorkerMessage 收到 workflow-call 消息后调本回调，
+ * 拿到子 workflow 执行结果后 postMessage(workflow-result) 回 worker。
+ *
+ * 不注入时 workflow() 返回 error result（向后兼容，不影响非嵌套场景）。
+ */
+  onWorkflowCall?: (
+    name: string,
+    args: Record<string, unknown>,
+    parentRun: WorkflowRun,
+  ) => Promise<unknown>;
+ /**
+ * UI streaming sink（ctx.ui.setWidget），workflow agent call 创建 SubagentStream 用。
+ *
+ * 由 Interface 层 makeDeps 注入（从 SubagentService.getStreamSink() 取）。
+ * dispatchAgentCall 用它创建 SubagentStream（widgetKey=subagent-stream-<runId>-<stepIndex>），
+ * 使 workflow agent call 的 text_delta 走与 background subagent 相同的 streaming 链路。
+ * 可选——无 UI 模式（TUI/RPC 无 setWidget）时为 undefined，dispatchAgentCall 不创建 stream。
+ */
+  streamSink?: StreamSink;
+}