@zhushanwen/pi-subagent-workflow 8.0.0 → 8.1.0

package/src/orchestration/__tests__/test-mocks.ts

@@ -32,8 +32,14 @@ import type {
   Theme,
 } from "@earendil-works/pi-coding-agent";
 
-/** 误用即抛错的占位成员：比静默返回 undefined 的 no-op 更早暴露「缺 mock」。 */
-function failLoud<T>(memberPath: string): T {
+/**
+ * 误用即抛错的占位成员：比静默返回 undefined 的 no-op 更早暴露「缺 mock」。
+ *
+ * T 收窄为 object：调用点（ModelRegistry/Theme）均为对象类型；Proxy 静态类型是 `{}`，
+ * 目标是 nominal class（private 字段阻断结构构造），单重 `as T` 断言已足够表达
+ * 「结构上无法构造，运行时 fail-loud 兜底」的意图，无需 `as unknown as T` 双重断言。
+ */
+function failLoud<T extends object>(memberPath: string): T {
   return new Proxy(
     {},
     {
@@ -44,7 +50,7 @@ function failLoud<T>(memberPath: string): T {
         );
       },
     },
-  ) as unknown as T;
+  ) as T;
 }
 
 /**

package/src/orchestration/__tests__/worker-returnmeta-passthrough.test.ts

@@ -0,0 +1,164 @@
+/**
+ * rfl 仪表 T1（tier-1 §7.1）：returnMeta 透传 usage/durationMs/sessionId。
+ *
+ * 两个对称点的运行时验证（worker-script-builder 模板字符串断言无法证明
+ * 「真实 Worker 线程里 resolve 对象字段齐全」）：
+ *   A1 live resolve——agent-result 消息回发完整 AgentResult，returnMeta:true
+ *      时 resolve 对象 = {value, sessionFile, worktreePath, error, usage, durationMs, sessionId}
+ *   A2 缓存重放——workerData.callCache 命中时重建对象同样含三字段（对称点）
+ *
+ * 模式与 worker-script-builder-runtime.test.ts 相同：真实 Worker 线程执行
+ * buildWorkerScript 产物，主线程模拟 runtime 回发消息。
+ */
+import { Worker } from "node:worker_threads";
+
+import { afterEach, describe, expect, it } from "vitest";
+
+import { buildWorkerScript } from "../worker-script-builder.ts";
+
+const USAGE = { input: 100, output: 50, cacheRead: 700, cacheWrite: 30, cost: 0.012, contextTokens: 850, turns: 3 };
+
+const createdWorkers: Worker[] = [];
+
+afterEach(() => {
+  for (const w of createdWorkers.splice(0)) {
+    w.terminate().catch(() => {});
+  }
+});
+
+interface RunOutcome {
+  returnValue?: unknown;
+  errorMessage?: string;
+  exitCode?: number;
+}
+
+/**
+ * 起 Worker 跑 userScript；收到首个 agent-call 即回发 agentResult（调用方提供），
+ * 等脚本 return。callCache 命中路径不会发出 agent-call（直接从缓存重建返回）。
+ */
+function runWorker(
+  userScript: string,
+  opts: { agentResult?: Record<string, unknown>; callCache?: Record<number, unknown>; timeoutMs?: number },
+): Promise<RunOutcome> {
+  const timeoutMs = opts.timeoutMs ?? 4000;
+  return new Promise((resolve, reject) => {
+    const worker = new Worker(buildWorkerScript(userScript), {
+      eval: true,
+      workerData: {
+        scriptPath: "test.js",
+        args: {},
+        workspace: process.cwd(),
+        budget: { maxTokens: 0, usedTokens: 0, usedCost: 0 },
+        callCache: opts.callCache ?? {},
+      },
+    });
+    createdWorkers.push(worker);
+    const out: RunOutcome = {};
+    let settled = false;
+    const timer = setTimeout(() => {
+      worker.terminate().catch(() => {});
+      reject(new Error("Worker timed out — likely hung"));
+    }, timeoutMs);
+    const finish = (r: RunOutcome): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(r);
+    };
+    worker.on("message", (raw: unknown) => {
+      const msg = raw as { type?: string; callId?: number };
+      if (msg.type === "agent-call" && typeof msg.callId === "number") {
+        worker.postMessage({
+          type: "agent-result",
+          callId: msg.callId,
+          result: opts.agentResult ?? { content: "fallback", parsedOutput: { ok: true } },
+          cached: false,
+        });
+      } else if (msg.type === "return") {
+        out.returnValue = (raw as { result?: unknown }).result;
+        finish(out);
+      } else if (msg.type === "error") {
+        out.errorMessage = (raw as { error?: string }).error;
+        finish(out);
+      }
+    });
+    worker.on("exit", (code: number) => {
+      out.exitCode = code;
+      if (code !== 0) finish(out);
+    });
+    worker.on("error", (err: Error) => {
+      out.errorMessage = err.message;
+      finish(out);
+    });
+  });
+}
+
+const META_SCRIPT = "const meta = await agent({ prompt: 'passthrough probe', returnMeta: true }); return meta;";
+
+describe("A1 returnMeta live resolve 透传（tier-1 §7.1）", () => {
+  it("A1 agent-result 回发完整 AgentResult 时 resolve 对象含 usage/durationMs/sessionId（七字段全集）", async () => {
+    const outcome = await runWorker(META_SCRIPT, {
+      agentResult: {
+        content: "raw text",
+        parsedOutput: { ok: true },
+        sessionFile: "/tmp/sess.jsonl",
+        worktreePath: "/tmp/wt",
+        error: undefined,
+        usage: USAGE,
+        durationMs: 83_000,
+        sessionId: "sess-abc-1",
+      },
+    });
+    expect(outcome.errorMessage).toBeUndefined();
+    expect(outcome.returnValue).toEqual({
+      value: { ok: true },
+      sessionFile: "/tmp/sess.jsonl",
+      worktreePath: "/tmp/wt",
+      error: undefined,
+      usage: USAGE,
+      durationMs: 83_000,
+      sessionId: "sess-abc-1",
+    });
+  });
+
+  it("A1 旧主线程（AgentResult 无三字段）时 resolve 对象三字段为 undefined（向后兼容不抛错）", async () => {
+    const outcome = await runWorker(META_SCRIPT, {
+      agentResult: { content: "raw", parsedOutput: { v: 1 }, sessionFile: "/tmp/s.jsonl" },
+    });
+    expect(outcome.returnValue).toMatchObject({
+      value: { v: 1 },
+      sessionFile: "/tmp/s.jsonl",
+      usage: undefined,
+      durationMs: undefined,
+      sessionId: undefined,
+    });
+  });
+});
+
+describe("A2 returnMeta 缓存重放重建透传（对称点，tier-1 §7.1）", () => {
+  it("A2 workerData.callCache 命中时重建对象含 usage/durationMs/sessionId（不回发 agent-call）", async () => {
+    const outcome = await runWorker(META_SCRIPT, {
+      callCache: {
+        0: {
+          content: "cached raw",
+          parsedOutput: { cached: true },
+          sessionFile: "/tmp/cached.jsonl",
+          worktreePath: "/tmp/cwt",
+          usage: USAGE,
+          durationMs: 42_000,
+          sessionId: "sess-cache-9",
+        },
+      },
+    });
+    expect(outcome.errorMessage).toBeUndefined();
+    expect(outcome.returnValue).toEqual({
+      value: { cached: true },
+      sessionFile: "/tmp/cached.jsonl",
+      worktreePath: "/tmp/cwt",
+      error: undefined,
+      usage: USAGE,
+      durationMs: 42_000,
+      sessionId: "sess-cache-9",
+    });
+  });
+});

