@zhushanwen/subagent-core 0.2.0

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

@@ -0,0 +1,104 @@
+/**
+ * Workflow Extension — Run Runtime
+ *
+ * 聚合内运行时资源（仅 status==="running" 时存在）。技术资源聚合，
+ * Engine 层类型，持 WorkerHandle 具体类（D-12 不造 interface）。
+ *
+ * 职责：封装一次 running-segment 的所有技术资源（worker 线程 +
+ * abort controller），统一 release 入口（AC-2：单 release 替代多 boolean flag）。
+ * （旧并发门闩 gate 抽象已删——no-op，实际并发由 SubagentService ConcurrencyPool 管理；
+ * 原 withSlot 的 pre-abort 检查内联到 error-recovery dispatchAgentCall。）
+ *
+ * 一次性生命周期（G3-001）：runtime 释放后不再复用——AbortController 一次性
+ * 语义决定 controller 无法跨释放复用，所以整个 RunRuntime 重建。唯一注入路径：
+ * assignRuntime（runWorkflow 创建）与 replaceRuntime（error-recovery 崩溃重试）。
+ *
+ * 参考：domain-models.md §10、clarification.md G3-001。
+ */
+
+import { WorkerHandle } from "../worker-handle.ts";
+
+/**
+ * release mode 枚举——调用方表达意图。
+ *
+ * 一次性生命周期后唯一语义：terminal（终局释放，worker + controller 全释放，
+ * runtime 即被调用方丢弃）。原 "pause" 值已随 pause/resume 生命周期删除（F8）
+ * ——release 后不存在「保留待恢复」的中间形态。
+ */
+export type ReleaseMode = "terminal";
+
+// ── RunRuntime ───────────────────────────────────────────────
+
+export class RunRuntime {
+ /** Worker 线程句柄。 */
+  readonly worker: WorkerHandle;
+ /** per-running-segment AbortController（一次性，无法复用——G3-001）。 */
+  readonly controller: AbortController;
+ /** Run 级墙钟时间预算计时器（spec.budgetTimeMs > 0 时由 lifecycle 调度，
+   * 到期 abortRun time_limited）。release 时清理，避免 abort/replaceRuntime
+   * 后孤儿计时器仍触发（rebuildRuntime 会重排一个全新的计时器，旧的不应残留）。 */
+  readonly timeBudgetTimer?: ReturnType<typeof setTimeout>;
+ /**
+ * 本 runtime 代际是否已收到 worker 的终态消息（return / error）。
+ *
+ * [F1] worker exit(0) 且本标记为 false = worker 静默退出、未交付任何终态——最常见根因
+ * 是 execute() 返回值不可克隆，worker 侧 _safePost 吞掉 DataCloneError 后 return 消息
+ * 根本没发出。旧实现 handleWorkerExit 对 code===0 no-op → run 永久 running、runAndWait
+ * 悬挂。handleWorkerExit 据此判定转 done,failed。
+ *
+ * 按代际归零：字段挂在 RunRuntime（每代际 new 一个实例）而非 run.meta——script-error
+ * 重试退避窗口内（error 消息已收到、run 仍 running、旧 worker exit(0)）必须 no-op 等
+ * rebuild；若挂 meta 则 rebuild 后新 worker 再静默退出时会被旧标记误放行，重新悬挂。
+ *
+ * 写点：① handleWorkerMessage 的 return/error 分支（WorkerHandle.isCurrent 守卫保证
+ * 消息必来自当前代际）；② handleWorkerError 进入处理前（[R4-F1] 同代际幂等守卫——
+ * worker 崩溃时 error + exit(1) 双事件各派发一次 handleWorkerError，第一个事件标记
+ * 本代际已处理，第二个事件命中标志跳过，消除单次崩溃计数 +2 / 双 rebuild 交错）。
+ * rebuildRuntime 构造新 RunRuntime 自然重置。
+ */
+  receivedTerminalMessage = false;
+ /** 防止 release 重复执行（幂等）。 */
+  private released = false;
+
+  constructor(
+    worker: WorkerHandle,
+    controller: AbortController,
+    timeBudgetTimer?: ReturnType<typeof setTimeout>,
+  ) {
+    this.worker = worker;
+    this.controller = controller;
+    this.timeBudgetTimer = timeBudgetTimer;
+  }
+
+ /**
+ * 释放所有资源：terminate worker + abort controller。
+ *
+ * 幂等——重复调用安全（第二次起 no-op，released flag 守卫）。
+ * 调用后此 RunRuntime 应被调用方丢弃（WorkflowRun.runtime = undefined），
+ * 崩溃重试时由 replaceRuntime 注入新实例（G3-001）。
+ *
+ * worker.terminate 本身幂等，controller.abort 本身幂等
+ * （重复 abort 无副作用），但 released flag 让本方法语义更明确：
+ * 「释放过一次的 runtime 不再释放第二次」。
+ *
+ * @param mode terminal —— 终局释放（唯一值，保留参数为调用方语义显式化）
+ */
+  release(_mode: ReleaseMode): void {
+    if (this.released) return;
+    this.released = true;
+ // 清理 run 级时间预算计时器——abort/terminate/replaceRuntime 后它不应再触发
+ // （rebuildRuntime 会重排全新计时器；孤儿触发会把已终态的 run 误转 done）。
+    if (this.timeBudgetTimer) clearTimeout(this.timeBudgetTimer);
+ // worker.terminate 异步但幂等——不 await（release 是同步签名，调用方
+ // 不应被底层线程关闭阻塞；worker 收到 terminate 后自行清理）。
+    void this.worker.terminate();
+ // controller.abort 触发 listener（kill agent subprocess、中止在飞调用）。
+ // 一次性语义——已 aborted 的 controller 重复 abort 无副作用。
+    this.controller.abort();
+  }
+
+ /** 是否已 release（测试 + 诊断用）。 */
+  get isReleased(): boolean {
+    return this.released;
+  }
+}

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

