pi-shadow-mind 0.1.15 → 0.1.16

package/DESIGN.md

@@ -340,9 +340,11 @@ Main 在会话中切换模型后，后续 heartbeat 直接依据新模型重新
 
 配置了 `final_response` 的 Shadow 在 Main 发出非空最终文字，并进入 `agent_settled` 状态后参与调度。该模式仍应用 `enabled` 和 `active_for_models`，但绕过 `heartbeat_probability` 与 `activation_probability`，所有匹配项都必须获得一次运行机会。
 
-最终回复检查使用当时的完整净化轨迹快照。`max_parallel_shadows` 仍是硬并发上限；没有空闲槽位或同一 Shadow 正在运行时，检查进入专用队列，槽位释放后继续执行。新用户输入或 Session 关闭会清空旧 epoch 的队列，防止过期结果介入新任务。
+最终回复检查使用当时的完整净化轨迹快照。`max_parallel_shadows` 仍是硬并发上限；没有空闲槽位或同一 Shadow 正在运行时，检查进入专用队列，槽位释放后继续执行。旧 epoch 的运行释放槽位时同样继续泵送当前队列，避免跨 epoch 的异步收尾把检查永久卡住。
 
-检查结果沿用普通 `shadow-report` 的 steer/follow-up 机制。因此 Main 根据报告修正并再次给出最终回复后，可以再次触发完成检查；Shadow 没有发现时保持沉默，循环自然结束。
+每次最终回复检查拥有独立、递增的 review generation。独立的 completion-review 协调器统一拥有 generation、等待队列、运行完成计数和报告聚合，Runtime 只转发宿主生命周期事件与 Shadow 启停通知。同一 generation 的报告先暂存，所有匹配 Shadow 都进入终态后才合并为一次 `shadow-report`；因此较慢的同批检查不会在 Main 已开始修订后单独 steer。新的最终回复、新用户输入、其他报告触发的修订或 Session 关闭都会使旧 generation 失效，并清空尚未启动的项目；仍在收尾的旧运行只能记录 lifetime usage，不能再投递报告。异步刷新配置和 Registry 时还会同时校验启动请求与 epoch，防止等待 I/O 的旧最终回复在新任务中恢复调度。
+
+检查结果沿用普通 `shadow-report` 的 steer/follow-up 机制。因此 Main 根据聚合报告修正并再次给出最终回复后，可以再次触发新一代完成检查；Shadow 没有发现时保持沉默，循环自然结束。
 
 ## 6. Shadow 的输出与介入
 
@@ -362,7 +364,7 @@ Shadow 返回
     └── 丢弃旧结果
 ```
 
-最终回复不会立即终止正在运行的 Shadow。迟到结果仍可在下一条用户消息到来前触发补充回复。
+Heartbeat Shadow 不会因为 Main 给出最终回复而立即终止，迟到结果仍可在下一条用户消息到来前触发补充回复。Final-response Shadow 则按 review generation 聚合，只有整批检查结束后才允许触发一次补充回复。
 
 每个用户任务拥有递增的 `epoch`：
 

package/README.md

@@ -72,7 +72,7 @@ This Shadow is read-only. It reviews the implementation in parallel and reports
 
 Each Shadow chooses one or both activation triggers with `trigger`. The default is `[heartbeat]`: after a main-agent `turn_end` that completed at least one tool call, the extension evaluates the global heartbeat probability, then eligible Shadows roll independently using `activation_probability`. Pure text-only conversation turns are skipped.
 
-Use `trigger: [final_response]` for completion review. It activates after the main agent has emitted its final text, bypasses both heartbeat and activation probability, and sends findings back through the normal `shadow-report` follow-up flow. `trigger: [heartbeat, final_response]` enables both modes. `max_parallel_shadows` remains the concurrency limit; excess final-response checks are queued rather than skipped.
+Use `trigger: [final_response]` for completion review. It activates after the main agent has emitted its final text and bypasses both heartbeat and activation probability. All checks for that final response finish before their findings are sent together through one `shadow-report` follow-up, so a slow sibling cannot leak into a revised answer. `trigger: [heartbeat, final_response]` enables both modes. `max_parallel_shadows` remains the concurrency limit; excess final-response checks are queued rather than skipped.
 
 Each activation starts a fresh temporary session. It inherits the main agent's unchanged system prompt but receives only a sanitized plain-text trajectory: assistant thinking is removed, while tool calls retain compact, deterministic result summaries.
 
@@ -83,7 +83,7 @@ Shadow definitions are ordinary Markdown files. They can be created and adjusted
 ## Installation
 
 ```bash
