@zhushanwen/pi-subagent-workflow 0.1.0

package/src/orchestration/models/types.ts

@@ -0,0 +1,242 @@
+/**
+ * Workflow Extension — Engine 共享类型
+ *
+ * Engine 层全局基础类型。零 infra 依赖——不 import 任何 infra 文件，
+ * 可独立编译测试（D-12 三层架构，AC-1）。
+ *
+ * 核心内容：
+ * - 状态机：RunStatus = "running" | "paused" | "done"（3 态，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";
+
+// ── 状态机 ────────────────────────────────────────────────────
+
+/**
+ * 状态机：3 态（D-12 / FR-3）。
+ *
+ * running ↔ paused → done
+ *
+ * `done` 是唯一终态，具体原因由 DoneReason 区分。
+ */
+export type RunStatus = "running" | "paused" | "done";
+
+/** 终态原因。done 时必有（WorkflowRun 不变式）。 */
+export type DoneReason =
+  | "completed"
+  | "failed"
+  | "aborted"
+  | "budget_limited"
+  | "time_limited";
+
+/** 合法的状态转换。空数组 = 无出边（done 终态）。 */
+export const VALID_RUN_TRANSITIONS: Record<RunStatus, readonly RunStatus[]> = {
+  running: ["paused", "done"] as const,
+  paused: ["running", "done"] as const,
+  done: [] as const,
+};
+
+export const ALL_RUN_STATUSES: readonly RunStatus[] = ["running", "paused", "done"] as const;
+
+export const ALL_DONE_REASONS: readonly DoneReason[] = [
+  "completed",
+  "failed",
+  "aborted",
+  "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;
+ /** Scene name for model-switch advisor recommendation. */
+  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 name to resolve from AgentRegistry. When set, the resolved
+ * agent's systemPrompt is injected via --append-system-prompt.
+ */
+  agent?: string;
+ /**
+ * Absolute paths to temp files containing system prompt injections.
+ * Set by agent-opts-resolver: agent systemPrompt + schema injection files.
+ * buildArgs injects each via --append-system-prompt.
+ */
+  systemPromptFiles?: 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;
+}
+
+/**
+ * 单次 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;
+ /** 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;
+ /**
+ * Live 执行进度对象（running 时存在，done 时由 dispatchAgentCall 清除）。
+ *
+ * 挂在 node 上（D-10 单源延伸：AgentCall.traceNode 与 Trace.nodes 共享同一引用）。
+ * TUI 通过 trace.toArray() 读 node.live，派生 getEventLog/getCurrentActivity 实时展示。
+ * 不持久化（pause/resume 时为 undefined，重跑时重建）。
+ */
+  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;
+}
+
+// ── 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

