@zhushanwen/pi-subagent-workflow 8.5.0 → 8.7.0

package/src/orchestration/models/types.ts

@@ -1,292 +0,0 @@
-/**
- * Workflow Extension — Engine 共享类型
- *
- * Engine 层全局基础类型。零 infra 依赖——不 import 任何 infra 文件，
- * 可独立编译测试（D-12 三层架构，AC-1）。
- *
- * 核心内容：
- * - 状态机：RunStatus = "running" | "done"（2 态，一次性生命周期，FR-3）
- * + DoneReason（completed/failed/aborted/budget_limited/time_limited）
- * - AgentCallOpts / AgentResult / AgentUsage（单次 agent 调用的输入/输出）
- * - ExecutionTraceNode / TracePatch / ToolCallEntry / WorkerLogEntry（trace 数据）
- *
- * 层归属：Engine（数据结构 + 不变式守卫）。
- */
-
-import type { ExecutionRecord } from "../../execution/types.ts";
-
-// ── 状态机 ────────────────────────────────────────────────────
-
-/**
- * 状态机：2 态（D-12 / FR-3，一次性生命周期——run 不可挂起）。
- *
- * running → done
- *
- * `done` 是唯一终态，具体原因由 DoneReason 区分。
- */
-export type RunStatus = "running" | "done";
-
-/** 终态原因。done 时必有（WorkflowRun 不变式）。 */
-export type DoneReason =
-  | "completed"
-  | "failed"
-  | "aborted"
-  | "budget_limited"
-  | "time_limited"
-  // m3：runAndWait 合成返回值专用——参数校验失败（run 从未创建，不进入 run.state.reason）
-  | "invalid_args";
-
-/** 合法的状态转换。空数组 = 无出边（done 终态）。 */
-export const VALID_RUN_TRANSITIONS: Record<RunStatus, readonly RunStatus[]> = {
-  running: ["done"] as const,
-  done: [] as const,
-};
-
-export const ALL_RUN_STATUSES: readonly RunStatus[] = ["running", "done"] as const;
-
-export const ALL_DONE_REASONS: readonly DoneReason[] = [
-  "completed",
-  "failed",
-  "aborted",
-  "invalid_args",
-  "budget_limited",
-  "time_limited",
-] as const;
-
-/** done 为终态，无出边。 */
-export function isDone(status: RunStatus): boolean {
-  return status === "done";
-}
-
-export function canRunTransition(from: RunStatus, to: RunStatus): boolean {
-  return (VALID_RUN_TRANSITIONS[from] as readonly RunStatus[]).includes(to);
-}
-
-// ── Agent 调用 ────────────────────────────────────────────────
-
-/**
- * 单次 agent 调用的输入选项。
- *
- * D-12 仅重组执行编排，AgentCallOpts 形状保持兼容。
- */
-export interface AgentCallOpts {
- /** The task prompt to send to the agent. */
-  prompt: string;
- /**
- * Optional JSON schema for structured output.
- * When provided, the schema is passed via PI_WORKFLOW_SCHEMA env to the subprocess,
- * which activates the structured-output tool + turn_end hook.
- * The tool's execute validates model output against the schema.
- * On success, `parsedOutput` on the result is set to `tool_execution_end.result.details`
- * (the validated, parsed data object — not the raw tool call args).
- */
-  schema?: Record<string, unknown>;
- /**
- * Model to use (e.g. "router-openai/glm-5.1").
- * When omitted, pi's default model is used.
- */
-  model?: string;
- /**
- * Thinking level override (e.g. "high", "medium", "low").
- * M2: Added to align with subagent path's ExecuteOptions.thinkingLevel.
- * When omitted, agent .md frontmatter thinkingLevel is used (via resolveIdentity/getAgentConfig).
- */
-  thinkingLevel?: string;
- /** Scene name passed through to the worker for model-selection hints. */
-  scene?: string;
- /**
- * Wall-clock timeout in milliseconds. When > 0, aborts the subprocess
- * if it runs longer than this, regardless of external signal.
- * Per-call，归 AgentCall 实体（G-027）。
- */
-  timeoutMs?: number;
- /**
- * Skill name to load (e.g. "code-review"). Resolved to SKILL.md path
- * and injected via --skill flag in the subprocess.
- */
-  skill?: string;
- /**
- * Resolved absolute path to the skill directory or SKILL.md file.
- * Set by agent-opts-resolver when opts.skill is present.
- */
-  skillPath?: string;
- /** Human-readable description for logging and debugging. */
-  description?: string;
- /**
- * Agent ref (absolute .md path). Resolved by resolveIdentity via getAgentConfig,
- * which injects the agent's systemPrompt/model/tools/thinkingLevel. Not handled by
- * resolveAgentOpts (single-responsibility: agent ref ownership belongs to resolveIdentity,
- * M2 fix — previously overlapped causing double-injection + model-tier confusion).
- */
-  agent?: string;
- /**
- * System prompt injection CONTENT (not file paths).
- * Set by agent-opts-resolver: schema structured-output instruction string.
- * Agent systemPrompt is NOT included here (handled by resolveIdentity/agentConfig).
- * mapToExecuteOptions passes this through to ExecuteOptions.appendSystemPrompt
- * (same name/semantics, transparent passthrough).
- */
-  appendSystemPrompt?: string[];
- /**
- * Schema JSON for PI_WORKFLOW_SCHEMA env var.
- * Set by agent-opts-resolver when opts.schema is present; passed as env var
- * to activate the structured-output tool + hook.
- */
-  schemaEnv?: string;
- /**
- * Per-call 工作目录（ADR-029 决策 1）。传给 child_process.spawn 的 cwd option。
- *
- * 用于 worktree 隔离：传入 worktree 绝对路径，spawn 的 pi 子进程绑定到该目录，
- * 其内部的 createAgentSession/ResourceLoader/bash 工具都在该目录运行。
- * undefined 时 spawn 继承 workflow 进程的 cwd（向后兼容）。
- */
-  cwd?: string;
-  /** Inherit parent session context (fork mode). Independent of worktree (file isolation). */
-  fork?: boolean;
-  /**
-   * 执行引擎 id（P4 D9 三层优先级的第一层：调用参数级，workflow step 显式指定）。
-   * 仅限「必须某引擎独有能力」的场景使用并注释原因（D9③ workflow 脚本不写死
-   * engine——环境差异由 frontmatter/全局默认承载）；透传链 worker-script-builder
-   * agent() → execute-agent-call → SAR 路由层。
-   */
-  engine?: string;
-  /** Filesystem isolation: when true, creates a new git worktree for the agent. Independent of fork. */
-  worktree?: boolean;
-  /** When true, agent() resolves {value, sessionFile, worktreePath, error} instead of a bare value.
-   * Worker-layer flag only — not forwarded to ExecuteOptions (mapToExecuteOptions drops it). */
-  returnMeta?: boolean;
-}
-
-/**
- * 单次 agent 调用的资源用量（FR-7 跨 turn 累积）。
- */
-export interface AgentUsage {
-  input: number;
-  output: number;
-  cacheRead: number;
-  cacheWrite: number;
-  cost: number;
-  contextTokens: number;
-  turns: number;
-}
-
-/**
- * 单次 tool 调用记录（FR-7 从 agent JSONL 流采）。
- */
-export interface ToolCallEntry {
- /** Tool name. */
-  name: string;
- /** Args preview string. */
-  input: string;
-}
-
-/**
- * 单次 agent 调用的结果（统一形态）。
- *
- * Engine 直接消费 SubprocessAgentRunner 返回值；callCache replay 时 worker
- * 取 parsedOutput ?? content（见 worker-script-builder.ts 消息处理）。
- */
-export interface AgentResult {
- /** Raw text output from the agent. */
-  content: string;
- /**
- * Parsed structured output.
- * Present when `schema` was provided and the output was valid JSON.
- * Source: tool_execution_end.result.details（validated data object）。
- */
-  parsedOutput?: unknown;
- /** Token and cost usage accumulated across all assistant turns. */
-  usage?: AgentUsage;
- /** Wall-clock duration in milliseconds. */
-  durationMs?: number;
- /** True when the pi process exited with code 0. */
-  error?: string;
- /**
- * Pi session ID for the subagent process (uuidv7).
- * Present when pi emits a session header (default in --mode json).
- * Can be used to locate the session JSONL file for post-run inspection (G-017)。
- */
-  sessionId?: string;
- /**
- * Session JSONL 绝对路径（不含目录的文件名在 subagents 侧 AgentResult.sessionFile）。
- * 由 mapToWorkflowAgentResult 从 subagents AgentResult 透传——让 workflow 编排层
- * 继承 subagent 执行管道产出的 session 文件路径，overlay/GUI 可直接定位。
- * 窗口期内可能 undefined（session 尚未创建成功）。
- */
-  sessionFile?: string;
- /**
- * Absolute path of the git worktree used for filesystem isolation (set when
- * worktree isolation is active). Injected by executeAndAwait from record.worktreeHandle.path.
- *
- * ⚠️ Diagnostic only, may not exist: executeAndAwait's finalizeRecord cleans up the
- * worktree (git worktree remove --force) before returning, so by the time this field
- * reaches the caller the directory has typically been deleted. Use it only for log/trace
- * correlation (e.g. attributing a session jsonl to its worktree origin) — never as a cwd
- * for a subsequent agent or filesystem operation (would ENOENT).
- */
-  worktreePath?: string;
- /** All tool calls collected from JSONL stream (FR-7). */
-  toolCalls?: ToolCallEntry[];
-}
-
-// ── Trace ─────────────────────────────────────────────────────
-
-/**
- * 执行追踪节点（事件流 D-10 单一来源）。
- */
-export interface ExecutionTraceNode {
-  stepIndex: number;
-  agent: string;
-  task: string;
-  model: string;
-  status: "pending" | "running" | "completed" | "failed";
- /** Phase name for TUI grouping. Set from explicit opts.phase or global _currentPhase. */
-  phase?: string;
-  startedAt?: string;
-  completedAt?: string;
-  result?: AgentResult;
-  error?: string;
- /**
- * Pi session ID (uuidv7) for the subagent process.
- * Used to locate the session JSONL for post-run inspection.
- */
-  sessionId?: string;
- /**
- * Session JSONL 绝对路径。finalizeCall 从 result.sessionFile 透传。
- * 持久化到快照（serializeRun），跨 session 重水合后保留。
- */
-  sessionFile?: string;
- /**
- * Live 执行进度对象（running 时存在，done 时由 dispatchAgentCall 清除）。
- *
- * 挂在 node 上（D-10 单源延伸：AgentCall.traceNode 与 Trace.nodes 共享同一引用）。
- * TUI 通过 trace.toArray() 读 node.live，派生 getEventLog/getCurrentActivity 实时展示。
- * 不持久化（序列化时 strip；重跑时由 dispatchAgentCall 重建）。
- */
-  live?: ExecutionRecord;
-}
-
-/**
- * Trace.update 用的 patch（字段全可选）。
- *
- * 不变式：只改单个 node 的 status/result/error/completedAt/sessionId。
- * callId 不存在时 update 为 no-op（D-10）。
- */
-export interface TracePatch {
-  status?: "pending" | "running" | "completed" | "failed";
-  result?: AgentResult;
-  error?: string;
-  completedAt?: string;
-  sessionId?: string;
-  sessionFile?: string;
-}
-
-// ── Worker 诊断 ───────────────────────────────────────────────
-
-/**
- * Worker console.* 捕获条目（run 级诊断，仅展示在 TUI widget，不泄漏到 input area）。
- */
-export interface WorkerLogEntry {
-  level: "log" | "warn" | "error" | "info";
-  message: string;
-}

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

