pi-ui-extend 1.0.42 → 1.0.45

package/external/pi-tools-suite/src/dcp/commands.ts

@@ -2,10 +2,11 @@ import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-c
 import type { AutocompleteItem } from "@earendil-works/pi-tui"
 import type { DcpState } from "./state.js"
 import { modelKeysFromContext, resolveModelConfig, type DcpConfig } from "./config.js"
-import type { DcpNudgeType } from "./pruner-types.js"
 import { isToolRecordProtected, markToolPruned } from "./pruner.js"
 import { ignoreStaleExtensionContextError, safeGetContextUsage } from "../context-usage.js"
 import { captureDcpTransactionGuard, cloneDcpTransactionState, runDcpStateTransaction } from "./state-transaction.js"
+import { readDcpJournalBranch } from "./journal.js"
+import { formatDcpStatistics } from "./statistics.js"
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -34,42 +35,6 @@ function fmt(n: number): string {
   return n.toLocaleString()
 }
 
-const NUDGE_TYPES: DcpNudgeType[] = ["turn", "iteration", "context-soft", "context-strong"]
-
-function pct(numerator: number, denominator: number): string {
-  if (denominator <= 0) return "n/a"
-  return `${((numerator / denominator) * 100).toFixed(1)}%`
-}
-
-function nudgeLabel(type: DcpNudgeType): string {
-  switch (type) {
-    case "context-strong": return "context-strong"
-    case "context-soft": return "context-soft"
-    case "iteration": return "iteration"
-    case "turn": return "turn"
-  }
-}
-
-function isNudgeType(value: unknown): value is DcpNudgeType {
-  return typeof value === "string" && (NUDGE_TYPES as string[]).includes(value)
-}
-
-function customEntryData(entry: unknown, customType: string): Record<string, unknown> | undefined {
-  const record = entry as { type?: unknown; customType?: unknown; data?: unknown }
-  if (record?.type !== "custom" || record.customType !== customType) return undefined
-  if (!record.data || typeof record.data !== "object" || Array.isArray(record.data)) return undefined
-  return record.data as Record<string, unknown>
-}
-
-function branchEntries(ctx: ExtensionCommandContext): any[] {
-  try {
-    const branch = ctx.sessionManager?.getBranch?.()
-    return Array.isArray(branch) ? branch : []
-  } catch {
-    return []
-  }
-}
-
 async function staleSafe(action: () => void | Promise<void>): Promise<void> {
   try {
     await action()
@@ -78,85 +43,6 @@ async function staleSafe(action: () => void | Promise<void>): Promise<void> {
   }
 }
 
-interface DcpNudgeStats {
-  emitted: number
-  reapplied: number
-  upgraded: number
-  clearedEvents: number
-  clearedAnchors: number
-  byType: Record<DcpNudgeType, number>
-  activeByType: Record<DcpNudgeType, number>
-  last?: {
-    type: DcpNudgeType
-    event: "emitted" | "reapplied" | "upgraded"
-    createdAt?: number
-    contextPercent?: number | null
-  }
-}
-
-function collectNudgeStats(ctx: ExtensionCommandContext, state: DcpState): DcpNudgeStats {
-  const stats: DcpNudgeStats = {
-    emitted: 0,
-    reapplied: 0,
-    upgraded: 0,
-    clearedEvents: 0,
-    clearedAnchors: 0,
-    byType: { "turn": 0, "iteration": 0, "context-soft": 0, "context-strong": 0 },
-    activeByType: { "turn": 0, "iteration": 0, "context-soft": 0, "context-strong": 0 },
-  }
-
-  for (const anchor of state.nudgeAnchors) {
-    if (isNudgeType(anchor.type)) stats.activeByType[anchor.type]++
-  }
-
-  for (const entry of branchEntries(ctx)) {
-    const data = customEntryData(entry, "dcp-nudge")
-    if (!data) continue
-    const event = data.event
-    if ((event === "emitted" || event === "reapplied" || event === "upgraded") && isNudgeType(data.type)) {
-      if (event === "emitted") stats.emitted++
-      else if (event === "reapplied") stats.reapplied++
-      else stats.upgraded++
-      stats.byType[data.type]++
-      const createdAt = typeof data.createdAt === "number" ? data.createdAt : undefined
-      const rawContextPercent = data.contextPercent
-      let contextPercent: number | null | undefined
-      if (typeof rawContextPercent === "number") contextPercent = rawContextPercent
-      else if (rawContextPercent === null) contextPercent = null
-      if (!stats.last || (createdAt ?? 0) >= (stats.last.createdAt ?? 0)) {
-        stats.last = { type: data.type, event, createdAt, contextPercent }
-      }
-    } else if (event === "cleared") {
-      stats.clearedEvents++
-      stats.clearedAnchors += typeof data.clearedAnchors === "number" ? Math.max(0, data.clearedAnchors) : 0
-    }
-  }
-
-  if (!stats.last && state.lastNudge && isNudgeType(state.lastNudge.type)) {
-    stats.last = {
-      type: state.lastNudge.type,
-      event: "emitted",
-      createdAt: state.lastNudge.createdAt,
-      contextPercent: typeof state.lastNudge.contextPercent === "number"
-        ? state.lastNudge.contextPercent * 100
-        : undefined,
-    }
-  }
-
-  return stats
-}
-
-function formatDate(ts: number | undefined): string {
-  if (typeof ts !== "number" || !Number.isFinite(ts) || ts <= 0) return "unknown time"
-  return new Date(ts).toLocaleString()
-}
-
-function formatContextPercent(value: number | null | undefined): string {
-  if (value === null) return "unknown context"
-  if (typeof value !== "number" || !Number.isFinite(value)) return "unknown context"
-  return `${value.toFixed(1)}% context`
-}
-
 function sendChatSystemMessage(pi: ExtensionAPI, customType: string, content: string, details?: Record<string, unknown>): void {
 	pi.sendMessage({
 		customType,
@@ -238,44 +124,16 @@ function handleContext(ctx: ExtensionCommandContext, state: DcpState): void {
 // Stats
 // ---------------------------------------------------------------------------
 
-function handleStats(pi: ExtensionAPI, ctx: ExtensionCommandContext, state: DcpState): void {
-  const activeBlocks = state.compressionBlocks.filter((b) => b.active).length
-  const totalBlocks = state.compressionBlocks.length
-  const nudgeStats = collectNudgeStats(ctx, state)
-  const totalNudgeEvents = nudgeStats.emitted + nudgeStats.reapplied + nudgeStats.upgraded
-  const activeAnchors = state.nudgeAnchors.length
-  const lines: string[] = []
-  lines.push("DCP Session Statistics:")
-  lines.push(`  Tokens saved (estimated): ${fmt(state.tokensSaved)}`)
-  lines.push(`  Total pruning operations: ${fmt(state.totalPruneCount)}`)
-  lines.push(`  Compression blocks active: ${activeBlocks} / ${totalBlocks} total`)
-  lines.push(`  Manual mode: ${state.manualMode ? "on" : "off"}`)
-  lines.push("")
-  lines.push("Nudge telemetry:")
-  lines.push(`  Sent: ${fmt(nudgeStats.emitted)} emitted, ${fmt(nudgeStats.reapplied)} reapplied, ${fmt(nudgeStats.upgraded)} upgraded`)
-  lines.push(
-    `  By type: ${NUDGE_TYPES.map((type) => `${nudgeLabel(type)}=${fmt(nudgeStats.byType[type])}`).join(", ")}`,
-  )
-  lines.push(
-    `  Active anchors: ${fmt(activeAnchors)}${activeAnchors > 0
-      ? ` (${NUDGE_TYPES.map((type) => `${nudgeLabel(type)}=${fmt(nudgeStats.activeByType[type])}`).join(", ")})`
-      : ""}`,
-  )
-  lines.push(`  Cleared after compress: ${fmt(nudgeStats.clearedEvents)} time${nudgeStats.clearedEvents === 1 ? "" : "s"} (${fmt(nudgeStats.clearedAnchors)} anchor${nudgeStats.clearedAnchors === 1 ? "" : "s"})`)
-  lines.push(`  Compliance proxy: ${fmt(nudgeStats.clearedEvents)} compress-after-nudge / ${fmt(totalNudgeEvents)} nudge event${totalNudgeEvents === 1 ? "" : "s"} (${pct(nudgeStats.clearedEvents, totalNudgeEvents)})`)
-  if (nudgeStats.last) {
-    lines.push(
-      `  Last nudge: ${nudgeLabel(nudgeStats.last.type)} ${nudgeStats.last.event} at ${formatDate(nudgeStats.last.createdAt)} (${formatContextPercent(nudgeStats.last.contextPercent)})`,
-    )
-  } else {
-    lines.push("  Last nudge: none recorded")
-  }
-
-  sendChatSystemMessage(pi, DCP_STATS_MESSAGE_TYPE, lines.join("\n"), {
-    generatedAt: new Date().toISOString(),
-    activeAnchors,
-    nudgeEvents: totalNudgeEvents,
-  })
+async function handleStats(pi: ExtensionAPI, ctx: ExtensionCommandContext, state: DcpState): Promise<void> {
+  const epoch = state.sessionEpoch
+  let branch: unknown[] = []
+  let historyStatus: "full" | "unavailable" = "full"
+  try { branch = await readDcpJournalBranch(ctx) }
+  catch { historyStatus = "unavailable" }
+  if (state.sessionEpoch !== epoch) return
+  sendChatSystemMessage(pi, DCP_STATS_MESSAGE_TYPE,
+    formatDcpStatistics({ branch, historyStatus, model: ctx.model, usage: safeGetContextUsage(ctx) }),
+    { generatedAt: new Date().toISOString() })
 }
 
 // ---------------------------------------------------------------------------
@@ -290,7 +148,7 @@ async function handleSweep(
 ): Promise<void> {
   await ctx.waitForIdle()
 
-  const branch = branchEntries(ctx)
+  const branch = await readDcpJournalBranch(ctx) as any[]
 
   // Build the full set of protected tool names.
   const protectedTools = new Set<string>([
@@ -480,7 +338,7 @@ export function registerCommands(
             break
 
           case "stats":
-            handleStats(pi, ctx, state)
+            await handleStats(pi, ctx, state)
             break
 
           case "doctor":

package/external/pi-tools-suite/src/dcp/compress-tool.ts

@@ -5,7 +5,7 @@
 import { Type } from "typebox"
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent"
 import type { CompressionMember, DcpState } from "./state.js"
-import { modelKeysFromContext, resolveModelConfig, type DcpConfig } from "./config.js"
+import { modelKeysFromContext, resolveModelConfig, summarizerModelRefs, type DcpConfig } from "./config.js"
 import { captureDcpTransactionGuard, cloneDcpTransactionState, runDcpStateTransaction } from "./state-transaction.js"
 import { createHash } from "node:crypto"
 import { clearDcpNudgeAnchors } from "./pruner.js"
@@ -534,7 +534,7 @@ export function registerCompressTool(
             includedBlockIds: [],
             reason: "manual delegated summary",
           },
-          modelRefs: effectiveConfig.compress.autoCompress.summarizerModel,
+          modelRefs: summarizerModelRefs(effectiveConfig.compress.autoCompress),
           timeoutMs: effectiveConfig.compress.autoCompress.timeoutMs,
           modelRegistry: (ctx as any).modelRegistry,
           signal: _signal,
@@ -795,6 +795,12 @@ export function registerCompressTool(
         for (const block of workingState.compressionBlocks) {
           if (newBlockIds.includes(block.id)) block.operationRequestHash = requestHash
         }
+        const firstBlock = workingState.compressionBlocks.find((block) => block.id === newBlockIds[0])
+        if (firstBlock) firstBlock.commitMetrics = {
+          operationId: `manual:${_toolCallId}`, kind: "manual",
+          beforeTokens: projection.projectedBeforeTokens,
+          afterTokens: projection.projectedAfterTokens, netGainTokens: projection.netGain,
+        }
         assertCurrent()
         let published = false
         await persistState(ctx, workingState, {

package/external/pi-tools-suite/src/dcp/compression-progress.ts

@@ -27,6 +27,28 @@ export function outstandingCompressionTokens(state: DcpState, input: Compression
   return Math.max(0, previous.remainingTokens + growth + stricterTarget)
 }
 
+/**
+ * Bound one automatic recovery plan to what the *current* budget actually
+ * requires. `compressionProgress.remainingTokens` is deliberately cumulative:
+ * it follows content growth and stricter historical targets across callbacks.
+ * That debt is useful for progress accounting, but feeding the whole stale debt
+ * back into candidate sizing can make a later, much smaller capacity gap select
+ * an uneconomically huge range (and repeatedly fail with non-positive gain).
+ */
+export function compressionPlanningTokens(
+  state: DcpState,
+  input: CompressionProgressInput,
+  remainingTokens: number | undefined = outstandingCompressionTokens(state, input),
+): number {
+  const requested = Math.max(1, Math.ceil(input.requiredTokens))
+  if (
+    remainingTokens === undefined ||
+    remainingTokens <= 0 ||
+    state.compressionProgress?.kind !== input.kind
+  ) return requested
+  return Math.min(remainingTokens, requested)
+}
+
 /** Follow actual projection growth, not context callback/retry count. */
 export function trackCompressionProgress(
   state: DcpState,

package/external/pi-tools-suite/src/dcp/config.ts

@@ -65,8 +65,12 @@ export interface DcpConfig {
        * Failed calls and insufficient commits do not reset patience. */
       patience: number
       /** Models to try, in order, for auto-compress and explicit generated summaries.
+       * The first entry is the primary summarizer. Additional entries remain
+       * supported for backward compatibility with the old inline fallback list.
        * Empty array → deterministic programmatic digest (no model call). */
       summarizerModel: string[]
+      /** Explicit fallback summarizers tried after `summarizerModel`, in order. */
+      summarizerFallbackModels: string[]
       /** Hard ceiling in ms for a summarizer model call on either path. */
       timeoutMs: number
     }
@@ -144,6 +148,7 @@ const DEFAULT_CONFIG: DcpConfig = {
       enabled: false,
       patience: 2,
       summarizerModel: [],
+      summarizerFallbackModels: [],
       timeoutMs: 20000,
     },
   },
@@ -312,6 +317,55 @@ function normalizeModelKey(key: string | undefined): string | undefined {
   return trimmed.length > 0 ? trimmed : undefined
 }
 
+export function summarizerModelRefs(
+  settings: DcpConfig["compress"]["autoCompress"],
+): string[] {
+  const refs = [
+    ...(Array.isArray(settings.summarizerModel) ? settings.summarizerModel : []),
+    ...(Array.isArray(settings.summarizerFallbackModels) ? settings.summarizerFallbackModels : []),
+  ]
+  const seen = new Set<string>()
+  const result: string[] = []
+  for (const ref of refs) {
+    if (typeof ref !== "string") continue
+    const normalized = ref.trim()
+    if (!normalized || seen.has(normalized)) continue
+    seen.add(normalized)
+    result.push(normalized)
+  }
+  return result
+}
+
+function normalizeModelRefArray(value: unknown): string[] {
+  if (!Array.isArray(value)) return []
+  const seen = new Set<string>()
+  const result: string[] = []
+  for (const ref of value) {
+    if (typeof ref !== "string") continue
+    const normalized = ref.trim()
+    if (!normalized || seen.has(normalized)) continue
+    seen.add(normalized)
+    result.push(normalized)
+  }
+  return result
+}
+
+function normalizeResolvedModelArrays(config: DcpConfig): DcpConfig {
+  const autoCompress = config.compress?.autoCompress
+  if (!autoCompress || typeof autoCompress !== "object") return config
+  return {
+    ...config,
+    compress: {
+      ...config.compress,
+      autoCompress: {
+        ...autoCompress,
+        summarizerModel: normalizeModelRefArray(autoCompress.summarizerModel),
+        summarizerFallbackModels: normalizeModelRefArray(autoCompress.summarizerFallbackModels),
+      },
+    },
+  }
+}
+
 function escapeRegExp(text: string): string {
   return text.replace(/[|\\{}()[\]^$+?.]/g, "\\$&")
 }
@@ -415,17 +469,17 @@ export function resolveModelConfig(
   modelKeys: Array<string | undefined> = [],
 ): DcpConfig {
   const overrides = config.modelOverrides
-  if (!overrides || Object.keys(overrides).length === 0) return config
+  if (!overrides || Object.keys(overrides).length === 0) return normalizeResolvedModelArrays(config)
 
   const matches = matchingModelEntries(overrides, modelKeys)
-  if (matches.length === 0) return config
+  if (matches.length === 0) return normalizeResolvedModelArrays(config)
 
   let resolved = deepMerge(config, {})
   for (const [, override] of matches) {
     resolved = deepMerge(resolved, override as Partial<DcpConfig>)
   }
 
-  return resolved
+  return normalizeResolvedModelArrays(resolved)
 }
 
 // ---------------------------------------------------------------------------
@@ -454,5 +508,5 @@ export function loadConfig(options: LoadConfigOptions = {}): DcpConfig {
   )
   config.issues = issues
 
-  return config
+  return normalizeResolvedModelArrays(config)
 }

package/external/pi-tools-suite/src/dcp/conversation-index.ts

@@ -76,19 +76,43 @@ function stripDcpCarrierText(text: string): string {
   return stripStaleDcpMetadataLines(text)
 }
 
-function canonicalHashValue(value: unknown, seen = new WeakSet<object>()): unknown {
+const OMIT_JSON_OBJECT_VALUE = Symbol("omit-json-object-value")
+
+function canonicalHashValue(
+  value: unknown,
+  seen = new WeakSet<object>(),
+  arrayElement = false,
+): unknown | typeof OMIT_JSON_OBJECT_VALUE {
   if (value === null || typeof value === "string" || typeof value === "boolean") return value
-  if (typeof value === "number") return Number.isFinite(value) ? value : String(value)
+  // Exact membership is persisted in JSONL, so hash the value that can actually
+  // survive that persistence boundary. JSON.stringify serializes non-finite
+  // numbers as null, drops undefined/function/symbol object properties, and
+  // converts those values to null when they occupy an array slot. Encoding an
+  // in-memory-only sentinel here made otherwise unchanged toolResult.details
+  // fail exact replay after restart.
+  if (typeof value === "number") return Number.isFinite(value) ? value : null
   if (typeof value === "bigint") return `${value}n`
-  if (typeof value === "undefined") return "[undefined]"
-  if (typeof value === "function" || typeof value === "symbol") return String(value)
-  if (Array.isArray(value)) return value.map((item) => canonicalHashValue(item, seen))
+  if (typeof value === "undefined" || typeof value === "function" || typeof value === "symbol") {
+    return arrayElement ? null : OMIT_JSON_OBJECT_VALUE
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => {
+      const canonical = canonicalHashValue(item, seen, true)
+      return canonical === OMIT_JSON_OBJECT_VALUE ? null : canonical
+    })
+  }
   if (typeof value === "object") {
     if (seen.has(value as object)) return "[cycle]"
+    const toJSON = (value as { toJSON?: unknown }).toJSON
+    if (typeof toJSON === "function") {
+      const serialized = (toJSON as () => unknown).call(value)
+      return canonicalHashValue(serialized, seen, arrayElement)
+    }
     seen.add(value as object)
     const output: Record<string, unknown> = {}
     for (const key of Object.keys(value as Record<string, unknown>).sort()) {
-      output[key] = canonicalHashValue((value as Record<string, unknown>)[key], seen)
+      const canonical = canonicalHashValue((value as Record<string, unknown>)[key], seen, false)
+      if (canonical !== OMIT_JSON_OBJECT_VALUE) output[key] = canonical
     }
     seen.delete(value as object)
     return output
@@ -106,14 +130,17 @@ export function canonicalMessageHash(message: any): string {
   if (message && typeof message === "object") {
     for (const key of Object.keys(message).sort()) {
       if (IDENTITY_ONLY_MESSAGE_KEYS.has(key)) continue
-      canonical[key] = key === "content"
+      const value = key === "content"
         ? canonicalContentForMessageHash(message)
         : canonicalHashValue(message[key])
+      if (value !== OMIT_JSON_OBJECT_VALUE) canonical[key] = value
     }
   } else {
-    canonical.value = canonicalHashValue(message)
+    const value = canonicalHashValue(message)
+    if (value !== OMIT_JSON_OBJECT_VALUE) canonical.value = value
   }
-  return createHash("sha256").update(JSON.stringify(canonicalHashValue(canonical))).digest("hex")
+  const normalized = canonicalHashValue(canonical)
+  return createHash("sha256").update(JSON.stringify(normalized === OMIT_JSON_OBJECT_VALUE ? {} : normalized)).digest("hex")
 }
 
 const CANONICAL_HASH_RE = /^[a-f0-9]{64}$/i

package/external/pi-tools-suite/src/dcp/diagnostics.ts

@@ -0,0 +1,41 @@
+import type { DcpConfig } from "./config.js";
+import { modelKeysFromContext } from "./config.js";
+import type { DcpState } from "./state.js";
+import { estimateMessageTokens, getActiveSummaryTokenEstimate, resolveContextThresholds } from "./pruner-metadata.js";
+import { planDcpBudget } from "./progress-controller.js";
+
+/** Scalar-only diagnostic snapshot; never stores raw messages or credentials.
+ * These records are observational, never journal/recovery authority. */
+export function dcpRequestSnapshot(config: DcpConfig, state: DcpState, model: any,
+  usage: { tokens?: number | null; contextWindow?: number } | undefined,
+  raw: any[], projected: any[], reason: string) {
+  const contextWindow = Number.isFinite(model?.contextWindow) && model.contextWindow > 0
+    ? model.contextWindow : usage?.contextWindow;
+  const rawTokens = raw.reduce((sum, message) => sum + estimateMessageTokens(message), 0);
+  const projectedTokens = projected.reduce((sum, message) => sum + estimateMessageTokens(message), 0);
+  const thresholds = resolveContextThresholds(config, modelKeysFromContext({ model } as any), contextWindow);
+  const budget = contextWindow ? planDcpBudget({
+    providerUsageTokens: usage?.tokens, repoProjectedTokens: projectedTokens, contextWindow,
+    reservedOutputTokens: model?.maxTokens ?? 0, reservedToolTokens: 0,
+    maxContextPercent: thresholds.maxContextPercent,
+    hardContextPercent: config.strategies.emergencyCurrentTurnPruning.hardContextPercent,
+    targetContextPercent: Math.min(config.strategies.emergencyCurrentTurnPruning.targetContextPercent, thresholds.maxContextPercent * 0.9),
+    summaryBufferEnabled: config.compress.summaryBuffer,
+    activeSummaryTokens: getActiveSummaryTokenEstimate(state), summaryBufferMaxBonusRatio: 0.05,
+    estimatorMarginTokens: Math.max(256, Math.ceil(contextWindow * 0.0025)),
+  }) : undefined;
+  const routineTokens = contextWindow ? thresholds.minContextPercent * contextWindow : undefined;
+  let pressure = "unknown";
+  if (budget && routineTokens !== undefined) {
+    pressure = budget.capacityExceeded ? "over capacity" : budget.hardPressure ? "hard" : budget.pressured ? "strong"
+      : budget.projectedBeforeTokens > routineTokens ? "routine" : "below routine threshold";
+  }
+  return { model: model?.provider && model?.id ? `${model.provider}/${model.id}` : undefined,
+    contextWindow, rawTokens, projectedTokens, inputCapacityTokens: budget?.inputCapacityTokens,
+    reservedOutputTokens: budget?.reservedOutputTokens, routineTokens, strongTokens: budget?.softHeadroomTokens,
+    hardTokens: budget?.hardHeadroomTokens, enabled: config.enabled, manualMode: state.manualMode,
+    autoEnabled: config.compress.autoCompress.enabled, ignored: state.consecutiveIgnoredNudges,
+    routineProjectedTokens: budget?.projectedBeforeTokens ?? projectedTokens,
+    routineUsageAdjustmentTokens: 0,
+    pressure, reason, createdAt: Date.now() };
+}

package/external/pi-tools-suite/src/dcp/fresh-tool-results.ts

@@ -0,0 +1,38 @@
+/**
+ * Proof that a tool result was produced locally in this epoch and has never
+ * belonged to an attempted provider prefix. This is NOT provider-seen evidence:
+ * failed/ambiguous sends consume freshness too. Never persist or rehydrate it.
+ */
+export class FreshToolResultTracker {
+  private ready = false;
+  private readonly pending = new Map<string, string>();
+  private readonly fresh = new Set<string>();
+
+  reset(): void {
+    this.ready = false;
+    this.pending.clear();
+    this.fresh.clear();
+  }
+
+  /** Call before every send, not after successful completion. */
+  beforeProviderRequest(): void {
+    this.reset();
+    this.ready = true;
+  }
+
+  toolCall(id: string, name: string, alreadyKnown: boolean): void {
+    // Resumed/in-flight old calls and reused IDs cannot create a freshness grant.
+    if (!this.ready || alreadyKnown) return;
+    this.pending.set(id, name);
+  }
+
+  toolResult(id: string, name: string): void {
+    const expectedName = this.pending.get(id);
+    this.pending.delete(id);
+    if (expectedName === name) this.fresh.add(id);
+  }
+
+  get eligibleIds(): ReadonlySet<string> {
+    return this.fresh;
+  }
+}