@zhushanwen/pi-subagent-workflow 9.0.1 → 9.1.0

package/src/workflow-events.ts

@@ -66,7 +66,7 @@ import { WorkflowScriptRegistryImpl } from "@zhushanwen/subagent-core";
 // 管道），session_start / session_shutdown 驱动 attach/detach；测试可注入 fake。
 import { createInFlightReporter, type InFlightReporter } from "./host/inflight-reporter.ts";
 // [W2/V1 D1 第 8 行] 判活类消费面（isScriptRunning）经 core 投影单点
-//（runSummary.status 二值——内部收拢注册表 ∨ 聚合混合判源）。
+//（runSummary.status 三态投影——终局判定源 = 终局记录注册表）。
 import { type RunSettlementRecord } from "./jsonl-run-store.ts";
 import { notifyDone, trackNotifiedRunId } from "./workflow-notify.ts";
 // ═══ 跨域事件注册（handler 体住各自域模块，本 seam 原位调用保注册顺序） ═══
@@ -74,6 +74,7 @@ import { setupNotifyLedgerCompactionGuard } from "./workflow-notify.ts";
 import { setupModelEvents } from "./model-events.ts";
 import { setupSubagentsCascadeEvents } from "./subagents-events.ts";
 // ═══ session 生命周期装配 seam（bootstrap seam，设计 §3.1/D1） ═══
