@zhushanwen/pi-subagent-workflow 8.9.0 → 8.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-subagent-workflow",
-  "version": "8.9.0",
+  "version": "8.10.0",
   "type": "module",
   "main": "index.ts",
   "description": "Unified subagent execution and multi-agent workflow orchestration for Pi — spawned-process agent runtime with sync/background modes, stateful workflow management with persistence, state machine, and execution tracing.",
@@ -58,15 +58,17 @@
     "@xyz-agent/session-delivery": "0.3.1",
     "@zhushanwen/pi-ext-guards": "0.2.1",
     "@zhushanwen/pi-extension-logger": "0.4.1",
-    "@zhushanwen/subagent-core": "0.6.0"
+    "@zhushanwen/subagent-core": "0.7.0",
+    "@zhushanwen/pi-subagent-cli": "0.1.1",
+    "@zhushanwen/zcode-subagent-cli": "0.1.1"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "^0.84.4",
     "@earendil-works/pi-coding-agent": "^0.84.4",
     "@earendil-works/pi-tui": "^0.84.4",
     "typebox": "*",
-    "@zhushanwen/pi-pending-notifications": "0.5.3",
-    "@zhushanwen/pi-structured-output": "5.1.3"
+    "@zhushanwen/pi-pending-notifications": "0.6.0",
+    "@zhushanwen/pi-structured-output": "5.1.4"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-coding-agent": {

package/relay/relay.mjs

@@ -8,8 +8,9 @@
  * 通道，payload 一律 base64 封装保字节精确。
  *
  * ============================ 镜像常量表 ============================
- * SSOT = packages/subagent-core/src/execution/relay-env.ts（零依赖脚本不能 import workspace 包，只能内嵌镜像；
- * 改名/改值必须双侧同步，一致性由 E-3 conformance relay 变体断言锁定——设计 §10-5）：
+ * SSOT = packages/subagent-engine-sdk/src/relay-env.ts（零依赖脚本不能 import workspace 包，只能内嵌镜像；
+ * core 侧经 subagent-core 的 ./relay-env 子入口 re-export 保 semver 面。改名/改值必须双侧同步，
+ * 一致性由 E-3 conformance relay 变体断言锁定——设计 §10-5）：
  *
  *   | relay-env.ts 常量         | 本文件常量                | 值                          |
  *   |---------------------------|---------------------------|-----------------------------|

package/src/host/__tests__/pi-host.test.ts

