@zhushanwen/pi-subagent-workflow 0.1.0

package/src/orchestration/models/ports.ts

@@ -0,0 +1,165 @@
+/**
+ * Workflow Extension — Engine Ports + 编排层共享类型
+ *
+ * 3 个注入 Port（AgentRunner / RunStore / WorkerHost）——Engine 定义、Infra 实现，
+ * 是真需要 mock 测试的依赖（子进程/文件系统/线程）。
+ *
+ * 编排层共享类型（WorkerHandlers / LifecycleDeps）——打破 lifecycle ↔
+ * error-recovery ↔ node-ops 循环依赖：3 个 engine 函数文件各自独立，共用同一组
+ * 依赖签名（D-12）。
+ *
+ * 层归属：Engine。零 infra 依赖（AC-1）。
+ */
+import type { AgentEvent } from "../../shared/agent-event.ts";
+import type { AgentRegistry } from "../../execution/agent-registry.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): Promise<AgentResult>;
+}
+
+// ── Port 2: RunStore ──────────────────────────────────────────
+
+/**
+ * WorkflowRun 持久化 port。Infra 实现：JsonlRunStore。
+ *
+ * save 在每次状态变更后持久化整个 WorkflowRun（聚合根）；
+ * loadAll 在 session_start 时重水合（D-5：JSONL 不向后兼容旧 session，旧格式返回空）。
+ */
+export interface RunStore {
+  save(run: WorkflowRun): Promise<void>;
+  loadAll(): Promise<WorkflowRun[]>;
+}
+
+// ── 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
+ * 构造并注入。3 个 engine 文件（lifecycle / error-recovery / node-ops）共用此签名，
+ * 避免各自定义形状不一致的 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 / node-ops 3 个 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;
+ /**
+ * BL-1：agent/skill/schema 解析依赖（per-session，可选）。
+ *
+ * Interface 层 factory 在 session_start 注入：agentRegistry（扫描 .agents/agents 等
+ * 7 路径）、sessionDir（临时文件根）、activeTempFiles（session_shutdown 回收集合）。
+ * error-recovery.dispatchAgentCall 用这 3 项调 resolveAgentOpts，把
+ * `agent({agent,skill,schema})` 的 inline override 解析成 systemPromptFiles /
+ * skillPath / schemaEnv，否则 pi 子进程只收到原始 prompt（D-12 重构误删导致回归）。
+ * 全部可选——测试 makeDeps 工厂无需改。
+ */
+  agentRegistry?: AgentRegistry;
+  sessionDir?: string;
+  activeTempFiles?: Set<string>;
+ /**
+ * 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>;
+}

package/src/orchestration/models/run-runtime.ts

@@ -0,0 +1,91 @@
+/**
+ * Workflow Extension — Run Runtime
+ *
+ * 聚合内运行时资源（仅 status==="running" 时存在）。技术资源聚合，
+ * Engine 层类型，持 WorkerHandle / ConcurrencyGate 具体类（D-12 不造 interface）。
+ *
+ * 职责：封装一次 running-segment 的所有技术资源（worker 线程 + 并发信号量 +
+ * abort controller），统一 release 入口（AC-2：单 release 替代多 boolean flag）。
+ *
+ * pause/resume 生命周期（G3-001）：
+ * - pause 时 WorkflowRun.releaseRuntime 使整个 RunRuntime 丢弃（runtime=undefined）
+ * - resume 时 WorkflowRun.assignRuntime(new RunRuntime(...)) 全部重建
+ * - 原因：AbortController 一次性语义决定 controller 无法跨 pause/resume 复用，
+ * gate 队列也在 worker 重跑脚本 + callCache replay 时清空无影响——所以整个
+ * RunRuntime 重建最简单、语义最清晰。
+ *
+ * 参考：domain-models.md §10、clarification.md G3-001。
+ */
+
+import { ConcurrencyGate } from "../concurrency-gate.ts";
+import { WorkerHandle } from "../worker-handle.ts";
+
+/**
+ * release mode 枚举——调用方表达意图。
+ *
+ * 注：pause 与 terminal 在 RunRuntime 内部行为等价（都全释放 worker + controller）。
+ * 保留枚举为可读性——调用方语义清晰（lifecycle pauseRun 传 "pause"，
+ * terminateRun 传 "terminal"），且为未来细分留余地。
+ */
+export type ReleaseMode = "pause" | "terminal";
+
+// ── RunRuntime ───────────────────────────────────────────────
+
+export class RunRuntime {
+ /** Worker 线程句柄。 */
+  readonly worker: WorkerHandle;
+ /** 并发信号量。 */
+  readonly gate: ConcurrencyGate;
+ /** per-running-segment AbortController（一次性，无法复用——G3-001）。 */
+  readonly controller: AbortController;
+ /** Run 级墙钟时间预算计时器（spec.budgetTimeMs > 0 时由 lifecycle 调度，
+   * 到期 abortRun time_limited）。release 时清理，避免 pause/abort 后孤儿计时器
+   * 仍触发（resume 会重新调度一个全新的计时器，旧的不应残留）。 */
+  readonly timeBudgetTimer?: ReturnType<typeof setTimeout>;
+ /** 防止 release 重复执行（幂等）。 */
+  private released = false;
+
+  constructor(
+    worker: WorkerHandle,
+    gate: ConcurrencyGate,
+    controller: AbortController,
+    timeBudgetTimer?: ReturnType<typeof setTimeout>,
+  ) {
+    this.worker = worker;
+    this.gate = gate;
+    this.controller = controller;
+    this.timeBudgetTimer = timeBudgetTimer;
+  }
+
+ /**
+ * 释放所有资源：terminate worker + abort controller。
+ *
+ * 幂等——重复调用安全（第二次起 no-op，released flag 守卫）。
+ * 调用后此 RunRuntime 应被调用方丢弃（WorkflowRun.runtime = undefined），
+ * resume/retry 时由 assignRuntime/replaceRuntime 注入新实例（G3-001）。
+ *
+ * worker.terminate 本身幂等，controller.abort 本身幂等
+ * （重复 abort 无副作用），但 released flag 让本方法语义更明确：
+ * 「释放过一次的 runtime 不再释放第二次」。
+ *
+ * @param mode pause | terminal —— 当前等价，保留为调用方表达意图
+ */
+  release(_mode: ReleaseMode): void {
+    if (this.released) return;
+    this.released = true;
+ // 清理 run 级时间预算计时器——pause/abort/replaceRuntime 后它不应再触发
+ // （resume 会调度全新计时器；孤儿触发会把已 paused/aborted 的 run 误转 done）。
+    if (this.timeBudgetTimer) clearTimeout(this.timeBudgetTimer);
+ // worker.terminate 异步但幂等——不 await（release 是同步签名，调用方
+ // 不应被底层线程关闭阻塞；worker 收到 terminate 后自行清理）。
+    void this.worker.terminate();
+ // controller.abort 触发 listener（kill agent subprocess、pause workflow）。
+ // 一次性语义——已 aborted 的 controller 重复 abort 无副作用。
+    this.controller.abort();
+  }
+
+ /** 是否已 release（测试 + 诊断用）。 */
+  get isReleased(): boolean {
+    return this.released;
+  }
+}

