llm-switcher 1.4.1 → 1.6.0

package/idlecompact.mjs

@@ -0,0 +1,284 @@
+// Idle-triggered compaction.
+//
+// A conversation that pauses long enough loses the provider's prompt cache. The next request pays
+// full price for a prefix the provider no longer holds, and it pays it again on the turn after
+// that if nothing changes. How long a provider keeps its cache is its own business and differs
+// per provider: Anthropic 5 minutes by default and 1 hour when the request asks for it, OpenAI 30
+// minutes, Gemini and DeepSeek publish no lifetime at all. So the time is a setting, not a
+// constant, and the default is the longest of those that is documented rather than the shortest,
+// because compacting a cache that is still warm throws history away and pays the cache write
+// again for nothing.
+//
+// What this does with the result is the part that matters, and it depends on the client:
+//
+//   - The request that is on its way out is shortened, so this turn costs the tokens of the
+//     summary instead of the tokens of the history. That saving is real whichever client it is.
+//   - For Claude Code the session file is also written, so the next resume starts from the
+//     summary instead of from the history. Claude Code reads that file to build every request, so
+//     the shortening lasts rather than lasting one turn.
+//
+// Codex needs neither half of that from here. Its compaction is a protocol item, not a file: a
+// compaction_trigger in, one compaction output item out, and Codex stores it in its own history.
+// The right place to serve that is the provider gateway, which can see the item, rather than a
+// client-side gateway that would have to rewrite a thread file to reach the same state.
+//
+// Not every turn of a long session is compacted, and that is deliberate. Compacting on every turn
+// would change the prefix every turn, so no turn would ever hit the cache, and the conversation
+// would be summarized over and over. Compacting once, when a long pause says the cache is gone,
+// keeps the summary stable for the turns that follow and spends one extra model call.
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export const IDLE_COMPACT_KEY = 'idleCompact';
+
+// Defaults. The idle time is the one setting worth being wrong about: too short and a warm cache
+// is thrown away, too long and the history is paid for at full price on a turn that had no cache
+// to lose anyway.
+const DEFAULTS = {
+  enabled: false,
+  // Codex is off by default while Claude Code is the default on: a Codex compaction writes into
+  // Codex's own SQLite store, and that is opt-in per install on purpose.
+  codex: false,
+  model: '',
+  idleMinutes: 15,
+  minBytes: 64 * 1024,
+  keepRecent: 6,
+  summaryMaxChars: 24000,
+  sessionLookbackHours: 72,
+};
+
+export function idleCompactPolicy(cfg) {
+  const raw = cfg?.[IDLE_COMPACT_KEY];
+  const p = { ...DEFAULTS, ...(raw && typeof raw === 'object' ? raw : {}) };
+  p.enabled = p.enabled === true;
+  p.codex = p.codex === true;
+  p.model = typeof p.model === 'string' ? p.model.trim() : '';
+  p.idleMinutes = Number.isFinite(+p.idleMinutes) && +p.idleMinutes > 0 ? +p.idleMinutes : DEFAULTS.idleMinutes;
+  p.minBytes = Number.isFinite(+p.minBytes) && +p.minBytes > 0 ? +p.minBytes : DEFAULTS.minBytes;
+  p.keepRecent = Number.isFinite(+p.keepRecent) && +p.keepRecent > 0 ? Math.floor(+p.keepRecent) : DEFAULTS.keepRecent;
+  p.summaryMaxChars = Number.isFinite(+p.summaryMaxChars) && +p.summaryMaxChars > 0
+    ? Math.floor(+p.summaryMaxChars) : DEFAULTS.summaryMaxChars;
+  p.sessionLookbackHours = Number.isFinite(+p.sessionLookbackHours) && +p.sessionLookbackHours > 0
+    ? +p.sessionLookbackHours : DEFAULTS.sessionLookbackHours;
+  p.idleMs = p.idleMinutes * 60000;
+  return p;
+}
+
+// ---- when a conversation was last here ----
+
+// A gateway restart forgets every conversation, which costs one compaction and nothing else: the
+// next request is treated as new, which is the safe direction to be wrong in.
+const seen = new Map();
+
+function prune(now) {
+  const cutoff = now - DEFAULTS.sessionLookbackHours * 3600000;
+  for (const [k, t] of seen) if (t < cutoff) seen.delete(k);
+}
+
+/** Records that this conversation has just been answered. */
+export function noteConversation(key, at = Date.now()) {
+  if (!key) return;
+  if (seen.size > 20000) prune(at);
+  seen.set(key, at);
+}
+
+/** Milliseconds since this conversation last asked for something, or 0 when it is not known. */
+export function idleFor(key, now = Date.now()) {
+  if (!key) return 0;
+  const t = seen.get(key);
+  if (!t) return 0;
+  return now - t;
+}
+
+// ---- which conversation this is ----
+
+// Claude Code names its session in a header and again inside metadata.user_id. Codex names it in
+// prompt_cache_key. A client that names nothing is keyed on the opening request instead, which is
+// the one message a compaction does not remove, so the key survives the compaction itself.
+export function conversationKey(_clientFormat, req, ir) {
+  const header = req?.headers?.['x-claude-code-session-id'];
+  if (header) return `h:${header}`;
+  const pck = ir?.promptCacheKey;
+  if (pck) return `p:${pck}`;
+  const uid = ir?.metadataUserId;
+  if (typeof uid === 'string') {
+    const m = /_session_([0-9a-f-]{8,})/i.exec(uid);
+    if (m) return `u:${m[1]}`;
+    if (/^[0-9a-f-]{36}$/i.test(uid)) return `u:${uid}`;
+  }
+  const first = firstUserText(ir);
+  if (first) return `c:${crypto.createHash('sha256').update(first).digest('hex').slice(0, 16)}`;
+  return '';
+}
+
+// The opening request is read from the IR rather than from the raw body, because by this point the
+// body has been parsed once already and the IR is what the rest of the gateway works with.
+function firstUserText(ir) {
+  for (const m of ir?.messages || []) {
+    if (m.role !== 'user' || m.role === 'tool') continue;
+    const t = textOf(m);
+    if (t) return t.slice(0, 2000);
+  }
+  return '';
+}
+
+function textOf(msg) {
+  if (!msg) return '';
+  const c = msg.content;
+  if (typeof c === 'string') return c;
+  if (!Array.isArray(c)) return '';
+  let out = '';
+  for (const part of c) {
+    if (typeof part === 'string') { out += part; continue; }
+    if (!part || typeof part !== 'object') continue;
+    if (part.type === 'text' || part.type === 'input_text' || part.type === 'output_text') out += part.text || '';
+  }
+  return out;
+}
+
+// ---- the history, shortened ----
+
+// The middle keeps its words and loses its tool calls and their results, because those are most
+// of the weight of a session and none of what a summary is for. The opening request and the last
+// few messages are kept as they are: the opening request is what the session is for, and the last
+// few messages are what the next turn reasons over.
+export function compactIR(ir, policy) {
+  const msgs = ir.messages || [];
+  if (msgs.length < policy.keepRecent + 2) return null;
+
+  const head = msgs.findIndex(m => m.role === 'user' && m.role !== 'tool');
+  if (head < 0) return null;
+  let tail = msgs.length - policy.keepRecent;
+  if (tail <= head + 1) return null;
+  // A tool result whose call was cut is a request the provider refuses, so the tail never starts
+  // on one.
+  while (tail < msgs.length && isToolResult(msgs[tail])) tail++;
+  if (tail <= head + 1) return null;
+
+  const kept = [];
+  kept.push(...msgs.slice(0, head));
+  kept.push(msgs[head]);
+  const middle = [];
+  for (let i = head + 1; i < tail; i++) {
+    const m = msgs[i];
+    if (m.role === 'tool' || m.role === 'assistant' && m.toolCalls) continue;
+    const t = textOf(m).trim();
+    if (!t) continue;
+    middle.push({ role: m.role === 'assistant' ? 'assistant' : 'user', content: trimText(t, policy.userChars ?? 3000) });
+  }
+  kept.push(...middle);
+  kept.push(...msgs.slice(tail));
+  // Where a summary belongs: right after the opening request, before the text that stands in for
+  // the middle. That is where Claude Code puts its own, and a reader meets it as the first thing
+  // after being told what it is.
+  return {
+    messages: kept,
+    insertAt: head + 1,
+    middle: middle.length,
+    dropped: (tail - head - 1) - middle.length,
+  };
+}
+
+function isToolResult(msg) {
+  if (!msg) return false;
+  if (msg.role === 'tool') return true;
+  return Array.isArray(msg.content) && msg.content.some(p => p && (p.type === 'tool_result'));
+}
+
+function trimText(t, max) {
+  if (t.length <= max) return t;
+  const cut = t.slice(0, max);
+  const nl = cut.lastIndexOf('\n');
+  return (nl > max / 2 ? cut.slice(0, nl) : cut) + `\n[... ${t.length - max} more characters cut here ...]`;
+}
+
+// ---- the summary request ----
+
+// The instruction names what a continuation needs, because "summarize this" produces something
+// useless to the agent that has to keep working: the decisions and their reasons, the files that
+// changed, the errors and their fixes, and what is still open.
+export const SUMMARY_INSTRUCTION = 'Summarize this conversation so it can replace the history. ' +
+  'Keep: what was asked, the decisions made and why, the files and commands that changed things, ' +
+  'the errors and how they were resolved, and what is still pending. Drop: full tool output, ' +
+  'intermediate reasoning, and anything already superseded. Write plain prose a continuing agent ' +
+  'can act on without the original transcript.';
+
+// The history handed to the summarizer is text only and already cut down, so the summarizer is not
+// asked to read a megabyte of tool output to produce a paragraph.
+export function summaryMessages(ir, policy) {
+  const compacted = compactIR(ir, policy) || { messages: (ir.messages || []).slice(-policy.keepRecent) };
+  const msgs = [{ role: 'user', content: [{ type: 'text', text: SUMMARY_INSTRUCTION }] }];
+  for (const m of compacted.messages) {
+    const t = textOf(m).trim();
+    if (t) msgs.push({ role: m.role === 'assistant' ? 'assistant' : 'user', content: [{ type: 'text', text: trimText(t, policy.userChars ?? 3000) }] });
+  }
+  return msgs;
+}
+
+/** What a session file records: the words of the summary, cut to the budget. */
+export function clampSummary(text, policy) {
+  const s = String(text || '').trim();
+  if (s.length <= policy.summaryMaxChars) return s;
+  const cut = s.slice(0, policy.summaryMaxChars);
+  const nl = cut.lastIndexOf('\n\n');
+  if (nl > policy.summaryMaxChars / 2) return cut.slice(0, nl);
+  const dot = cut.lastIndexOf('. ');
+  if (dot > policy.summaryMaxChars / 2) return cut.slice(0, dot + 1);
+  return cut;
+}
+// ---- the Responses shape, where the history lives in the request ----
+
+// Codex sends its history as an input array and reaches a Responses provider as the bytes it
+// wrote, so its history is shortened here rather than through a renderer. Same rule as the
+// intermediate form: the opening request and the recent turns stay as they are, the middle keeps
+// its words and loses its calls and their output.
+export function compactResponsesInput(input, policy) {
+  if (!Array.isArray(input) || input.length < policy.keepRecent + 2) return input;
+  const head = input.findIndex(isResponseMessage);
+  if (head < 0) return input;
+  let tail = input.length - policy.keepRecent;
+  if (tail <= head + 1) return input;
+  while (tail < input.length && isResponseResult(input[tail])) tail++;
+  if (tail <= head + 1) return input;
+
+  const kept = [];
+  kept.push(...input.slice(0, head));
+  kept.push(input[head]);
+  for (let i = head + 1; i < tail; i++) {
+    // A call, a result and a reasoning block are the weight of the session and none of the thread.
+    const t = responseText(input[i]);
+    if (!t) continue;
+    kept.push({
+      type: 'message',
+      role: input[i]?.role === 'assistant' ? 'assistant' : 'user',
+      content: [{ type: 'input_text', text: trimText(t, policy.userChars ?? 3000) }],
+    });
+  }
+  kept.push(...input.slice(tail));
+  return kept;
+}
+
+function isResponseMessage(item) {
+  return item && item.type === 'message' && item.role !== 'developer' && item.role !== 'system';
+}
+
+function isResponseResult(item) {
+  return !!item && (item.type === 'function_call_output' || item.type === 'custom_tool_call_output'
+    || item.type === 'local_shell_call_output');
+}
+
+function responseText(item) {
+  if (!isResponseMessage(item)) return '';
+  const c = item.content;
+  if (typeof c === 'string') return c;
+  if (!Array.isArray(c)) return '';
+  let out = '';
+  for (const b of c) {
+    if (b && typeof b === 'object' && typeof b.text === 'string' &&
+      ['input_text', 'output_text', 'summary_text', 'text'].includes(b.type)) out += b.text;
+  }
+  return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-switcher",
-  "version": "1.4.1",
+  "version": "1.6.0",
   "description": "Zero-dependency multi-protocol edge gateway & provider switcher for Claude Code and Codex, with OpenAI-compatible, Anthropic and Vertex upstreams",
   "keywords": [
     "llm",

package/proxy.mjs

@@ -9,7 +9,7 @@ import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { createFrameReader } from './blindfold/wsframe.mjs';
 import {
-  OUT_FORMATS, parseToIR, emitUpstreamBody, createUpstreamNormalizer, createCollector,
+  OUT_FORMATS, parseToIR, emitUpstreamBody, irToAnthropicBody, createUpstreamNormalizer, createCollector,
   createThinkTagSplitter, splitThinkTags, healAnthropicPayload, estimateTokens, THINKING_MODES,
   toGeminiSchema, isAntigravityModel,
   createAnthropicStream, createChatStream, createResponsesStream, createVertexStream,
@@ -32,6 +32,12 @@ import { classifyCodexRole, classifyClaudeTier, syncLocalCatalog, refreshCatalog
 import { checkForUpdate } from './version.mjs';
 import { applyUpdate } from './update.mjs';
 import { createContractLab, createHalfTap, tapClientWrites, capText, capJson, toolVersionFromUA, finishHalf, PROBE_HEADER, TRACE_ID_RE } from './contract.mjs';
+import {
+  idleCompactPolicy, conversationKey, idleFor, noteConversation, compactIR, compactResponsesInput, IDLE_COMPACT_KEY,
+} from './idlecompact.mjs';
+import { askSummary } from './idlecall.mjs';
+import { claudeSessionId, findSessionFile, writeCompaction } from './claudesession.mjs';
+import { writeCodexCompaction } from './codexsession.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const uiHtmlPath = path.join(__dirname, 'ui.html');
@@ -743,6 +749,124 @@ function cleanSchemaDeep(obj) {
 // 1. Strip disallowed keywords ('encrypted', '$schema', 'cache_control')
 // 2. Fix invalid schema values where a property has a string value "object" instead of a valid schema object
 // 3. For ag/* targets (Gemini behind 9Router): rewrite to the strict Schema subset
+// ---- idle compaction ----
+
+// Claude Code only. Codex is left alone on purpose: its compaction is a protocol item, which the
+// provider gateway answers, and the answer is stored by Codex in its own history. Shortening a
+// Codex request here would replace that with a summary no client ever records, which costs the
+// tokens of the summary and saves only one turn. The Antigravity CLI has no session file of its
+// own to write, so there would be nothing to make the shortening last.
+async function maybeCompactIdle(req, clientFormat, payload, ir, profile, profileKey, bodyBuffer) {
+  const policy = idleCompactPolicy(loadConfig());
+  const key = conversationKey(clientFormat, req, ir);
+  if (!key) return null;
+  const wants = clientFormat === 'anthropic'
+    ? policy.enabled
+    : clientFormat === 'responses' && policy.enabled && policy.codex;
+  if (wants && idleFor(key) > policy.idleMs && payloadBytes(payload) >= policy.minBytes) {
+    const r = compactNow({ req, payload, ir, profile, profileKey, policy, key, bodyBuffer, clientFormat });
+    // Recorded on the way through rather than on the way out, so a request the provider then
+    // fails still counts as the conversation having been here. What is being measured is the
+    // client's pause, not the provider's answer.
+    noteConversation(key);
+    return r;
+  }
+  noteConversation(key);
+  return null;
+}
+
+// Measured from the parsed body rather than from Content-Length, which is absent on a chunked
+// request and smaller than the body once it has been decoded.
+function payloadBytes(payload) {
+  try { return JSON.stringify(payload).length; } catch { return 0; }
+}
+
+function compactNow({ req, payload, ir, profile, profileKey, policy, key, bodyBuffer, clientFormat }) {
+  const compacted = compactIR(ir, policy);
+  if (!compacted) return null;
+
+  const before = JSON.stringify(ir.messages || []).length;
+  const mapped = mapModel(ir.model || payload.model || '', profile, 'anthropic');
+  const outFormat = resolveOutFormat(profile, mapped);
+  const build = (prof, model, ir2) => buildUpstreamRequest(prof, outFormat, ir2, model, req);
+
+  // A summary is only made when the reader named a model for it, and never with the conversation's
+  // own: that would spend the expensive model of an official account to save the tokens of the
+  // turn, which is a bad trade and, on a plan with limits, worse. With no model named there is
+  // still a saving, because the request leaves shortened, and without a summary there is nothing to
+  // write to the session file -- so a model call here would cost tokens and buy nothing.
+  const summary = policy.model
+    ? askSummary({ ir, policy, profile, model: policy.model, build })
+    : Promise.resolve('');
+
+  // The request goes out shortened now, before the summary exists. The summary belongs in the
+  // next resume, not in this answer, so this turn carries the text that stands in for the middle
+  // and nothing else; a turn that also carried the summary would pay for it twice.
+  // Written back into the client's own body. Claude Code goes through the renderer this gateway
+  // already uses, because it is translated on the way out. Codex is not: a Responses client
+  // reaches a Responses provider as the bytes it sent, so its history is shortened where it
+  // lives, in the request itself.
+  const field = clientFormat === 'responses' ? 'input' : 'messages';
+  const rendered = clientFormat === 'responses'
+    ? compactResponsesInput(payload.input, policy)
+    : irToAnthropicBody({ ...ir, messages: compacted.messages }, ir.model || payload.model).messages;
+  const next = { ...payload, [field]: rendered };
+  const nextBuf = Buffer.from(JSON.stringify(next), 'utf8');
+
+  console.log(
+    `[llm-switcher] idle compact ${key.slice(0, 12)} [${profileKey}]: ${before} -> ${JSON.stringify(rendered).length} bytes, ` +
+    `${compacted.middle} messages kept as text, ${compacted.dropped} dropped; summary call in flight`);
+
+  // The summary is not waited for. It serves the next resume, not this answer, and holding the
+  // client's turn open for a call nobody reads would make the saving feel like a cost. The file is
+  // written when it lands, which is also later than the response and therefore never races the
+  // entries Claude Code is appending right now.
+  Promise.resolve(summary).then(async (s) => {
+    if (!s) {
+      console.log(`[llm-switcher] idle compact ${key.slice(0, 12)}: the summary call produced nothing; the request went out shortened anyway`);
+      return;
+    }
+    // Found by session id rather than by working directory: nothing in the request says what the
+    // client's directory is, and a compaction written to the wrong project is one nothing reads.
+    // Codex and Claude Code keep their history in different places, so each is written its own
+    // way: Codex in its rollout file and its store, Claude Code in its session file.
+    let written;
+    if (clientFormat === 'responses') {
+      written = await writeCodexCompaction({ summary: s });
+    } else {
+      const sessionId = claudeSessionId(req, payload);
+      const file = sessionId ? findSessionFile(sessionId) : '';
+      written = file
+        ? writeCompaction({
+          file, summary: s, sessionId,
+          preTokens: Math.round(before / 4), postTokens: Math.round(JSON.stringify(rendered).length / 4),
+        })
+        : null;
+    }
+    console.log(`[llm-switcher] idle compact ${key.slice(0, 12)}: summary ${written ? 'stored' : 'made, not stored'}`);
+  }).catch(() => {});
+
+  return { payload: next, bodyBuffer: nextBuf };
+}
+
+// The summary goes in as a user message right after the opening request, which is where Claude
+// Code puts its own. A conversation handed a hole in it reads the hole as something it forgot
+// unless something says otherwise.
+function withSummary(msgs, insertAt, summary) {
+  const at = Math.min(Math.max(1, insertAt), msgs.length);
+  return [
+    ...msgs.slice(0, at),
+    { role: 'user', content: [{ type: 'text', text: summaryNotice(summary) }] },
+    ...msgs.slice(at),
+  ];
+}
+
+function summaryNotice(summary) {
+  return 'Earlier in this conversation the history was shortened because it had been idle long ' +
+    'enough that the provider no longer held its prompt cache. What follows is a summary of the ' +
+    'part that was replaced, then the more recent messages unchanged.\n\nSummary:\n' + summary;
+}
+
 function buildUpstreamRequest(profile, outFormat, ir, mappedModel, req) {
   const upBody = emitUpstreamBody(outFormat, ir, mappedModel, { thinkingMode: profile.thinkingMode });
   if (upBody?.tools && Array.isArray(upBody.tools)) {
@@ -839,6 +963,23 @@ async function handleConvert(clientFormat, req, res, bodyBuffer, opts = {}) {
   // Code Assist names streaming in the path (:streamGenerateContent), not in the body.
   if (clientFormat === 'codeassist') ir.stream = Boolean(opts.codeAssistStream);
 
+  // Compaction rewrites the request itself, not just the intermediate form: when the client and
+  // the provider speak the same shape this gateway forwards the client's own bytes, so a change
+  // made only to the parsed form would shorten nothing that leaves the building.
+  const shrunk = await maybeCompactIdle(req, clientFormat, payload, ir, profile, profileKey, bodyBuffer);
+  if (shrunk) {
+    payload = shrunk.payload;
+    bodyBuffer = shrunk.bodyBuffer;
+    try {
+      ir = parseToIR(clientFormat, payload);
+    } catch {
+      // The compacted body was built from this one, so it parses. If it ever did not, the
+      // original is still what the caller meant to send.
+      payload = JSON.parse(bodyBuffer.toString('utf8'));
+      return sendClientError(res, clientFormat, 400, 'Cannot reparse the compacted request');
+    }
+  }
+
   const reqStartTime = Date.now();
   const requestPreview = previewOf(ir);
   const requestedModel = ir.model || payload.model || '';
@@ -1575,6 +1716,42 @@ async function routeApi(req, res, method, pathname) {
     return sendJson(res, 200, syncLocalCatalog(STATE_DIR));
   }
 
+  // Idle compaction. The settings live under one key so the dashboard and `switch compact`
+  // write the same place, and the same defaults, instead of two views that can disagree.
+  if (method === 'GET' && pathname === '/api/idle-compact') {
+    return sendJson(res, 200, { idleCompact: idleCompactPolicy(loadConfig()) });
+  }
+  if (method === 'POST' && pathname === '/api/idle-compact') {
+    let patch;
+    try {
+      patch = JSON.parse((await readBody(req, 64 * 1024)).toString('utf8'));
+    } catch (err) {
+      return sendJson(res, err.status || 400, { error: err.message });
+    }
+    if (!patch || typeof patch !== 'object' || Array.isArray(patch)) {
+      return sendJson(res, 400, { error: 'body must be an object' });
+    }
+    // Per key, not per type-group. A loose check lets "yes" through for a boolean, and the
+    // policy then reads it as false: a typo would switch the feature off without saying so.
+    const kinds = { enabled: 'boolean', model: 'string', idleMinutes: 'number', minBytes: 'number', keepRecent: 'number' };
+    for (const [k, want] of Object.entries(kinds)) {
+      if (!(k in patch)) continue;
+      const v = patch[k];
+      const ok = want === 'number'
+        ? (typeof v === 'number' && Number.isFinite(v))
+        : typeof v === want;
+      if (!ok) return sendJson(res, 400, { error: `${k} must be ${want === 'number' ? 'a number' : `a ${want}`}` });
+    }
+    const cfg = loadConfig() || {};
+    cfg[IDLE_COMPACT_KEY] = { ...(cfg[IDLE_COMPACT_KEY] || {}), ...patch };
+    try {
+      saveConfig(cfg);
+    } catch (err) {
+      return sendJson(res, 500, { error: err.message });
+    }
+    return sendJson(res, 200, { idleCompact: idleCompactPolicy(loadConfig()) });
+  }
+
   if (method !== 'POST') {
     req.resume();
     return sendJson(res, 404, { error: `Not found: ${method} ${pathname}` });

package/switch.mjs

@@ -13,6 +13,7 @@ import {
   getMigrationError, getMigrationCollision, getLastLoadError,
   casClearToolPointers, emptyToolEnvFiles, syncInterceptorTools
 } from './state.mjs';
+import { idleCompactPolicy } from './idlecompact.mjs';
 import { runProbe, runCheck } from './contract.mjs';
 import { installPlugin, uninstallPlugin, pluginStatus, PLUGIN_NAME } from './plugin.mjs';
 import {
@@ -845,6 +846,57 @@ async function managePlugin(action = 'status') {
   }
 }
 
+// Idle compaction: a conversation that comes back after a pause has lost the provider's prompt
+// cache, so its history is paid for at full price. This turns that on and says what it will do.
+async function manageCompact(action = 'status', arg = '') {
+  const cfg = loadConfig() || {};
+  const policy = idleCompactPolicy(cfg);
+  const key = 'idleCompact';
+  const set = (patch) => {
+    cfg[key] = { ...(cfg[key] || {}), ...patch };
+    saveConfig(cfg);
+  };
+  const act = (action || 'status').toLowerCase();
+  const show = () => {
+    const p = idleCompactPolicy(loadConfig() || {});
+    console.log('Idle compaction (Claude Code)');
+    console.log(`  Enabled:        ${p.enabled ? 'yes' : 'no'}`);
+    console.log(`  Idle over:      ${p.idleMinutes} minutes`);
+    console.log(`  Context over:   ${Math.round(p.minBytes / 1024)} KB`);
+    console.log(`  Keep recent:    ${p.keepRecent} messages`);
+    console.log(`  Summary model:  ${p.model || '(none set)'}`);
+    if (!p.enabled) console.log('\n  Turn it on with: switch compact on');
+    else if (!p.model) console.log('\n  No summary model: requests still go out shortened, and no model is called at all.');
+  };
+
+  if (act === 'on' || act === 'enable') {
+    set({ enabled: true });
+    console.log('[OK] Idle compaction is on.');
+    show();
+  } else if (act === 'off' || act === 'disable') {
+    set({ enabled: false });
+    console.log('[OK] Idle compaction is off.');
+  } else if (act === 'model') {
+    const m = String(arg || '').trim();
+    if (!m) { console.log(`Summary model is currently: ${policy.model || '(none set)'}`); return; }
+    if (m === 'none' || m === 'default') { set({ model: '' }); console.log('[OK] The conversation\'s own model will write the summary.'); return; }
+    set({ model: m });
+    console.log(`[OK] Summaries will be written by: ${m}`);
+  } else if (act === 'idle') {
+    const n = Number(arg);
+    if (!Number.isFinite(n) || n <= 0) { console.error('Usage: switch compact idle <minutes>'); process.exit(1); }
+    set({ idleMinutes: Math.floor(n) });
+    console.log(`[OK] Compact a conversation idle over ${Math.floor(n)} minutes.`);
+  } else if (act === 'min') {
+    const n = Number(arg);
+    if (!Number.isFinite(n) || n <= 0) { console.error('Usage: switch compact min <KB>'); process.exit(1); }
+    set({ minBytes: Math.floor(n) * 1024 });
+    console.log(`[OK] Compact a conversation over ${Math.floor(n)} KB.`);
+  } else {
+    show();
+  }
+}
+
 async function manageShim(action = 'status') {
   const act = (action || 'status').toLowerCase();
 
@@ -1247,6 +1299,8 @@ if (cmd === 'off' || cmd === 'stop') {
   await runDoctor();
 } else if (cmd === 'service' || cmd === 'daemon') {
   await manageService(subArg.toLowerCase() || 'status');
+} else if (cmd === 'compact') {
+  await manageCompact(subArg.toLowerCase() || 'status', positionalArgs()[2] || '');
 } else if (cmd === 'shim' || cmd === 'shims') {
   await manageShim(subArg.toLowerCase() || 'status');
 } else if (cmd === 'plugin' || cmd === 'plugins') {