@@ -197,20 +197,31 @@ describe("createPiHostServices.log（桥接 pi-extension-logger）", () => {
 });
 
 describe("createPiNotifyDomainPorts.countActiveFromEntries（适配读 .count）", () => {
-  it("拆 CountActiveResult.count 为 number（core 端口契约），entries 透传", () => {
-    const entries: unknown[] = [{ customType: "pending:register" }];
-    vi.mocked(countActiveFromEntries).mockReturnValue({ count: 3, ids: ["a", "b", "c"], entries: [] });
+	it("拆 CountActiveResult.count 为 number（core 端口契约），entries 透传（缺省过滤基准 undefined = 不过滤）", () => {
+		const entries: unknown[] = [{ customType: "pending:register" }];
+		vi.mocked(countActiveFromEntries).mockReturnValue({ count: 3, ids: ["a", "b", "c"], entries: [] });
 
-    const result = createPiNotifyDomainPorts().countActiveFromEntries?.(entries);
+		const result = createPiNotifyDomainPorts().countActiveFromEntries?.(entries);
 
-    expect(result).toBe(3);
-    expect(vi.mocked(countActiveFromEntries)).toHaveBeenCalledWith(entries);
-  });
+		expect(result).toBe(3);
+		// [W4 读侧过滤②] 端口适配恒透传过滤基准 opts（缺省 undefined = 不过滤，
+		// 既有调用方零改动行为不变）。
+		expect(vi.mocked(countActiveFromEntries)).toHaveBeenCalledWith(entries, { currentSessionId: undefined });
+	});
 
-  it("零活跃返回 0（{count: 0} 形状）", () => {
-    vi.mocked(countActiveFromEntries).mockReturnValue({ count: 0, ids: [], entries: [] });
-    expect(createPiNotifyDomainPorts().countActiveFromEntries?.([])).toBe(0);
-  });
+	it("[W4 读侧过滤② / F1] 调用时传 currentSessionId（per-call 基准）→ 透传差集过滤基准", () => {
+		const entries: unknown[] = [{ customType: "pending:register" }];
+		vi.mocked(countActiveFromEntries).mockReturnValue({ count: 1, ids: ["a"], entries: [] });
+
+		createPiNotifyDomainPorts().countActiveFromEntries?.(entries, { currentSessionId: "sess-child" });
+
+		expect(vi.mocked(countActiveFromEntries)).toHaveBeenCalledWith(entries, { currentSessionId: "sess-child" });
+	});
+
+	it("零活跃返回 0（{count: 0} 形状）", () => {
+		vi.mocked(countActiveFromEntries).mockReturnValue({ count: 0, ids: [], entries: [] });
+		expect(createPiNotifyDomainPorts().countActiveFromEntries?.([])).toBe(0);
+	});
 });
 
 describe("createPiNotifyDomainPorts.createDelivery（透传 session-delivery）", () => {

package/src/host/pi-host.ts

@@ -29,6 +29,7 @@
 
 import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { getLogger } from "@zhushanwen/pi-extension-logger";
@@ -117,6 +118,45 @@ function skillRoots(): DiscoveryRoot[] {
   ];
 }
 
+/**
+ * 引擎包发现根（W4 L1 第二通道，设计 §3.4）。打包态主通道 = env
+ * XYZ_AGENT_ENGINE_ROOTS（W9 注入），此处承载 pi 宿主的常规安装路径：
+ *   1. 宿主包自身 node_modules——引擎包（<engine>-subagent-cli）作为本包
+ *      dependencies 安装位（W9「扩展 package.json 声明引擎包为 dependencies」）；
+ *   2. <agentDir>/npm/node_modules——pi npm 安装位（org 分组二层布局由扫描器
+ *      下钻覆盖）；
+ *   3. <agentDir>/extensions——dev symlink 位（agents kind 同款 npm-dev 根）。
+ * 根目录不存在时由扫描器静默跳过（不在此预检）。 */
+function engineRoots(): DiscoveryRoot[] {
+  const agentDir = getAgentDir();
+  const roots: DiscoveryRoot[] = [];
+  const selfNodeModules = hostPackageNodeModulesRoot();
+  if (selfNodeModules !== undefined) {
+    roots.push({ dir: selfNodeModules, source: "npm" });
+  }
+  roots.push({ dir: join(agentDir, "npm", "node_modules"), source: "npm" });
+  roots.push({ dir: join(agentDir, "extensions"), source: "npm-dev" });
+  return roots;
+}
+
+/** 宿主包（本扩展）node_modules 根：src/host/pi-host.ts 上溯三级 = 包根。
+ *  jiti 加载下 import.meta.url 可用（corePackageNpmRoot 同款可靠性先例）；解析失败
+ *  降级为不注入并 warn——绝不因根定位失败阻断发现主链。 */
+function hostPackageNodeModulesRoot(): string | undefined {
+  try {
+    const here = fileURLToPath(import.meta.url);
+    // src/host/pi-host.ts → src/host → src → 包根
+    const packageRoot = dirname(dirname(dirname(here)));
+    return join(packageRoot, "node_modules");
+  } catch (err) {
+    getLogger("pi-host").warn(
+      "[pi-host] 宿主包 node_modules 引擎发现根解析失败——dependencies 安装的引擎包可能不可发现",
+      { reason: toErrorMessage(err) },
+    );
+    return undefined;
+  }
+}
+
 /** pi 宿主 HostServices 实现（扩展初始化最早处经 configureCore 注入）。 */
 export function createPiHostServices(): HostServices {
   return {
@@ -139,23 +179,37 @@ export function createPiHostServices(): HostServices {
       agents?: DiscoveryRoot[];
       skills?: DiscoveryRoot[];
       workflows?: DiscoveryRoot[];
+      engines?: DiscoveryRoot[];
     } {
       return {
         agents: agentDirKindRoots("agents"),
         skills: skillRoots(),
         workflows: agentDirKindRoots("workflows"),
+        engines: engineRoots(),
       };
     },
   };
 }
 
-/** pi 侧通知域窄端口实现（configureNotifyDomain 注入）。zsw 壳不注入本端口
- *  （其完成通知走 HostServices.notify，P2 落地）。 */
+/**
+ * pi 侧通知域窄端口实现（configureNotifyDomain 注入）。zsw 壳不注入本端口
+ * （其完成通知走 HostServices.notify，P2 落地）。
+ *
+ * [F1 形态升级] 跨 session 残留过滤基准（W4 读侧过滤②）不走 factory 定型——本装配
+ * 在扩展模块加载时执行一次，session id 逐 session 变化（session_start 每次更新），
+ * factory 参数表达不了 per-call 基准；且生产装配点从未传参（注释声称的防御实际
+ * 缺基准）。现形态 = core 端口契约第二参（NotifyDomainPorts.countActiveFromEntries
+ * 的 opts）per-call 透传，基准由 core 读侧按「被读 entries 所属 session」提供
+ * （session-pending.ts 读 pi session 文件首行 SessionHeader.id）——fork 继承的父级
+ * 注册残留不进后代判定差集，防御真实生效。
+ */
 export function createPiNotifyDomainPorts(): NotifyDomainPorts {
   return {
     // pi 真函数返回 CountActiveResult，core 契约只读 .count——壳侧拆数值。
-    countActiveFromEntries(entries: unknown[]): number {
-      return countActiveFromEntries(entries).count;
+    // [W4 读侧过滤② / F1] per-call 基准透传差集口径（缺省 undefined = 不过滤，
+    // 向后兼容：无基准的调用方零改动行为不变）。
+    countActiveFromEntries(entries: unknown[], opts?: { currentSessionId?: string }): number {
+      return countActiveFromEntries(entries, { currentSessionId: opts?.currentSessionId }).count;
     },
 
     // 投递内核工厂直传本体（结构兼容论证见文件头）；不经包装避免多一层间接面。

package/src/index.ts

@@ -26,10 +26,11 @@ import { bestEffort } from "@zhushanwen/subagent-core";
 // ═══ execution/ 层（subagents 核心 + 运行时） ═══
 // [U7] 引擎列表状态文件（registry → engines.json，GUI 引擎选择器数据源）
 import { syncEnginesFile } from "@zhushanwen/subagent-core";
-// [P1 引擎接线] 组合根登记 'pi' 引擎进 registry（引擎获取统一经 getEngine，缺省 id 'pi'）
-import { registerPiEngine } from "@zhushanwen/subagent-core";
-// [P3 引擎接线] 组合根登记 'zcode' 引擎（spawn 单轮模式；engineDataDir 默认走
-// common/data-dir SSOT，见 engines/zcode/registration.ts）
+// [W11/DoD#5] registerPiEngine（inproc 'pi' 注册）已随内建引擎删除：registry 'pi'
+// 由下方 syncEnginesFile 的三级发现装载 cli descriptor（engines/zcode 同理由
+// registerZcodeEngine D8 薄壳承载）。
+// [P3 引擎接线] 组合根登记 'zcode' 引擎（D8 薄壳：vendored 定位 cli descriptor；
+// engineDataDir 默认走 common/data-dir SSOT）
 import { registerZcodeEngine } from "@zhushanwen/subagent-core";
 import { getModelConfigService } from "@zhushanwen/subagent-core";
 import { getBoundNotifyLedger } from "@zhushanwen/subagent-core";
@@ -132,16 +133,17 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
   // 完整；且先于任何可能消费 core 端口的初始化逻辑（引擎登记等）。缺省态若被消费，
   // dataRoot 抛 core_host_not_configured（§3.4），接线后不再可达。
   configureCore(createPiHostServices());
+  // [F1] 通知域端口无 factory 基准参数：跨 session 残留过滤基准（W4 读侧过滤②）
+  // 由 core 读侧 per-call 提供（session-pending 读「被读 entries 所属 session」）——
+  // 本装配在扩展启动时执行一次，session id 逐 session 变化，factory 定型表达不了
+  // per-call 基准（生产装配也从未传参，防御曾实际缺基准）。
   configureNotifyDomain(createPiNotifyDomainPorts());
 
-  // [P1 引擎接线] 组合根登记缺省引擎：进程级 SubagentService 单例（session_start 注入）
-  // 经 registry 以 'pi' 暴露——引擎获取从此统一走 getEngine(DEFAULT_ENGINE_ID)，上层
-  // 不再硬编码「spawn pi」。幂等（registerEngine 覆盖语义），工厂惰性解析服务单例。
-  // P4 配置路由（agent frontmatter engine 字段 + 三层优先级）在本登记之上消费。
-  registerPiEngine();
-
-  // [P3 引擎接线] 登记 'zcode'（幂等同上）。惰性工厂：不触发 CLI/凭据探测，引擎被
-  // 实际选用（P4 路由或显式 getEngine('zcode')）才解析 deps。
+  // [W11/DoD#5] 'pi' 的 inproc 注册（registerPiEngine）已删除——缺省引擎 'pi' 的
+  // registry 条目由下方 syncEnginesFile 内的三级发现装载（cli descriptor，幂等），
+  // P4 配置路由（agent frontmatter engine 字段 + 三层优先级）在其上消费；chat 域
+  // pi 引擎不经 registry（SubagentService 自持 DI，W11 主 agent 裁决的临时豁免面）。
+  // [P3 引擎接线] 登记 'zcode'（幂等同上）。D8 薄壳：vendored 定位 cli descriptor。
   registerZcodeEngine();
 
   // [U7b] 引擎列表在 extension 模块加载时即同步 engines.json（不等 session_start——

package/src/interface/subagent-tool-schema.ts

@@ -1,6 +1,6 @@
 // src/interface/subagent-tool-schema.ts
 //
-// `subagent` 工具的参数 schema 纯常量叶子（零运行时依赖，先例 shared/schema-env.ts）。
+// `subagent` 工具的参数 schema 纯常量叶子（零运行时依赖）。
 //
 // 抽取自 subagent-tool.ts（跨包契约另一半）：subagent-tool 依赖树沉重（pi SDK /
 // handler / render 链），structured-output 侧的跨包契约测试若从它 import schema

package/src/jsonl-run-store.ts

@@ -87,6 +87,7 @@ import {
   SNAPSHOT_VERSION,
   fromRunSnapshot,
   toRunSnapshot,
+  pruneStateFilesBeyondCap,
   type RunSnapshot,
 } from "@zhushanwen/subagent-core";
 import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
@@ -217,56 +218,11 @@ async function loadRunFromStateFile(filePath: string): Promise<WorkflowRun | nul
 }
 
 // ── State file retention (OR-5 ⑥b, default-on) ───────────────
-
-/** run state 文件名 glob：runId 形如 `wf-<ts>-<rand>`（lifecycle.ts 生成），只删命中者。
- *  同目录可能存在的非 state 文件（及 session JSONL——在父目录，本就不在扫描范围）永不碰。 */
-const STATE_FILE_GLOB = /^wf-.*\.jsonl$/;
-
-/**
- * 把 workflow-state 目录裁剪到 maxRuns 个最新 state 文件（mtime 升序，删最旧）。
- *
- * 只删本目录内命中 {@link STATE_FILE_GLOB} 的文件；任何失败都不抛（清理是旁路
- * 维护，不能拖垮持久化主链路）：readdir/stat 失败静默放弃本轮，单个 unlink 失败
- * （非 ENOENT）logger.warn 留证后继续删其余——ENOENT 视为并发删除竞态下的已达成
- * 目标，不告警。
- */
-async function pruneStateFilesBeyondCap(stateDir: string, maxRuns: number): Promise<void> {
-  let names: string[];
-  try {
-    names = await fs.promises.readdir(stateDir);
-  } catch (err) {
-    if (!isEnoentError(err)) {
-      const reason = toErrorMessage(err);
-      logger.warn(`[subagent-workflow] state retention: readdir ${stateDir} failed: ${reason}`);
-    }
-    return;
-  }
-  const stateFiles = names.filter((n) => STATE_FILE_GLOB.test(n)).sort();
-  if (stateFiles.length <= maxRuns) return;
-
-  // stat 全集取 mtime；allSettled 部分降级——单文件 stat 失败（并发删除 ENOENT 等）
-  // 静默跳过该文件，不阻断本轮裁剪
-  const settled = await Promise.allSettled(
-    stateFiles.map(async (name) => {
-      const full = path.join(stateDir, name);
-      return { full, mtimeMs: (await fs.promises.stat(full)).mtimeMs };
-    }),
-  );
-  const byMtimeAsc = settled
-    .flatMap((r) => (r.status === "fulfilled" ? [r.value] : []))
-    .sort((a, b) => a.mtimeMs - b.mtimeMs);
-  const victims = byMtimeAsc.slice(0, byMtimeAsc.length - maxRuns);
-  for (const victim of victims) {
-    try {
-      await fs.promises.unlink(victim.full);
-      logger.debug(`[subagent-workflow] state retention: pruned ${victim.full}`);
-    } catch (err) {
-      if (isEnoentError(err)) continue; // 并发删除已达成目标
-      const reason = toErrorMessage(err);
-      logger.warn(`[subagent-workflow] state retention: failed to delete ${victim.full}: ${reason}`);
-    }
-  }
-}
+//
+// 裁剪主体单源消费 core pruneStateFilesBeyondCap（S4-A7 收口：本地曾有一份逐段
+// 同构的私有实现，retention 语义双份各自演化是漂移隐患）；日志注入本模块
+// logger + [subagent-workflow] tag，错误字符串化用 ext-guards toErrorMessage——
+// 行为与收口前一致（差异仅经 core 单源演化时两宿主同步）。
 
 // ── JsonlRunStore ────────────────────────────────────────────
 
@@ -580,7 +536,13 @@ export class JsonlRunStore {
       if (rollbackFirstWrite) {
         const maxRuns = getEnvStateMaxRuns();
         if (maxRuns !== undefined) {
-          await pruneStateFilesBeyondCap(this.stateDir, maxRuns);
+          // 单源裁剪（core pruneStateFilesBeyondCap），注入本扩展 logger tag 与
+          // toErrorMessage（行为与本地实现收口前一致）
+          await pruneStateFilesBeyondCap(this.stateDir, maxRuns, {
+            warn: (msg) => logger.warn(`[subagent-workflow] ${msg}`),
+            debug: (msg) => logger.debug(`[subagent-workflow] ${msg}`),
+            toMsg: toErrorMessage,
+          });
         }
       }
       for (const s of settlers) s.resolve();