@@ -1,254 +0,0 @@
-/**
- * Workflow Extension — WorkflowRun
- *
- * 单次 workflow run 的聚合根。封装状态机 + runtime 生命周期 + 不变式守卫。
- * 架构核心——所有字段变更通过方法（transition/assignRuntime/releaseRuntime/
- * replaceRuntime），engine 模块不直接打洞（AC-3）。
- *
- * 层归属：Engine。依赖 RunRuntime（具体类，D-12 允许）+ RunSpec/RunState + 类型。
- *
- * 关键不变式（必须全测）：
- * I1: state.status === "running" ⟺ runtime !== undefined
- * I2: state.status === "done" ⟹ state.reason !== undefined
- *
- * 状态机（一次性生命周期，2 态）：
- * 构造（status="running"，I1 构造期跳过——runtime 由 assignRuntime 注入）
- * running ──transition("done", reason)──→ done (releaseRuntime + completedAt)
- * done ──(no out edges, zombie)
- *
- * 「创建即 running」与 I1 的协调（F4）：构造瞬间 running 而 runtime 尚未注入，
- * I1 在构造期跳过（仅查 I2），完整校验由 assignRuntime/transition/replaceRuntime
- * 末尾的 validateInvariants 维持；构造到 assignRuntime 的 I1 窗口由调用方
- * （lifecycle.runWorkflow 在 assignRuntime 之后才 runs.set）保证对外不可见。
- *
- * worker-error-retry（G5-001 + G6-001）：
- * - replaceRuntime(newRt): 前置 status==="running"（G6-001），原子释放前一个 runtime
- * + 绑定新 runtime，全程保持不变式 I1（中间不经过 runtime===undefined 的可见状态）。
- *
- * 参考：domain-models.md §1（聚合根定义）、clarification.md G3-001/G5-001/G6-001。
- */
-
-import { RunRuntime } from "./run-runtime.ts";
-import type { RunSpec } from "./run-spec.ts";
-import type { RunState } from "./run-state.ts";
-import type { DoneReason, RunStatus } from "./types.ts";
-import { canRunTransition } from "./types.ts";
-
-// ── WorkflowRunMeta ──────────────────────────────────────────
-
-/**
- * 聚合根级 meta（非 RunState 的一部分，不随 trace 持久化到 worker JSONL）。
- *
- * workerErrorCount/scriptErrorCount 跨 runtime 存活（C.5：error-recovery 重试计数载体），
- * 因为 retry 会 replaceRuntime，但计数是 run 级而非 runtime 级。
- */
-export interface WorkflowRunMeta {
- /** ISO 时间戳，run 创建/启动时刻。 */
-  startedAt: string;
- /** ISO 时间戳，transition("done") 时设置。 */
-  completedAt?: string;
- /** Worker 线程错误计数（C.5：跨 runtime 存活，重试计数载体）。 */
-  workerErrorCount?: number;
- /** 脚本错误计数（C.5：跨 runtime 存活）。 */
-  scriptErrorCount?: number;
-}
-
-// ── WorkflowRun ──────────────────────────────────────────────
-
-export class WorkflowRun {
-  readonly runId: string;
-  readonly spec: RunSpec;
-  state: RunState;
-  runtime?: RunRuntime;
-  meta: WorkflowRunMeta;
-
- /**
- * 创建聚合根。初始状态 "running"（一次性生命周期：run 从创建起即在执行，
- * runtime 由紧随其后的 assignRuntime 注入）。也可传入 done 状态用于重水合
- * 已完成的 run（loadAll 后的只读聚合）。
- *
- * 不变式 I1 构造期跳过——「创建即 running」要求构造瞬间 runtime===undefined
- * 合法（runtime 必须由 assignRuntime 注入，构造函数无从持有）；重水合的
- * running 快照同样无 worker。I1 的运行时校验在 assignRuntime/transition/
- * replaceRuntime 末尾的 validateInvariants 处生效。
- */
-  constructor(
-    runId: string,
-    spec: RunSpec,
-    state: RunState,
-    meta: WorkflowRunMeta,
-  ) {
-    this.runId = runId;
-    this.spec = spec;
-    this.state = state;
-    this.meta = meta;
- // runtime 在构造时始终为 undefined——run 创建时无活 worker，loadAll 重水合
- // 时也不恢复 runtime（worker 必须由 lifecycle 重新 start）。
-    this.runtime = undefined;
- // 构造期仅校验 I2（I1 跳过，见方法 doc）；I1 由 assignRuntime 末尾
- // validateInvariants 恢复。
-    this.validateInvariantI2();
-  }
-
- /**
- * 从持久化快照重水合聚合根。与构造函数同语义（构造期跳过 I1——持久化的
- * running 状态没有 worker，进程被杀后 worker 不可能还活着）。保留独立工厂
- * 标注重水合意图；调用方（D-4 kill-9 恢复）负责在 session_start 时把残留
- * running 转 done,failed，恢复 I1。
- *
- * @throws I2 违反（done 快照缺 reason 仍是 bug，不可跳过）
- */
-  static reconstruct(runId: string, spec: RunSpec, state: RunState, meta: WorkflowRunMeta): WorkflowRun {
-    return new WorkflowRun(runId, spec, state, meta);
-  }
-
- // ── 不变式校验 ─────────────────────────────────────────────
-
- /**
- * 校验不变式 I1 + I2。违反抛错（聚合根自我保护，fail-fast）。
- * 在每个 mutation 方法末尾调用（防御式编程 + 测试可断言）。
- */
-  private validateInvariants(): void {
-    this.validateInvariantI2();
- // I1: status==="running" ⟺ runtime!==undefined
-    if (this.state.status === "running" && this.runtime === undefined) {
-      throw new Error(
-        `WorkflowRun invariant I1 violated: status==="running" but runtime is undefined (runId=${this.runId})`,
-      );
-    }
-    if (this.state.status !== "running" && this.runtime !== undefined) {
-      throw new Error(
-        `WorkflowRun invariant I1 violated: status!=="running" but runtime is defined (runId=${this.runId})`,
-      );
-    }
-  }
-
- /**
- * 仅校验不变式 I2（done ⟹ reason）。构造期用——「创建即 running」与重水合的
- * running 快照都无 runtime（I1 构造期跳过），但 I2 必须保证（done 缺 reason 是真 bug）。
- */
-  private validateInvariantI2(): void {
-    if (this.state.status === "done" && this.state.reason === undefined) {
-      throw new Error(
-        `WorkflowRun invariant I2 violated: status==="done" but reason is undefined (runId=${this.runId})`,
-      );
-    }
-  }
-
- // ── 状态机转换 ─────────────────────────────────────────────
-
- /**
- * 状态机转换。合法转换：running→done。
- *
- * running 的进入不走 transition——构造即 running，replaceRuntime 保持 running。
- * 调用 transition("running") 抛错，防止绕过 runtime 注入直接改状态。
- *
- * 副作用：
- * - →done: releaseRuntime + 设 state.reason + meta.completedAt
- *
- * @param target 目标状态（不允许 "running"——runtime 注入只走 assignRuntime/replaceRuntime）
- * @param reason →done 时必填（done ⟹ reason，不变式 I2）
- * @throws 非法转换 / done 缺 reason / target==="running"
- */
-  transition(target: RunStatus, reason?: DoneReason): void {
- // "running" 必须经 assignRuntime（需 runtime 参数，transition 无法提供）
-    if (target === "running") {
-      throw new Error(
-        `WorkflowRun.transition: cannot transition to "running" directly — use assignRuntime() (runId=${this.runId})`,
-      );
-    }
-
-    if (!canRunTransition(this.state.status, target)) {
-      throw new Error(
-        `WorkflowRun.transition: illegal transition ${this.state.status} → ${target} (runId=${this.runId})`,
-      );
-    }
-
- // →done 需 reason（不变式 I2）
-    if (target === "done" && reason === undefined) {
-      throw new Error(
-        `WorkflowRun.transition: transition to "done" requires a reason (runId=${this.runId})`,
-      );
-    }
-
- // 副作用：先清理 runtime（releaseRuntime 守不变式 I1），再改 status
- // （canRunTransition 已排除 target==="running"，此处 target 恒为 "done"）
-    this.releaseRuntime();
-    this.state.status = target;
-    this.state.reason = reason;
-    this.meta.completedAt = new Date().toISOString();
-
-    this.validateInvariants();
-  }
-
- // ── Runtime 生命周期 ───────────────────────────────────────
-
- /**
- * 绑定 runtime（run 创建后注入执行资源）。
- *
- * 前置：status==="running" && runtime===undefined（runWorkflow 创建路径——
- * 构造即 running 但 runtime 延迟到此处注入）。
- * 原子地：设 runtime 后末尾 validateInvariants，恢复构造期跳过的 I1
- * （running ⟺ runtime!==undefined）。
- *
- * @throws runtime 已定义 / status 不是 "running"（done 僵尸不可复活）
- */
-  assignRuntime(rt: RunRuntime): void {
-    if (this.runtime !== undefined) {
-      throw new Error(
-        `WorkflowRun.assignRuntime: runtime already defined (runId=${this.runId})`,
-      );
-    }
-    if (this.state.status !== "running") {
-      throw new Error(
-        `WorkflowRun.assignRuntime: requires status==="running" (current: ${this.state.status}, runId=${this.runId})`,
-      );
-    }
- // 原子绑定：构造期 I1 处于跳过窗口（running 而 runtime undefined），设 runtime
- // 后末尾 validateInvariants 恢复 I1。调用方在 assignRuntime 后才对外注册
- // （lifecycle.runWorkflow 的 runs.set 后移），窗口外部不可见。
-    this.runtime = rt;
-    this.validateInvariants();
-  }
-
- /**
- * 解绑 runtime（done 时由 transition 调用，也可独立调用）。
- *
- * 前置：无（runtime===undefined 时 no-op，幂等）。
- * 副作用：调 runtime.release("terminal") 释放 worker/controller，置 runtime=undefined。
- */
-  releaseRuntime(): void {
-    if (this.runtime === undefined) return;
-    this.runtime.release("terminal");
-    this.runtime = undefined;
- // 不改 status——调用方（transition）负责。独立调用时调用方需自行确保
- // status 一致（如 worker-error-retry 用 replaceRuntime 而非 release+assign）。
-  }
-
- /**
- * 原地替换 runtime（G5-001：worker-error-retry）。
- *
- * 前置：status==="running"（G6-001：终态 run 拒绝重建）。
- * 原子地：释放旧 runtime（worker.terminate + abort）+ 绑定新 runtime，
- * 全程 status 保持 "running"，不变式 I1 不违反（中间无 runtime===undefined 可见态）。
- *
- * 与 release+assign 的区别：replaceRuntime 不改 status，中间同步完成，
- * 外部观察不到违反不变式的瞬间。
- *
- * @throws status!=="running"
- */
-  replaceRuntime(rt: RunRuntime): void {
-    if (this.state.status !== "running") {
-      throw new Error(
-        `WorkflowRun.replaceRuntime: requires status==="running" (current: ${this.state.status}, runId=${this.runId})`,
-      );
-    }
- // 原子替换：旧 runtime 释放（terminate+abort），新 runtime 绑定。
- // status 保持 "running"，runtime 全程 !== undefined，I1 不违反。
-    if (this.runtime !== undefined) {
-      this.runtime.release("terminal");
-    }
-    this.runtime = rt;
-    this.validateInvariants();
-  }
-}

