talon-agent 4.6.1 → 5.0.1

package/src/backend/codex/handler/message.ts

@@ -7,11 +7,14 @@
  * `codex.resumeThread(id)`, the rollout-JSONL live/settle usage accounting
  * (`rollout-accounting.ts`), and the ChatGPT-OAuth model-mismatch recovery
  * ladder. The post-stream phases are the shared ones in
- * `backend/shared/turn-phases.ts`.
+ * `backend/runtime/turn/turn-phases.ts`.
  */
 
 import type { Thread, Usage } from "@openai/codex-sdk";
-import type { QueryParams, QueryResult } from "../../shared/handler-types.js";
+import type {
+  QueryParams,
+  QueryResult,
+} from "../../runtime/turn/handler-types.js";
 import {
   getSession,
   incrementTurns,
@@ -37,7 +40,7 @@ import {
   nameSessionFromFirstMessage,
   finishCallbackTurn,
   type StreamState,
-} from "../../shared/index.js";
+} from "../../runtime/index.js";
 
 import {
   codexSystemPromptSuffix,
@@ -48,7 +51,7 @@ import {
 import {
   frontendsForChat,
   nonTerminalFrontends,
-} from "../../shared/frontends.js";
+} from "../../runtime/frontends.js";
 import { getState } from "../state.js";
 import { ensureCodex, getCodexAuthInfo } from "../init.js";
 import {
@@ -213,6 +216,23 @@ async function maybeFallbackForChatGptMismatch(
  * ChatGPT-OAuth account is swapped pre-emptively rather than letting the
  * first turn fail.
  */
+/**
+ * The turn's user prompt: the shared framing every backend emits, plus
+ * whatever this turn's memory retrieval produced. `formatUserPrompt` is
+ * the one place `retrievedMemory` is rendered — see
+ * `backend/runtime/prompt/prompt-format.ts`.
+ */
+function buildTurnPrompt(params: QueryParams): string {
+  return formatUserPrompt({
+    text: params.text,
+    senderName: params.senderName ?? "user",
+    senderHandle: params.senderHandle,
+    isGroup: params.isGroup,
+    messageId: params.messageId,
+    retrievedMemory: params.retrievedMemory,
+  });
+}
+
 function resolveCodexModel(chatId: string, requested: string | undefined) {
   const authInfo = getCodexAuthInfo();
   const authAwareDefault =
@@ -409,7 +429,7 @@ export async function handleMessage(
   }
   const codex = ensureCodex(params.chatId);
 
-  const { chatId, text, senderName, senderHandle, isGroup, messageId } = params;
+  const { chatId, text, senderName, isGroup } = params;
   const t0 = Date.now();
   const session = getSession(chatId);
   const previousTurns = session.turns;
@@ -432,13 +452,7 @@ export async function handleMessage(
     sessionEpoch: session.createdAt,
   });
 
-  const prompt = formatUserPrompt({
-    text,
-    senderName: senderName ?? "user",
-    senderHandle,
-    isGroup,
-    messageId,
-  });
+  const prompt = buildTurnPrompt(params);
 
   log("agent", `[${chatId}] <- (${text.length} chars)`);
   traceMessage(chatId, "in", text, { senderName, isGroup });

package/src/backend/codex/handler/rollout-accounting.ts

@@ -19,7 +19,7 @@ import {
   pushLiveUsage,
   recordTokens,
   type StreamState,
-} from "../../shared/index.js";
+} from "../../runtime/index.js";
 import { CODEX_LIVE_POLL_INTERVAL_MS } from "../constants.js";
 import {
   readLastRolloutSnapshot,

package/src/backend/codex/init.ts

@@ -25,7 +25,7 @@ import { Codex } from "@openai/codex-sdk";
 import type { TalonConfig } from "../../core/config/index.js";
 import type { FrontendName } from "../../core/agent-runtime/backend-registry.js";
 import { log, logWarn } from "../../util/log.js";
-import { nonTerminalFrontends } from "../shared/frontends.js";
+import { nonTerminalFrontends } from "../runtime/frontends.js";
 import { getState } from "./state.js";
 import { asCodexConfig, buildCodexMcpServers } from "./mcp-config.js";
 import { detectCodexAuth, type CodexAuthInfo } from "./auth.js";

package/src/backend/codex/mcp-config.ts

@@ -29,8 +29,8 @@ import {
   pluginHubUrl,
   hubPluginServerNames,
 } from "../../core/mcp-hub/index.js";
-import type { ToolExclusionConfig } from "../../core/tools/mcp-env.js";
-import { frontendsForChat } from "../shared/frontends.js";
+import type { ToolExclusionConfig } from "../../core/tools/ops/mcp-env.js";
+import { frontendsForChat } from "../runtime/frontends.js";
 
 /**
  * AppToolApproval values accepted by Codex's `mcp_servers.<name>` table.

package/src/backend/codex/one-shot.ts

@@ -19,7 +19,7 @@
 
 import type { OneShotAgentParams, OneShotUsage } from "../../core/types.js";
 import { log, logWarn } from "../../util/log.js";
-import { appendBackendSuffix } from "../shared/index.js";
+import { appendBackendSuffix } from "../runtime/index.js";
 import { ensureCodex, getCodexAuthInfo } from "./init.js";
 import {
   CODEX_SYSTEM_PROMPT_SUFFIX,

package/src/backend/kilo/handler/message.ts

@@ -3,7 +3,10 @@
  * Kilo's server bindings.
  */
 
-import type { QueryParams, QueryResult } from "../../shared/handler-types.js";
+import type {
+  QueryParams,
+  QueryResult,
+} from "../../runtime/turn/handler-types.js";
 import { runRemoteChatTurn } from "../../remote-server/chat-turn.js";
 import {
   ensureServer,

package/src/backend/openai-agents/constants.ts

@@ -10,7 +10,7 @@
  * orchestration) with MCP servers wired from the plugin system.
  */
 
-import { buildDeliveryContract } from "../shared/delivery-contract.js";
+import { buildDeliveryContract } from "../runtime/prompt/delivery-contract.js";
 
 /**
  * Agents-specific addendum to the shared tool-only delivery contract:

package/src/backend/openai-agents/factory.ts

@@ -13,8 +13,8 @@ import { registerBackend } from "../../core/agent-runtime/backend-registry.js";
 import { openAIAgentsDoctorChecks } from "./doctor.js";
 import type { BackendFactory } from "../../core/agent-runtime/backend-registry.js";
 import { log } from "../../util/log.js";
-import { handlerToEvents } from "../shared/handler-to-events.js";
-import { interruptChatTurn } from "../shared/turn-interrupt.js";
+import { handlerToEvents } from "../runtime/turn/handler-to-events.js";
+import { interruptChatTurn } from "../runtime/turn/turn-interrupt.js";
 import {
   composeBackend,
   type ChatBackend,

package/src/backend/openai-agents/handler/events.ts

@@ -9,7 +9,7 @@ import {
   createStreamState,
   recordToolUse,
   recordToolCall,
-} from "../../shared/index.js";
+} from "../../runtime/index.js";
 
 export interface HandleRunItemContext {
   state: ReturnType<typeof createStreamState>;

package/src/backend/openai-agents/handler/message.ts

@@ -6,11 +6,14 @@
  * MCP bundle, iterating the `StreamedRunResult` (see `events.ts`), and
  * `.cancel()` on terminator. The post-stream phases — accounting, the
  * trailing-prose flow-violation retry, the result — are the shared ones in
- * `backend/shared/turn-phases.ts`.
+ * `backend/runtime/turn/turn-phases.ts`.
  */
 
 import { Agent, run } from "@openai/agents";
-import type { QueryParams, QueryResult } from "../../shared/handler-types.js";
+import type {
+  QueryParams,
+  QueryResult,
+} from "../../runtime/turn/handler-types.js";
 import { getSession, incrementTurns } from "../../../storage/sessions.js";
 import { getChatSettings } from "../../../storage/chat-settings.js";
 import { log, logError, logWarn } from "../../../util/log.js";
@@ -33,7 +36,7 @@ import {
   enforceTrailingProse,
   finishCallbackTurn,
   type StreamState,
-} from "../../shared/index.js";
+} from "../../runtime/index.js";
 
 import {
   buildOpenAiAgentsSuffix,
@@ -43,7 +46,7 @@ import {
 } from "../constants.js";
 import { getState, getOrCreateSession } from "../state.js";
 import { getActiveFrontends } from "../init.js";
-import { frontendsForChat } from "../../shared/frontends.js";
+import { frontendsForChat } from "../../runtime/frontends.js";
 import { getOrCreateBundle } from "../mcp-pool.js";
 import { OPENAI_AGENTS_BUILTIN_TOOLS } from "../builtins.js";
 import { activeAborts } from "./state.js";
@@ -105,6 +108,7 @@ function buildTurnPrompt(
     senderHandle: params.senderHandle,
     isGroup: params.isGroup,
     messageId: params.messageId,
+    retrievedMemory: params.retrievedMemory,
   });
   if (frontend && previousTurns === 0 && !isRetry) {
     prompt += `\n\n${buildFirstTurnReminder(frontend)}`;

package/src/backend/openai-agents/init.ts

@@ -46,7 +46,7 @@ import { setDefaultOpenAIClient, setOpenAIAPI } from "@openai/agents";
 import type { TalonConfig } from "../../core/config/index.js";
 import type { FrontendName } from "../../core/agent-runtime/backend-registry.js";
 import { log, logWarn } from "../../util/log.js";
-import { nonTerminalFrontends } from "../shared/frontends.js";
+import { nonTerminalFrontends } from "../runtime/frontends.js";
 import { getState } from "./state.js";
 import { startDiscovery } from "./discovery.js";
 

package/src/backend/openai-agents/mcp-pool.ts

@@ -30,8 +30,8 @@ import {
   pluginHubUrl,
   hubPluginServerNames,
 } from "../../core/mcp-hub/index.js";
-import type { ToolExclusionConfig } from "../../core/tools/mcp-env.js";
-import { frontendsForChat } from "../shared/frontends.js";
+import type { ToolExclusionConfig } from "../../core/tools/ops/mcp-env.js";
+import { frontendsForChat } from "../runtime/frontends.js";
 import { log, logWarn } from "../../util/log.js";
 
 /**

package/src/backend/opencode/handler/message.ts

@@ -3,7 +3,10 @@
  * bound to OpenCode's server bindings.
  */
 
-import type { QueryParams, QueryResult } from "../../shared/handler-types.js";
+import type {
+  QueryParams,
+  QueryResult,
+} from "../../runtime/turn/handler-types.js";
 import { runRemoteChatTurn } from "../../remote-server/chat-turn.js";
 import {
   ensureServer,

package/src/backend/remote-server/chat-turn.ts

@@ -5,7 +5,7 @@
  * Resolves the active model against the server's catalog, makes sure the
  * server, session, and this chat's MCP servers exist, builds the prompt
  * pair, drives the turn (`./turn.ts`), then runs the shared post-turn
- * phases (`backend/shared/turn-phases.ts`) with the one family-specific
+ * phases (`backend/runtime/turn/turn-phases.ts`) with the one family-specific
  * step in between: the usage fallback from the session summary.
  *
  * Kilo and OpenCode ran byte-for-byte copies of this (modulo the backend
@@ -18,8 +18,14 @@ import { getSession, incrementTurns } from "../../storage/sessions.js";
 import { getChatSettings } from "../../storage/chat-settings.js";
 import { log, logError } from "../../util/log.js";
 import { traceMessage } from "../../util/trace.js";
-import type { QueryParams, QueryResult } from "../shared/handler-types.js";
-import { frontendsForChat, nonTerminalFrontends } from "../shared/frontends.js";
+import type {
+  QueryParams,
+  QueryResult,
+} from "../runtime/turn/handler-types.js";
+import {
+  frontendsForChat,
+  nonTerminalFrontends,
+} from "../runtime/frontends.js";
 import {
   createStreamState,
   recordTokens,
@@ -33,7 +39,7 @@ import {
   accountFailedTurn,
   nameSessionFromFirstMessage,
   finishCallbackTurn,
-} from "../shared/index.js";
+} from "../runtime/index.js";
 import type { RemoteAgentClient } from "./client.js";
 import type { RemoteServerBindings } from "./server-bindings.js";
 import { getTurnSummary, type RemoteSessionClient } from "./session-helpers.js";
@@ -68,16 +74,7 @@ export async function runRemoteChatTurn<TClient extends RemoteAgentClient>(
   const config = bindings.getConfig();
   if (!config) throw new Error(`${label} agent not initialized`);
 
-  const {
-    chatId,
-    text,
-    senderName,
-    senderHandle,
-    isGroup,
-    messageId,
-    onTextBlock,
-    onToolUse,
-  } = params;
+  const { chatId, text, senderName, onTextBlock, onToolUse } = params;
   const t0 = Date.now();
   const session = getSession(chatId);
   const previousTurns = session.turns;
@@ -108,14 +105,8 @@ export async function runRemoteChatTurn<TClient extends RemoteAgentClient>(
     pluginMcpServerNames,
   );
 
-  // Build the prompt (time tag + sender + msg_id reference).
-  const prompt = formatUserPrompt({
-    text,
-    senderName: senderName ?? "user",
-    senderHandle,
-    isGroup,
-    messageId,
-  });
+  // Build the prompt (time tag + sender + msg_id + recalled memory).
+  const prompt = buildTurnPrompt(params);
 
   // Per-session frozen prompt + this backend's delivery suffix.
   const { text: systemPrompt } = prepareSystemPrompt({
@@ -130,7 +121,7 @@ export async function runRemoteChatTurn<TClient extends RemoteAgentClient>(
   });
 
   log("agent", `[${chatId}] <- (${text.length} chars)`);
-  traceMessage(chatId, "in", text, { senderName, isGroup });
+  traceMessage(chatId, "in", text, { senderName, isGroup: params.isGroup });
 
   // Bind the stream state to the chat so token mutators mirror counts
   // into the live-turn overlay — /status updates while the turn runs.
@@ -268,6 +259,23 @@ export async function runRemoteChatTurn<TClient extends RemoteAgentClient>(
  * session summaries can race on cancellation, so a failure leaves the
  * counts at zero.
  */
+/**
+ * The turn's user prompt: the shared framing every backend emits, plus
+ * whatever this turn's memory retrieval produced. `formatUserPrompt` is
+ * the one place `retrievedMemory` is rendered — see
+ * `backend/runtime/prompt/prompt-format.ts`.
+ */
+function buildTurnPrompt(params: QueryParams): string {
+  return formatUserPrompt({
+    text: params.text,
+    senderName: params.senderName ?? "user",
+    senderHandle: params.senderHandle,
+    isGroup: params.isGroup,
+    messageId: params.messageId,
+    retrievedMemory: params.retrievedMemory,
+  });
+}
+
 async function fillUsageFromSummary(
   oc: RemoteSessionClient,
   sessionId: string,

package/src/backend/remote-server/events.ts

@@ -33,7 +33,7 @@ import {
   recordToolUse,
   recordToolCall,
   type StreamState,
-} from "../shared/index.js";
+} from "../runtime/index.js";
 import {
   extractAssistantUsage,
   type RemoteAssistantInfo,
@@ -68,7 +68,7 @@ export interface EventProcessingContext {
   chatId: string;
   /** Session id we're scoped to — events for other sessions are dropped. */
   sessionId: string;
-  /** Stream state accumulator (shared/). */
+  /** Stream state accumulator (runtime/turn/). */
   state: StreamState;
   /** Tool-call ids we've already fired callbacks for. */
   seenToolCallIds: Set<string>;
@@ -164,7 +164,7 @@ export async function processStreamEvent(
  * lands so token/context stats are live mid-turn instead of appearing
  * only at the post-loop accounting. `recordTokens` also mirrors the
  * counts into the chat's live-turn overlay when the state is bound to a
- * chat (see `shared/stream-state.ts: pushLiveUsage`).
+ * chat (see `runtime/turn/stream-state.ts: pushLiveUsage`).
  *
  * Values are the message's totals (not deltas), matching what the
  * post-loop `extractAssistantUsage(lastAssistant.info)` reads — so the

package/src/backend/remote-server/factory.ts

@@ -28,9 +28,12 @@ import type { OneShotAgentParams, OneShotUsage } from "../../core/types.js";
 import type { TalonConfig } from "../../core/config/index.js";
 import { binaryOnPath } from "../../util/binary-on-path.js";
 import { log } from "../../util/log.js";
-import { handlerToEvents } from "../shared/handler-to-events.js";
-import type { QueryParams, QueryResult } from "../shared/handler-types.js";
-import { interruptChatTurn } from "../shared/turn-interrupt.js";
+import { handlerToEvents } from "../runtime/turn/handler-to-events.js";
+import type {
+  QueryParams,
+  QueryResult,
+} from "../runtime/turn/handler-types.js";
+import { interruptChatTurn } from "../runtime/turn/turn-interrupt.js";
 import type { RemoteModelProvider } from "./model-catalog/provider.js";
 import type { RemoteSessionSnapshot } from "./session-helpers.js";
 

package/src/backend/remote-server/index.ts

@@ -28,7 +28,7 @@
  * What's NOT here (intentionally):
  *
  *   - Tool definitions, frontend prompt format — those are backend-
- *     agnostic and live in `core/` and `backend/shared/`.
+ *     agnostic and live in `core/` and `backend/runtime/`.
  *
  * This barrel exposes the helper layer for tests and the conformance
  * suite; the bindings modules import from the concrete files directly.

package/src/backend/remote-server/mcp.ts

@@ -50,7 +50,7 @@ import { ALL_TOOLS, nativeTools } from "../../core/tools/index.js";
 import {
   frontendForChatId,
   nonTerminalFrontends,
-} from "../shared/frontends.js";
+} from "../runtime/frontends.js";
 
 // ── Constants ───────────────────────────────────────────────────────────────
 

package/src/backend/remote-server/one-shot.ts

@@ -41,7 +41,7 @@ import {
   type RemoteSessionClient,
   type RemoteAssistantInfo,
 } from "./session-helpers.js";
-import { appendBackendSuffix, sleep } from "../shared/index.js";
+import { appendBackendSuffix, sleep } from "../runtime/index.js";
 import { buildPermissionRuleset } from "./sessions.js";
 
 // ── Client surface ──────────────────────────────────────────────────────────

package/src/backend/remote-server/server-bindings.ts

@@ -25,7 +25,7 @@ import type { FrontendName } from "../../core/agent-runtime/backend-registry.js"
 import {
   buildDeliveryContract,
   type DeliveryMode,
-} from "../shared/delivery-contract.js";
+} from "../runtime/prompt/delivery-contract.js";
 import type { RemoteAgentClient } from "./client.js";
 import { createRemoteServerState, errMsg } from "./state.js";
 import { ensureRemoteServer, stopRemoteServer } from "./lifecycle.js";

package/src/backend/remote-server/turn.ts

@@ -13,7 +13,7 @@
  */
 
 import { logWarn } from "../../util/log.js";
-import { createStreamState, recordTokens, sleep } from "../shared/index.js";
+import { createStreamState, recordTokens, sleep } from "../runtime/index.js";
 import { processStreamEvent, finalizePartsIntoState } from "./events.js";
 import { findLastAssistantMessage } from "./messages.js";
 import {

package/src/backend/runtime/cache/cache-metrics.ts

@@ -0,0 +1,126 @@
+/**
+ * Prompt-cache rollups — the per-turn verdict, the tool fingerprint and the
+ * SDK's compaction boundaries, folded into counters an operator can read.
+ *
+ * `cache-telemetry.ts` next door decides WHAT a turn did (verdict,
+ * fingerprint, lookback risk) and is pure apart from its own per-chat maps.
+ * This module is the side-effecting half: it writes to the metrics store and
+ * logs, so the telemetry stays testable without a store.
+ *
+ * Why these numbers exist (docs/cache-economics.md, PR A): every decision in
+ * PR B ("one prefix per frontend") and PR C ("compact when the cache has gone
+ * cold") needs a before/after figure, and nothing here changes a prompt byte
+ * or a turn's behaviour — measurement only.
+ *
+ *   - `cache.first_request.{hit,miss,none}` — did the previous turn's prefix
+ *     survive? The turn's first request is the only one that can say, and it
+ *     is the number that tracks cost.
+ *   - `cache.first_request.{read,write}_tokens` — how big the prefix is, so a
+ *     miss can be priced.
+ *   - `cache.session_start.{hit,miss,none}` — the same verdict restricted to a
+ *     chat's FIRST turn. A hit there means another chat had already warmed an
+ *     identical prefix: the cross-chat sharing signal PR B is aiming at.
+ *   - `cache.tool_fingerprint.changed` — tools render before the system
+ *     prompt, so a change invalidates everything after it.
+ *   - `session.compacted.{manual,auto}` + `session.compact.{pre,post}_tokens`
+ *     — how often the SDK compacts and how much it reclaims, the baseline
+ *     PR C's idle-compaction policy is measured against.
+ */
+
+import { log } from "../../../util/log.js";
+import {
+  incrementCounter,
+  noteCacheVerdict,
+  recordHistogram,
+} from "../../../storage/metrics.js";
+import {
+  crossTurnVerdict,
+  fingerprintHash,
+  hasToolFingerprint,
+  noteToolFingerprint,
+  type CrossTurnVerdict,
+  type TurnCacheStats,
+} from "./cache-telemetry.js";
+
+/**
+ * Roll one finished turn's cache behaviour up into the metrics store and
+ * remember the verdict for `/status`.
+ *
+ * `turnsIncludingThis` is the chat's turn count with this turn already
+ * counted, so 1 means the turn was the session's first — the only turn whose
+ * verdict says anything about cross-chat prefix sharing.
+ */
+export function rollUpTurnCache(
+  chatId: string,
+  stats: TurnCacheStats,
+  turnsIncludingThis: number,
+): CrossTurnVerdict {
+  const verdict = crossTurnVerdict(stats);
+  incrementCounter(`cache.first_request.${verdict}`);
+  // Recorded on every turn, zeros included: the average is then "tokens per
+  // turn", which is what a miss costs, rather than an average over the
+  // turns that happened to be interesting.
+  recordHistogram("cache.first_request.read_tokens", stats.firstRead);
+  recordHistogram("cache.first_request.write_tokens", stats.firstWrite);
+  if (turnsIncludingThis <= 1) {
+    incrementCounter(`cache.session_start.${verdict}`);
+  }
+  noteCacheVerdict(chatId, verdict);
+  return verdict;
+}
+
+/**
+ * Record a chat's tool set: one info line the first time a chat is seen (so
+ * two chats on the same frontend can be compared by eye — identical hash +
+ * identical static prompt ⇒ shared cache), and a counter whenever it changes
+ * mid-process. `noteToolFingerprint` still owns the warning it already logs
+ * for a mid-session change.
+ */
+export function reportToolFingerprint(
+  chatId: string,
+  fingerprint: readonly string[],
+): void {
+  const seen = hasToolFingerprint(chatId);
+  const changed = noteToolFingerprint(chatId, fingerprint);
+  if (!seen) {
+    log(
+      "agent",
+      `[${chatId}] tool fingerprint ${fingerprintHash(fingerprint)} ` +
+        `(${fingerprint.length} tools)`,
+    );
+  }
+  if (changed) incrementCounter("cache.tool_fingerprint.changed");
+}
+
+/** The SDK's compaction metadata, narrowed to the fields that are measured. */
+export type CompactBoundary = {
+  trigger: "manual" | "auto";
+  pre_tokens: number;
+  post_tokens?: number;
+};
+
+/**
+ * Record a compaction boundary the SDK reported mid-stream. Purely
+ * observational — the turn carries on exactly as it did before, this just
+ * stops the event being dropped on the floor.
+ */
+export function recordCompactBoundary(
+  chatId: string,
+  meta: CompactBoundary,
+): void {
+  const trigger = meta.trigger === "manual" ? "manual" : "auto";
+  incrementCounter(`session.compacted.${trigger}`);
+  const pre = Number.isFinite(meta.pre_tokens) ? meta.pre_tokens : 0;
+  const post =
+    typeof meta.post_tokens === "number" && Number.isFinite(meta.post_tokens)
+      ? meta.post_tokens
+      : undefined;
+  recordHistogram("session.compact.pre_tokens", pre);
+  if (post !== undefined) recordHistogram("session.compact.post_tokens", post);
+  log(
+    "agent",
+    `[${chatId}] context compacted (${trigger}): ${pre} tokens` +
+      (post !== undefined ? ` -> ${post}` : "") +
+      ` — the prefix after the boundary is new, so the next turn re-writes it`,
+  );
+}

package/src/backend/{shared → runtime/cache}/cache-telemetry.ts

@@ -36,7 +36,9 @@
  * did.
  */
 
-import { logWarn } from "../../util/log.js";
+import { createHash } from "node:crypto";
+
+import { logWarn } from "../../../util/log.js";
 
 // ── Per-turn cache stats ────────────────────────────────────────────────────
 
@@ -244,7 +246,7 @@ export function cacheMinimumTokens(model: string): number | undefined {
   return best?.min;
 }
 
-/** Cheap tokenizer-free estimate (~4 chars/token), matching soul/projector. */
+/** Cheap tokenizer-free estimate (~4 chars/token), the house heuristic. */
 function estimateTokens(text: string): number {
   return Math.ceil(text.length / 4);
 }
@@ -307,6 +309,24 @@ export function toolFingerprint(
   ].sort();
 }
 
+/**
+ * Short, stable digest of a tool set — the thing to compare between two
+ * chats. Two chats whose fingerprints (and static prompt) match render a
+ * byte-identical prefix and therefore share the cache; two that don't,
+ * can't, however similar they look (docs/cache-economics.md, PR B).
+ */
+export function fingerprintHash(fingerprint: readonly string[]): string {
+  return createHash("sha256")
+    .update(fingerprint.join("\n"))
+    .digest("hex")
+    .slice(0, 12);
+}
+
+/** True once a fingerprint has been recorded for this chat in this process. */
+export function hasToolFingerprint(chatId: string): boolean {
+  return lastToolSets.has(chatId);
+}
+
 /**
  * Record this turn's tool set for a chat and warn when it differs from the
  * previous turn's. Returns true when a change was detected.