@zhushanwen/pi-agent-ext 1.2.2 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-agent-ext",
-  "version": "1.2.2",
+  "version": "1.4.0",
   "description": "taiji extension for Pi — internal host commands for extension reload and system prompt fetch",
   "type": "module",
   "main": "src/index.ts",

package/src/__tests__/agent-ext.test.ts

@@ -3,18 +3,26 @@
  *
  * 复用 system-prompt-trace index-wiring.test.ts 的 Proxy 假体模式：
  * - pi 用 Proxy 假体：捕获 registerCommand 注册的命令定义 + appendEntry 落点
- * - ctx 只需 index.ts 实际消费的字段（reload / getSystemPrompt），
+ * - ctx 只需 index.ts 实际消费的字段（getSystemPrompt / navigateTree），
  *   以 ExtensionCommandContext 最小形状驱动 handler（SDK 双参契约 (args, ctx)）
  * - index.ts 对 @earendil-works/pi-coding-agent 是 type-only import（运行时擦除），
  *   无需 vi.mock SDK 模块
  *
  * 锚定两命令注册面 + handler 行为：
- * - __taiji_reload__（host 触发的 skill/extension 重载内部命令）→ ctx.reload()
  * - __taiji_get_system_prompt__（Trace 视图「现取当前值」通道）→ pi.appendEntry
  *   写 taiji:current-system-prompt custom entry（fullText/charCount/fetchedAt 形状）
+ * - __taiji_nav__（消息撤回信令，ADR-0076 D1）→ handler 以显式 await 把
+ *   ctx.navigateTree(entryId, {summarize:false, label:'taiji:revoked'}) 的 promise
+ *   纳入自身返回链——写法契约判别断言（deferred sentinel 时序判别）：handler 返回
+ *   promise（非 undefined）且其 settle 严格晚于 navigateTree 的 sentinel settle
+ *   （fire-and-forget 花括号体：同步体返回 undefined / async 无 await 体先 settle，
+ *   两违禁形态均在断言处红）
  *
  * [HISTORICAL] session tree 导航命令（旧品牌时期命名）及其测试随命令删除一并移除
- * （2026-08-31，桥接对端 runtime 消费端已在 monorepo 时代删除）。
+ * （2026-08-31，桥接对端 runtime 消费端已在 monorepo 时代删除）；随消息撤回设计
+ * （ADR-0076）以 __taiji_nav__ 形态回归，本文件同步锚定其注册面与写法契约。
+ * [HISTORICAL] __taiji_reload__ 及其测试随 W5 skill 变更→pi reload 编排退役一并移除
+ * （2026-09-25，消费端已 D7 切源 taiji SkillRegistry，pi 侧列表滞后归 ADR-0050 降级）。
  *
  * 运行：cd extensions/taiji/agent-ext && npx vitest run
  */