@@ -0,0 +1,275 @@
+/**
+ * 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
+ *
+ * 状态机（FR-3，3 态）：
+ * paused ──assignRuntime──→ running
+ * running ──transition("paused")──→ paused (releaseRuntime, G3-001)
+ * running ──transition("done", reason)──→ done (releaseRuntime + completedAt)
+ * paused ──transition("done", reason)──→ done (completedAt)
+ * done ──(no out edges, zombie)
+ *
+ * pause/resume 生命周期（G3-001）：
+ * - transition("paused") 调 releaseRuntime，整个 RunRuntime 被丢弃
+ * （runtime=undefined）。AbortController 一次性无法复用。
+ * - resume 走 assignRuntime(new RunRuntime(...))，重建 worker/gate/controller。
+ *
+ * retryNode / worker-error-retry（G5-001 + G6-001）：
+ * - replaceRuntime(newRt): 前置 status==="running"（G6-001），原子释放前一个 runtime
+ * + 绑定新 runtime，全程保持不变式 I1（中间不经过 runtime===undefined 的可见状态）。
+ * - paused 状态下 retry 被拒（要 retry 先 resume）。
+ *
+ * 参考：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;
+ /** ISO 时间戳，transition("paused") 时设置（最近一次 pause）。 */
+  pausedAt?: 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;
+
+ /**
+ * 创建聚合根。初始状态通常为 "paused"（runtime=undefined，符合不变式 I1），
+ * 随后 assignRuntime 进入 "running"。也可传入 done 状态用于 reconstruct
+ * 已完成的 run（loadAll 后的只读聚合）。
+ *
+ * 不变式 I1 由构造函数校验——**不可用于 reconstruct 持久化的 running 快照**
+ *（持久化的 running run 没有 worker，违反 I1；进程被杀后 worker 不可能还活着）。
+ * 重水合用 `WorkflowRun.reconstruct`，它跳过 I1 校验（快照是可信状态）。
+ *
+ * @param reconstructMode 内部用——true 时跳过 I1 校验（仅校验 I2）。
+ * 调用方用 `WorkflowRun.reconstruct` 静态工厂，不直接传此 flag。
+ */
+  constructor(
+    runId: string,
+    spec: RunSpec,
+    state: RunState,
+    meta: WorkflowRunMeta,
+    reconstructMode = false,
+  ) {
+    this.runId = runId;
+    this.spec = spec;
+    this.state = state;
+    this.meta = meta;
+ // runtime 在构造时始终为 undefined——run 创建时无活 worker，resume/loadAll
+ // 时也不重水合 runtime（worker 必须由 lifecycle 重新 start）。
+    this.runtime = undefined;
+    if (reconstructMode) {
+ // 重水合：仅校验 I2（done ⟹ reason）。I1 跳过——持久化的 running 状态没有
+ // worker，违反 I1；调用方（D-4 kill-9 恢复）负责恢复 I1。
+      this.validateInvariantI2();
+    } else {
+      this.validateInvariants();
+    }
+  }
+
+ /**
+ * 从持久化快照重水合聚合根。跳过 I1 校验——持久化的 running 状态没有 worker
+ * （进程被杀后 worker 不可能还活着），违反 I1。调用方（D-4 kill-9 恢复）负责
+ * 在 session_start 时把残留 running 转 done,failed，恢复 I1。
+ *
+ * 与 `new WorkflowRun(...)` 的区别：constructor 校验 I1（适合 live 创建），
+ * reconstruct 跳过（适合可信快照重水合）。
+ *
+ * @throws I2 违反（done 快照缺 reason 仍是 bug，不可跳过）
+ */
+  static reconstruct(runId: string, spec: RunSpec, state: RunState, meta: WorkflowRunMeta): WorkflowRun {
+    return new WorkflowRun(runId, spec, state, meta, true);
+  }
+
+ // ── 不变式校验 ─────────────────────────────────────────────
+
+ /**
+ * 校验不变式 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）。reconstruct 时用——持久化的 running 快照
+ * 违反 I1（无 worker），但 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→{paused,done}, paused→done。
+ *
+ * paused→running 不走 transition——用 assignRuntime（需注入 runtime）。
+ * 调用 transition("running") 抛错，引导调用方用 assignRuntime。
+ *
+ * 副作用：
+ * - →paused: releaseRuntime（G3-001 丢弃 runtime）+ 设 meta.pausedAt
+ * - →done: releaseRuntime + 设 state.reason + meta.completedAt
+ *
+ * @param target 目标状态（不允许 "running"——用 assignRuntime）
+ * @param reason →done 时必填（done ⟹ reason，不变式 I2）；→paused 时忽略
+ * @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
+    if (target === "paused" || target === "done") {
+      this.releaseRuntime();
+    }
+
+    this.state.status = target;
+    if (target === "paused") {
+      this.meta.pausedAt = new Date().toISOString();
+    }
+    if (target === "done") {
+      this.state.reason = reason;
+      this.meta.completedAt = new Date().toISOString();
+    }
+
+    this.validateInvariants();
+  }
+
+ // ── Runtime 生命周期 ───────────────────────────────────────
+
+ /**
+ * 绑定 runtime 并进入 running 状态。
+ *
+ * 前置：status==="paused" && runtime===undefined（首次启动或 resume）。
+ * 原子地：设 runtime + status="running"，保持不变式 I1 全程不违反。
+ *
+ * @throws runtime 已定义 / status 不是 "paused"
+ */
+  assignRuntime(rt: RunRuntime): void {
+    if (this.runtime !== undefined) {
+      throw new Error(
+        `WorkflowRun.assignRuntime: runtime already defined (runId=${this.runId})`,
+      );
+    }
+    if (this.state.status !== "paused") {
+      throw new Error(
+        `WorkflowRun.assignRuntime: requires status==="paused" (current: ${this.state.status}, runId=${this.runId})`,
+      );
+    }
+ // 原子绑定：先设 runtime（I1 暂时违反：status!=="running" 但 runtime!==undefined），
+ // 紧接着设 status="running"，末尾 validateInvariants 通过。
+ // 两条赋值间无 await/外部观察点，外部不可见中间状态。
+    this.runtime = rt;
+    this.state.status = "running";
+    this.validateInvariants();
+  }
+
+ /**
+ * 解绑 runtime（pause/done 时由 transition 调用，也可独立调用）。
+ *
+ * 前置：无（runtime===undefined 时 no-op，幂等）。
+ * 副作用：调 runtime.release("pause") 释放 worker/controller，置 runtime=undefined。
+ */
+  releaseRuntime(): void {
+    if (this.runtime === undefined) return;
+    this.runtime.release("pause");
+    this.runtime = undefined;
+ // 不改 status——调用方（transition）负责。独立调用时调用方需自行确保
+ // status 一致（如 retryNode 用 replaceRuntime 而非 release+assign）。
+  }
+
+ /**
+ * 原地替换 runtime（G5-001：retryNode / worker-error-retry）。
+ *
+ * 前置：status==="running"（G6-001：paused 下拒绝，要 retry 先 resume）。
+ * 原子地：释放旧 runtime（worker.terminate + abort）+ 绑定新 runtime，
+ * 全程 status 保持 "running"，不变式 I1 不违反（中间无 runtime===undefined 可见态）。
+ *
+ * 与 release+assign 的区别：replaceRuntime 不改 status（避免经过 paused 中间态），
+ * 中间同步完成，外部观察不到违反不变式的瞬间。
+ *
+ * @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

@@ -0,0 +1,32 @@
+/**
+ * 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>;
+
+ /** 失效缓存——下次 loadAll/get 重新扫描文件系统。 */
+  invalidate(): void;
+}

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

