@zhushanwen/pi-subagent-workflow 0.1.0

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

@@ -0,0 +1,174 @@
+/**
+ * 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）
+ * - 成功：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 { 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）。
+ *
+ * pi session context 被 compact/cancel 时报告的模式。这种情况下重试无意义——
+ * 同样的 call 会再次失败。直接 markDone failed 终止单次调用。
+ */
+export const STALE_CONTEXT_PATTERNS = [
+  "stale context",
+  "stalecontext",
+  "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));
+}
+
+// ── 内部 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 单源，调用方保证）。
+ */
+function finalizeCall(call: AgentCall, result: AgentResult, trace: Trace): void {
+  call.markDone(result);
+  const status = result.error === undefined ? "completed" : "failed";
+  trace.update(call.id, {
+    status,
+    result,
+    completedAt: new Date().toISOString(),
+    sessionId: result.sessionId,
+  });
+}
+
+/**
+ * 延迟工具（testable —— 测试可通过 fake timers 推进）。
+ */
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// ── 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）
+ */
+export async function executeAgentCall(
+  call: AgentCall,
+  runner: AgentRunner,
+  budget: Budget,
+  signal: AbortSignal,
+  trace: Trace,
+  onEvent?: (event: AgentEvent) => void,
+): Promise<void> {
+  call.markRunning();
+
+  const result = await runner.run(call.opts, signal, onEvent);
+
+ // 累加 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);
+    budget.incrementCallCount();
+    return;
+  }
+
+ // signal 已 abort：调用方终止，不重试（避免无意义的递归）
+  if (signal.aborted) {
+    finalizeCall(call, result, trace);
+    budget.incrementCallCount();
+    return;
+  }
+
+ // 预算超限：不重试（重试只会突破预算且无意义）
+  if (result.error !== undefined && budget.isExceeded()) {
+    finalizeCall(call, result, trace);
+    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);
+      budget.incrementCallCount();
+      return;
+    }
+    await executeAgentCall(call, runner, budget, signal, trace, onEvent);
+    return;
+  }
+
+ // 终态（成功或达到重试上限的失败）
+  finalizeCall(call, result, trace);
+  budget.incrementCallCount();
+}

package/src/orchestration/jsonl-run-store.ts