-pi install npm:pi-shadow-mind@0.1.11
+pi install npm:pi-shadow-mind
 ```
 
 On the first session start, the extension creates:

package/README.zh-CN.md

@@ -69,7 +69,7 @@ tools: [read, grep]
 
 每个 Shadow 可以通过 `trigger` 选择一种或两种激活方式。默认值是 `[heartbeat]`：主 Agent 的一次 `turn_end` 只有在该轮至少完成过一个工具调用时，扩展才进行全局 heartbeat 概率判断，符合条件的 Shadow 再按照各自的 `activation_probability` 独立抽选。纯文本对话轮次不会触发 heartbeat。
 
-使用 `trigger: [final_response]` 可以进行完成后审查。它在主 Agent 发出最终文字并完全 settled 后激活，不受 heartbeat 和 `activation_probability` 影响，检查结果仍通过正常的 `shadow-report` follow-up 流程返回。`trigger: [heartbeat, final_response]` 会同时启用两种模式。`max_parallel_shadows` 仍然限制并发数；超出并发槽位的最终回复检查会排队，而不会被跳过。
+使用 `trigger: [final_response]` 可以进行完成后审查。它在主 Agent 发出最终文字并完全 settled 后激活，不受 heartbeat 和 `activation_probability` 影响。同一最终回复的全部检查结束后，发现会合并为一次 `shadow-report` follow-up，较慢的同批检查不会介入已经修订的回复。`trigger: [heartbeat, final_response]` 会同时启用两种模式。`max_parallel_shadows` 仍然限制并发数；超出并发槽位的最终回复检查会排队，而不会被跳过。
 
 每次激活都会创建一个全新的临时 Session。它继承主 Agent 原封不动的 system prompt，但只接收净化后的文本轨迹：思考内容会被移除，工具调用后仅保留简洁、确定性的结果概述。
 
@@ -80,7 +80,7 @@ Shadow 定义只是普通 Markdown 文件，可以由用户创建和调整，也
 ## 安装
 
 ```bash