@@ -0,0 +1,83 @@
+/**
+ * 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），崩溃恢复重水合后
+ * 需要 scriptSource/args 重建 worker（G3-001）。
+ */
+export interface RunSpec {
+ /** 已 strip export 的可执行源（WorkflowScript.toExecutable 产物）。 */
+  readonly scriptSource: string;
+ /**
+ * 参数契约（JSON Schema draft-07，来自 script.meta.parameters 整对象透传，m3 DM2）。
+ *
+ * undefined = 不校验（安全退化——漏拷 parameters 退化是「不校验」非「校验错」）。
+ * 由调用方（actionRun/runAndWait/executeNestedWorkflow）从 script.meta.parameters 拷贝。
+ * lifecycle.runWorkflow 首行经 validateRunArgs 校验 spec.args（coerceTypes 原地规范化
+ * args 对象内容，字段引用不变；worker 启动与崩溃重建共用同一对象）。
+ */
+  readonly parameters?: Record<string, unknown>;
+  /** 调用方传入的参数（worker 内通过 $ARGS 访问）。 */
+  readonly args: Record<string, unknown>;
+ /**
+ * Run 级 model override（Option B：经 workerData → worker global $MODEL → agent() fallback）。
+ *
+ * undefined = 继承主 agent 模型（零配置默认）。设置时该 run 内所有 agent() 调用默认继承
+ * （除非 per-call 显式指定 model）。注意：不 merge 进 args（对称单路径注入），
+ * 而是经 worker-script-builder 注入为 $MODEL worker global。
+ */
+  readonly model?: string;
+ /**
+ * Run 级 thinkingLevel override（Option B：经 workerData → worker global $THINKING_LEVEL）。
+ *
+ * undefined = 继承主 agent thinkingLevel。取值范围由 THINKING_ORDER SSOT 派生（含 max）。
+ */
+  readonly thinkingLevel?: string;
+ /** 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;
+ /**
+ * Run 级简短标签（≤20 字符），区别于 scriptName（脚本身份名）。
+ * 区分同脚本的不同 run 实例（如 'migrate-users-batch1' vs 'migrate-users-batch2'）。
+ * 旧持久化 run 缺失时为 undefined，渲染时回落 scriptName。
+ */
+  readonly slug?: 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）。
+ * 跨进程重启时 RunState 从 JSONL 重水合（callCache 保留，worker 由崩溃恢复重建）。
+ */
+export interface RunState {
+ /** 当前状态（running/done）。 */
+  status: RunStatus;
+ /** 终态原因（done 时必有）。 */
+  reason?: DoneReason;
+ /** Token/cost 预算（含 usedTokens/usedCost 累积）。 */
+  budget: Budget;
+ /** 按 callId 索引的 agent 调用集合（含 result，跨 runtime 重建存活——callCache replay）。 */
+  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,183 @@
+/**
+ * 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 { AgentResult, ExecutionTraceNode, TracePatch } from "./types.ts";
+
+// ── result.content 裁剪 ────────────────────────────────────────
+
+/**
+ * trace 节点 result.content 裁剪上限（严格大于才裁）。
+ *
+ * export 供测试边界构造（对齐 budget.ts export 常量先例）。
+ * 只裁 trace 节点侧——AgentCall.result 不裁（markDone 存全量在前，
+ * worker cached replay 数据源保真）。
+ */
+export const TRACE_RESULT_MAX_CHARS = 8000;
+
+/**
+ * 裁剪保留的头/尾长度（各半）。
+ *
+ * 耦合声明：TRIM_HEAD_CHARS + TRIM_TAIL_CHARS === TRACE_RESULT_MAX_CHARS
+ * （各半相等）是 doc 示例「8001 → 裁后 8000+标记 ≈ 8057」的前提
+ * （rt-w1-design.json W1C2 / trimTraceResult 注释同款表述）——改 MAX 时
+ * 需同步检查 head/tail 是否仍各半，及上述注释/文档示例数字。
+ * 比例钉死在 trace.test.ts 断言中；变更需复查 detail-content.ts
+ * 尾 5 行消费点（TUI 尾部预览依赖 tail 段）。
+ */
+const TRIM_HEAD_CHARS = 4000;
+const TRIM_TAIL_CHARS = 4000;
+
+/**
+ * 裁剪 trace result 的 content（Trace 私有纯函数）。
+ *
+ * - undefined 透传；未超限原引用透传（零拷贝，不超限路径行为与无裁剪时一致）。
+ * - 超限返回新对象：head + 含原始长度的标记 + tail（只裁 content，
+ *   result 其他字段浅拷贝保留）。节点持裁剪副本，与传入对象脱钩。
+ * - 边界附近（如 8001 字符）裁后总长 8000 + 标记长度 > 原始长度属
+ *   既定语义（head/tail 固定比例下净增长有界），禁止自行缩短 head/tail。
+ */
+function trimTraceResult(result: AgentResult | undefined): AgentResult | undefined {
+  if (result === undefined) return result;
+  const { content } = result;
+  if (content.length <= TRACE_RESULT_MAX_CHARS) return result;
+  const trimmed =
+    content.slice(0, TRIM_HEAD_CHARS) +
+    `\n…[trace result truncated, original ${content.length} chars]…\n` +
+    content.slice(-TRIM_TAIL_CHARS);
+  return { ...result, content: trimmed };
+}
+
+/**
+ * Trace 值对象（事件流，唯一来源 D-10）。
+ *
+ * 不变式：
+ * - nodes 只增不改索引顺序（append-only）
+ * - update 只改单个 node 的 status/result/error/completedAt/sessionId
+ * - byIndex 与 nodes 恒一致（每个 append/remove 同步维护，无惰性重建）；
+ *   Map 值与数组元素引用共享（非拷贝），nodes 仍是持久化与 TUI 投影 SSOT
+ * - 不含 verifyStrategy（G-020 删除，不迁移）
+ */
+export class Trace {
+  private readonly nodes: ExecutionTraceNode[] = [];
+  /** stepIndex 倒排索引（查询加速 O(1)；值与 nodes 元素引用共享）。 */
+  private readonly byIndex = new Map<number, ExecutionTraceNode>();
+
+ /**
+ * 从已有节点数组重建 Trace（用于 RunStore 反序列化重水合）。
+ *
+ * 防御性拷贝——传入数组不被持有，外部 mutation 不影响 Trace。
+ * 不验证节点顺序/唯一性（调用方保证快照来源可信）。
+ * 不做裁剪——落盘快照已是 write 路径裁剪后形态，旧版本未裁剪长
+ * content 重水合保持原样（read 路径无二次信息损失）。
+ * 重水合后 call.traceNode（来自快照 calls[].traceNode，
+ * jsonl-run-store.ts:156 直接传入）与 Trace.nodes 副本非同引用——
+ * D-10 引用共享仅 live append 路径成立。
+ */
+  static fromArray(nodes: readonly ExecutionTraceNode[]): Trace {
+    const trace = new Trace();
+    for (const node of nodes) {
+      const copy = { ...node };
+      trace.nodes.push(copy);
+      trace.byIndex.set(copy.stepIndex, copy); // 重复 stepIndex last-wins
+    }
+    return trace;
+  }
+
+ /**
+ * Append a trace node（append-only，不改已有节点）。
+ *
+ * 入口裁剪：超长 result.content 先 mutate 入参节点的 result 字段，
+ * 再 push 原节点引用（禁止 push 副本——保持 AgentCall.traceNode 与
+ * Trace.nodes 共享同一引用的 D-10 不变式）。
+ */
+  append(node: ExecutionTraceNode): void {
+    node.result = trimTraceResult(node.result);
+    this.nodes.push(node);
+    this.byIndex.set(node.stepIndex, 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;
+    // 入口裁剪：节点持裁剪副本，与 patch.result 脱钩为两个对象
+    // （call.result 保留全量——replay 数据源保真）。patch.result 未提供不动。
+    if (patch.result !== undefined) node.result = trimTraceResult(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;
+    if (patch.sessionFile !== undefined) node.sessionFile = patch.sessionFile;
+  }
+
+ /**
+ * 查找指定 stepIndex 的节点（byIndex O(1)，trace 中 stepIndex 应唯一）。
+ *
+ * 语义差异声明（旧线性扫 first-match → Map last-wins）：仅在破坏
+ * stepIndex 唯一性的违规使用下可见，两组场景——
+ * 1. 重复 append 同 stepIndex 且未 remove：返回最后一个节点（last-wins；
+ *    旧线性扫 first-match 会返回第一个）。
+ * 2. 重复 append 后 removeByStepIndex：remove 的 findIndex 命中首个旧节点
+ *    splice，而 byIndex.delete 把整个 stepIndex 键删掉——nodes 残留第二个
+ *    节点成为孤儿（find/update 不可达，length/toArray 仍可见）。
+ * 合法路径无差异：唯一性由 discard 先 remove 再 append 保证（W1TC12 锚定）。
+ */
+  private findByStepIndex(stepIndex: number): ExecutionTraceNode | undefined {
+    return this.byIndex.get(stepIndex);
+  }
+
+ /** 按节点引用删除（仅用于测试或 run 重建场景；正常运行不调用）。 */
+  find(stepIndex: number): ExecutionTraceNode | undefined {
+    return this.findByStepIndex(stepIndex);
+  }
+
+ /**
+ * 按 stepIndex 移除节点（崩溃重建清理在飞 call 用）。
+ *
+ * 正常运行不调用（append-only 不变式）。仅 error-recovery 的 discardInFlightCalls
+ * （rebuildRuntime 内，F2）清理被旧 runtime abort 的在飞 call 时用——移除其 trace
+ * 节点，让重跑重发 agent-call 时 append 全新节点走全新执行路径（避免 stale
+ * "running" 节点残留 + trace.update 命中旧节点导致新节点 orphan）。
+ * stepIndex 不存在时 no-op（防御性）。
+ */
+  removeByStepIndex(stepIndex: number): void {
+    // 先 findIndex 判存在再删，避免 byIndex 与 nodes 漂移
+    const idx = this.nodes.findIndex((n) => n.stepIndex === stepIndex);
+    if (idx === -1) return;
+    this.nodes.splice(idx, 1);
+    this.byIndex.delete(stepIndex);
+  }
+
+ /**
+ * readonly 视图——返回内部 nodes 数组引用（仅类型级 readonly，运行时无
+ * 防御）。消费方禁止结构化 mutate（push/splice/重排/覆盖元素）：byIndex
+ * 引入后外部结构化 mutate 会使 nodes 与倒排索引 desync。字段级变更走 update()。
+ */
+  toArray(): readonly ExecutionTraceNode[] {
+    return this.nodes;
+  }
+
+ /** 当前节点数。 */
+  get length(): number {
+    return this.nodes.length;
+  }
+}