talon-agent 4.6.1 → 5.0.1

package/README.md

@@ -119,9 +119,9 @@ index.ts                    Composition root
   |   +-- bus/              Typed pub-sub spine + event journal
   |   +-- vfs/              The talon:// namespace (~/.talon/ns), FUSE-backed
   |   +-- mesh/             Device mesh: presence, exec/fs channel, teleport
-  |   +-- soul/             Soul kernel — associative recall over memory
-  |   +-- scripts/          Run-to-completion execution of saved scripts
-  |   +-- scripting/        WASM-sandboxed Lua runner for trigger scripts
+  |   +-- memory/           Typed memory store policy: core view, import, taps
+  |   +-- scripts/          Run-to-completion execution of saved scripts +
+  |   |                     the WASM-sandboxed Lua runner for trigger scripts
   |   +-- daemon/           Start / stop / restart, pidfile, discovery
   |   +-- plugin/           Plugin loader, registry, hot-reload
   |   +-- update/           Self-update for git-checkout deployments

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "4.6.1",
+  "version": "5.0.1",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "Dylan Neve",
   "license": "MIT",
@@ -84,6 +84,7 @@
     "depcruise": "node scripts/check-architecture.mjs",
     "ratchets": "node scripts/check-ratchets.mjs",
     "function-size": "node scripts/check-function-size.mjs",
+    "tree": "node scripts/check-tree.mjs",
     "knip": "knip",
     "format": "prettier --write src/ prompts/",
     "format:check": "prettier --check src/ prompts/",

package/prompts/README.md

@@ -95,7 +95,7 @@ frontend, so it never belongs in the frontend `.md` files:
 The delivery TOOL NAMES are per-frontend (`end_turn`/`send`/`react` on
 telegram & discord, `end_turn`/`send_message`/`react` on native,
 `end_turn`/`send_message` on teams) and are injected into the templates
-by `src/backend/shared/delivery-contract.ts`, which is also where the
+by `src/backend/runtime/prompt/delivery-contract.ts`, which is also where the
 frontend-aware `[FLOW VIOLATION]` reminder and the first-turn nudge
 (appended to the turn-0 user message) are built.
 
@@ -109,7 +109,7 @@ contradictions between backends.
 `heartbeat.md` and `dream.md` are not part of the chat system prompt — they
 are standalone prompts for the background heartbeat and memory-consolidation
 (dream) agents, loaded by `src/core/background/heartbeat.ts` /
-`src/core/background/dream.ts`.
+`src/core/background/dream/index.ts`.
 
 ## Token budget
 

package/prompts/system/memory-recall.md

@@ -59,3 +59,19 @@ memory instead is what crowds a memory file with snapshots that were true for
 an hour.
 
 Memory updates should usually be quiet unless the user asks about them.
+
+### Remembering
+
+When the `remember`, `recall`, and `forget` tools are available, they are the
+canonical store — use them in preference to editing memory files by hand.
+
+Call `remember` as you learn something durable: a stated preference, a
+correction to something you had wrong, a fact about a person or a project the
+user would expect you to still know next week. One claim per call.
+
+Never store secrets or credentials, live operational status, or anything the
+user asked you to keep off the record — and never store a claim as fact when
+you are only guessing.
+
+If a claim is already on file in a different wording, replace it rather than
+adding a second copy; `forget` needs a reason, and drops are recoverable.

package/src/app.ts

@@ -7,11 +7,14 @@
  */
 
 import { getFrontends } from "./core/config/index.js";
-import { startUploadCleanup, stopUploadCleanup } from "./util/workspace.js";
+import { startUploadCleanup, stopUploadCleanup } from "./core/vfs/workspace.js";
 import { flushDatabase } from "./storage/db.js";
 import { getActiveCount, stopAllTurns } from "./core/engine/dispatcher.js";
-import { startPulseTimer, stopPulseTimer } from "./core/background/pulse.js";
-import { stopPlanAlerts } from "./core/background/plan-alerts.js";
+import {
+  startPulseTimer,
+  stopPulseTimer,
+} from "./core/background/pulse/pulse.js";
+import { stopPlanAlerts } from "./core/background/pulse/plan-alerts.js";
 import {
   startHeartbeatTimer,
   stopHeartbeatTimer,
@@ -21,13 +24,13 @@ import {
   startCronTimer,
   stopCronTimer,
   runStartupCatchup,
-} from "./core/background/cron.js";
+} from "./core/background/cron/scheduler.js";
 import { shutdownTriggers } from "./core/background/triggers/index.js";
 import { pruneSettledTriggers } from "./storage/triggers.js";
 import { startWatchdog, stopWatchdog } from "./util/watchdog.js";