-pi install npm:pi-shadow-mind@0.1.11
+pi install npm:pi-shadow-mind
 ```
 
 首次启动 Session 时，扩展会创建：

package/dist/index.js

@@ -12,6 +12,121 @@ import {
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 
+// src/final-response-queue.ts
+var FinalResponseQueue = class {
+  constructor(options) {
+    this.options = options;
+  }
+  pending = [];
+  enqueue(items) {
+    this.pending.push(...items);
+    this.pump();
+  }
+  slotAvailable() {
+    this.pump();
+  }
+  clear() {
+    this.pending.length = 0;
+  }
+  pump() {
+    while (this.options.activeCount() < this.options.maxParallel() && this.pending.length > 0) {
+      const epoch = this.options.currentEpoch();
+      const activeShadowIds = this.options.activeShadowIds();
+      const index = this.pending.findIndex(
+        (item2) => item2.epoch !== epoch || !activeShadowIds.has(item2.shadowId)
+      );
+      if (index < 0) return;
+      const [item] = this.pending.splice(index, 1);
+      if (!item || item.epoch !== epoch) continue;
+      this.options.launch(item);
+    }
+  }
+};
+
+// src/completion-review.ts
+var CompletionReview = class {
+  constructor(host) {
+    this.host = host;
+    this.queue = new FinalResponseQueue({
+      currentEpoch: () => this.host.currentEpoch(),
+      maxParallel: () => this.host.maxParallel(),
+      activeCount: () => this.host.activeCount(),
+      activeShadowIds: () => this.host.activeShadowIds(),
+      launch: ({ job, run }) => host.launch(job, run)
+    });
+  }
+  requestId = 0;
+  state;
+  requestByRun = /* @__PURE__ */ new WeakMap();
+  queue;
+  begin(epoch) {
+    this.invalidate();
+    return { id: this.requestId, epoch };
+  }
+  isCurrent(request) {
+    return request.id === this.requestId && request.epoch === this.host.currentEpoch();
+  }
+  schedule(request, jobs) {
+    if (!this.isCurrent(request) || this.state?.requestId === request.id || jobs.some((job) => job.epoch !== request.epoch)) {
+      return false;
+    }
+    if (jobs.length === 0) {
+      this.retire(request.id);
+      return true;
+    }
+    this.state = {
+      requestId: request.id,
+      epoch: request.epoch,
+      remaining: jobs.length,
+      reports: []
+    };
+    this.queue.enqueue(
+      jobs.map((job) => {
+        const run = {
+          accept: (report) => this.accept(request.id, report)
+        };
+        this.requestByRun.set(run, request.id);
+        return { epoch: job.epoch, shadowId: job.shadowId, job, run };
+      })
+    );
+    return true;
+  }
+  slotAvailable() {
+    this.queue.slotAvailable();
+  }
+  complete(run) {
+    if (!run) return;
+    const requestId = this.requestByRun.get(run);
+    this.requestByRun.delete(run);
+    if (requestId === void 0 || this.state?.requestId !== requestId) return;
+    this.state.remaining -= 1;
+    if (this.state.remaining > 0) return;
+    const reports = this.state.reports;
+    this.retire(requestId);
+    if (reports.length > 0) this.host.deliver(reports);
+  }
+  cancel(request) {
+    if (this.isCurrent(request)) this.retire(request.id);
+  }
+  invalidate() {
+    this.requestId += 1;
+    this.state = void 0;
+    this.queue.clear();
+  }
+  retire(requestId) {
+    if (requestId !== this.requestId) return;
+    this.requestId += 1;
+    this.state = void 0;
+    this.queue.clear();
+  }
+  accept(requestId, report) {
+    if (this.state?.requestId !== requestId || report.epoch !== this.state.epoch) {
+      return;
+    }
+    this.state.reports.push(report);
+  }
+};
+
 // src/config.ts
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
@@ -7007,37 +7122,6 @@ function definedOnly(value) {
   );
 }
 
-// src/final-response-queue.ts
-var FinalResponseQueue = class {
-  constructor(options) {
-    this.options = options;
-  }
-  pending = [];
-  enqueue(items) {
-    this.pending.push(...items);
-    this.pump();
-  }
-  slotAvailable() {
-    this.pump();
-  }
-  clear() {
-    this.pending.length = 0;
-  }
-  pump() {
-    while (this.options.activeCount() < this.options.maxParallel() && this.pending.length > 0) {
-      const epoch = this.options.currentEpoch();
-      const activeShadowIds = this.options.activeShadowIds();
-      const index = this.pending.findIndex(
-        (item2) => item2.epoch !== epoch || !activeShadowIds.has(item2.shadowId)
-      );
-      if (index < 0) return;
-      const [item] = this.pending.splice(index, 1);
-      if (!item || item.epoch !== epoch) continue;
-      this.options.launch(item);
-    }
-  }
-};
-
 // src/management-tools.ts
 import { Type } from "typebox";
 var ID = Type.String({ pattern: "^[a-z0-9][a-z0-9_-]*$" });
@@ -8280,7 +8364,10 @@ var ShadowMindRuntime = class {
     this.pi = pi;
     this.batcher = new ReportBatcher(
       this.configStore.current.resultBatchWindowMs,
-      (reports) => this.deliverReports(reports)
+      (reports) => {
+        this.completionReview.invalidate();
+        void this.deliverReports(reports);
+      }
     );
   }
   agentDir = getAgentDir();
@@ -8293,22 +8380,14 @@ var ShadowMindRuntime = class {
   runner = new ShadowRunner();
   usageStore = new UsageStore(this.agentDir);
   active = /* @__PURE__ */ new Map();
-  finalResponseQueue = new FinalResponseQueue(
-    {
-      currentEpoch: () => this.epoch,
-      maxParallel: () => this.configStore.current.maxParallelShadows,
-      activeCount: () => this.active.size,
-      activeShadowIds: () => new Set([...this.active.values()].map(({ shadow }) => shadow.id)),
-      launch: (pending) => this.launchShadow(
-        pending.ctx,
-        pending.shadow,
-        pending.mainModel,
-        pending.fullModelId,
-        pending.context,
-        pending.availableTools
-      )
-    }
-  );
+  completionReview = new CompletionReview({
+    currentEpoch: () => this.epoch,
+    maxParallel: () => this.configStore.current.maxParallelShadows,
+    activeCount: () => this.active.size,
+    activeShadowIds: () => new Set([...this.active.values()].map(({ shadow }) => shadow.id)),
+    launch: (pending, review) => this.launchShadow({ ...pending, completionReview: review }),
+    deliver: (reports) => void this.deliverReports(reports)
+  });
   recentEvents = [];
   recentRuns = [];
   batcher;
@@ -8458,7 +8537,7 @@ var ShadowMindRuntime = class {
     );
   }
   async onHeartbeat(ctx) {
-    await this.refresh(ctx);
+    const snapshot = await this.refresh(ctx);
     if (this.paused || !ctx.model) {
       this.record("heartbeat-skipped", {
         reason: this.paused ? "paused" : "no-model",
@@ -8466,7 +8545,6 @@ var ShadowMindRuntime = class {
       });
       return;
     }
-    const snapshot = await this.registry.load();
     const fullModelId = `${ctx.model.provider}/${ctx.model.id}`;
     const decision = decideHeartbeat({
       heartbeatProbability: this.configStore.current.heartbeatProbability,
@@ -8501,25 +8579,30 @@ var ShadowMindRuntime = class {
       this.pi.getAllTools().map((tool2) => tool2.name)
     );
     for (const { shadow } of decision.activated) {
-      this.launchShadow(
+      this.launchShadow({
         ctx,
         shadow,
-        ctx.model,
+        mainModel: ctx.model,
         fullModelId,
         context,
         availableTools
-      );
+      });
     }
   }
   async onFinalResponse(ctx) {
-    await this.refresh(ctx);
+    const request = this.completionReview.begin(this.epoch);
+    const snapshot = await this.refresh(ctx);
+    if (!this.completionReview.isCurrent(request)) {
+      this.record("final-response-skipped", { reason: "superseded" });
+      return;
+    }
     if (this.paused || !ctx.model) {
+      this.completionReview.cancel(request);
       this.record("final-response-skipped", {
         reason: this.paused ? "paused" : "no-model"
       });
       return;
     }
-    const snapshot = await this.registry.load();
     const mainModel = ctx.model;
     const fullModelId = `${mainModel.provider}/${mainModel.id}`;
     const decision = decideFinalResponse({
@@ -8532,7 +8615,10 @@ var ShadowMindRuntime = class {
       ...decision.modelFiltered.length ? { modelFiltered: decision.modelFiltered } : {},
       ...decision.runningExcluded.length ? { runningExcluded: decision.runningExcluded } : {}
     });
-    if (!decision.activated.length) return;
+    if (!decision.activated.length) {
+      this.completionReview.schedule(request, []);
+      return;
+    }
     const context = buildSessionContext(
       ctx.sessionManager.getEntries(),
       ctx.sessionManager.getLeafId()
@@ -8540,9 +8626,10 @@ var ShadowMindRuntime = class {
     const availableTools = new Set(
       this.pi.getAllTools().map((tool2) => tool2.name)
     );
-    this.finalResponseQueue.enqueue(
+    this.completionReview.schedule(
+      request,
       decision.activated.map(({ shadow }) => ({
-        epoch: this.epoch,
+        epoch: request.epoch,
         shadowId: shadow.id,
         ctx,
         shadow,
@@ -8553,11 +8640,22 @@ var ShadowMindRuntime = class {
       }))
     );
   }
-  launchShadow(ctx, shadow, mainModel, fullModelId, context, availableTools) {
+  launchShadow(options) {
+    const {
+      ctx,
+      shadow,
+      mainModel,
+      fullModelId,
+      context,
+      availableTools,
+      completionReview
+    } = options;
     const runId = randomUUID3();
-    const runEpoch = this.epoch;
+    const runEpoch = options.epoch ?? this.epoch;
     const { tools, missing } = resolveShadowTools(shadow.tools, availableTools);
-    this.active.set(runId, { shadow, epoch: runEpoch });
+    const activeRun = { shadow, epoch: runEpoch };
+    if (completionReview) activeRun.completionReview = completionReview;
+    this.active.set(runId, activeRun);
     this.record("run-start", {
       runId,
       shadowId: shadow.id,
@@ -8573,30 +8671,39 @@ var ShadowMindRuntime = class {
       cwd: ctx.cwd,
       agentDir: this.agentDir,
       mainSystemPrompt: ctx.getSystemPrompt(),
-      // SAFETY: buildSessionContext returns Pi message objects; the runner treats them as read-only generic records.
+      // SAFETY: buildSessionContext returns Pi messages; ShadowRunner treats them as read-only records.
       messages: context.messages,
       mainModel,
       tools,
       resolveModel: (id) => resolveModel(ctx, id),
       modelAuthOk: (model) => ctx.modelRegistry.hasConfiguredAuth(model) || ctx.modelRegistry.isUsingOAuth(model),
       mainThinkingLevel: ctx.thinkingLevel,
-      onReport: (report) => this.acceptReport(report)
+      onReport: (report) => {
+        if (completionReview) completionReview.accept(report);
+        else this.acceptReport(report);
+      }
     }).then((result) => this.handleRunEnd(runId, shadow, result)).catch((error) => {
+      const activeRun2 = this.active.get(runId);
       this.active.delete(runId);
+      this.completionReview.slotAvailable();
+      this.completionReview.complete(activeRun2?.completionReview);
       this.record("run-end", {
         runId,
         shadowId: shadow.id,
         reason: "error",
         error: error instanceof Error ? error.message : String(error)
       });
-      this.finalResponseQueue.slotAvailable();
     });
   }
   handleRunEnd(runId, shadow, result) {
     const activeRun = this.active.get(runId);
     this.active.delete(runId);
+    this.completionReview.slotAvailable();
     const persisted = this.usageStore.add(result.usage);
-    if (activeRun?.epoch !== this.epoch) return;
+    if (activeRun?.epoch !== this.epoch) {
+      this.completionReview.complete(activeRun?.completionReview);
+      return;
+    }
     this.sessionUsage = addUsage(this.sessionUsage, result.usage);
     this.recentRuns.push({
       shadowName: shadow.name,
@@ -8607,7 +8714,7 @@ var ShadowMindRuntime = class {
     this.record("run-end", { runId, shadowId: shadow.id, ...result });
     if (this.latestContext && this.sessionLifetime.isActive)
       this.updateStatus(this.latestContext);
-    this.finalResponseQueue.slotAvailable();
+    this.completionReview.complete(activeRun.completionReview);
     void persisted.then(() => {
       if (this.latestContext && this.sessionLifetime.isActive)
         this.updateStatus(this.latestContext);
@@ -8655,10 +8762,11 @@ var ShadowMindRuntime = class {
       )
     ];
     this.updateStatus(ctx);
+    return registry;
   }
   abortAll(reason) {
     this.runner.abortAll();
-    this.finalResponseQueue.clear();
+    this.completionReview.invalidate();
     this.batcher.clear();
     this.record("runs-aborted", { reason, count: this.active.size });
   }