@zhushanwen/pi-subagent-workflow 8.6.0 → 8.8.0

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

@@ -1,256 +0,0 @@
-/**
- * Workflow Extension — executeAgentCall（关键路径）
- *
- * 单次 agent 调用执行的 Engine free function（D-12）。显式 5 参数
- * `(call, runner, budget, signal, trace)`，无依赖注入 bag（AC-2：消除散落的
- * Context factory）。
- *
- * 职责：
- * - 重试：3 次 + 指数退避（BACKOFF_MS = [1000, 2000, 4000]）
- * - 预算：超限不重试（直接 markDone failed）
- * - stale-context：不重试（直接 markDone failed）
- * - [MF-1] 确定性 schema 失败：不重试（直接 markDone failed）
- * - 成功：consume usage + incrementCallCount + markDone + trace.update(completed)
- *
- * 关键设计：
- * - **usage 透传**：result.usage 直接交给 budget.consume，加权由 Budget 内部的权重常量
- * 处理（见 budget.ts）。此函数不再做 usage 形状的改写。
- * - **参数显式化**：runner 直接传入（而非 ctx.getRun(runId).pool），无 runId 查找 / pool 守卫。
- * - **stale-state 检查**：signal.aborted 时早返回。WorkflowRun 状态由调用方 lifecycle
- * 持有，executeAgentCall 只关心单次 call 生命周期。
- *
- * 层归属：Engine。零 infra 依赖（runner 是 AgentRunner port，budget/trace/call 是 Engine 模型）。
- *
- * 参考：domain-models.md §5 + §失败处理矩阵。
- */
-
-import type { SubagentStream } from "../execution/stream-sink.ts";
-import type { AgentEvent } from "../shared/agent-event.ts";
-import type { AgentCall } from "./models/agent-call.ts";
-import type { Budget } from "./models/budget.ts";
-import type { AgentRunner } from "./models/ports.ts";
-import type { Trace } from "./models/trace.ts";
-import type { AgentResult } from "./models/types.ts";
-
-// ── 常量 ─────────────────────────────────────────────────────
-
-/** 指数退避基数（ms）：第 n 次重试等待 BASE^n。 */
-const BACKOFF_BASE_MS = 1000;
-const BACKOFF_EXPONENT_BASE = 2;
-
-/** 最大尝试次数（含首次）：initial + 2 retries = 3。 */
-const MAX_ATTEMPTS = 3;
-
-/**
- * Stale context 检测模式（P1-5；W4b 对齐 pi 0.84.x 真实文案）。
- *
- * pi session context 被 compact/cancel 时报告的模式。这种情况下重试无意义——
- * 同样的 call 会再次失败。直接 markDone failed 终止单次调用。
- *
- * W4b：原 "stale context"/"stalecontext" 与 pi 真实文案零匹配（真实文案为
- * "This extension ctx is stale after session replacement or reload. ..."——
- * runner.ts:544（dist runner.js:352），词序是 "ctx is stale" 而非 "stale context"），stale 分诊对
- * 真实文案失效。现对齐：
- * - "ctx is stale"：真实文案核心子串（词序修正）
- * - "stale after session replacement"：scheduler 已验证 marker（runtime.ts
- *   STALE_CTX_MARKER，同文案锚定）
- * - "context canceled"/"aborted"：保留——abort 族错误同样不重试（signal.aborted
- *   分支的先行分诊，防边界竞态漏网），删除会放宽重试语义。
- */
-export const STALE_CONTEXT_PATTERNS = [
-  "ctx is stale",
-  "stale after session replacement",
-  "context canceled",
-  "aborted",
-] as const;
-
-/**
- * 判断错误信息是否表示 stale/canceled pi session context。
- * 命中时不重试——重试只会再次失败（P1-5）。
- */
-export function isStaleContextErrorMsg(msg: string | undefined): boolean {
-  if (!msg) return false;
-  const lower = msg.toLowerCase();
-  return STALE_CONTEXT_PATTERNS.some((p) => lower.includes(p));
-}
-
-/**
- * [MF-1] 确定性 schema 失败标记（error 文本前缀，产出方 = output-collector 的
- * describeMissingParsedOutput）。
- *
- * 标记 SSOT 放本模块（与 STALE_CONTEXT_PATTERNS 同布局：orchestration 持表、
- * execution 值引用；反向引用会形成 execute-agent-call → output-collector →
- * execute-agent-call 运行时循环）。
- *
- * 标记词逐字核对不命中 STALE_CONTEXT_PATTERNS 任一 pattern 与
- * isStaleContextErrorMsg 的子串匹配（否则归因 error 被误诊 stale-context，
- * 虽然同样不重试但归因语义被污染；output-collector.test 有交叉锁定）。
- *
- * 三态可重试性矩阵（F-1 归因）：
- * | 归因态                     | 带本标记 | 可重试性 | 理由 |
- * |----------------------------|---------|---------|------|
- * | ① 从未调用 SO tool         | 是      | 不可重试 | 缺 extension 是环境确定性（C1 安装盲区），同环境重试必同结果 |
- * | ② SO 调用 isError（gate 终止/不可满足 schema） | 是 | 不可重试 | 同 schema 重试必同结果（第五轮实测：3 attempts/4 子进程/235s 纯烧钱） |
- * | ③ 调用过但无 details        | 否      | 可重试   | 可能瞬态（details 提取/序列化异常），保留既有重试语义 |
- */
-export const DETERMINISTIC_SCHEMA_FAILURE_PREFIX = "Structured output failed deterministically:";
-
-/**
- * [MF-1] 判断错误信息是否为确定性 schema 失败（命中标记前缀）。
- * 命中时不重试——同 schema 重试必同结果（矩阵见 DETERMINISTIC_SCHEMA_FAILURE_PREFIX）。
- */
-export function isDeterministicSchemaFailureMsg(msg: string | undefined): boolean {
-  if (!msg) return false;
-  return msg.includes(DETERMINISTIC_SCHEMA_FAILURE_PREFIX);
-}
-
-// ── 内部 helper ──────────────────────────────────────────────
-
-/**
- * 计算第 n 次重试前的退避时间（ms）。
- * 第 1 次重试 → 1000ms，第 2 次 → 2000ms，第 3 次 → 4000ms（指数退避）。
- */
-function backoffDelay(retryIndex: number): number {
-  return BACKOFF_BASE_MS * Math.pow(BACKOFF_EXPONENT_BASE, retryIndex - 1);
-}
-
-/**
- * 终态化单次 call：markDone + trace.update。
- *
- * 成功：status="completed"；失败：status="failed"。
- * traceNode.stepIndex === call.id（D-10 单源，调用方保证）。
- *
- * 孤儿守卫（OB2，S7 残留）：isOrphaned 谓词为 true 时跳过 trace.update——
- * rebuild 竞态窗口中，重跑 dispatch 已 append 同 stepIndex 新节点，旧代际
- * finalize 的 update 会命中新节点，TUI/中间快照短暂可见错误终态。正确性论证：
- * 运行期 calls Map 写点仅 discardInFlightCalls 的 delete 与 dispatchAgentCall 的
- * set 两族（error-recovery.ts isOrphanedCall 文档注释既定），故实例不等 ⟺ 本
- * finalize 属于被丢弃/被替换的旧代际——与 dispatch 层 .then/.catch 守卫
- * （S7-second 修复，8353f6b60）同一判定语义，本守卫只是把它前移到 trace.update
- * 之前。markDone 与 sessionId/sessionFile 同步保留（markDone 在孤儿实例上无害，
- * dispatch 层 catch 路径依赖 call.status 语义）。跳过时不记日志——本文件是纯
- * 函数层无日志通道，dispatch 层 .then 守卫的 orphan completion dropped 日志已
- * 覆盖同一事件的可观察性。
- */
-function finalizeCall(
-  call: AgentCall,
-  result: AgentResult,
-  trace: Trace,
-  isOrphaned?: () => boolean,
-): void {
-  call.markDone(result);
-  const status = result.error === undefined ? "completed" : "failed";
-  // 同步 AgentCall 的 sessionId/sessionFile（对齐 trace 节点，持久化 + reset 用）
-  if (result.sessionId !== undefined) call.setSessionId(result.sessionId);
-  if (result.sessionFile !== undefined) call.setSessionFile(result.sessionFile);
-  if (isOrphaned?.()) return;
-  trace.update(call.id, {
-    status,
-    result,
-    completedAt: new Date().toISOString(),
-    sessionId: result.sessionId,
-    sessionFile: result.sessionFile,
-  });
-}
-
-/**
- * 延迟工具（testable —— 测试可通过 fake timers 推进）。
- */
-function delay(ms: number): Promise<void> {
-  return new Promise((resolve) => {
-    const timer = setTimeout(resolve, ms);
-    timer.unref();
-  });
-}
-
-// ── executeAgentCall ─────────────────────────────────────────
-
-/**
- * 执行单次 agent 调用，含重试 + 预算 + stale-context 检测。
- *
- * 流程：
- * 1. markRunning（attempts++，含首次）
- * 2. await runner.run(opts, signal)（AgentRunner port，infra 实现 spawn pi 子进程）
- * 3. 若 result.usage 存在：consumeUsage（D.4 修复）
- * 4. stale-context → finalizeCall failed，返回（不重试）
- * 5. signal.aborted → 返回（调用方已终止，不重试）
- * 6. budget.isExceeded → finalizeCall failed，返回（不重试）
- * 7. 失败 && attempts < MAX → 退避后递归（下一次 markRunning）
- * 8. 否则 finalizeCall（completed 或 failed）+ incrementCallCount
- *
- * @param call AgentCall 实体（markRunning/markDone 由本函数驱动）
- * @param runner AgentRunner port（执行子进程）
- * @param budget Budget 值对象（consume + isExceeded 检查）
- * @param signal AbortSignal（runner.run 传播；abort 后不重试）
- * @param trace Trace 值对象（finalizeCall 时 update）
- * @param onEvent 实时事件回调（live record 更新用）
- * @param stream streaming sink（透传 runner.run）
- * @param isOrphaned 孤儿判定谓词（OB2，可选，默认恒 false）：true 时 finalizeCall
- *   跳过 trace.update（判定语义与正确性论证见 finalizeCall 文档注释）。递归重试
- *   透传本谓词。
- */
-export async function executeAgentCall(
-  call: AgentCall,
-  runner: AgentRunner,
-  budget: Budget,
-  signal: AbortSignal,
-  trace: Trace,
-  onEvent?: (event: AgentEvent) => void,
-  stream?: SubagentStream,
-  isOrphaned?: () => boolean,
-): Promise<void> {
-  call.markRunning();
-
-  const result = await runner.run(call.opts, signal, onEvent, stream);
-
- // 累加 usage（加权由 budget.consume 内部按权重常量处理，见 budget.ts）
-  if (result.usage) {
-    budget.consume(result.usage);
-  }
-
- // stale-context：不重试（P1-5）
-  if (result.error !== undefined && isStaleContextErrorMsg(result.error)) {
-    finalizeCall(call, result, trace, isOrphaned);
-    budget.incrementCallCount();
-    return;
-  }
-
- // [MF-1] 确定性 schema 失败：不重试（gate 终止/不可满足 schema 同 schema 重试必同
- // 结果——重试纯烧钱；三态可重试性矩阵见 DETERMINISTIC_SCHEMA_FAILURE_PREFIX）
-  if (result.error !== undefined && isDeterministicSchemaFailureMsg(result.error)) {
-    finalizeCall(call, result, trace, isOrphaned);
-    budget.incrementCallCount();
-    return;
-  }
-
- // signal 已 abort：调用方终止，不重试（避免无意义的递归）
-  if (signal.aborted) {
-    finalizeCall(call, result, trace, isOrphaned);
-    budget.incrementCallCount();
-    return;
-  }
-
- // 预算超限：不重试（重试只会突破预算且无意义）
-  if (result.error !== undefined && budget.isExceeded()) {
-    finalizeCall(call, result, trace, isOrphaned);
-    budget.incrementCallCount();
-    return;
-  }
-
- // 可重试失败：退避后递归
-  if (result.error !== undefined && call.attempts < MAX_ATTEMPTS) {
-    await delay(backoffDelay(call.attempts));
- // 退避期间 signal 可能 abort
-    if (signal.aborted) {
-      finalizeCall(call, result, trace, isOrphaned);
-      budget.incrementCallCount();
-      return;
-    }
-    await executeAgentCall(call, runner, budget, signal, trace, onEvent, stream, isOrphaned);
-    return;
-  }
-
- // 终态（成功或达到重试上限的失败）
-  finalizeCall(call, result, trace, isOrphaned);
-  budget.incrementCallCount();
-}