package/src/orchestration/__tests__/worker-script-template-snapshot.test.ts

@@ -62,6 +62,18 @@ describe("buildWorkerScript — 模板 hoisting byte-identical 快照（IF5）",
     const [preB] = b.split("\n  y\n");
     expect(preA).toBe(preB);
   });
+
+  it("A8 rfl 仪表透传字段字面量锚定（tier-1 §7.1）：live resolve 与缓存重放两对称点均含三字段", () => {
+    const out = buildWorkerScript("// noop");
+    // live resolve 分支（agent-result 消息处理）
+    expect(out).toContain("usage: msg.result.usage,");
+    expect(out).toContain("durationMs: msg.result.durationMs,");
+    expect(out).toContain("sessionId: msg.result.sessionId,");
+    // 缓存重放分支（_callCache 命中重建，对称点）
+    expect(out).toContain("usage: cached.usage,");
+    expect(out).toContain("durationMs: cached.durationMs,");
+    expect(out).toContain("sessionId: cached.sessionId,");
+  });
 });
 
 describe("buildWorkerScript — _KNOWN_FIELDS module scope 提升（IF6）", () => {

package/src/orchestration/__tests__/workflows-e2e.test.ts

@@ -476,63 +476,61 @@ describe("内置 workflow E2E（真实 worker thread + mock LLM runner）", () =
 
   it("TC4: actionRun 顺序——not_found 优先（平铺 + 不存在名）；slug 护栏保留；chain 平铺 Correct 文案", async () => {
     const deps = makeDeps();
-    // 平铺 + 不存在 name → not_found 优先（m6：registry.get 先于平铺检测）
-    const notFound = await actionRun(
+    // 平铺 + 不存在 name → not_found 优先（m6：registry.get 先于平铺检测）。
+    // W4：not_found 改 throw（pi 只对 execute throw 置 isError:true，返回值里的
+    // isError 被 agent-loop 丢弃）——文案含 <available_workflows> <location> 恢复指引，
+    // pi catch 后原样进 toolResult content。
+    const notFoundErr: Error = await actionRun(
       { action: "run", name: wf("nope"), task: "x" },
       deps,
       undefined,
-    );
-    expect(notFound.isError).toBe(true);
-    expect(notFound.content![0]!.text).toContain("not found"); // DoD 用户可见断言
-    // R5（D7）：workflow not_found 文案含 <available_workflows> <location> 恢复指引
-    expect(notFound.content![0]!.text).toContain("<available_workflows>");
-    expect(notFound.content![0]!.text).toContain("<location>");
-    // chain 平铺 task → isError Correct 正例（动态集来自 registry）
-    const flat = await actionRun(
+    ).catch((e: unknown) => e as Error);
+    expect(notFoundErr).toBeInstanceOf(Error);
+    expect(notFoundErr.message).toContain("not found"); // DoD 用户可见断言
+    expect(notFoundErr.message).toContain("<available_workflows>");
+    expect(notFoundErr.message).toContain("<location>");
+    // chain 平铺 task → throw Correct 正例（动态集来自 registry；W4b：原 textResult
+    // 间接 isError 返回改 throw——pi 只对 execute throw 置 isError:true，
+    // 返回值里的 isError 被 agent-loop 丢弃）
+    const flatErr: Error = await actionRun(
       { action: "run", name: wf("chain"), task: "x" },
       deps,
       undefined,
-    );
-    expect(flat.isError).toBe(true);
-    expect(flat.content![0]!.text).toContain("Detected task at top level");
-    expect(flat.content![0]!.text).toContain("Correct:");
-    // slug 护栏保留（m6 顺序调整后仍在 runWorkflow 前）
-    const slug = await actionRun(
+    ).catch((e: unknown) => e as Error);
+    expect(flatErr).toBeInstanceOf(Error);
+    expect(flatErr.message).toContain("Detected task at top level");
+    expect(flatErr.message).toContain("Correct:");
+    // slug 护栏保留（m6 顺序调整后仍在 runWorkflow 前；W4b 同改 throw）
+    const slugErr: Error = await actionRun(
       { action: "run", name: wf("chain"), args: { task: "x" }, slug: "a".repeat(40) },
       deps,
       undefined,
-    );
-    expect(slug.isError).toBe(true);
-    expect(slug.content![0]!.text).toContain("slug exceeds");
+    ).catch((e: unknown) => e as Error);
+    expect(slugErr).toBeInstanceOf(Error);
+    expect(slugErr.message).toContain("slug exceeds");
   });
 
   it("TC6: 跨 workflow 平铺语义——review-fix-loop 平铺 task（非其参数）走 args-validator", async () => {
     const deps = makeDeps();
     // task 是 chain 参数非 review-fix-loop 参数 → 不报平铺 → args 缺 targetType
-    // → m3 chokepoint invalid_args（错误更准——评审 m-5 语义锁定）
-    const result = await actionRun(
-      { action: "run", name: wf("review-fix-loop"), task: "x" },
-      deps,
-      undefined,
-    );
-    expect(result.isError).toBe(true);
-    expect(result.content![0]!.text).toContain("Invalid args for workflow 'review-fix-loop'");
-    expect(result.content![0]!.text).toContain("targetType");
+    // → m3 chokepoint invalid_args（错误更准——评审 m-5 语义锁定）。
+    // W4：ArgsValidationError 直接 throw（message 原文即 §5.3 指引）
+    await expect(
+      actionRun({ action: "run", name: wf("review-fix-loop"), task: "x" }, deps, undefined),
+    ).rejects.toThrow(/Invalid args for workflow 'review-fix-loop'[\s\S]*targetType/);
   });
 
-  it("TC9: actionRun 参数校验失败 → isError ToolResult + §5.3 指引", async () => {
+  it("TC9: actionRun 参数校验失败 → throw + §5.3 指引（W4）", async () => {
     const deps = makeDeps();
-    const result = await actionRun(
-      { action: "run", name: wf("review-fix-loop"), args: { batch1: agentMd("code-reviewer") } },
-      deps,
-      undefined,
+    await expect(
+      actionRun(
+        { action: "run", name: wf("review-fix-loop"), args: { batch1: agentMd("code-reviewer") } },
+        deps,
+        undefined,
+      ),
+    ).rejects.toThrow(
+      /Invalid args for workflow 'review-fix-loop'[\s\S]*targetType[\s\S]*Read the workflow script file/,
     );
-
-    expect(result.isError).toBe(true);
-    const text = result.content?.[0]?.text ?? "";
-    expect(text).toContain("Invalid args for workflow 'review-fix-loop'");
-    expect(text).toContain("targetType");
-    expect(text).toContain("Read the workflow script file");
   });
 
 

package/src/orchestration/error-recovery.ts

@@ -63,6 +63,9 @@ const EXPONENTIAL_BACKOFF_BASE = 2;
 /** errorLogs 最大保留条数（防止超长 session 中日志无界增长）。 */
 const MAX_ERROR_LOGS = 500;
 
+/** malformed agent-call 日志中 opts JSON 的预览截断长度（字符）。 */
+const MALFORMED_MSG_LOG_PREVIEW_CHARS = 200;
+
 // ── Worker 消息类型（与 infra/worker-script-builder.ts WorkerInMsg 对齐） ──
 
 interface AgentCallMsg {
@@ -312,7 +315,7 @@ function dispatchAgentCall(
   if (typeof msg.callId !== "number" || !Number.isFinite(msg.callId) ||
       typeof msg.opts !== "object" || msg.opts === null ||
       typeof msg.opts.prompt !== "string") {
-    logger.error(`[workflow] malformed agent-call message: callId=${JSON.stringify(msg.callId)}, opts=${JSON.stringify(msg.opts)?.slice(0, 200)}`);
+    logger.error(`[workflow] malformed agent-call message: callId=${JSON.stringify(msg.callId)}, opts=${JSON.stringify(msg.opts)?.slice(0, MALFORMED_MSG_LOG_PREVIEW_CHARS)}`);
     return;
   }
 

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

@@ -41,14 +41,24 @@ const BACKOFF_EXPONENT_BASE = 2;
 const MAX_ATTEMPTS = 3;
 
 /**
- * Stale context 检测模式（P1-5）。
+ * 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 = [
-  "stale context",
-  "stalecontext",
+  "ctx is stale",
+  "stale after session replacement",
   "context canceled",
   "aborted",
 ] as const;