package/src/orchestration/models/run-spec.ts

@@ -0,0 +1,54 @@
+/**
+ * Workflow Extension — RunSpec 值对象
+ *
+ * 单次 workflow run 的不可变规格（domain-models.md §2）。
+ *
+ * 设计：
+ * - 全部字段 readonly——run 一旦创建，规格不可改（状态变化走 RunState）
+ * - scriptSource 是已 strip `export const meta` 的可执行源（WorkflowScript.toExecutable）
+ * - budgetTokens/budgetTimeMs 是上限（可选，未设 = 不限制）
+ *
+ * 层归属：Engine。
+ *
+ * 参考：domain-models.md §2。
+ */
+
+import type { Budget } from "./budget.ts";
+
+/**
+ * RunSpec——一次 workflow run 的不可变输入规格。
+ *
+ * 作为 RunStore 持久化的一部分（WorkflowRun.spec），跨 session pause/resume 时
+ * 需要 scriptSource/args 重建 worker（G3-001）。
+ */
+export interface RunSpec {
+ /** 已 strip export 的可执行源（WorkflowScript.toExecutable 产物）。 */
+  readonly scriptSource: string;
+ /** 调用方传入的参数（worker 内通过 $ARGS 访问）。 */
+  readonly args: Record<string, unknown>;
+ /** Token 预算上限（未设或 0 = 不限制，见 Budget 守卫）。 */
+  readonly budgetTokens?: number;
+ /** 时间预算上限（ms，wall-clock，由 lifecycle.scheduleTimeBudget 调度）。 */
+  readonly budgetTimeMs?: number;
+ /**
+ * 父 Budget 共享引用（嵌套 workflow() 时由 executeNestedWorkflow 传入）。
+ *
+ * 设置时 lifecycle.runWorkflow 直接复用此 Budget 实例，而非 new 一个独立 Budget——
+ * 子 run 的 consume 直接反映到父 Budget，消除并行嵌套下的超支窗口（F-7 方案 B）。
+ * 顶层 run 无此字段（budgetTokens 走独立 Budget 构造）。
+ */
+  readonly budgetRef?: Budget;
+ /** 脚本名（meta.name 或文件名 stem）。 */
+  readonly scriptName: string;
+ /** 脚本文件绝对路径（用于诊断/日志）。 */
+  readonly scriptPath: string;
+ /** 人类可读描述（meta.description）。 */
+  readonly description?: string;
+ /**
+ * 父 workflow 调用链（嵌套 workflow() 时自动填充，循环检测用）。
+ *
+ * 顶层 run 无此字段。子 run 的 chain = [...parentChain, parentScriptName]。
+ * executeNestedWorkflow 检查目标 name 是否已在 chain 中，防止 A→B→A 死循环。
+ */
+  readonly parentWorkflowChain?: readonly string[];
+}