package/src/orchestration/models/workflow-script-registry.ts

@@ -1,35 +0,0 @@
-/**
- * Workflow Extension — WorkflowScriptRegistry 仓库接口
- *
- * workflow 脚本的仓库（repository）接口——Engine 定义、Infra 实现。
- *
- * 与 Ports 节的 3 个注入 port（AgentRunner/RunStore/WorkerHost）的区别：
- * - 3 个 port 是"执行依赖"（子进程/文件系统/线程），注入到 LifecycleDeps
- * - WorkflowScriptRegistry 是"发现依赖"（扫描文件系统），是 repository（§8），
- * 不进 LifecycleDeps，由 Interface 层 tool 直接调用（list/get 脚本）
- *
- * 优先级：tmp > project > user（domain-models.md §8）。60s TTL，按 workspaceRoot 分桶。
- * 实现在 Infra 层 WorkflowScriptRegistryImpl（扫描 + 缓存 + 去重）。
- *
- * 层归属：Engine（interface），Infra（impl）。
- *
- * 参考：domain-models.md §8。
- */
-import type { WorkflowScript } from "./workflow-script.ts";
-
-/**
- * workflow 脚本仓库接口（repository，需 mock 文件扫描）。
- */
-export interface WorkflowScriptRegistry {
- /** 扫描并返回所有 workflow 脚本（含 available=false 的解析失败项）。去重按 tmp>project>user。 */
-  loadAll(): Promise<WorkflowScript[]>;
-
- /** 按名查单个脚本（含缓存）。返回 undefined 当 name 不存在。 */
-  get(name: string): Promise<WorkflowScript | undefined>;
-
- /** 按绝对路径加载单个脚本（workflowRef 统一解析入口——S2 路径统一）。 */
-  getPath(ref: string): Promise<WorkflowScript | undefined>;
-
- /** 失效缓存——下次 loadAll/get 重新扫描文件系统。 */
-  invalidate(): void;
-}