pi-shadow-mind 0.1.19 → 0.1.21

package/dist/index.js

@@ -6,11 +6,8 @@ var __export = (target, all) => {
 
 // src/runtime.ts
 import { randomUUID as randomUUID3 } from "node:crypto";
-import {
-  buildSessionContext
-} from "@earendil-works/pi-coding-agent";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
-import { Text } from "@earendil-works/pi-tui";
+import { Text as Text2 } from "@earendil-works/pi-tui";
 
 // src/final-response-queue.ts
 var FinalResponseQueue = class {
@@ -29,6 +26,7 @@ var FinalResponseQueue = class {
     this.pending.length = 0;
   }
   pump() {
+    if (this.options.canLaunch && !this.options.canLaunch()) return;
     while (this.options.activeCount() < this.options.maxParallel() && this.pending.length > 0) {
       const epoch = this.options.currentEpoch();
       const activeShadowIds = this.options.activeShadowIds();
@@ -52,6 +50,7 @@ var CompletionReview = class {
       maxParallel: () => this.host.maxParallel(),
       activeCount: () => this.host.activeCount(),
       activeShadowIds: () => this.host.activeShadowIds(),
+      canLaunch: () => this.host.canLaunch ? this.host.canLaunch() : true,
       launch: ({ job, run }) => host.launch(job, run)
     });
   }
@@ -78,7 +77,8 @@ var CompletionReview = class {
       requestId: request.id,
       epoch: request.epoch,
       remaining: jobs.length,
-      reports: []
+      reports: [],
+      shadowIds: jobs.map((job) => job.shadowId)
     };
     this.queue.enqueue(
       jobs.map((job) => {
@@ -102,7 +102,9 @@ var CompletionReview = class {
     this.state.remaining -= 1;
     if (this.state.remaining > 0) return;
     const reports = this.state.reports;
+    const shadowIds = this.state.shadowIds;
     this.retire(requestId);
+    this.host.onReviewCompleted?.(shadowIds);
     if (reports.length > 0) this.host.deliver(reports);
   }
   cancel(request) {
@@ -145,6 +147,12 @@ function isNonEmptyString(value) {
 function isStringArray(value) {
   return Array.isArray(value) && value.every((item) => isNonEmptyString(item));
 }
+function cleanStringArray(value, fallback, name) {
+  if (value === void 0) return [...fallback];
+  if (!isStringArray(value))
+    throw new Error(`${name} must be an array of non-empty strings`);
+  return [...new Set(value.map((item) => item.trim()))];
+}
 function isThinkingLevel(value) {
   return typeof value === "string" && THINKING_LEVELS.has(value);
 }
@@ -152,6 +160,7 @@ function isThinkingLevel(value) {
 // src/config.ts
 var DEFAULT_CONFIG = {
   heartbeatProbability: 1 / 3,
+  heartbeatTools: [],
   maxParallelShadows: 2,
   defaultShadowTimeoutSeconds: 300,
   headlessDrainTimeoutSeconds: 120,
@@ -164,6 +173,7 @@ function parseConfig(input) {
   }
   const value = input;
   const probability = numberInRange(value.heartbeat_probability, 0, 1, DEFAULT_CONFIG.heartbeatProbability, "heartbeat_probability");
+  const heartbeatTools = cleanStringArray(value.heartbeat_tools, DEFAULT_CONFIG.heartbeatTools, "heartbeat_tools");
   const parallel = positiveInteger(value.max_parallel_shadows, DEFAULT_CONFIG.maxParallelShadows, "max_parallel_shadows");
   const timeout = positiveNumber(value.default_shadow_timeout_seconds, DEFAULT_CONFIG.defaultShadowTimeoutSeconds, "default_shadow_timeout_seconds");
   const drainTimeout = positiveNumber(value.headless_drain_timeout_seconds, DEFAULT_CONFIG.headlessDrainTimeoutSeconds, "headless_drain_timeout_seconds");
@@ -176,6 +186,7 @@ function parseConfig(input) {
   }
   return {
     heartbeatProbability: probability,
+    heartbeatTools,
     maxParallelShadows: parallel,
     defaultShadowTimeoutSeconds: timeout,
     headlessDrainTimeoutSeconds: drainTimeout,
@@ -188,6 +199,7 @@ function parseConfig(input) {
 function serializeConfig(config) {
   return `${JSON.stringify({
     heartbeat_probability: config.heartbeatProbability,
+    ...config.heartbeatTools && config.heartbeatTools.length ? { heartbeat_tools: config.heartbeatTools } : {},
     max_parallel_shadows: config.maxParallelShadows,
     default_shadow_timeout_seconds: config.defaultShadowTimeoutSeconds,
     headless_drain_timeout_seconds: config.headlessDrainTimeoutSeconds,
@@ -6968,7 +6980,7 @@ function parseShadowMarkdown(source, filePath) {
       "activation_probability"
     ),
     trigger: triggerArray(value.trigger, ["heartbeat"], "trigger"),
-    activeForModels: stringArray(
+    activeForModels: cleanStringArray(
       value.active_for_models,
       ["*"],
       "active_for_models"
@@ -6979,7 +6991,16 @@ function parseShadowMarkdown(source, filePath) {
       value.timeout_seconds,
       "timeout_seconds"
     ),
-    tools: stringArray(value.tools, [], "tools"),
+    finalResponseRounds: optionalNonNegativeInteger(
+      value.final_response_rounds,
+      "final_response_rounds"
+    ),
+    activationTools: cleanStringArray(
+      value.activation_tools,
+      [],
+      "activation_tools"
+    ),
+    tools: cleanStringArray(value.tools, [], "tools"),
     prompt,
     filePath
   };
@@ -7010,15 +7031,15 @@ function optionalPositiveNumber(value, name) {
     throw new Error(`${name} must be positive`);
   return value;
 }
-function stringArray(value, fallback, name) {
-  if (value === void 0) return [...fallback];
-  if (!isStringArray(value))
-    throw new Error(`${name} must be an array of non-empty strings`);
-  return [...new Set(value.map((item) => item.trim()))];
+function optionalNonNegativeInteger(value, name) {
+  if (value === void 0) return void 0;
+  if (!isFiniteNumber(value) || !Number.isInteger(value) || value < 0)
+    throw new Error(`${name} must be a non-negative integer`);
+  return value;
 }
 function triggerArray(value, fallback, name) {
   const values = typeof value === "string" ? [value] : value;
-  const items = stringArray(values, fallback, name);
+  const items = cleanStringArray(values, fallback, name);
   const allowed = new Set(SHADOW_TRIGGERS);
   const invalid = items.filter((item) => !allowed.has(item));
   if (invalid.length)
@@ -7104,6 +7125,8 @@ function serializeShadow(shadow) {
     ...shadow.runWithModel ? { run_with_model: shadow.runWithModel } : {},
     ...shadow.thinkingLevel ? { thinking_level: shadow.thinkingLevel } : {},
     ...shadow.timeoutSeconds !== void 0 ? { timeout_seconds: shadow.timeoutSeconds } : {},
+    ...shadow.finalResponseRounds !== void 0 ? { final_response_rounds: shadow.finalResponseRounds } : {},
+    ...shadow.activationTools && shadow.activationTools.length ? { activation_tools: shadow.activationTools } : {},
     tools: shadow.tools ?? []
   };
   return `---
@@ -7114,7 +7137,9 @@ ${(shadow.prompt ?? "").trim()}
 `;
 }
 function describeShadow(shadow) {
-  return `${shadow.enabled ? "enabled" : "disabled"} ${shadow.id} (${shadow.name}) p=${shadow.activationProbability} trigger=${shadow.trigger.join(",")} models=${shadow.activeForModels.join(",")} tools=${shadow.tools.join(",") || "default"} file=${basename2(shadow.filePath)}`;
+  const actTools = shadow.activationTools.length ? ` act_tools=${shadow.activationTools.join(",")}` : "";
+  const finalRounds = shadow.finalResponseRounds ? ` final_rounds=${shadow.finalResponseRounds}` : "";
+  return `${shadow.enabled ? "enabled" : "disabled"} ${shadow.id} (${shadow.name}) p=${shadow.activationProbability} trigger=${shadow.trigger.join(",")} models=${shadow.activeForModels.join(",")}${finalRounds}${actTools} tools=${shadow.tools.join(",") || "default"} file=${basename2(shadow.filePath)}`;
 }
 function definedOnly(value) {
   return Object.fromEntries(
@@ -7122,6 +7147,27 @@ function definedOnly(value) {
   );
 }
 
+// src/final-response-budget.ts
+var FinalResponseBudget = class {
+  counts = /* @__PURE__ */ new Map();
+  canRun(shadow) {
+    const limit = shadow.finalResponseRounds ?? 0;
+    if (limit <= 0) return true;
+    return this.used(shadow.id) < limit;
+  }
+  commit(shadowIds) {
+    for (const id of shadowIds) {
+      this.counts.set(id, this.used(id) + 1);
+    }
+  }
+  used(shadowId) {
+    return this.counts.get(shadowId) ?? 0;
+  }
+  reset() {
+    this.counts.clear();
+  }
+};
+
 // src/management-tools.ts
 import { Type } from "typebox";
 var ID = Type.String({ pattern: "^[a-z0-9][a-z0-9_-]*$" });
@@ -7149,6 +7195,8 @@ var SHADOW_FIELDS = {
   run_with_model: Type.Optional(Type.String()),
   thinking_level: Type.Optional(THINKING),
   timeout_seconds: Type.Optional(Type.Number({ exclusiveMinimum: 0 })),
+  final_response_rounds: Type.Optional(Type.Integer({ minimum: 0 })),
+  activation_tools: Type.Optional(Type.Array(Type.String())),
   tools: Type.Optional(Type.Array(Type.String())),
   prompt: Type.Optional(Type.String())
 };
@@ -7270,6 +7318,7 @@ function configWriteTool(store, getConfig) {
       heartbeat_probability: Type.Optional(
         Type.Number({ minimum: 0, maximum: 1 })
       ),
+      heartbeat_tools: Type.Optional(Type.Array(Type.String())),
       max_parallel_shadows: Type.Optional(Type.Integer({ minimum: 1 })),
       default_shadow_timeout_seconds: Type.Optional(
         Type.Number({ exclusiveMinimum: 0 })
@@ -7289,6 +7338,7 @@ function configWriteTool(store, getConfig) {
       const raw = params;
       const next = parseConfig({
         heartbeat_probability: raw.heartbeat_probability ?? current.heartbeatProbability,
+        heartbeat_tools: raw.heartbeat_tools ?? current.heartbeatTools,
         max_parallel_shadows: raw.max_parallel_shadows ?? current.maxParallelShadows,
         default_shadow_timeout_seconds: raw.default_shadow_timeout_seconds ?? current.defaultShadowTimeoutSeconds,
         headless_drain_timeout_seconds: raw.headless_drain_timeout_seconds ?? current.headlessDrainTimeoutSeconds,
@@ -7336,6 +7386,8 @@ function toPatch(raw) {
     runWithModel: raw.run_with_model,
     thinkingLevel: raw.thinking_level,
     timeoutSeconds: raw.timeout_seconds,
+    finalResponseRounds: raw.final_response_rounds,
+    activationTools: raw.activation_tools,
     tools: raw.tools,
     prompt: raw.prompt
   };
@@ -7385,6 +7437,147 @@ function formatReportBatch(reports) {
 ${report.content}`).join("\n\n");
 }
 
+// src/report-history.ts
+var ReportHistory = class {
+  constructor(limit = 5) {
+    this.limit = limit;
+    if (!Number.isInteger(limit) || limit < 0) throw new Error("Report limit must be a non-negative integer");
+  }
+  reports = [];
+  add(reports, deliveredAt = (/* @__PURE__ */ new Date()).toISOString()) {
+    for (const report of reports) {
+      this.reports = this.reports.filter(({ runId }) => runId !== report.runId);
+      this.reports.push({ ...report, deliveredAt });
+      if (this.reports.length > this.limit) this.reports.shift();
+    }
+  }
+  /** Newest delivery first; callers receive an isolated snapshot. */
+  list() {
+    return this.reports.map((report) => ({ ...report })).reverse();
+  }
+  clear() {
+    this.reports = [];
+  }
+};
+
+// src/report-viewer.ts
+import { matchesKey, Text, truncateToWidth } from "@earendil-works/pi-tui";
+var ReportViewer = class {
+  constructor(reports, theme, host) {
+    this.theme = theme;
+    this.host = host;
+    this.body = new Text(reports.map(
+      (report) => `${report.shadowName} \xB7 ${report.deliveredAt}
+run ${report.runId}
+${report.content.replace(/\r\n?/g, "\n")}`
+    ).join("\n\n"), 0, 0);
+    this.actions = [
+      ["escape", () => host.close()],
+      ["up", () => this.scroll(-1)],
+      ["down", () => this.scroll(1)],
+      ["pageUp", () => this.scroll(-this.pageSize)],
+      ["pageDown", () => this.scroll(this.pageSize)],
+      ["home", () => {
+        this.offset = 0;
+      }],
+      ["end", () => {
+        this.offset = this.maxOffset();
+      }]
+    ];
+  }
+  body;
+  offset = 0;
+  contentHeight = 0;
+  pageSize = 1;
+  actions;
+  render(width) {
+    const height = Math.max(1, Math.min(Math.floor(this.host.rows() * 0.8), this.host.rows() - 2));
+    this.pageSize = Math.max(1, height - 2);
+    const lines = this.body.render(Math.max(1, width));
+    this.contentHeight = lines.length;
+    this.offset = Math.min(this.offset, this.maxOffset());
+    const page = lines.slice(this.offset, this.offset + this.pageSize);
+    if (height < 3) return page.slice(0, height).map((line) => truncateToWidth(line, width));
+    return [
+      this.theme.fg("accent", truncateToWidth("Recent Shadow reports \xB7 newest first", width)),
+      ...page,
+      this.theme.fg("dim", truncateToWidth(
+        `Esc close \xB7 \u2191\u2193 PgUp/PgDn Home/End \xB7 ${this.offset + 1}\u2013${Math.min(this.offset + this.pageSize, lines.length)}/${lines.length}`,
+        width
+      ))
+    ];
+  }
+  handleInput(data) {
+    const action = this.actions.find(([key]) => matchesKey(data, key));
+    if (!action) return;
+    action[1]();
+    this.host.requestRender();
+  }
+  invalidate() {
+    this.body.invalidate();
+  }
+  maxOffset() {
+    return Math.max(0, this.contentHeight - this.pageSize);
+  }
+  scroll(lines) {
+    this.offset = Math.max(0, Math.min(this.maxOffset(), this.offset + lines));
+  }
+};
+
+// src/report-browser.ts
+var ReportBrowser = class {
+  history = new ReportHistory();
+  closeViewer;
+  add(reports) {
+    this.history.add(reports);
+  }
+  reset() {
+    this.closeViewer?.();
+    this.history.clear();
+  }
+  async handleCommand(command, ctx) {
+    const [name, ...args] = command.split(/\s+/);
+    if (name !== "reports") return false;
+    if (args.length && args.join(" ") !== "hide") {
+      ctx.ui.notify("Usage: /shadow reports [hide]", "warning");
+      return true;
+    }
+    if (args[0] === "hide" || this.closeViewer) {
+      this.closeViewer?.();
+      return true;
+    }
+    if (ctx.mode !== "tui") {
+      if (ctx.hasUI) ctx.ui.notify("The report viewer requires TUI mode. Delivered reports remain in the conversation.", "warning");
+      return true;
+    }
+    const reports = this.history.list();
+    if (!reports.length) {
+      ctx.ui.notify("No reports delivered in this session yet.", "info");
+      return true;
+    }
+    const view = { close: () => {
+    } };
+    try {
+      await ctx.ui.custom((tui, theme, _keys, done) => {
+        view.close = () => {
+          if (this.closeViewer !== view.close) return;
+          this.closeViewer = void 0;
+          done();
+        };
+        this.closeViewer = view.close;
+        return new ReportViewer(reports, theme, {
+          rows: () => tui.terminal.rows,
+          requestRender: () => tui.requestRender(),
+          close: view.close
+        });
+      }, { overlay: true, overlayOptions: { width: "90%", maxHeight: "80%", margin: 1 } });
+    } finally {
+      if (this.closeViewer === view.close) this.closeViewer = void 0;
+    }
+    return true;
+  }
+};
+
 // src/random.ts
 function createRandom(seed) {
   if (seed === void 0) return Math.random;
@@ -7398,9 +7591,143 @@ function createRandom(seed) {
   };
 }
 
+// src/acp-projection.ts
+import {
+  buildContextEntries,
+  buildSessionContext,
+  sessionEntryToContextMessages
+} from "@earendil-works/pi-coding-agent";
+
+// src/acp-state.ts
+import { readFileSync } from "node:fs";
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function readAcpBlocks(sessionFile) {
+  if (!sessionFile) return [];
+  try {
+    const state = JSON.parse(readFileSync(`${sessionFile}.acp.json`, "utf8"));
+    if (!isRecord(state) || !Array.isArray(state.blocks)) return [];
+    const blocks = [];
+    const seen = /* @__PURE__ */ new Set();
+    for (const block of state.blocks) {
+      if (!isRecord(block)) return [];
+      if (block.active === false) continue;
+      if (block.active !== true || typeof block.blockId !== "string" || !block.blockId || typeof block.summary !== "string" || !block.summary.trim() || !Array.isArray(block.effectiveMessageIds) || !block.effectiveMessageIds.every((id) => typeof id === "string" && id.length > 0) || seen.has(block.blockId)) return [];
+      seen.add(block.blockId);
+      blocks.push({
+        blockId: block.blockId,
+        summary: block.summary,
+        effectiveMessageIds: [...block.effectiveMessageIds]
+      });
+    }
+    return blocks;
+  } catch {
+    return [];
+  }
+}
+
+// src/acp-projection.ts
+function buildShadowSessionContext(entries, leafId, sessionFile) {
+  const context = buildSessionContext(entries, leafId);
+  const blocks = readAcpBlocks(sessionFile);
+  if (!blocks.length) return context;
+  const visible = buildContextEntries(entries, leafId).flatMap(
+    (entry) => sessionEntryToContextMessages(entry).map((message) => ({ id: entry.id, message }))
+  );
+  return { ...context, messages: projectMessages(visible, blocks) };
+}
+function toolCalls(message) {
+  return message.role === "assistant" ? message.content.filter((part) => part.type === "toolCall") : [];
+}
+function coverageIds({ id, message }) {
+  const calls = toolCalls(message);
+  return calls.length > 1 ? calls.map((call) => `${id}#${call.id}`) : [id];
+}
+function summaryMessage(block) {
+  return {
+    role: "compactionSummary",
+    summary: `[ACP block ${block.blockId} \u2014 ${block.effectiveMessageIds.length} folded messages]
+${block.summary}`,
+    tokensBefore: 0,
+    timestamp: 0
+  };
+}
+function projectMessages(visible, blocks) {
+  const indexById = /* @__PURE__ */ new Map();
+  visible.forEach((item, index) => {
+    for (const id of coverageIds(item)) indexById.set(id, index);
+  });
+  const covered = /* @__PURE__ */ new Set();
+  const anchors = /* @__PURE__ */ new Map();
+  for (const block of blocks) {
+    const positions = block.effectiveMessageIds.flatMap((id) => {
+      const index = indexById.get(id);
+      return index === void 0 ? [] : [index];
+    });
+    if (!positions.length) continue;
+    const first = positions.reduce((left, right) => Math.min(left, right));
+    anchors.set(first, [...anchors.get(first) ?? [], block]);
+    for (const id of block.effectiveMessageIds) covered.add(id);
+  }
+  if (!covered.size) return visible.map(({ message }) => message);
+  const firstUser = visible.findIndex(
+    ({ message }) => message.role === "user" || message.role === "custom"
+  );
+  const messages = [];
+  visible.forEach((item, index) => {
+    for (const block of anchors.get(index) ?? []) messages.push(summaryMessage(block));
+    const retained = index === firstUser ? item.message : retainUncovered(item, covered);
+    if (retained) messages.push(retained);
+  });
+  return removeOrphanedTools(messages);
+}
+function retainUncovered(item, covered) {
+  const ids = coverageIds(item);
+  if (!ids.some((id) => covered.has(id))) return item.message;
+  if (ids.every((id) => covered.has(id))) return void 0;
+  const message = item.message;
+  if (message.role !== "assistant") return message;
+  return {
+    ...message,
+    content: message.content.filter(
+      (part) => part.type !== "toolCall" || !covered.has(`${item.id}#${part.id}`)
+    )
+  };
+}
+function removeOrphanedTools(messages) {
+  const resultIds = new Set(messages.flatMap(
+    (message) => message.role === "toolResult" ? [message.toolCallId] : []
+  ));
+  const paired = messages.flatMap((message) => {
+    const calls = toolCalls(message);
+    if (!calls.length || message.role !== "assistant") return [message];
+    const retained = calls.filter((call) => call.name === "compress" || resultIds.has(call.id));
+    if (!retained.length) return [];
+    const ids = new Set(retained.map((call) => call.id));
+    return [{ ...message, content: message.content.filter((part) => part.type !== "toolCall" || ids.has(part.id)) }];
+  });
+  const callIds = new Set(paired.flatMap((message) => toolCalls(message).map((call) => call.id)));
+  return paired.filter((message) => message.role !== "toolResult" || callIds.has(message.toolCallId));
+}
+
 // src/scheduler.ts
-function shouldEvaluateHeartbeat(toolResults) {
-  return toolResults.length > 0;
+function extractToolNames(toolResults) {
+  const names = /* @__PURE__ */ new Set();
+  for (const item of toolResults) {
+    if (!item || typeof item !== "object") continue;
+    const name = item.toolName;
+    if (typeof name === "string" && name.trim().length > 0) {
+      names.add(name.trim());
+    }
+  }
+  return names;
+}
+function shouldEvaluateHeartbeat(toolsOrResults, heartbeatTools) {
+  const toolNames = toolsOrResults instanceof Set ? toolsOrResults : extractToolNames(toolsOrResults);
+  if (toolNames.size === 0) return false;
+  if (!heartbeatTools || heartbeatTools.length === 0) return true;
+  return heartbeatTools.some((tool2) => toolNames.has(tool2));
 }
 function shouldEvaluateFinalResponse(messages) {
   const message = messages.at(-1);
@@ -7423,11 +7750,14 @@ function decideHeartbeat(options) {
       activated: [],
       candidates: [],
       modelFiltered: [],
-      runningExcluded: []
+      runningExcluded: [],
+      roundFiltered: [],
+      toolFiltered: []
     };
   }
   const modelFiltered = [];
   const runningExcluded = [];
+  const toolFiltered = [];
   const rolls = options.shadows.filter((shadow) => {
     if (!shadow.enabled || !hasTrigger(shadow, "heartbeat")) return false;
     if (options.activeShadowIds.has(shadow.id)) {
@@ -7438,6 +7768,10 @@ function decideHeartbeat(options) {
       modelFiltered.push(shadow.id);
       return false;
     }
+    if (!matchesActivationTools(shadow, options.executedTools)) {
+      toolFiltered.push(shadow.id);
+      return false;
+    }
     return true;
   }).map((shadow) => ({ shadow, roll: random() }));
   const hits = rolls.filter(
@@ -7458,11 +7792,14 @@ function decideHeartbeat(options) {
       selected: selectedIds.has(shadow.id)
     })),
     modelFiltered,
-    runningExcluded
+    runningExcluded,
+    roundFiltered: [],
+    toolFiltered
   };
 }
 function decideFinalResponse(options) {
   const modelFiltered = [];
+  const roundFiltered = [];
   const candidates = options.shadows.filter((shadow) => {
     if (!shadow.enabled || !hasTrigger(shadow, "final_response"))
       return false;
@@ -7470,6 +7807,10 @@ function decideFinalResponse(options) {
       modelFiltered.push(shadow.id);
       return false;
     }
+    if (options.canRunFinalResponse && !options.canRunFinalResponse(shadow)) {
+      roundFiltered.push(shadow.id);
+      return false;
+    }
     return true;
   }).map((shadow) => ({ shadow, roll: 0 }));
   return {
@@ -7480,12 +7821,21 @@ function decideFinalResponse(options) {
       selected: true
     })),
     modelFiltered,
-    runningExcluded: []
+    runningExcluded: [],
+    roundFiltered
   };
 }
 function matchesModel(shadow, fullModelId) {
   return shadow.activeForModels.includes("*") || shadow.activeForModels.includes(fullModelId);
 }
+function matchesActivationTools(shadow, executedTools) {
+  if (shadow.activationTools.length === 0) {
+    return true;
+  }
+  if (!executedTools) return false;
+  const executedSet = executedTools instanceof Set ? executedTools : new Set(executedTools);
+  return shadow.activationTools.some((tool2) => executedSet.has(tool2));
+}
 function hasTrigger(shadow, trigger) {
   return shadow.trigger.includes(trigger);
 }
@@ -7716,7 +8066,7 @@ function serializeTrajectory(messages) {
       continue;
     }
     if (message.role === "compactionSummary" || message.role === "branchSummary") {
-      appendText(lines, "SUMMARY", message.content);
+      appendText(lines, "SUMMARY", message.summary ?? message.content);
     }
   }
   return `<main-agent-trajectory>
@@ -8380,16 +8730,20 @@ var ShadowMindRuntime = class {
   runner = new ShadowRunner();
   usageStore = new UsageStore(this.agentDir);
   active = /* @__PURE__ */ new Map();
+  finalResponseBudget = new FinalResponseBudget();
   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)),
+    canLaunch: () => !this.batcher.hasPending,
     launch: (pending, review) => this.launchShadow({ ...pending, completionReview: review }),
-    deliver: (reports) => void this.deliverReports(reports)
+    deliver: (reports) => void this.deliverReports(reports),
+    onReviewCompleted: (shadowIds) => this.finalResponseBudget.commit(shadowIds)
   });
   recentEvents = [];
   recentRuns = [];
+  reports = new ReportBrowser();
   batcher;
   sessionLifetime = new SessionLifetime();
   epoch = 0;
@@ -8417,8 +8771,10 @@ var ShadowMindRuntime = class {
       this.latestContext = ctx;
       this.modelCalls = 0;
       this.completedWithFinalText = false;
+      this.finalResponseBudget.reset();
       this.sessionUsage = zeroUsage();
       this.recentRuns.length = 0;
+      this.reports.reset();
       await this.configStore.initialize();
       await this.usageStore.initialize();
       this.random = createRandom(this.configStore.current.randomSeed);
@@ -8433,6 +8789,7 @@ var ShadowMindRuntime = class {
       this.latestContext = ctx;
       if (event.source === "extension") return;
       this.completedWithFinalText = false;
+      this.finalResponseBudget.reset();
       this.epoch += 1;
       this.abortAll("new-user-input");
     });
@@ -8442,14 +8799,16 @@ var ShadowMindRuntime = class {
     });
     this.pi.on("turn_end", async (event, ctx) => {
       this.latestContext = ctx;
-      if (!shouldEvaluateHeartbeat(event.toolResults)) {
+      const toolResults = event.toolResults ?? [];
+      const executedTools = extractToolNames(toolResults);
+      if (executedTools.size === 0) {
         this.record("heartbeat-skipped", {
           reason: "no-tool-activity",
           modelCalls: this.modelCalls
         });
         return;
       }
-      await this.onHeartbeat(ctx);
+      await this.onHeartbeat(ctx, executedTools);
     });
     this.pi.on("agent_end", (event, ctx) => {
       this.latestContext = ctx;
@@ -8481,6 +8840,7 @@ var ShadowMindRuntime = class {
         if (!result.settled) this.active.clear();
       }
       await this.usageStore.flush();
+      this.reports.reset();
       ctx.ui.setStatus("shadow-mind", void 0);
       ctx.ui.setWidget("shadow-mind-panel", void 0);
       this.sessionLifetime.deactivate();
@@ -8504,6 +8864,7 @@ var ShadowMindRuntime = class {
           this.setPaused(!this.paused, ctx);
           return;
         }
+        if (await this.reports.handleCommand(command, ctx)) return;
         if (command === "status") {
           await this.refresh(ctx);
           ctx.ui.notify(
@@ -8534,12 +8895,20 @@ var ShadowMindRuntime = class {
       (message, _options, theme) => {
         const content = typeof message.content === "string" ? message.content : "Shadow report";
         const prefix = theme.fg("accent", "\u{1F419} shadow \xB7 ");
-        return new Text(`${prefix}${content}`, 0, 0);
+        return new Text2(`${prefix}${content}`, 0, 0);
       }
     );
   }
-  async onHeartbeat(ctx) {
+  async onHeartbeat(ctx, executedTools) {
     const snapshot = await this.refresh(ctx);
+    const config = this.configStore.current;
+    if (!shouldEvaluateHeartbeat(executedTools, config.heartbeatTools)) {
+      this.record("heartbeat-skipped", {
+        reason: "tool-filtered",
+        modelCalls: this.modelCalls
+      });
+      return;
+    }
     if (this.paused || !ctx.model) {
       this.record("heartbeat-skipped", {
         reason: this.paused ? "paused" : "no-model",
@@ -8549,17 +8918,18 @@ var ShadowMindRuntime = class {
     }
     const fullModelId = `${ctx.model.provider}/${ctx.model.id}`;
     const decision = decideHeartbeat({
-      heartbeatProbability: this.configStore.current.heartbeatProbability,
+      heartbeatProbability: config.heartbeatProbability,
       availableSlots: Math.max(
         0,
-        this.configStore.current.maxParallelShadows - this.active.size
+        config.maxParallelShadows - this.active.size
       ),
       shadows: snapshot.shadows,
       activeShadowIds: new Set(
         [...this.active.values()].map(({ shadow }) => shadow.id)
       ),
       mainModelId: fullModelId,
-      random: this.random
+      random: this.random,
+      executedTools
     });
     this.record("heartbeat", {
       modelCalls: this.modelCalls,
@@ -8570,12 +8940,14 @@ var ShadowMindRuntime = class {
         roll
       })),
       ...decision.modelFiltered.length ? { modelFiltered: decision.modelFiltered } : {},
-      ...decision.runningExcluded.length ? { runningExcluded: decision.runningExcluded } : {}
+      ...decision.runningExcluded.length ? { runningExcluded: decision.runningExcluded } : {},
+      ...decision.toolFiltered.length ? { toolFiltered: decision.toolFiltered } : {}
     });
     if (!decision.activated.length) return;
-    const context = buildSessionContext(
+    const context = buildShadowSessionContext(
       ctx.sessionManager.getEntries(),
-      ctx.sessionManager.getLeafId()
+      ctx.sessionManager.getLeafId(),
+      ctx.sessionManager.getSessionFile()
     );
     const availableTools = new Set(
       this.pi.getAllTools().map((tool2) => tool2.name)
@@ -8592,6 +8964,10 @@ var ShadowMindRuntime = class {
     }
   }
   async onFinalResponse(ctx) {
+    if (this.batcher.hasPending) {
+      await this.batcher.flush();
+      return;
+    }
     const request = this.completionReview.begin(this.epoch);
     const snapshot = await this.refresh(ctx);
     if (!this.completionReview.isCurrent(request)) {
@@ -8609,21 +8985,24 @@ var ShadowMindRuntime = class {
     const fullModelId = `${mainModel.provider}/${mainModel.id}`;
     const decision = decideFinalResponse({
       shadows: snapshot.shadows,
-      mainModelId: fullModelId
+      mainModelId: fullModelId,
+      canRunFinalResponse: (shadow) => this.finalResponseBudget.canRun(shadow)
     });
     this.record("final-response", {
       candidates: decision.candidates,
       activated: decision.activated.map(({ shadow }) => shadow.id),
       ...decision.modelFiltered.length ? { modelFiltered: decision.modelFiltered } : {},
-      ...decision.runningExcluded.length ? { runningExcluded: decision.runningExcluded } : {}
+      ...decision.runningExcluded.length ? { runningExcluded: decision.runningExcluded } : {},
+      ...decision.roundFiltered.length ? { roundFiltered: decision.roundFiltered } : {}
     });
     if (!decision.activated.length) {
       this.completionReview.schedule(request, []);
       return;
     }
-    const context = buildSessionContext(
+    const context = buildShadowSessionContext(
       ctx.sessionManager.getEntries(),
-      ctx.sessionManager.getLeafId()
+      ctx.sessionManager.getLeafId(),
+      ctx.sessionManager.getSessionFile()
     );
     const availableTools = new Set(
       this.pi.getAllTools().map((tool2) => tool2.name)
@@ -8735,7 +9114,7 @@ var ShadowMindRuntime = class {
       count: current.length
     });
     const idle = this.latestContext?.isIdle() ?? true;
-    this.sessionLifetime.run(() => {
+    const delivered = this.sessionLifetime.run(() => {
       this.pi.sendMessage(
         {
           customType: "shadow-report",
@@ -8751,6 +9130,7 @@ var ShadowMindRuntime = class {
         { triggerTurn: true, deliverAs: idle ? "followUp" : "steer" }
       );
     });
+    if (delivered) this.reports.add(current);
   }
   async refresh(ctx) {
     const config = await this.configStore.reload();
@@ -8852,7 +9232,7 @@ var ShadowMindRuntime = class {
         const detail = failed ? ` ${event.data?.error ?? event.data?.reason}` : "";
         return `${new Date(event.at).toLocaleTimeString("en-GB", { hour12: false })} ${event.kind}${detail}`;
       }),
-      "Shortcut: Alt+S toggle \xB7 Commands: /shadow toggle | pause | resume | status | hide"
+      "Shortcut: Alt+S toggle \xB7 Commands: /shadow toggle | pause | resume | status | hide | reports"
     ];
   }
 };