package/src/orchestration/models/run-state.ts

@@ -0,0 +1,44 @@
+/**
+ * Workflow Extension — RunState 值对象
+ *
+ * 单次 workflow run 的可持久化状态（domain-models.md §3）。
+ *
+ * 设计：
+ * - status/reason/budget/calls/trace/errorLogs 是可变字段（运行中持续更新）
+ * - error/scriptResult 仅终态有值（done 时）
+ * - 与 RunSpec 的区别：RunSpec 不可变（输入），RunState 可变（执行快照）
+ *
+ * 层归属：Engine。
+ *
+ * 参考：domain-models.md §3。
+ */
+
+import type { AgentCall } from "./agent-call.ts";
+import type { Budget } from "./budget.ts";
+import type { Trace } from "./trace.ts";
+import type { DoneReason, RunStatus, WorkerLogEntry } from "./types.ts";
+
+/**
+ * RunState——一次 run 的可持久化执行状态。
+ *
+ * 持久化由 RunStore.save(WorkflowRun) 触发（WorkflowRun 持 RunState）。
+ * 跨 session pause/resume 时，RunState 从 JSONL 重水合（callCache 保留，worker 重建）。
+ */
+export interface RunState {
+ /** 当前状态（running/paused/done）。 */
+  status: RunStatus;
+ /** 终态原因（done 时必有）。 */
+  reason?: DoneReason;
+ /** Token/cost 预算（含 usedTokens/usedCost 累积）。 */
+  budget: Budget;
+ /** 按 callId 索引的 agent 调用集合（含 result，跨 pause/resume 存活）。 */
+  calls: Map<number, AgentCall>;
+ /** 执行追踪事件流（唯一来源 D-10）。 */
+  trace: Trace;
+ /** Worker console.* 捕获条目（run 级诊断，仅展示在 TUI widget）。 */
+  errorLogs: WorkerLogEntry[];
+ /** done && reason !== completed 时可有（失败/中止/预算超限的原因）。 */
+  error?: string;
+ /** done && reason === completed 时有（脚本 execute 返回值）。 */
+  scriptResult?: unknown;
+}

package/src/orchestration/models/trace.ts