@@ -27,7 +35,10 @@ import type {
 
 interface RecordedCommand {
   description: string;
-  handler: (args: string, ctx: ExtensionCommandContext) => Promise<void> | void;
+  handler: (
+    args: string,
+    ctx: ExtensionCommandContext,
+  ) => Promise<unknown> | void;
 }
 
 interface RecordedEntry {
@@ -63,20 +74,20 @@ function createWiringHarness(): WiringHarness {
   return { pi, commands, entries };
 }
 
-/** ctx 假体（index.ts 实际消费：reload / getSystemPrompt；vi.fn 捕获调用）。 */
+/** ctx 假体（index.ts 实际消费：getSystemPrompt / navigateTree；vi.fn 捕获调用）。 */
 function createCtx(prompt = "current system prompt"): {
   ctx: ExtensionCommandContext;
-  reload: ReturnType<typeof vi.fn>;
   getSystemPrompt: ReturnType<typeof vi.fn>;
+  navigateTree: ReturnType<typeof vi.fn>;
 } {
-  const reload = vi.fn();
   const getSystemPrompt = vi.fn(() => prompt);
+  const navigateTree = vi.fn(() => Promise.resolve({ cancelled: false }));
   const ctx = {
     cwd: "/home/user/project",
-    reload,
     getSystemPrompt,
+    navigateTree,
   } as unknown as ExtensionCommandContext;
-  return { ctx, reload, getSystemPrompt };
+  return { ctx, getSystemPrompt, navigateTree };
 }
 
 /** 以 SDK 双参契约 (args, ctx) 驱动已注册命令 handler。 */
@@ -98,13 +109,13 @@ async function loadExtension(): Promise<(pi: ExtensionAPI) => void> {
 }
 
 describe("index.ts wiring SDK 契约", () => {
-  it("注册恰好两个命令（__taiji_reload__ / __taiji_get_system_prompt__），各带非空 description", async () => {
+  it("注册恰好两个命令（__taiji_get_system_prompt__ / __taiji_nav__），各带非空 description", async () => {
     const ext = await loadExtension();
     const h = createWiringHarness();
     ext(h.pi);
     expect([...h.commands.keys()].sort()).toEqual([
       "__taiji_get_system_prompt__",
-      "__taiji_reload__",
+      "__taiji_nav__",
     ]);
     for (const def of h.commands.values()) {
       expect(typeof def.description).toBe("string");
@@ -113,16 +124,6 @@ describe("index.ts wiring SDK 契约", () => {
     }
   });
 
-  it("__taiji_reload__ handler → 调 ctx.reload()（host 触发的 skill/extension 重载，无参）", async () => {
-    const ext = await loadExtension();
-    const h = createWiringHarness();
-    ext(h.pi);
-    const { ctx, reload } = createCtx();
-    await runCommand(h, "__taiji_reload__", "", ctx);
-    expect(reload).toHaveBeenCalledTimes(1);
-    expect(reload).toHaveBeenCalledWith();
-  });
-
   it("__taiji_get_system_prompt__ → appendEntry 写 taiji:current-system-prompt（fullText/charCount/fetchedAt 形状，不写其他 customType）", async () => {
     const ext = await loadExtension();
     const h = createWiringHarness();
@@ -141,4 +142,63 @@ describe("index.ts wiring SDK 契约", () => {
     expect(typeof data.fetchedAt).toBe("string");
     expect(Number.isNaN(Date.parse(String(data.fetchedAt)))).toBe(false);
   });
+
+  it("__taiji_nav__ → 调 ctx.navigateTree 参数三件套逐字（entryId 直传 / summarize:false / label:'taiji:revoked'）", async () => {
+    const ext = await loadExtension();
+    const h = createWiringHarness();
+    ext(h.pi);
+    const { ctx, navigateTree } = createCtx();
+    await runCommand(h, "__taiji_nav__", "msg-entry-1", ctx);
+
+    expect(navigateTree).toHaveBeenCalledTimes(1);
+    expect(navigateTree).toHaveBeenCalledWith("msg-entry-1", {
+      summarize: false,
+      label: "taiji:revoked",
+    });
+  });
+
+  it("__taiji_nav__ handler 把 navigateTree 的 promise 纳入自身返回链（D1 写法契约判别：返回 promise 非 undefined 且 settle 严格晚于 navigateTree——非 fire-and-forget）", async () => {
+    const ext = await loadExtension();
+    const h = createWiringHarness();
+    ext(h.pi);
+    // deferred sentinel：可控 resolve 时点。写法契约（D1）：pi `await command.handler(...)`
+    // 接住的 promise 必须等待 navigateTree 完成——「revokeMessage reply 前树变更+落盘
+    // 完成」的保证链。判别两违禁形态：①同步花括号体 fire-and-forget 返回 undefined；
+    // ②async 无 await 体返回的 promise 先于 sentinel settle。
+    // 注：SDK 0.84.4 RegisteredCommand.handler 钉死 Promise<void>，「直接 return
+    // navigateTree promise」形态编译不过（TS2322），故 D1 许可形态为显式 await，判别
+    // 断言用 settle 时序而非 promise 引用全等。
+    let resolveNav!: (value: { cancelled: boolean }) => void;
+    const sentinel = new Promise<{ cancelled: boolean }>((resolve) => {
+      resolveNav = resolve;
+    });
+    const { ctx, navigateTree } = createCtx();
+    navigateTree.mockReturnValue(sentinel);
+
+    const cmd = h.commands.get("__taiji_nav__");
+    if (cmd === undefined) throw new Error('command "__taiji_nav__" not registered');
+
+    const returned = cmd.handler("msg-entry-2", ctx);
+    // 违禁形态 ①：fire-and-forget 同步花括号体返回 undefined
+    expect(returned).toBeInstanceOf(Promise);
+    const returnedPromise = returned as Promise<unknown>;
+    let handlerSettled = false;
+    void returnedPromise.then(() => {
+      handlerSettled = true;
+    });
+    // 泵微任务：给违禁形态 ②（async 无 await 体）让它的 promise 先 settle 的机会
+    await Promise.resolve();
+    await Promise.resolve();
+    // sentinel 未 resolve 前，handler 的 promise 不得 settle——fire-and-forget 在此红
+    expect(handlerSettled).toBe(false);
+
+    resolveNav({ cancelled: false });
+    await returnedPromise;
+    expect(handlerSettled).toBe(true);
+    expect(navigateTree).toHaveBeenCalledTimes(1);
+    expect(navigateTree).toHaveBeenCalledWith("msg-entry-2", {
+      summarize: false,
+      label: "taiji:revoked",
+    });
+  });
 });

package/src/index.ts

@@ -1,30 +1,25 @@
 /**
  * taiji extension for Pi — internal commands for the host.
  *
- * Registers `/__taiji_reload__` internal command for host-triggered
- * skill/extension reload, and `/__taiji_get_system_prompt__` for the Trace
- * view fetch-current button.
+ * Registers `/__taiji_get_system_prompt__` (Trace view fetch-current button)
+ * and `/__taiji_nav__` (session tree rewind for message revoke).
  *
- * [HISTORICAL] The former session tree navigation command was removed
- * (2026-08-31): its bridge consumer on the runtime side was deleted in the
- * monorepo era, so the command had no reachable caller. See the ADR-0008
- * note in the retired-decisions genealogy of docs/adr/decisions.md for the
- * original design.
+ * [HISTORICAL] The session tree navigation command was removed 2026-08-31:
+ * its bridge consumer on the runtime side had been deleted, leaving the
+ * command with no reachable caller (ADR-0008). It returns as `__taiji_nav__`
+ * under the message-revoke design (ADR-0076, decision D1) — the runtime
+ * revoke orchestration is the new consumer.
+ * [HISTORICAL] `/__taiji_reload__` was removed (2026-09-25): the W5
+ * skill-change→pi-reload orchestration was retired — slash menu and composer
+ * injection resolve skills from the taiji SkillRegistry (D7 source switch),
+ * so a full pi reload (extension ctx invalidate + clearExtensionCache, which
+ * broke background-task completion notifications in the stale module world)
+ * bought nothing but stale-pi-side lists, accepted per ADR-0050 degradation.
  */
 
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 
 export default function (pi: ExtensionAPI): void {
-  // W5: builtin internal reload command. `/__taiji_reload__` 由 host 在 skill 文件变动时
-  // 经 client.prompt 发起（不经 LLM），handler 调 pi ctx.reload() 重扫 skill + 重建 runtime。
-  // 双下划线前缀 = 内部命令（前端 W4 internal-command-filter 过滤 `/__` 前缀不显示）。
-  pi.registerCommand('__taiji_reload__', {
-    description: 'Internal: reload skills/extensions/prompts (triggered by host on skill file change)',
-    handler: async (_args: string, ctx: ExtensionCommandContext) => {
-      await ctx.reload();
-    },
-  });
-
   // [fetch-current-system-prompt] Trace 视图「现取当前值」通道（session-trace design §3.1
   // 失败路径 / D2）：pi RPC 无 get_system_prompt 命令、getSystemPrompt() 只在 extension
   // API，且现取不能依赖可禁的留痕包（system-prompt-trace 是 feature tier）——挂本
@@ -46,4 +41,30 @@ export default function (pi: ExtensionAPI): void {
       });
     },
   });
+
+  // [message-revoke D1] 已消费层（消息已注入模型上下文）撤回信令：runtime 撤回编排经
+  // 系统信令入口直达 client.prompt('/__taiji_nav__ <entryId>')——command 同步执行、
+  // 不进模型、无 turn（pi agent-session _tryExecuteExtensionCommand）。entryId 从命令
+  // args 取（pi 切首个空格后的原样余串，单空格形态下精确等于 entryId——pi-semantics
+  // PS-63 实锚：dist/core/agent-session.js:956-958）。
+  // 双下划线前缀 = 内部命令（前端 internal-command-filter 过滤 `/__` 前缀不显示）。
+  // summarize:false = 不触发 tree summary；label:'taiji:revoked' = pi 追加 LabelEntry
+  // 落盘（树重放规则 leaf=文件尾，重启/空闲回收后回退不复活——pi-semantics PS-60 实锚：
+  // dist/core/session-manager.js:673 _buildIndex 文件序循环置 leafId=entry.id、:616
+  // _setSessionFile 加载路径重放；navigateTree 回退 = branch() 移指针 + appendLabelChange
+  // 落锚文件尾两步，dist/core/agent-session.js:2464）。
+  // 写法契约（D1 硬要求）：handler 必须把 navigateTree 的 promise 纳入自身返回链——
+  // pi `await command.handler(...)` 接住返回值是「revokeMessage reply 前树变更+落盘
+  // 完成」的保证链。取 D1 许可形态「显式 await」而非「直接 return」：SDK 0.84.4
+  // RegisteredCommand.handler 钉死 `(args, ctx) => Promise<void>`，直接 return
+  // navigateTree 的 `Promise<{cancelled}>` 编译不过（TS2322，as 断言亦被拒/禁）。
+  // fire-and-forget（去掉 await）会使 reply 先于树变更，产生偶发假阴性 nav-failed——
+  // 禁止。
+  pi.registerCommand('__taiji_nav__', {
+    description:
+      'Internal: rewind the session tree to before the target entry (host-triggered for message revoke)',
+    handler: async (entryId: string, ctx: ExtensionCommandContext) => {
+      await ctx.navigateTree(entryId, { summarize: false, label: 'taiji:revoked' });
+    },
+  });
 }