@@ -0,0 +1,90 @@
+/**
+ * Workflow Extension — WorkflowScript 实体
+ *
+ * 一个 workflow 脚本文件的数据 + 操作收敛（domain-models.md §7）。
+ *
+ * 设计：
+ * - 将"脚本源 + meta + validate + toExecutable"收敛为实体。
+ * - validate 委托 engine/script-lint.ts 的 lintScript。
+ * - toExecutable 只做 strip `export const meta`（纯文本变换）；worker 线程 wrap
+ * （注入 agent/parallel/pipeline globals）由 infra/worker-script-builder.ts
+ * 的 buildWorkerScript 承担——那是技术资源模板生成，不属于实体职责（D-12：
+ * 模型只管数据+不变式）。
+ *
+ * 层归属：Engine。
+ *
+ * 参考：domain-models.md §7（字段/操作）、engine/script-lint.ts（lint 实现）。
+ */
+import { type LintResult,lintScript } from "../script-lint.ts";
+// LintFinding/LintResult 类型规范归属 engine/script-lint.ts（canonical 源）。
+
+/** 脚本来源：saved（.pi/workflows/ 固定）或 tmp（.pi/workflows/.tmp/ 临时）。 */
+export type WorkflowSource = "saved" | "tmp";
+
+/** 脚本元信息（regex 提取，不执行用户代码）。 */
+export interface WorkflowMeta {
+  name: string;
+  description: string;
+  phases: (string | { title: string; detail?: string })[];
+}
+
+/** strip `export const meta` → `const meta`（lifecycle.ts:66 逻辑迁移）。 */
+const EXPORT_META_PATTERN = /\bexport\s+const\s+meta\b/g;
+
+/**
+ * WorkflowScript 实体。
+ *
+ * 不变式：
+ * - name 非空（meta 提取成功时来自 meta.name，失败时来自文件名 stem）
+ * - available=false 时 meta 为空壳（name=stem, description="", phases=[]）
+ * - sourceCode 为原始文件内容（含 export）；toExecutable 返回 strip 后的副本
+ */
+export class WorkflowScript {
+  readonly name: string;
+  readonly source: WorkflowSource;
+  readonly path: string;
+ /** 原始文件内容（可编辑）。toExecutable 返回 strip 后的副本，不改本字段。 */
+  sourceCode: string;
+  readonly meta: WorkflowMeta;
+ /** false 当 meta 提取失败（loader 不抛错，标记不可用但仍列出）。 */
+  available: boolean;
+
+  constructor(opts: {
+    name: string;
+    source: WorkflowSource;
+    path: string;
+    sourceCode: string;
+    meta: WorkflowMeta;
+    available: boolean;
+  }) {
+    this.name = opts.name;
+    this.source = opts.source;
+    this.path = opts.path;
+    this.sourceCode = opts.sourceCode;
+    this.meta = opts.meta;
+    this.available = opts.available;
+  }
+
+ /**
+ * 静态检查脚本合法性。
+ *
+ * 委托 engine/script-lint.ts 的 lintScript——检查项含：
+ * - 必须含 agent/parallel/pipeline 入口之一
+ * - agent 选项 outputSchema → schema
+ * - result.output/parsedOutput/content 不存在
+ * - 文件传状态警告
+ */
+  validate(): LintResult {
+    return lintScript(this.sourceCode);
+  }
+
+ /**
+ * 返回可执行源（strip `export const meta` → `const meta`）。
+ *
+ * 脚本格式不变（AC-4）。Worker 线程 wrap（注入 globals）由 infra
+ * infra/worker-script-builder.ts buildWorkerScript 完成——本方法只做纯文本变换。
+ */
+  toExecutable(): string {
+    return this.sourceCode.replace(EXPORT_META_PATTERN, "const meta");
+  }
+}