+import { GLOBAL_SLOT_KEYS } from "@zhushanwen/subagent-core";
 import {
   getOrCreateDialogQueue,
   setupSessionLifecycle,
@@ -125,7 +126,7 @@ function createWorkflowDomainState(): WorkflowDomainState {
 // 此槽拿回同一 domain state，session_shutdown(reload) 跳过清理（D1）保住的
 // 在飞 run / store 由 post-reload session_start(reason=reload) 的 adoption
 // 接管（D4，session-lifecycle.ts）。
-const WORKFLOW_DOMAIN_SLOT_KEY = Symbol.for("@zhushanwen/pi-subagents.workflow-domain-state");
+const WORKFLOW_DOMAIN_SLOT_KEY = Symbol.for(GLOBAL_SLOT_KEYS.workflowDomainState);
 
 function getOrCreateWorkflowDomainState(): WorkflowDomainState {
   let state = Reflect.get(globalThis, WORKFLOW_DOMAIN_SLOT_KEY) as WorkflowDomainState | undefined;
@@ -148,7 +149,7 @@ function resolveCurrentPi(): ExtensionAPI {
   if (!pi) {
     throw new Error(
       "workflow deps current pi binding unset: setupWorkflowDomain has not run " +
-        "(slot @zhushanwen/pi-subagents.workflow-domain-state); re-run extension factory to re-register",
+        `(slot ${GLOBAL_SLOT_KEYS.workflowDomainState}); re-run extension factory to re-register`,
     );
   }
   return pi;
@@ -482,6 +483,15 @@ export function setupWorkflowDomain(
     const sessionId = ctx.sessionManager.getSessionId();
     lsRef.lastSessionId = sessionId;
 
+    // [PS-68] tree 导航 = 同进程分支导航，非会话替换：pi 原地换叶子
+    //（agent.state.messages = sessionContext.messages）后 emit，不 teardown、不失效
+    // runner——pi 绑定保持有效，此处不作废。替换形态 = new/fork/resume/quit +
+    // switchSession（借 reason="resume"，无专用枚举成员），全部发 session_shutdown；
+    // switchSession 的替换语义由 session_shutdown 非 reload 分支承接，与本 handler
+    // 无交集。reload 另有本文件 :546 显式作废。禁止在此 invalidatePiBinding：作废后
+    // 唯一重臂点 initSession 只由 session_start 触发，tree 导航不触发 session_start，
+    // 本 session 余生 record/notify 的 pi 写入将静默 no-op。
+    // [HISTORICAL] 曾按「switchSession 不发 session_shutdown、其内部路径即 tree 导航域」的假前提在此作废绑定，撤销依据与触发词表登记见 docs/pi-semantics.json PS-61。
     const state = sessionState.get(sessionId);
     if (state) {
       // 一次性生命周期（D-2）：running run 转 done,failed 落盘（helper 内部自过滤
@@ -526,6 +536,14 @@ export function setupWorkflowDomain(
   // ════════════════════════════════════════════════════════════
   pi.on("session_shutdown", async (event: SessionShutdownEvent, _ctx: ExtensionContext) => {
     if (event.reason === "reload") {
+      // [§1.4 (a) reload 分支显式作废句柄] reload 有意跳过全部破坏性清理（下方 D1 分支
+      // 说明——在途 run 交给 reload 后 adoption 接管），但 pi 会话替换会使旧 runner
+      // 失效（PS-30：assertActive 抛 stale after session replacement），core SubagentService
+      // 的 late-bound pi 读面在旧失效句柄上会一路命中 assertActive 抛错（在途 run 的
+      // 轮终收尾正落该窗口）。此处只作废「句柄可用性判定」，不动在途 run 纳管：
+      // 作废后读面降级 null（轮终收尾经有界等待挂到新 initSession 注入），新 session_start
+      // 注入新代际句柄后自然恢复。方法本身不抛（字段写 + 唤醒等待者）。
+      getSubagentService()?.invalidatePiBinding("session replacement (reload)");
       // b 动作保留（理由见上方 D1 分支说明）。
       inflightReporter.detachSession();
 

package/src/workflow-notify.ts

@@ -35,7 +35,7 @@ import {
   boundedPrettySerialize,
   getBoundNotifyLedger,
   isTerminalDoneReason,
-  RUN_EVENT_JOURNAL_SUFFIX,
+  RUN_EVENTS_SUFFIX,
   type RunOutcome,
 } from "@zhushanwen/subagent-core";
 import type { WorkflowRun } from "@zhushanwen/subagent-core";
@@ -58,12 +58,13 @@ const MAX_RESULT_SUMMARY_LENGTH = 500;
 const RECORD_FAIL_CONTENT_PREVIEW_LENGTH = 200;
 
 /**
- * [D7] 事件 journal 文件名（run store 旁，artifactsDir 内）：`<runId>.events.jsonl`
- * （runId 即 generateRunId 的 wf- 前缀产物，渲染名 = 设计 D5 的 wf-<id>.events.jsonl；
- * 后缀经 core barrel 单源 RUN_EVENT_JOURNAL_SUFFIX，core 命名变更时编译期同步）。
+ * [D7] 事件 journal 文件名（run store 旁，artifactsDir 内）：`<runId>.record.jsonl`
+ * （runId 即 generateRunId 的 wf- 前缀产物；后缀随 core RUN_EVENTS_SUFFIX 改名，
+ * 历史 .events.jsonl = 旧写入方实体，设计 D5 的渲染名 wf-<id>.events.jsonl 即该
+ * 旧形态；实值经 core barrel 单源 RUN_EVENTS_SUFFIX，core 命名变更时编译期同步）。
  */
 function runEventsJournalPath(artifactsDir: string, runId: string): string {
-  return join(artifactsDir, `${runId}${RUN_EVENT_JOURNAL_SUFFIX}`);
+  return join(artifactsDir, `${runId}${RUN_EVENTS_SUFFIX}`);
 }
 
 /**
@@ -138,7 +139,7 @@ interface WorkflowNotifyDetails { // oe-exempt:20260929:framework:workflow/recor
    */
   artifactsDir?: string;
   /**
-   * [D7] 事件 journal 指针（`<artifactsDir>/wf-<runId>.events.jsonl`）——终局
+   * [D7] 事件 journal 指针（`<artifactsDir>/wf-<runId>.record.jsonl`）——终局
    * 证据的入口载荷（D5-3 诊断引用落账的消费面）。
    */
   eventsJournalPath?: string;

package/src/interface/__tests__/tool-workflow-resume.test.ts

@@ -1,227 +0,0 @@
-/**
- * workflow tool resume action 契约（workflow-run-resume-revision U3 / D14）。
- *
- * 覆盖面：
- * - D14 args 校验（场景 24 单元层）：传入 args 与 run-created 帧 argsSummary 的
- *   逐字段深度比对（排除 _runId）——不一致明确拒绝且差异字段可见；一致幂等通过；
- *   不传默认沿用历史（D14 层不拦）。场景级（真链路）用例由 u4b 落地。
- * - argsSummary 截断形态的保守拒绝（全文 args 不进 record，截断摘要不可比对）。
- * - record 流无 run-created 帧 → D14 层透传（资格判据归 core resumeRun 权威文案）。
- * - resumeRun 接线：budgetTimeMs（time 形参透传）/ host / runId；成功文案与 details。
- * - diffResumeArgs 纯逻辑（差异三形态 + 嵌套 + 数组 + _runId 排除）。
- *
- * mock 策略：resume-run 深路径 stub（resumeRun 为 vi.fn——不起锁/IO，只测入口
- * 面与校验层）；record 流用 mkdtemp 真文件（D14 读取面读真实路径）。范式对齐
- * tool-workflow.test.ts（lifecycle 深路径 mock + captureTool 注册层黑盒）。
- */
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-
-// 被 mock 的模块——import 路径与被测源文件的等值实例（vi.mock hoist 后 barrel
-// re-export 与深路径指向同一 mock 实例，对齐 tool-workflow.test.ts 先例）
-import { resumeRun } from "@zhushanwen/subagent-core/orchestration/resume-run.ts";
-
-import { actionResume, diffResumeArgs } from "../tool-workflow.ts";
-
-/** 桩化 resume-run——resumeRun 为 vi.fn（不起锁/record IO，只测入口校验与接线面）。 */
-vi.mock("@zhushanwen/subagent-core/orchestration/resume-run.ts", () => ({
-  resumeRun: vi.fn(),
-}));
-
-// ── fixture ──────────────────────────────────────────────────
-
-let tmpDir: string;
-
-beforeEach(() => {
-  vi.mocked(resumeRun).mockReset();
-  vi.mocked(resumeRun).mockResolvedValue("wf-test");
-  tmpDir = mkdtempSync(join(tmpdir(), "u3-resume-"));
-});
-
-afterEach(() => {
-  rmSync(tmpDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
-  vi.restoreAllMocks();
-});
-
-/** 写 record 流（每行一个 JSON 对象）并返回路径——D14 读取面的真实文件。 */
-function writeRecordStream(lines: unknown[]): string {
-  const path = join(tmpDir, "wf-test.record.jsonl");
-  writeFileSync(path, lines.map((l) => JSON.stringify(l)).join("\n") + "\n", "utf8");
-  return path;
-}
-
-/** run-created 帧（args 含 _runId——对齐 lifecycle runWorkflow 注入后落账形态）。 */
-function runCreatedFrame(argsSummary: string) {
-  return {
-    type: "run-created",
-    seq: 1,
-    ts: 1_700_000_000_000,
-    runId: "wf-test",
-    workflowName: "demo",
-    argsSummary,
-    scriptSource: "// demo",
-  };
-}
-
-/** 最小 deps stub（actionResume 只触 store.stateFilePath 与 resumeRun(deps)）。 */
-function makeDeps(stateFilePath: string): unknown {
-  return {
-    runs: new Map(),
-    store: { stateFilePath: () => stateFilePath },
-    registry: { get: vi.fn(), getPath: vi.fn(), loadAll: vi.fn() },
-  };
-}
-
-// ── diffResumeArgs 纯逻辑 ────────────────────────────────────
-
-describe("diffResumeArgs（D14 深度比对）", () => {
-  it("值不等 → 差异字段可见（场景 24 前半：{a:1} 历史以 {a:2} 发）", () => {
-    expect(diffResumeArgs({ a: 2 }, { a: 1, _runId: "wf-test" })).toEqual([
-      "args.a: resume 2 vs original 1",
-    ]);
-  });
-
-  it("一致 → 空（场景 24 后半：{a:1} 幂等通过）", () => {
-    expect(diffResumeArgs({ a: 1 }, { a: 1, _runId: "wf-test" })).toEqual([]);
-  });
-
-  it("_runId 双侧排除（incoming 侧携带同样不比）", () => {
-    expect(diffResumeArgs({ a: 1, _runId: "other" }, { a: 1, _runId: "wf-test" })).toEqual([]);
-  });
-
-  it("仅 resume 侧有 → unexpected 形态", () => {
-    expect(diffResumeArgs({ a: 1, b: 2 }, { a: 1 })).toEqual([
-      "args.b: resume args only (not in original run)",
-    ]);
-  });
-
-  it("仅原 run 侧有 → missing 形态", () => {
-    expect(diffResumeArgs({ a: 1 }, { a: 1, b: "x" })).toEqual([
-      "args.b: original run only (missing from resume args)",
-    ]);
-  });
-
-  it("嵌套 plain object 递归（路径 a.b 形态）", () => {
-    expect(
-      diffResumeArgs({ cfg: { deep: 1, same: "s" } }, { cfg: { deep: 2, same: "s" } }),
-    ).toEqual(["args.cfg.deep: resume 1 vs original 2"]);
-  });
-
-  it("数组按值整体比（不递归元素）", () => {
-    expect(diffResumeArgs({ items: [1, 2] }, { items: [1, 3] })).toEqual([
-      'args.items: resume [1,2] vs original [1,3]',
-    ]);
-    expect(diffResumeArgs({ items: [1, 2] }, { items: [1, 2] })).toEqual([]);
-  });
-});
-
-// ── actionResume：入口校验与接线 ─────────────────────────────
-
-describe("actionResume", () => {
-  it("runId 缺失 → throw 用法指引（不触 resumeRun）", async () => {
-    await expect(
-      actionResume({ action: "resume" } as never, makeDeps("/nonexistent") as never),
-    ).rejects.toThrow(/resume requires 'runId'/);
-    expect(vi.mocked(resumeRun)).not.toHaveBeenCalled();
-  });
-
-  it("args 与历史不一致 → 拒绝且差异字段可见，不触 resumeRun（场景 24 前半）", async () => {
-    const recordPath = writeRecordStream([runCreatedFrame('{"a":1,"_runId":"wf-test"}')]);
-    const err = await actionResume(
-      { action: "resume", runId: "wf-test", args: { a: 2 } } as never,
-      makeDeps(recordPath) as never,
-    ).catch((e: unknown) => e as Error);
-    expect(err).toBeInstanceOf(Error);
-    expect(err.message).toContain("differ from the original run");
-    expect(err.message).toContain("args.a: resume 2 vs original 1");
-    expect(err.message).toContain("start a new run");
-    expect(vi.mocked(resumeRun)).not.toHaveBeenCalled();
-  });
-
-  it("args 与历史一致 → 幂等通过（场景 24 后半），resumeRun 接线生效", async () => {
-    const recordPath = writeRecordStream([runCreatedFrame('{"a":1,"_runId":"wf-test"}')]);
-    const result = (await actionResume(
-      { action: "resume", runId: "wf-test", args: { a: 1 } } as never,
-      makeDeps(recordPath) as never,
-    )) as { content: Array<{ text: string }>; details: Record<string, unknown> };
-    expect(vi.mocked(resumeRun)).toHaveBeenCalledTimes(1);
-    const [calledRunId, calledDeps, options] = vi.mocked(resumeRun).mock.calls[0]!;
-    expect(calledRunId).toBe("wf-test");
-    expect(calledDeps).toBeDefined();
-    expect((options as { budgetTimeMs?: number }).budgetTimeMs).toBeUndefined();
-    expect(typeof (options as { host?: string }).host).toBe("string");
-    expect(result.content[0]!.text).toContain("Resuming workflow run wf-test");
-    expect(result.details).toMatchObject({ action: "resume", runId: "wf-test", status: "running" });
-  });
-
-  it("args 缺省 → 默认沿用历史（D14 层不拦，不读 record）", async () => {
-    await actionResume(
-      { action: "resume", runId: "wf-test" } as never,
-      makeDeps(join(tmpDir, "missing.record.jsonl")) as never,
-    );
-    expect(vi.mocked(resumeRun)).toHaveBeenCalledTimes(1);
-  });
-
-  it("record 流无 run-created 帧 → D14 层透传（资格判据归 resumeRun 权威文案）", async () => {
-    const recordPath = writeRecordStream([
-      { type: "phase-started", seq: 1, ts: 1, phase: "p1" },
-    ]);
-    await actionResume(
-      { action: "resume", runId: "wf-test", args: { a: 1 } } as never,
-      makeDeps(recordPath) as never,
-    );
-    expect(vi.mocked(resumeRun)).toHaveBeenCalledTimes(1);
-  });
-
-  it("argsSummary 截断 → 保守拒绝（无法逐字段比对；引导免 args resume 或开新 run）", async () => {
-    const long = "x".repeat(300);
-    const recordPath = writeRecordStream([runCreatedFrame(`{"payload":"${long}","_runId":"wf-test"}…`)]);
-    const err = await actionResume(
-      { action: "resume", runId: "wf-test", args: { payload: long } } as never,
-      makeDeps(recordPath) as never,
-    ).catch((e: unknown) => e as Error);
-    expect(err).toBeInstanceOf(Error);
-    expect(err.message).toContain("exceed the record's args summary limit");
-    expect(vi.mocked(resumeRun)).not.toHaveBeenCalled();
-  });
-
-  it("argsSummary 被篡改为非法 JSON → 拒绝含恢复指引（不含裸 SyntaxError；U21 与 malformed 分支同构）", async () => {
-    // 字段篡改形态：未截断摘要字符串是非法 JSON（JSON.stringify 只把它当字符串值
-    // 序列化，读取面 parse 必炸）——catch 后抛结构化拒绝文案，原生 SyntaxError
-    // 不透出。
-    const recordPath = writeRecordStream([runCreatedFrame("{broken json")]);
-    const err = await actionResume(
-      { action: "resume", runId: "wf-test", args: { a: 1 } } as never,
-      makeDeps(recordPath) as never,
-    ).catch((e: unknown) => e as Error);
-    expect(err).toBeInstanceOf(Error);
-    expect(err.message).toContain("Resume rejected: original args of run wf-test are malformed");
-    expect(err.message).toContain("Recovery: inspect the record file");
-    expect(err.message).toContain("start a new run");
-    expect(err.message).not.toContain("SyntaxError");
-    expect(vi.mocked(resumeRun)).not.toHaveBeenCalled();
-  });
-
-  it("time 形参透传 budgetTimeMs（u2 偏差②：预算经 D14 同款通道传入）", async () => {
-    const recordPath = writeRecordStream([runCreatedFrame('{"a":1}')]);
-    await actionResume(
-      { action: "resume", runId: "wf-test", args: { a: 1 }, time: 120_000 } as never,
-      makeDeps(recordPath) as never,
-    );
-    const options = vi.mocked(resumeRun).mock.calls[0]![2] as { budgetTimeMs?: number };
-    expect(options.budgetTimeMs).toBe(120_000);
-  });
-
-  it("time 负值 → 入口护栏拒绝（与 run action 同源 assertEntryTimeBudget）", async () => {
-    await expect(
-      actionResume(
-        { action: "resume", runId: "wf-test", time: -1 } as never,
-        makeDeps("/nonexistent") as never,
-      ),
-    ).rejects.toThrow(/time/);
-    expect(vi.mocked(resumeRun)).not.toHaveBeenCalled();
-  });
-});

package/src/interface/gui-mappers.ts

@@ -1,81 +0,0 @@
-/**
- * GUI 协议映射辅助函数 —— run/subagent 状态字符串 → 协议 TreeItem 状态 + 图标。
- *
- * 协议包 @zhushanwen/extension-protocol 的 list-tree 组件用 TreeItem.status（三态）
- * + TreeItem.icon 表达运行态。本模块把 workflow/subagent 领域的丰富状态字符串收口
- * 到这两个枚举，供 helpers.ts / tool-workflow.ts / subagent-actions.ts 复用。
- *
- * 参考：@zhushanwen/extension-protocol GuiComponentProps['list-tree']。
- */
-
-import type { GuiContext, TreeItem, TreeItemIcon } from "@zhushanwen/extension-protocol";
-
-/**
- * 从 Pi ExtensionContext 构造协议 GuiContext 的最小子集。
- *
- * Pi SDK 的 ExtensionContext 在结构上满足协议 GuiContext（有 mode/hasUI/ui），
- * 但 ui.custom 的泛型签名与协议 GuiContext.ui.custom 不兼容（前者复杂泛型，后者
- * 简化签名），直接 `as GuiContext` 会触发 TS 结构兼容错误（ui.custom 参数逆变）。
- * 此 helper 显式提取 mode/hasUI，构造最小 GuiContext，规避 ui.custom 签名冲突。
- *
- * 与 ask-user extension 的 runRpcInteraction 同构（见 ask-user/src/index.ts）。
- */
-export function toGuiCtx(ctx: { mode: GuiContext["mode"]; hasUI: boolean } | undefined): GuiContext | undefined {
-  if (!ctx) return undefined;
-  return { mode: ctx.mode, hasUI: ctx.hasUI };
-}
-
-/** TreeItem.status 枚举（协议三态）。 */
-type TreeStatus = NonNullable<TreeItem["status"]>;
-
-/**
- * 状态字符串是否为失败态（mapRunStatus/mapRunIcon 共享谓词——两映射仅返回值形态不同，
- * 关键词表必须同步演化，抽单点防双写漂移）。入参须已 toLowerCase。
- */
-function isFailedStatus(s: string): boolean {
-  return (
-    s.includes("failed") ||
-    s.includes("abort") ||
-    s.includes("cancel") ||
-    s.includes("crash") ||
-    s.includes("error") ||
-    s.includes("budget") ||
-    s.includes("time_limited")
-  );
-}
-
-/**
- * 把 workflow/subagent 状态字符串映射到 list-tree 的三态 status。
- *
- * 输入可能是纯 RunStatus（running/done）、RunStatus+reason 组合
- * （如 "done (failed)"），或 subagent status（running/idle/legacy done/failed/
- * cancelled/crashed）。
- *
- * 映射规则：
- *   - running → running
- *   - failed / aborted / error / crashed / cancelled / budget_limited / time_limited → failed
- *   - 其他（done / completed / success / pending / idle）→ done
- *
- * [U8 两态] subagent 的 idle（无任务在飞可续聊）在协议三态里落 done（空闲 = 无
- * 进行中工作，check 图标）；「为什么停」不进树形状态（协议无该维度）。
- */
-export function mapRunStatus(status: string): TreeStatus {
-  const s = status.toLowerCase();
-  if (s.includes("running")) return "running";
-  if (isFailedStatus(s)) return "failed";
-  return "done";
-}
-
-/**
- * 把状态字符串映射到 TreeItem.icon。
- *
- *   running                       → circle（进行中）
- *   failed/abort/cancel/crash     → cross
- *   其他（done）                  → check
- */
-export function mapRunIcon(status: string): TreeItemIcon {
-  const s = status.toLowerCase();
-  if (s.includes("running")) return "circle";
-  if (isFailedStatus(s)) return "cross";
-  return "check";
-}