-import { spawnSuccessor } from "./util/respawn.js";
+import { spawnSuccessor } from "./core/daemon/respawn.js";
 import { log, logError, logWarn } from "./util/log.js";
-import { bootPhase, bootReport } from "./util/boot-timer.js";
+import { bootPhase, bootReport } from "./core/daemon/boot-timer.js";
 import {
   getVfs,
   mountNamespaceFs,
@@ -51,6 +54,11 @@ import {
   writePidRecord,
   removePidRecordIfOwnedBy,
 } from "./core/daemon/pidfile.js";
+import {
+  recordBootMetrics,
+  startResourceSampler,
+  stopResourceSampler,
+} from "./core/daemon/resource-sampler.js";
 
 const { config } = await bootPhase("bootstrap", () => bootstrap());
 
@@ -202,6 +210,7 @@ async function gracefulShutdown(signal: string): Promise<void> {
   });
   await shutdownStep("triggers", shutdownTriggers);
   await shutdownStep("watchdog", stopWatchdog);
+  await shutdownStep("resource sampler", stopResourceSampler);
   await shutdownStep("upload cleanup", stopUploadCleanup);
   await shutdownStep("mcp hub", async () => {
     const { shutdownHub } = await import("./core/mcp-hub/index.js");
@@ -311,7 +320,13 @@ async function main(): Promise<void> {
   await bootPhase("frontends start", () =>
     Promise.all(blockingFrontends.map((frontend) => frontend.start())),
   );
-  log("bot", `Ready in ${bootReport()}`);
+  // Phase 0 accounting (docs/ts-migration-plan.md): the boot is over the
+  // moment the frontends are listening, so the totals are folded into the
+  // metrics store here, from the same uptime figure the log line prints.
+  const bootMs = Math.round(process.uptime() * 1000);
+  recordBootMetrics(bootMs);
+  startResourceSampler();
+  log("bot", `Ready in ${bootReport(bootMs)}`);
   for (const frontend of stdinFrontends) {
     void frontend
       .start()

package/src/backend/claude-sdk/factory.ts

@@ -24,23 +24,12 @@ import {
   type ToolRuntime,
   type UsageTelemetry,
 } from "../../core/agent-runtime/capabilities.js";
-import { getPlanUsage } from "./plan-usage.js";
 
 import {
-  initAgent as initClaudeAgent,
   updateSystemPrompt as claudeUpdateSystemPrompt,
-  warmSession as claudeWarmSession,
-  getActiveQuery,
-  buildMcpServers,
-  buildPluginMcpServers,
-  runOneShotAgent as claudeRunOneShotAgent,
   evictOrphanSubprocesses as claudeEvictOrphanSubprocesses,
 } from "./index.js";
-import {
-  runChatTurn as claudeRunChatTurn,
-  interruptChatTurn as claudeInterruptChatTurn,
-} from "./handler.js";
-import { waitForMcpServersReady } from "./mcp-ready.js";
+import { createInProcessAgentHost } from "./host/in-process.js";
 
 import * as modelProvider from "./model-provider.js";
 import { claudeDoctorChecks } from "./doctor.js";
@@ -54,16 +43,25 @@ const claudeSdkFactory: BackendFactory = {
   doctor: (config, isActive) => claudeDoctorChecks(config, isActive),
 
   async init(config, ctx) {
-    await initClaudeAgent(config, ctx.getBridgePort);
+    // Everything SDK-side goes through the agent-host seam
+    // (docs/agent-host-sidecar.md). Phase 1 binds the in-process client,
+    // which calls the same functions this factory used to call inline;
+    // Phase 2 swaps in a process-backed client behind the same interface.
+    const host = createInProcessAgentHost(config, ctx.getBridgePort);
+    await host.hello();
     log("bot", "Backend: Claude SDK (@anthropic-ai/claude-agent-sdk)");
 
     const chat: ChatBackend = {
-      runChatTurn: (params) => claudeRunChatTurn(params),
-      interruptChatTurn: (chatId) => claudeInterruptChatTurn(chatId),
+      runChatTurn: (params) => host.runTurn(params),
+      interruptChatTurn: (chatId) => host.interrupt(chatId),
     };
 
     const background: BackgroundRunner = {
-      runOneShotAgent: (p) => claudeRunOneShotAgent(p),
+      runOneShotAgent: (p) => host.runOneShot(p),
+      // Not a protocol-table row yet: subprocess eviction reaches into
+      // the SDK's own children, so it belongs to the host — but the
+      // design's message table has no request for it. Tracked as an open
+      // question against Phase 2; bound directly until it gains one.
       evictOrphanSubprocesses: (label) => claudeEvictOrphanSubprocesses(label),
     };
 
@@ -81,7 +79,10 @@ const claudeSdkFactory: BackendFactory = {
       getProviderModels: (p, pg, ps) =>
         modelProvider.getProviderModels(p, pg, ps),
       formatModelError: (q, r) => modelProvider.formatModelError(q, r),
-      listModels: (f) => modelProvider.listModels(f),
+      // The one catalog member that asks the host: `list_models` is the
+      // protocol's model row. The seven above are daemon-side formatting
+      // over `core/models/catalog.ts`, which `hello` populates.
+      listModels: (f) => host.listModels(f),
     };
 
     // Claude SDK's per-turn subprocess model has no shared session
@@ -89,32 +90,11 @@ const claudeSdkFactory: BackendFactory = {
     // dispatcher's `/reset` clears Talon's stored session id via
     // `storage/sessions.ts:resetSession` regardless.
     const sessions: SessionBackend = {
-      warmSession: (chatId) => claudeWarmSession(chatId),
+      warmSession: (chatId) => host.warmSession(chatId),
     };
 
     const tools: ToolRuntime = {
-      refreshTools: async (chatId) => {
-        const qi = getActiveQuery(chatId);
-        if (!qi) return null;
-        // Two-phase teardown: remove all MCP servers first so each
-        // subprocess receives an OS-agnostic shutdown via stdio, then
-        // install the fresh set.
-        await qi.setMcpServers({});
-        const freshServers = {
-          ...buildMcpServers(chatId),
-          ...buildPluginMcpServers(chatId),
-        };
-        const result = await qi.setMcpServers(freshServers);
-        // setMcpServers resolves on REGISTER, not CONNECT — MCP startup is
-        // non-blocking. A stdio server that dials a slow remote (e.g. the
-        // playwright plugin connecting to the Camoufox websocket) is still
-        // 'pending' at this point and its tools are absent from the live
-        // registry, so the turn would proceed with mcp__playwright-tools__*
-        // stuck "connecting" until the next refresh. Wait (bounded) for the
-        // newly-added servers to finish connecting before returning.
-        await waitForMcpServersReady(qi, result.added);
-        return result;
-      },
+      refreshTools: (chatId) => host.refreshTools(chatId),
     };
 
     const control: SystemControl = {
@@ -124,7 +104,7 @@ const claudeSdkFactory: BackendFactory = {
     // No per-session snapshot to offer (each turn is a fresh subprocess),
     // but the subscription's rate-limit windows are readable.
     const usage: UsageTelemetry = {
-      getPlanUsage: () => getPlanUsage(),
+      getPlanUsage: () => host.planUsage(),
     };
 
     const backend = composeBackend({

package/src/backend/claude-sdk/handler.ts

@@ -6,7 +6,7 @@
  * (session expired / context overflow / model fallback via
  * `applyRetryDecisionStream`) and the post-result watchdog. The phases
  * after the stream — accounting, the trailing-prose contract, the result
- * events — are the shared ones in `backend/shared/turn-phases.ts`.
+ * events — are the shared ones in `backend/runtime/turn/turn-phases.ts`.
  *
  * The exported async generator `runChatTurn` is what the factory wires
  * onto `ChatBackend.runChatTurn` — no wrapper, no callback shim.
@@ -34,12 +34,13 @@ import {
 } from "../../core/agent-runtime/events.js";
 import type { ChatRunParams } from "../../core/agent-runtime/capabilities.js";
 import { makeBareModelRef } from "../../core/agent-runtime/model-ref.js";
-import { applyRetryDecisionStream } from "../shared/handle-retry.js";
+import { applyRetryDecisionStream } from "../runtime/turn/handle-retry.js";
 import { getConfig } from "./state.js";
 import { buildSdkOptions, getActiveFrontends } from "./options.js";
 import { waitForMcpServersReady } from "./mcp-ready.js";
 import { invalidatePlanUsage } from "./plan-usage.js";
-import { frontendsForChat } from "../shared/frontends.js";
+import { frontendsForChat } from "../runtime/frontends.js";
+import { rollUpTurnCache } from "../runtime/cache/cache-metrics.js";
 import {
   createStreamState,
   isSystemInit,
@@ -47,10 +48,12 @@ import {
   isAssistant,
   isResult,
   isRateLimitEvent,
+  isCompactBoundary,
   isUserMessage,
   extractToolResults,
   processStreamDelta,
   processAssistantMessage,
+  processCompactBoundary,
   processResultMessage,
   type StreamState,
 } from "./stream.js";
@@ -74,7 +77,7 @@ import {
   enforceTrailingProse,
   buildResultEvents,
   turnUsageSnapshot,
-} from "../shared/index.js";
+} from "../runtime/index.js";
 
 // ── Post-result watchdog ────────────────────────────────────────────────────
 // The SDK's PostToolBatch hook is the canonical loop-terminator — it returns
@@ -334,6 +337,12 @@ async function* consumeSdkStream(
       yield* translateToolResults(ctx, message);
       continue;
     }
+    // The SDK compacted the session mid-turn. Measured, not acted on: the
+    // turn carries on exactly as before.
+    if (isCompactBoundary(message)) {
+      processCompactBoundary(message, ctx.chatId);
+      continue;
+    }
     // The turn just moved the plan's usage — drop the cached windows so
     // the next /status reads them again instead of showing pre-turn
     // figures.
@@ -399,6 +408,7 @@ function buildTurnPrompt(
     senderHandle: params.senderHandle,
     isGroup: params.isGroup,
     messageId: params.messageId,
+    retrievedMemory: params.retrievedMemory,
   });
   if (frontend && previousTurns === 0 && !internal.flowRetries) {
     prompt += `\n\n${buildFirstTurnReminder(frontend)}`;
@@ -445,12 +455,23 @@ function accountFailedClaudeTurn(
 /**
  * The aggregate `cache=NN%` can't distinguish a turn that reused the
  * previous turn's prefix from one that re-wrote it — see
- * shared/cache-telemetry.ts. A lookback overflow only *predicts* a miss,
+ * runtime/cache/cache-telemetry.ts. A lookback overflow only *predicts* a miss,
  * so warn when this turn's verdict proves the previous turn's overflow
  * cost a prefix re-write, then record this turn's overflow for the next.
+ *
+ * Also the rollup seam: the verdict goes into `cache.first_request.*` (and
+ * `cache.session_start.*` on a chat's first turn) here rather than in
+ * `runChatTurn`, which is at its size limit. `turnsIncludingThis` is the
+ * session's turn count with this turn already counted — `incrementTurns`
+ * has run by the time this is called, so 1 means "this was the first".
  */
-function reportCacheVerdict(chatId: string, state: StreamState): void {
+function reportCacheVerdict(
+  chatId: string,
+  state: StreamState,
+  turnsIncludingThis: number,
+): void {
   if (state.cacheStats) {
+    rollUpTurnCache(chatId, state.cacheStats, turnsIncludingThis);
     const overflow = priorLookbackOverflow(chatId);
     if (
       overflow !== undefined &&
@@ -647,7 +668,7 @@ export async function* runChatTurn(
   incrementTurns(chatId);
 
   state.allResponseText += state.currentBlockText;
-  reportCacheVerdict(chatId, state);
+  reportCacheVerdict(chatId, state, session.turns);
 
   const usage = turnUsageSnapshot(state);
   log(

package/src/backend/claude-sdk/host/in-process.ts

@@ -0,0 +1,147 @@
+/**
+ * The in-process agent host — `AgentHostClient` implemented as direct
+ * calls into `backend/claude-sdk/`.
+ *
+ * `docs/agent-host-sidecar.md` Phase 1. This is the implementation that
+ * keeps today's behaviour exactly: every method is a call-through to the
+ * function the claude-sdk `BackendFactory` used to call itself. There is
+ * no process, no framing and no logic of its own — the only code that
+ * moved here is `refreshTools`' two-phase MCP teardown, which had to,
+ * because it drives a `Query` handle and handles do not cross a process
+ * boundary.
+ *
+ * Phase 2 adds a sibling that speaks the same interface over a child
+ * process's stdio. Nothing above this file changes when it does.
+ */
+
+import type {
+  AgentHostClient,
+  HostReadyInfo,
+  HostSessionInfo,
+  HostToolRefresh,
+} from "../../../core/agent-runtime/agent-host.js";
+import { AGENT_HOST_PROTOCOL_VERSION } from "../../../core/agent-runtime/agent-host.js";
+import type { TalonConfig } from "../../../core/config/index.js";
+import { getSession } from "../../../storage/sessions.js";
+import { talonVersion } from "../../../util/version.js";
+
+import {
+  initAgent as claudeInitAgent,
+  warmSession as claudeWarmSession,
+  getActiveQuery,
+  buildMcpServers,
+  buildPluginMcpServers,
+  runOneShotAgent as claudeRunOneShotAgent,
+} from "../index.js";
+import {
+  runChatTurn as claudeRunChatTurn,
+  interruptChatTurn as claudeInterruptChatTurn,
+} from "../handler.js";
+import { waitForMcpServersReady } from "../mcp-ready.js";
+import { listModels as claudeListModels } from "../model-provider.js";
+import { getPlanUsage } from "../plan-usage.js";
+
+/**
+ * Install an MCP server set on the chat's live query. `null` when the
+ * chat has no query in flight — the same "nothing to refresh" answer
+ * `ToolRuntime.refreshTools` has always given.
+ */
+async function setMcpServers(
+  chatId: string,
+  servers: Record<string, unknown>,
+): Promise<HostToolRefresh | null> {
+  const qi = getActiveQuery(chatId);
+  if (!qi) return null;
+  return qi.setMcpServers(servers as Parameters<typeof qi.setMcpServers>[0]);
+}
+
+/**
+ * Re-derive the chat's MCP config from the live plugin registry. Body
+ * lifted verbatim from the claude-sdk factory's `tools.refreshTools`,
+ * comments included — the ordering is load-bearing.
+ */
+async function refreshTools(chatId: string): Promise<HostToolRefresh | null> {
+  const qi = getActiveQuery(chatId);
+  if (!qi) return null;
+  // Two-phase teardown: remove all MCP servers first so each
+  // subprocess receives an OS-agnostic shutdown via stdio, then
+  // install the fresh set.
+  await qi.setMcpServers({});
+  const freshServers = {
+    ...buildMcpServers(chatId),
+    ...buildPluginMcpServers(chatId),
+  };
+  const result = await qi.setMcpServers(freshServers);
+  // setMcpServers resolves on REGISTER, not CONNECT — MCP startup is
+  // non-blocking. A stdio server that dials a slow remote (e.g. the
+  // playwright plugin connecting to the Camoufox websocket) is still
+  // 'pending' at this point and its tools are absent from the live
+  // registry, so the turn would proceed with mcp__playwright-tools__*
+  // stuck "connecting" until the next refresh. Wait (bounded) for the
+  // newly-added servers to finish connecting before returning.
+  await waitForMcpServersReady(qi, result.added);
+  return result;
+}
+
+/**
+ * The context figures `warm_session` populates, read back out of the
+ * daemon's session store. In-process the host and the store share a
+ * process, so this is a lookup; in Phase 2 it is the reply that carries
+ * those numbers home.
+ */
+async function sessionInfo(chatId: string): Promise<HostSessionInfo> {
+  const session = getSession(chatId);
+  return {
+    chatId,
+    sessionId: session.sessionId,
+    turns: session.turns,
+    contextTokens: session.usage.contextTokens,
+    contextWindow: session.usage.contextWindow,
+  };
+}
+
+/**
+ * The Claude SDK backend keeps no conversation memory of its own — each
+ * turn is a fresh subprocess — so the only per-chat state the host holds
+ * is the in-flight query handle. Dropping it is interrupting it.
+ *
+ * Not bound into the `Backend` object: claude-sdk has no `resetChat`
+ * slot today and Phase 1 does not add one. `/reset` still clears the
+ * stored session id through `storage/sessions.ts`, as it always has.
+ */
+async function resetSession(chatId: string): Promise<boolean> {
+  return claudeInterruptChatTurn(chatId);
+}
+
+/**
+ * Build the in-process host. `config` and `getBridgePort` are held only
+ * for `hello()`, which performs the same `initAgent(config,
+ * getBridgePort)` the factory used to call inline.
+ */
+export function createInProcessAgentHost(
+  config: TalonConfig,
+  getBridgePort?: () => number,
+): AgentHostClient {
+  return {
+    async hello(): Promise<HostReadyInfo> {
+      await claudeInitAgent(config, getBridgePort);
+      // `sdk` is omitted: in-process there is no separately-pinned SDK
+      // build to name — the daemon's own lockfile is the answer, and
+      // Phase 4 gives the host a `package.json` of its own to report.
+      return { protocol: AGENT_HOST_PROTOCOL_VERSION, host: talonVersion() };
+    },
+    runTurn: (params) => claudeRunChatTurn(params),
+    interrupt: (chatId) => claudeInterruptChatTurn(chatId),
+    runOneShot: (params) => claudeRunOneShotAgent(params),
+    warmSession: (chatId) => claudeWarmSession(chatId),
+    setMcpServers,
+    refreshTools,
+    listModels: (filter) => claudeListModels(filter),
+    planUsage: () => getPlanUsage(),
+    sessionInfo,
+    resetSession,
+    // Nothing to drain while the host is this process: the daemon's own
+    // shutdown path already aborts in-flight turns.
+    shutdown: async () => undefined,
+  };
+}

package/src/backend/claude-sdk/one-shot.ts

@@ -19,7 +19,7 @@ import { log, logWarn } from "../../util/log.js";
 import { ALLOWED_TOOLS_BACKGROUND } from "../../core/constants.js";
 import { EFFORT_MAP } from "./constants.js";
 import { buildMcpServers, buildPluginMcpServers } from "./options.js";
-import { warnIfBelowCacheMinimum } from "../shared/cache-telemetry.js";
+import { warnIfBelowCacheMinimum } from "../runtime/cache/cache-telemetry.js";
 
 const DEFAULT_SUBPROCESS_KILL_GRACE_MS = 5 * 1000;
 

package/src/backend/claude-sdk/options.ts

@@ -15,7 +15,7 @@ import type {
   HookCallback,
   HookJSONOutput,
 } from "@anthropic-ai/claude-agent-sdk";
-import type { PreparedSystemPrompt } from "../shared/system-prompt.js";
+import type { PreparedSystemPrompt } from "../runtime/prompt/system-prompt.js";
 import { getSession } from "../../storage/sessions.js";
 import { getChatSettings } from "../../storage/chat-settings.js";
 import { resolveModelId } from "../../core/models/catalog.js";
@@ -25,11 +25,12 @@ import {
   pluginHubUrl,
   hubPluginServerNames,
 } from "../../core/mcp-hub/index.js";
-import { nonTerminalFrontends, frontendsForChat } from "../shared/frontends.js";
 import {
-  noteToolFingerprint,
-  toolFingerprint,
-} from "../shared/cache-telemetry.js";
+  nonTerminalFrontends,
+  frontendsForChat,
+} from "../runtime/frontends.js";
+import { toolFingerprint } from "../runtime/cache/cache-telemetry.js";
+import { reportToolFingerprint } from "../runtime/cache/cache-metrics.js";
 import { log, logError } from "../../util/log.js";
 import { getConfig, getBridgePort } from "./state.js";
 import { ALLOWED_TOOLS_CHAT, EFFORT_MAP } from "./constants.js";
@@ -395,7 +396,7 @@ export function buildSdkOptions(
   // mid-session invalidates the system prompt and every cached message after
   // it — the most expensive cache event there is, and one the aggregate
   // hit-rate can't show. Plugin-provided MCP servers are the mutable part.
-  noteToolFingerprint(
+  reportToolFingerprint(
     chatId,
     toolFingerprint(builtinTools, Object.keys(mcpServers)),
   );

package/src/backend/claude-sdk/stream.ts

@@ -7,6 +7,7 @@
  */
 
 import type {
+  SDKCompactBoundaryMessage,
   SDKMessage,
   SDKSystemMessage,
   SDKPartialAssistantMessage,
@@ -22,7 +23,8 @@ import { checkModelDrift } from "./model-drift.js";
 import {
   turnCacheStats,
   type TurnCacheStats,
-} from "../shared/cache-telemetry.js";
+} from "../runtime/cache/cache-telemetry.js";
+import { recordCompactBoundary } from "../runtime/cache/cache-metrics.js";
 
 // ── Stream state accumulator ────────────────────────────────────────────────
 
@@ -46,7 +48,7 @@ export type StreamState = {
    * `usage.iterations`. Undefined when the provider reported none — the
    * aggregate totals above cannot distinguish a turn that read the previous
    * turn's prefix from one that re-wrote it, and that distinction is the
-   * whole cost signal (see shared/cache-telemetry.ts).
+   * whole cost signal (see runtime/cache/cache-telemetry.ts).
    */
   cacheStats: TurnCacheStats | undefined;
   lastStreamUpdate: number;
@@ -156,6 +158,18 @@ export function isRateLimitEvent(msg: SDKMessage): boolean {
   return msg.type === "rate_limit_event";
 }
 
+/**
+ * Emitted when the SDK compacts the session — the transcript before the
+ * boundary is replaced by a summary, so every cached block after the system
+ * prompt is gone and the next turn re-writes it. Shares `type: 'system'`
+ * with the init message, so the subtype is what tells them apart.
+ */
+export function isCompactBoundary(
+  msg: SDKMessage,
+): msg is SDKCompactBoundaryMessage {
+  return msg.type === "system" && msg.subtype === "compact_boundary";
+}
+
 // ── Message processors ──────────────────────────────────────────────────────
 
 /** Output of `processStreamDelta` when the throttle interval has elapsed. */
@@ -334,6 +348,19 @@ export function extractToolResults(msg: SDKUserMessage): ToolResultInfo[] {
   return results;
 }
 
+/**
+ * Record a compaction boundary. Observational only: the turn proceeds
+ * exactly as it did before this message was recognised — what changes is
+ * that `session.compacted.*` now says how often the SDK compacts and how
+ * much it reclaims (docs/cache-economics.md, PR A step 3).
+ */
+export function processCompactBoundary(
+  msg: SDKCompactBoundaryMessage,
+  chatId: string,
+): void {
+  recordCompactBoundary(chatId, msg.compact_metadata);
+}
+
 /** Context fill of the last API iteration + whether the turn's first request hit the cache. */
 function readContextFill(
   state: StreamState,
@@ -450,4 +477,4 @@ export function processResultMessage(
 export {
   normalizeForDedupe,
   isDuplicateOfDelivered,
-} from "../shared/delivered-text.js";
+} from "../runtime/turn/delivered-text.js";

package/src/backend/claude-sdk/warm.ts

@@ -11,7 +11,7 @@ import { getSession } from "../../storage/sessions.js";
 import { log, logWarn } from "../../util/log.js";
 import { getConfig } from "./state.js";
 import { buildSdkOptions } from "./options.js";
-import { prepareSystemPrompt } from "../shared/index.js";
+import { prepareSystemPrompt } from "../runtime/index.js";
 
 export async function warmSession(chatId: string): Promise<void> {
   // Guard against being called before initAgent()

package/src/backend/codex/constants.ts

@@ -2,7 +2,7 @@
  * Codex backend constants.
  */
 
-import { buildDeliveryContract } from "../shared/delivery-contract.js";
+import { buildDeliveryContract } from "../runtime/prompt/delivery-contract.js";
 
 /**
  * System-prompt suffix appended to the user-configured system prompt.

package/src/backend/codex/factory.ts

@@ -10,8 +10,8 @@ import { registerBackend } from "../../core/agent-runtime/backend-registry.js";
 import { codexDoctorChecks } 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/codex/handler/events.ts

@@ -16,7 +16,7 @@ import {
   recordToolUse,
   recordToolCall,
   type StreamState,
-} from "../../shared/index.js";
+} from "../../runtime/index.js";
 
 export interface HandleEventContext {
   state: StreamState;