pi-shadow-mind 0.1.15 → 0.1.17

package/DESIGN.md

@@ -111,7 +111,7 @@ active_for_models:
 | `run_with_model` | Shadow 自己使用的模型；省略时使用插件默认模型 |
 | `thinking_level` | Shadow 使用的 thinking level；省略时使用插件默认值，再回退到 Main 会话当前生效等级 |
 | `timeout_seconds` | Shadow 单次运行超时；省略时使用插件默认超时 |
-| `tools` | 在 Pi SDK `readOnlyTools` 之上追加的工具白名单；默认 `[]` |
+| `tools` | 在 Pi SDK `readOnlyTools` 之上追加的工具白名单；`["*"]` 授权当前 Session 的全部工具；默认 `[]` |
 
 `name` 只用于 `shadow-report` 和状态界面展示，不参与身份判断；省略时回退到最终解析出的 `id`。Markdown 正文就是 Shadow 的认知定义、长期职责和行为要求。
 
@@ -131,9 +131,9 @@ Pi SDK readOnlyTools
 
 默认名称集合包含 `read`、`grep`、`find` 和 `ls`。激活时插件按名称从当前 Main Session 的最终工具 registry 解析实际实现，因此会继承其他插件对同名工具的覆盖以及当前环境适配。这里的 `readOnlyTools` 表示默认名称约定，不保证被覆盖后的实现仍然没有副作用。
 
-`tools` 是在该集合之上追加的显式白名单，省略时视为 `[]`。例如 `tools: [write]` 会获得当前 registry 中的默认四个工具、`write` 和内置 `report_to_main`。
+`tools` 是在该集合之上追加的显式白名单，省略时视为 `[]`。例如 `tools: [write]` 会获得当前 registry 中的默认四个工具、`write` 和内置 `report_to_main`。使用 `tools: ["*"]` 时，Shadow 会获得激活时 Main Session registry 中的全部工具以及 `report_to_main`；之后新增或改名的工具会自动随 registry 解析，不需要同步维护定义文件。
 
-Pi 的通用 `ToolDefinition` 没有可供插件查询的只读属性，因此自定义工具不会被自动归类或加入；编辑文件、执行 Shell 或其他能力也不会被隐式继承自 Main。配置的追加工具在当前 Session 不存在时，插件忽略该项、写入轻量运行事件，其余工具继续正常提供。
+Pi 的通用 `ToolDefinition` 没有可供插件查询的只读属性，因此自定义工具不会被自动归类或加入；编辑文件、执行 Shell 或其他能力也不会被隐式继承自 Main，除非显式列出名称或使用 `"*"`。配置的追加工具在当前 Session 不存在时，插件忽略该项、写入轻量运行事件，其余工具继续正常提供。
 
 `tools` 白名单本身就是用户对该 Shadow 的执行授权。列入白名单的写入、Shell 或其他工具可以由后台 Shadow 直接调用，插件不增加逐次确认层。
 
@@ -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

@@ -66,13 +66,13 @@ Report only concrete, actionable issues grounded in the visible trajectory or
 repository. If the current work is unrelated, do not intervene.
 ```
 
-This Shadow is read-only. It reviews the implementation in parallel and reports concrete architectural concerns without taking control of the main task.
+This Shadow is read-only. It reviews the implementation in parallel and reports concrete architectural concerns without taking control of the main task. Tool names extend the default read-only set; use `tools: ["*"]` only when the Shadow should inherit every tool currently registered in the main session, including tools added later.
 
 ## How it works
 
 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

@@ -63,13 +63,13 @@ tools: [read, grep]
 无关，不要介入。
 ```
 
-这个 Shadow 默认只读。它会在实现过程中并行审阅架构，并向主 Agent 报告具体问题，但不会接管主任务。
+这个 Shadow 默认只读。它会在实现过程中并行审阅架构，并向主 Agent 报告具体问题，但不会接管主任务。`tools` 中的名称会追加到默认只读工具集；只有确实需要继承 Main Session 当前注册的全部工具（包括未来新增工具）时，才使用 `tools: ["*"]`。
 
 ## 工作方式
 
 每个 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_-]*$" });
@@ -7663,7 +7747,7 @@ function compactJson(value) {
 // src/shadow-runner.ts
 function resolveShadowTools(whitelist, available, defaults = DEFAULT_READ_TOOLS) {
   const builtin = /* @__PURE__ */ new Set(["report_to_main"]);
-  const requested = [.../* @__PURE__ */ new Set([...defaults, ...whitelist, ...builtin])];
+  const requested = whitelist.includes("*") ? [.../* @__PURE__ */ new Set([...available, ...builtin])] : [.../* @__PURE__ */ new Set([...defaults, ...whitelist, ...builtin])];
   const tools = [];
   const missing = [];
   for (const name of requested) {
@@ -7685,13 +7769,13 @@ function buildRunResult(options) {
   const usage = usageMetrics(ownMessages);
   return {
     reason,
-    ...error !== void 0 ? { error } : {},
+    ...error === void 0 ? {} : { error },
     durationMs,
     toolNames: session?.getActiveToolNames() ?? [],
     missingTools,
     ...metrics,
     usage,
-    ...thinkingLevel !== void 0 ? { thinkingLevel } : {},
+    ...thinkingLevel === void 0 ? {} : { thinkingLevel },
     sessionFile: session?.sessionFile
   };
 }
@@ -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 });
   }