@@ -0,0 +1,102 @@
+/**
+ * Workflow Extension — Trace 值对象
+ *
+ * 执行追踪事件流（D-10 单一来源）。纯 append-only + 单字段 update。
+ *
+ * 设计：
+ * - trace 节点存储 + 变更逻辑收敛为值对象（外部不能直接打洞 nodes 数组）。
+ * - update 只改单个 node 的 status/result/error/completedAt/sessionId（TracePatch）。
+ * - callId 不存在时 update no-op（防御性，避免 race 下抛错）。
+ * - 持久化（appendEntry）与事件通知（emit）不在本值对象内——它们由 engine 函数
+ * 在调用 update 前后负责（值对象只管数据形状，不管 IO）。
+ *
+ * 层归属：Engine。
+ *
+ * 参考：domain-models.md §6（字段/不变式）。
+ */
+import type { ExecutionTraceNode, TracePatch } from "./types.ts";
+
+/**
+ * Trace 值对象（事件流，唯一来源 D-10）。
+ *
+ * 不变式：
+ * - nodes 只增不改索引顺序（append-only）
+ * - update 只改单个 node 的 status/result/error/completedAt/sessionId
+ * - 不含 verifyStrategy（G-020 删除，不迁移）
+ */
+export class Trace {
+  private readonly nodes: ExecutionTraceNode[] = [];
+
+ /**
+ * 从已有节点数组重建 Trace（用于 RunStore 反序列化重水合）。
+ *
+ * 防御性拷贝——传入数组不被持有，外部 mutation 不影响 Trace。
+ * 不验证节点顺序/唯一性（调用方保证快照来源可信）。
+ */
+  static fromArray(nodes: readonly ExecutionTraceNode[]): Trace {
+    const trace = new Trace();
+    for (const node of nodes) {
+      trace.nodes.push({ ...node });
+    }
+    return trace;
+  }
+
+ /** Append a trace node（append-only，不改已有节点）。 */
+  append(node: ExecutionTraceNode): void {
+    this.nodes.push(node);
+  }
+
+ /**
+ * Update a trace node by stepIndex (callId) with a partial patch.
+ *
+ * 只改 patch 中提供的字段（status/result/error/completedAt/sessionId）。
+ * stepIndex 不存在时 no-op（防御性——agent 完成/失败回调可能晚于 run 终止到达）。
+ */
+  update(stepIndex: number, patch: TracePatch): void {
+    const node = this.findByStepIndex(stepIndex);
+    if (!node) return; // no-op: 不存在不抛错（D-10 防御性）
+
+    if (patch.status !== undefined) node.status = patch.status;
+    if (patch.result !== undefined) node.result = patch.result;
+    if (patch.error !== undefined) node.error = patch.error;
+    if (patch.completedAt !== undefined) node.completedAt = patch.completedAt;
+    if (patch.sessionId !== undefined) node.sessionId = patch.sessionId;
+  }
+
+ /** 查找指定 stepIndex 的节点（首个匹配，trace 中 stepIndex 应唯一）。 */
+  private findByStepIndex(stepIndex: number): ExecutionTraceNode | undefined {
+    for (const node of this.nodes) {
+      if (node.stepIndex === stepIndex) return node;
+    }
+    return undefined;
+  }
+
+ /** 按节点引用删除（仅用于测试或 run 重建场景；正常运行不调用）。 */
+  find(stepIndex: number): ExecutionTraceNode | undefined {
+    return this.findByStepIndex(stepIndex);
+  }
+
+ /**
+ * 按 stepIndex 移除节点（仅 pause 清理在飞 call 用）。
+ *
+ * 正常运行不调用（append-only 不变式）。仅 lifecycle.pauseRun 清理被 abort 的
+ * 在飞 call 时用——移除其 trace 节点，让 resume 重发 agent-call 时 append 全新
+ * 节点走全新执行路径（避免 stale "running" 节点残留 + trace.update 命中旧节点
+ * 导致新节点 orphan）。stepIndex 不存在时 no-op（防御性）。
+ */
+  removeByStepIndex(stepIndex: number): void {
+    const idx = this.nodes.findIndex((n) => n.stepIndex === stepIndex);
+    if (idx === -1) return;
+    this.nodes.splice(idx, 1);
+  }
+
+ /** readonly 视图——外部不应直接 mutate（不变式保护）。 */
+  toArray(): readonly ExecutionTraceNode[] {
+    return this.nodes;
+  }
+
+ /** 当前节点数。 */
+  get length(): number {
+    return this.nodes.length;
+  }
+}