@@ -0,0 +1,292 @@
+/**
+ * Workflow Extension — JSONL Run Store
+ *
+ * RunStore port 的 Infra 实现。
+ *
+ * 职责：持久化 WorkflowRun 聚合根到 JSONL 文件 + 跨 session 重水合。
+ *
+ * 层归属：Infra（D-12）。implements Engine 层的 RunStore port。
+ * 依赖 @mariozechner/pi-coding-agent 的 ExtensionAPI/ExtensionContext（Infra 允许 Pi SDK）。
+ *
+ * 设计：
+ * - JsonlRunStore implements RunStore（而非散落的 persist/reconstruct 自由函数）。
+ * - **D-5: 不向后兼容**——reconstruct 时检查 snapshotVersion，无版本号或版本不匹配
+ * 的 session 返回空数组（spec 决策：旧 run 历史价值低，不尝试兼容迁移）。
+ * - rewrite mode（writeFile 覆盖，文件始终是最新单行快照）。
+ * - workflow-state-link 指针条目机制保留（pi.appendEntry）。
+ *
+ * 序列化策略：
+ * - WorkflowRun 是带方法的 class 聚合根——序列化只取公共字段快照。
+ * - Budget/Trace/AgentCall 都有公共构造器或 fromArray 工厂，反序列化时重建实例。
+ * - Snapshot 形态用 SnapshotVersion 守护（D-5：格式识别）。
+ *
+ * 参考：domain-models.md §Ports（RunStore 定义）、clarification.md D-5。
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+
+import { AgentCall } from "./models/agent-call.ts";
+import { Budget } from "./models/budget.ts";
+import type { RunSpec } from "./models/run-spec.ts";
+import type { RunState } from "./models/run-state.ts";
+import { Trace } from "./models/trace.ts";
+import type { DoneReason, RunStatus, WorkerLogEntry } from "./models/types.ts";
+import type { AgentCallOpts, AgentResult, ExecutionTraceNode } from "./models/types.ts";
+import type { WorkflowRunMeta } from "./models/workflow-run.ts";
+import { WorkflowRun } from "./models/workflow-run.ts";
+
+// ── Snapshot format (D-5 version guard) ──────────────────────
+
+/**
+ * 快照格式版本。D-5：旧 session（无此字段或值不匹配）被 loadAll 忽略。
+ *
+ * 升级格式时 bump 此常量并在 deserializeRun 中适配——旧文件返回 null（被 loadAll 跳过）。
+ */
+export const SNAPSHOT_VERSION = "wf-run-v1" as const;
+
+/**
+ * 持久化快照形态——WorkflowRun 公共字段的 JSON 可序列化投影。
+ *
+ * calls 序列化为数组（Map 不能直接 JSON.stringify）；反序列化时重建 Map。
+ * budget/trace 在 deserialize 时重建实例（带方法的 class）。
+ */
+interface RunSnapshot {
+  v: typeof SNAPSHOT_VERSION;
+  runId: string;
+  spec: RunSpec;
+  state: {
+    status: RunStatus;
+    reason?: DoneReason;
+    budget: {
+      maxTokens?: number;
+      maxCost?: number;
+      maxTimeMs?: number;
+      usedTokens: number;
+      usedCost: number;
+      totalCallCount: number;
+    };
+    calls: Array<{
+      id: number;
+      opts: AgentCallOpts;
+      status: "pending" | "running" | "done";
+      attempts: number;
+      result?: AgentResult;
+      sessionId?: string;
+      traceNode: ExecutionTraceNode;
+    }>;
+    trace: ExecutionTraceNode[];
+    errorLogs: WorkerLogEntry[];
+    error?: string;
+    scriptResult?: unknown;
+  };
+  meta: {
+    startedAt: string;
+    completedAt?: string;
+    pausedAt?: string;
+    workerErrorCount?: number;
+    scriptErrorCount?: number;
+  };
+}
+
+// ── Serialization ────────────────────────────────────────────
+
+function serializeRun(run: WorkflowRun): RunSnapshot {
+  return {
+    v: SNAPSHOT_VERSION,
+    runId: run.runId,
+    spec: run.spec,
+    state: {
+      status: run.state.status,
+      reason: run.state.reason,
+      budget: {
+        maxTokens: run.state.budget.maxTokens,
+        maxCost: run.state.budget.maxCost,
+        maxTimeMs: run.state.budget.maxTimeMs,
+        usedTokens: run.state.budget.usedTokens,
+        usedCost: run.state.budget.usedCost,
+        totalCallCount: run.state.budget.totalCallCount,
+      },
+      calls: Array.from(run.state.calls.values()).map((c) => {
+        // strip live（同 trace 序列化，不持久化运行期对象）
+        const { live: _live, ...traceNodeRest } = c.traceNode;
+        return {
+          id: c.id,
+          opts: c.opts,
+          status: c.status,
+          attempts: c.attempts,
+          result: c.result,
+          sessionId: c.sessionId,
+          traceNode: traceNodeRest,
+        };
+      }),
+      // trace 节点浅拷贝时 strip live 字段——ExecutionRecord 含可变 turns[]/controller，
+      // 不适合序列化；pause/resume 后 live 为 undefined（重跑时由 dispatchAgentCall 重建）。
+      trace: run.state.trace.toArray().map(({ live: _live, ...rest }) => rest),
+      errorLogs: run.state.errorLogs,
+      error: run.state.error,
+      scriptResult: run.state.scriptResult,
+    },
+    meta: run.meta,
+  };
+}
+
+/**
+ * 反序列化快照为 WorkflowRun。D-5：版本不匹配返回 null（旧 session）。
+ */
+function deserializeRun(snapshot: RunSnapshot): WorkflowRun | null {
+ // D-5 version guard
+  if (snapshot.v !== SNAPSHOT_VERSION) return null;
+
+  const budget = new Budget({
+    maxTokens: snapshot.state.budget.maxTokens,
+    maxCost: snapshot.state.budget.maxCost,
+    maxTimeMs: snapshot.state.budget.maxTimeMs,
+    usedTokens: snapshot.state.budget.usedTokens,
+    usedCost: snapshot.state.budget.usedCost,
+  });
+  budget.totalCallCount = snapshot.state.budget.totalCallCount;
+
+  const calls = new Map<number, AgentCall>();
+  for (const c of snapshot.state.calls) {
+    const call = new AgentCall(c.id, c.opts, c.traceNode);
+    call.status = c.status;
+    call.attempts = c.attempts;
+ // Restore result directly — bypasses markRunning/markDone state-machine guards
+ // because we're reconstructing a known-good persisted state, not transitioning.
+    if (c.result !== undefined) {
+      call.result = c.result;
+    }
+    if (c.sessionId !== undefined) {
+      call.setSessionId(c.sessionId);
+    }
+    calls.set(c.id, call);
+  }
+
+  const trace = Trace.fromArray(snapshot.state.trace);
+
+  const state: RunState = {
+    status: snapshot.state.status,
+    reason: snapshot.state.reason,
+    budget,
+    calls,
+    trace,
+    errorLogs: snapshot.state.errorLogs,
+    error: snapshot.state.error,
+    scriptResult: snapshot.state.scriptResult,
+  };
+
+  const meta: WorkflowRunMeta = {
+    startedAt: snapshot.meta.startedAt,
+    completedAt: snapshot.meta.completedAt,
+    pausedAt: snapshot.meta.pausedAt,
+    workerErrorCount: snapshot.meta.workerErrorCount,
+    scriptErrorCount: snapshot.meta.scriptErrorCount,
+  };
+
+ // WorkflowRun.reconstruct 跳过 I1 校验——持久化的 running 状态没有 worker
+ // （进程被杀后 worker 不可能还活着），违反 I1。D-4 kill-9 恢复在 session_start
+ // 时把残留 running 转 done,failed，恢复 I1（见 index.ts session_start handler）。
+  return WorkflowRun.reconstruct(snapshot.runId, snapshot.spec, state, meta);
+}
+
+// ── JsonlRunStore ────────────────────────────────────────────
+
+export interface JsonlRunStoreOptions {
+ /** Session directory root (state files live under <sessionDir>/workflow-state/). */
+  sessionDir: string;
+ /** Pi ExtensionAPI for appendEntry pointer writes (optional for testing). */
+  pi?: ExtensionAPI;
+ /** Pi ExtensionContext for sessionManager.getEntries (optional for testing). */
+  ctx?: ExtensionContext;
+}
+
+export class JsonlRunStore {
+  private readonly sessionDir: string;
+  private readonly pi?: ExtensionAPI;
+  private readonly ctx?: ExtensionContext;
+
+  constructor(opts: JsonlRunStoreOptions) {
+    this.sessionDir = opts.sessionDir;
+    this.pi = opts.pi;
+    this.ctx = opts.ctx;
+  }
+
+ /** State directory: <sessionDir>/workflow-state/ */
+  private get stateDir(): string {
+    return path.join(this.sessionDir, "workflow-state");
+  }
+
+ /** State file path for a given runId. */
+  private filePathFor(runId: string): string {
+    return path.join(this.stateDir, `${runId}.jsonl`);
+  }
+
+ /**
+ * Persist a single run: rewrite mode (overwrite) — file always contains the
+ * latest complete snapshot on a single line. Appends a workflow-state-link
+ * pointer entry via pi.appendEntry so loadAll can locate files.
+ */
+  async save(run: WorkflowRun): Promise<void> {
+    const filePath = this.filePathFor(run.runId);
+    await fs.promises.mkdir(path.dirname(filePath), { recursive: true });
+    const snapshot = serializeRun(run);
+    await fs.promises.writeFile(filePath, JSON.stringify(snapshot) + "\n", "utf8");
+    if (this.pi) {
+      this.pi.appendEntry("workflow-state-link", {
+        runId: run.runId,
+        path: filePath,
+        updatedAt: new Date().toISOString(),
+      });
+    }
+  }
+
+ /**
+ * Reconstruct all runs from session JSONL pointer entries.
+ *
+ * D-5:旧格式（无版本号 / 版本不匹配）返回空——loadAll 跳过这些条目，
+ * 不尝试向后兼容旧 session（spec 决策）。
+ *
+ * 需要 ctx（构造时注入）——无 ctx 时返回空（测试或非 Pi 环境下）。
+ */
+  async loadAll(): Promise<WorkflowRun[]> {
+    if (!this.ctx) return [];
+    const runs: WorkflowRun[] = [];
+    try {
+      const entries = this.ctx.sessionManager.getEntries();
+      const pointers = new Map<string, { path: string }>();
+
+      for (const entry of entries) {
+        if (entry.type !== "custom") continue;
+        if (entry.customType !== "workflow-state-link") continue;
+        const data = entry.data as { runId?: string; path?: string } | undefined;
+        if (data?.runId && data?.path) {
+          pointers.set(data.runId, { path: data.path });
+        }
+      }
+
+      for (const [, pointer] of pointers) {
+        try {
+          const content = await fs.promises.readFile(pointer.path, "utf8");
+          const lines = content.split("\n").filter((l) => l.trim());
+          const lastLine = lines[lines.length - 1];
+          if (!lastLine) continue;
+          const parsed = JSON.parse(lastLine) as RunSnapshot;
+          const run = deserializeRun(parsed);
+ // D-5: null = old format / version mismatch — skip silently
+          if (run) runs.push(run);
+        } catch (err) {
+ // Corrupt/unreadable state file — skip (don't crash loadAll).
+ // Single bad file must not abort reconstruction of the rest.
+          void err;
+        }
+      }
+    } catch (err) {
+ // getEntries failed — return what we have (empty).
+      void err;
+    }
+    return runs;
+  }
+}