llm-switcher 1.4.0 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,84 @@
 # Changelog — LLM Switcher
 
+## Release 1.6.0 — 2026-10-07
+
+- **A Codex thread now keeps the shortening, behind the same opt-in switch.** A Codex compaction is
+  three writes that have to agree, all read off a thread that had compacted seven times:
+
+  1. a `compacted` entry in the rollout file, carrying the summary and the history that replaces
+     the old one;
+  2. a row of type `contextCompaction` in `thread_items`, whose `item_json` is nothing but a type
+     and an id -- a marker, not a summary;
+  3. `thread_history_projection_state` moved forward to the byte offset and ordinal of that entry.
+
+  The third is the one that is easy to leave out, and leaving it out looks exactly like success.
+  That table records how far the store has consumed the rollout file: `next_rollout_byte_offset` is
+  the size of the file, exactly, and `next_rollout_ordinal` is the ordinal after the last entry
+  read. The rollout file is the record and the store is a projection of it, so an entry appended to
+  the file without moving the projection is simply never read. With all three written, Codex
+  resumes and answers from the summary; with the first two alone it resumes and says it has none.
+
+  `idleCompact.codex` remains off by default, because this opens Codex's database. With no summary
+  model named, no model is called: the request still goes out shortened, which is the whole of the
+  saving, and nothing is spent to earn it.
+
+## Release 1.5.3 — 2026-10-07
+
+- **Idle compaction no longer calls a model unless one was named for it.** With no summary model set,
+  a summary was written with the conversation's own model — the expensive one, on an official
+  account, and the one with limits. That spends the costly model to save the tokens of a single
+  turn, and on a plan with limits it is worse than doing nothing.
+
+  There was no point paying for it either: the summary is used only to write the session file, so
+  with no model named there was nothing to store and the call bought nothing. Now no model is called
+  at all. The saving is unchanged — the request still leaves shortened, which is the whole of what
+  this feature costs and all of what it saves without a model. Set one with
+  `switch compact model <id>` to also make the shortening last.
+
+## Release 1.5.2 — 2026-10-07
+
+- **Codex conversations can be shortened on an idle return too, behind its own switch.**
+  `idleCompact.codex`, off by default. The history is shortened in the request, which is
+  where a Responses client keeps it: a Responses client reaches a Responses provider as the
+  bytes it sent, so there is nothing to render through. Measured on a 25 KB conversation,
+  6 KB goes out.
+
+  The thread itself is left to Codex. Its history is a SQLite store of its own, and a
+  compaction there needs two halves: a `contextCompaction` row in `thread_items`, whose
+  `item_json` is nothing but a type and an id, and a `compacted` entry in the rollout file
+  carrying the summary. Both were written, in the shape a real compaction takes, and Codex
+  resumed as if neither existed. Something else in that store says where the summary begins;
+  it was not found. So the summary is produced and the request goes out short, which saves
+  the tokens of this turn, and no claim is made that the thread stays short.
+
+## Release 1.5.1 — 2026-10-07
+
+- **Idle compaction is now in the dashboard.** A card on the Routes page carries the switch, the pause that counts as losing the cache, the size it must exceed, and the model that writes the summary. It reads and writes `/api/idle-compact`, the same endpoint and the same key `switch compact` uses, so the page and the terminal cannot show two different settings.
+
+  One bug came out of writing the endpoint: the field types were checked as groups, so `{"enabled":"yes"}` was accepted and then read as `false` — a typo switched the feature off without a word. Each field is now checked as the type it actually is, and a wrong type is refused rather than quietly turned into the default.
+
+## Release 1.5.0 — 2026-10-07
+
+- **A conversation that comes back after a pause no longer pays full price for a cache nobody holds.** When a Claude Code session resumes after being idle long enough, and the context is large enough to be worth it, the gateway shortens the history and writes the compaction into the session file. Off by default. `switch compact on`, and `switch compact model <id>` for the model that writes the summary (empty means the conversation's own model).
+
+Two decisions worth naming, because the obvious alternatives are worse.
+
+Compacting once, not every turn. Changing the prefix on every turn means no turn ever hits the cache and the conversation is summarized over and over. Compacting when a pause says the cache is gone keeps the summary stable for the turns that follow.
+
+The session file, not the API. Claude Code builds every request from the entry chain in `~/.claude/projects/<project>/<session>.jsonl`, so a compaction written there shortens every request after it rather than only the turn that triggered it. The two entries are the ones Claude Code writes itself, read off a real session: a `compact_boundary` and a `user` entry marked `isCompactSummary`. Old entries stay in the file, as they do after Claude Code's own compaction, because a transcript a person can still read is worth more than a small file.
+
+Codex and the Antigravity CLI are deliberately untouched. Codex compaction is a protocol item the provider gateway answers and Codex stores in its own history, so shortening a Codex request here would replace that with a summary no client records. The CLI has no session file to write.
+
+Tests: 14, including one that runs the real Claude Code binary against a local server and reads the request it sends. With twelve synthetic turns behind a boundary, that request carries the summary and none of the twelve.
+
+## Release 1.4.1 — 2026-10-07
+
+- **The update comes from npm, because that is where a release is published.** The gateway asked npm what the newest version is and ran `npm install -g llm-switcher@<version>` for exactly that version. Before, the install decided: a directory with a `.git` pulled and never asked npm, and the dashboard's Update now button read as a git operation on a project that ships to npm.
+- **A git checkout is the one install npm cannot serve, and it says so.** npm writes into the global prefix while the running code is the checkout itself, so the install lands somewhere nothing runs. The checkout is then asked, and it pulls fast-forward only. When npm held a release the checkout could not take, the notice names that version and what the checkout has, because "already the latest version" on its own would hide the one version the reader does not have.
+- **A failed npm install no longer fails the update of a checkout.** A checkout used to update without npm in the way. Asking npm first put an install between the reader and a pull, and any failure of that install -- a version the registry does not serve, a network, a read-only prefix -- ended the update even though the checkout could still have moved. Now a checkout reports what npm did and goes on to pull; an npm install with no checkout still fails loudly, because there is nothing else to try.
+
+Tests: 17 in `tests/update.test.mjs`, plus the rest of the suite.
+
 ## Release 1.4.0 — 2026-10-07
 
 - **A model answers with the tool names it was trained on, and the caller only runs its own.** A Codex model says `shell` where Claude Code declared `Bash`, and the turn ends with `Error: No such tool available: shell`. The gateway now writes the call back in the vocabulary the caller declared, and says the names in the prompt so most calls never need rewriting.

package/README.md

@@ -550,14 +550,53 @@ The service runs without your shell. `switch service install` therefore copies `
 
 On Linux the unit is a systemd *user* service: it starts when you log in. To start it at boot without a login (a server reached over SSH), run `loginctl enable-linger $USER` once. The unit records the absolute path of the current `node`; if you manage Node with nvm and remove that version, run `switch service install` again.
 
+### Idle 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 pays it again on the turn after that. How long
+a provider keeps its cache is its own business: 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.
+
+When a Claude Code conversation comes back after a pause and is large enough to be worth it, the
+gateway shortens the history and writes the compaction into the session file. The turn that would
+have cost the whole history costs the summary instead.
+
+| | |
+| --- | --- |
+| `switch compact status` | Show the settings |
+| `switch compact on` / `off` | Turn it on or off (off by default) |
+| `switch compact model <id>` | Which model writes the summary. Empty or `default`: the model of the conversation itself |
+| `switch compact idle <minutes>` | How long a pause counts as losing the cache (15) |
+| `switch compact min <KB>` | How large a conversation must be to be worth it (64) |
+
+Two things are deliberate.
+
+**Only once, not on every turn.** Compacting 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
+when a pause says the cache is gone keeps the summary stable for the turns that follow.
+
+**The session file, not the API.** Claude Code builds every request from a chain of entries in
+`~/.claude/projects/<project>/<session>.jsonl`, so a compaction written there shortens every
+request after it, not just the turn that triggered it. The two entries are the ones Claude Code
+writes itself: a `compact_boundary` and a `user` entry marked `isCompactSummary`. The old entries
+stay in the file, which is what Claude Code does too, so a transcript a person can still read is
+worth more than a small file. The shortening takes effect the next time the session is resumed.
+
+A free model writes a free summary and a worse one: the summary replaces the history, so what it
+leaves out is gone. That is the reader's call, which is why the model is a setting.
+
+Codex is not handled here. Its compaction is a protocol item rather than a file, which the provider
+gateway answers, and the answer is stored by Codex in its own history. Shortening a Codex request at
+the client would replace that with a summary no client records. The Antigravity CLI has no session
+file of its own, so there would be nothing to make the shortening last.
+
 ### Updates
 
 When npm has a newer release, the dashboard shows a notice. Click **Update now** in this notice. The gateway installs the release and starts the new code. Then the dashboard reloads. `switch update` does the same from a terminal.
 
-The gateway installs a release in one of two ways:
+The gateway installs a release from npm, because that is where a release is published. It asks the registry for the newest version and runs `npm install -g llm-switcher@<version>`, then restarts into it.
 
-- A git checkout runs `git pull --ff-only`. If the checkout has local changes, or commits that are not on the upstream branch, the update stops and changes nothing.
-- An npm install runs `npm install -g llm-switcher@<latest>`.
+A git checkout is the one install npm cannot serve: npm writes into the global prefix while the running code is the checkout itself. So when npm did not move the directory the gateway runs from, and that directory is a checkout, the checkout is asked next, and it runs `git pull --ff-only`. If the checkout has local changes, or commits that are not on the upstream branch, the update stops and changes nothing. When npm held a release the checkout could not take, the notice says both: which version npm has, and that the checkout has nothing.
 
 Requests that are open on the gateway when the update starts finish on the old code. New requests go to the new code. The Codex interceptor stops, and the new gateway starts it again. Thus a Codex request that is open at that moment fails one time. The old process stays as the parent of the new process until the gateway stops. Thus a service manager keeps the process that it started.
 

package/README.vi.md

@@ -548,14 +548,53 @@ Service không chạy trong shell của bạn. Vì vậy `switch service install
 
 Trên Linux, unit là service systemd *của user*: nó khởi động khi bạn đăng nhập. Muốn nó chạy ngay khi máy boot mà không cần đăng nhập (ví dụ server truy cập qua SSH), chạy một lần `loginctl enable-linger $USER`. Unit ghi đường dẫn tuyệt đối của `node` hiện tại; nếu bạn quản lý Node bằng nvm và gỡ phiên bản đó, hãy chạy lại `switch service install`.
 
+### Nén hội thoại khi để lâu
+
+Một hội thoại để lâu đủ thì sẽ mất cache của provider. Request kế tiếp phải trả full price cho một
+prefix mà provider không còn giữ, và lượt sau đó lại trả tiếp. Mỗi provider giữ cache bao lâu là
+việc của riêng họ: Anthropic 5 phút mặc định, 1 giờ nếu request yêu cầu; OpenAI 30 phút; Gemini và
+DeepSeek không công bố thời hạn nào.
+
+Khi một hội thoại Claude Code quay lại sau một khoảng nghỉ, và đủ lớn để đáng xử lý, gateway rút gọn
+lịch sử và ghi kết quả nén vào session file. Lượt lẽ ra phải tốn cả lịch sử giờ chỉ tốn phần tóm
+tắt.
+
+| | |
+| --- | --- |
+| `switch compact status` | Xem cấu hình |
+| `switch compact on` / `off` | Bật hoặc tắt (mặc định tắt) |
+| `switch compact model <id>` | Model nào viết phần tóm tắt. Rỗng hoặc `default`: dùng model của chính hội thoại đó |
+| `switch compact idle <phút>` | Nghỉ bao lâu thì coi là mất cache (15) |
+| `switch compact min <KB>` | Hội thoại phải lớn bao nhiêu mới đáng nén (64) |
+
+Hai điều là cố ý.
+
+**Chỉ một lần, không nén mọi lượt.** Nén mỗi lượt sẽ làm prefix đổi mỗi lượt, nên không lượt nào
+trúng cache, và hội thoại bị tóm tắt đi đi lại. Nén đúng lúc một khoảng nghỉ báo đã mất cache thì
+phần tóm tắt giữ nguyên cho các lượt sau.
+
+**Ghi vào session file, không qua API.** Claude Code dựng mọi request từ chuỗi entry trong
+`~/.claude/projects/<project>/<session>.jsonl`, nên một lần nén ghi vào đó rút gọn **mọi** request sau
+đó, chứ không chỉ lượt đã kích hoạt. Hai entry đúng bằng hai entry Claude Code tự ghi: một
+`compact_boundary` và một entry `user` mang cờ `isCompactSummary`. Các entry cũ vẫn nằm trong file —
+Claude Code cũng vậy — nên một bản transcript người ta vẫn đọc được đáng giá hơn một file nhỏ. Việc
+rút gọn có hiệu lực từ lần resume kế tiếp của phiên đó.
+
+Model rẻ viết phần tóm tắt rẻ và tệ hơn: tóm tắt thay cả lịch sử, nên thứ nó bỏ sót là mất hẳn.
+Đó là quyết định của người đọc, nên nó là một setting.
+
+Codex không xử lý ở đây. Nén của Codex là một item protocol chứ không phải file, provider gateway trả
+lời, và Codex tự lưu vào history của nó. Rút gọn request Codex ở phía client sẽ thay bằng một phần
+tóm tắt mà không client nào ghi lại. Antigravity CLI không có session file riêng, nên không có gì để
+làm cho việc rút gọn kéo dài.
+
 ### Cập nhật
 
 Khi npm có bản mới, dashboard hiện một thông báo. Bấm **Update now** trong thông báo này. Gateway cài bản mới và chạy code mới. Sau đó dashboard tự tải lại. `switch update` làm việc tương tự từ terminal.
 
-Gateway cài bản mới theo một trong hai cách:
+Gateway cài bản mới từ npm, vì đó là nơi bản phát hành được đăng. Nó hỏi registry lấy số phiên bản mới nhất rồi chạy `npm install -g llm-switcher@<phiên bản>`, sau đó khởi động lại vào bản đó.
 
-- Bản git checkout chạy `git pull --ff-only`. Nếu checkout có thay đổi cục bộ, hoặc có commit không nằm trên nhánh upstream, việc cập nhật dừng lại và không đổi gì.
-- Bản cài bằng npm chạy `npm install -g llm-switcher@<latest>`.
+Bản git checkout là thứ duy nhất npm không phục vụ được: npm ghi vào global prefix, trong khi code đang chạy chính là thư mục checkout. Nên khi npm không dịch chuyển được thư mục mà gateway đang chạy, và thư mục đó là một checkout, gateway hỏi tiếp checkout, và checkout chạy `git pull --ff-only`. Nếu checkout có thay đổi cục bộ, hoặc có commit không nằm trên nhánh upstream, việc cập nhật dừng lại và không đổi gì. Khi npm có bản mới mà checkout không lấy được, thông báo nói cả hai: npm đang có số phiên bản nào, và checkout không có gì để cập nhật.
 
 Các request đang chạy trên gateway lúc cập nhật sẽ chạy xong trên code cũ. Request mới đi vào code mới. Interceptor của Codex dừng lại, và gateway mới khởi động nó lại. Vì vậy một request Codex đang chạy đúng lúc đó sẽ lỗi một lần. Tiến trình cũ ở lại làm tiến trình cha của tiến trình mới cho tới khi gateway dừng. Nhờ vậy service manager vẫn giữ đúng tiến trình mà nó đã khởi động.
 

package/claudesession.mjs

@@ -0,0 +1,196 @@
+// Claude Code's session file.
+//
+// Claude Code keeps a conversation as a JSONL file, one entry per line, and builds every request
+// it sends from the chain of entries linked by parentUuid. That is a fact about the file, not about
+// any API, and it is the reason a compaction written here lasts: the next request is built from
+// whatever the chain says, so an entry that starts a new chain shortens every request after it.
+//
+// A compaction is two entries, and this is the shape Claude Code itself writes. It was read off a
+// real session on this machine, from Claude Code's own automatic compaction:
+//
+//   {"type":"system","subtype":"compact_boundary","content":"Conversation compacted",
+//    "parentUuid":null,"logicalParentUuid":"<the last entry before>",
+//    "compactMetadata":{"trigger":"auto","preTokens":968627,"postTokens":19320, ...}}
+//
+//   {"type":"user","isCompactSummary":true,
+//    "message":{"role":"user","content":"This session is being continued from a previous
+//     conversation that ran out of context. The summary below covers the earlier portion..."}}
+//
+// The boundary is what makes the old entries unreachable rather than deleted. That is Claude Code's
+// own behaviour: its automatic compaction drops ~949k tokens of history and leaves the entries in
+// the file, because a transcript the person can still read is worth more than a small file. This
+// writes the same thing for the same reason, so nothing here destroys anything a resume would
+// otherwise show.
+//
+// Verified against Claude Code 2.1.292 on this machine: with twelve synthetic turns and a boundary
+// before them, the next resume sent four messages instead of the thirteen, and none of the twelve.
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const UUID = () => crypto.randomUUID();
+
+// The line Claude Code writes, kept verbatim so a summary written here is read exactly like one
+// Claude Code wrote itself.
+const SUMMARY_PREFIX =
+  'This session is being continued from a previous conversation. The summary below covers the ' +
+  'earlier portion of the conversation.\n\nSummary:\n';
+
+export function claudeConfigDir(env = process.env) {
+  return env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
+}
+
+/**
+ * The file a session lives in. Claude Code names the directory after the working directory, with
+ * the separators folded into dashes, and the file after the session id.
+ */
+export function sessionFileFor(sessionId, cwd, env = process.env) {
+  const dir = path.join(claudeConfigDir(env), 'projects', encodeCwd(cwd));
+  return { dir, file: path.join(dir, `${sessionId}.jsonl`) };
+}
+
+// A gateway does not know the client's working directory: nothing in the request says so, and
+// guessing it would write the compaction somewhere nothing reads it. The session id is enough,
+// though, because Claude Code names the file after it and never reuses one. So the file is found
+// by looking for it, which also means a session started somewhere else is found too.
+export function findSessionFile(sessionId, env = process.env) {
+  if (!sessionId || !/^[A-Za-z0-9._-]{1,128}$/.test(sessionId)) return '';
+  const projects = path.join(claudeConfigDir(env), 'projects');
+  let dirs;
+  try {
+    dirs = fs.readdirSync(projects, { withFileTypes: true });
+  } catch {
+    return '';
+  }
+  for (const d of dirs) {
+    if (!d.isDirectory()) continue;
+    const f = path.join(projects, d.name, `${sessionId}.jsonl`);
+    try {
+      fs.accessSync(f, fs.constants.R_OK);
+      return f;
+    } catch { /* another project directory, keep looking */ }
+  }
+  return '';
+}
+
+function encodeCwd(cwd) {
+  return String(cwd || '').replace(/[\\/:]/g, '-');
+}
+
+/** Reads the session id out of the headers or body Claude Code sends. */
+export function claudeSessionId(req, payload) {
+  const h = req?.headers?.['x-claude-code-session-id'];
+  if (h && typeof h === 'string' && h.trim()) return h.trim();
+  const uid = payload?.metadata?.user_id;
+  if (typeof uid === 'string') {
+    const m = /_session_([0-9a-f-]{8,})/i.exec(uid);
+    if (m) return m[1];
+    if (/^[0-9a-f-]{36}$/i.test(uid.trim())) return uid.trim();
+  }
+  return '';
+}
+
+/** The last entry in the chain, which is where a compaction cuts. */
+export function readLeaf(file) {
+  let last = null;
+  let text;
+  try {
+    text = fs.readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue;
+    let e;
+    try { e = JSON.parse(line); } catch { continue; }
+    if (e && typeof e.uuid === 'string') last = e;
+  }
+  return last;
+}
+
+/**
+ * Writes the two entries. Appends, because the chain is append-only and the old entries stay: the
+ * boundary makes them unreachable, and a person who resumes an old session id by hand still finds
+ * the transcript.
+ *
+ * Returns what it wrote, or null when it could not: a session file this cannot write is not a
+ * reason to fail the request. The turn is still shortened on the wire either way.
+ */
+export function writeCompaction({ file, summary, sessionId, cwd, preTokens, postTokens, version }) {
+  if (!file || !summary) return null;
+  const leaf = readLeaf(file);
+  if (!leaf) return null;
+  // A file that already ends in a boundary has nothing to cut again, and writing a second one
+  // would drop the summary that is already in place.
+  if (isBoundaryTail(file)) return null;
+
+  const sid = sessionId || leaf.sessionId || 'unknown';
+  const at = new Date().toISOString();
+  const base = {
+    isSidechain: false,
+    cwd: cwd || '',
+    version: version || '',
+    sessionId: sid,
+    timestamp: at,
+  };
+  const boundaryUuid = UUID();
+  const boundary = {
+    ...base,
+    parentUuid: null,
+    logicalParentUuid: leaf.uuid,
+    type: 'system',
+    subtype: 'compact_boundary',
+    content: 'Conversation compacted',
+    level: 'info',
+    uuid: boundaryUuid,
+    compactMetadata: {
+      trigger: 'auto',
+      preTokens: preTokens || 0,
+      postTokens: postTokens || 0,
+      cumulativeDroppedTokens: Math.max(0, (preTokens || 0) - (postTokens || 0)),
+      durationMs: 0,
+    },
+  };
+  const summaryEntry = {
+    ...base,
+    parentUuid: boundaryUuid,
+    uuid: UUID(),
+    promptId: UUID(),
+    type: 'user',
+    isCompactSummary: true,
+    message: { role: 'user', content: SUMMARY_PREFIX + summary },
+  };
+
+  const lines = [JSON.stringify(boundary), JSON.stringify(summaryEntry)].join('\n') + '\n';
+  try {
+    // Appended in place, never rewritten through a rename. Claude Code holds this file open while
+    // a session runs, so a rename would replace the file it is writing to: its next append would
+    // land on the old inode and every entry written in between would be lost. One O_APPEND write
+    // puts both entries at the end together.
+    fs.appendFileSync(file, lines, { mode: 0o600 });
+  } catch {
+    return null;
+  }
+  return { boundaryUuid, summaryUuid: summaryEntry.uuid };
+}
+
+function isBoundaryTail(file) {
+  let text;
+  try {
+    text = fs.readFileSync(file, 'utf8');
+  } catch {
+    return false;
+  }
+  const lines = text.split('\n').filter(l => l.trim());
+  for (let i = lines.length - 1; i >= 0 && i >= lines.length - 40; i--) {
+    let e;
+    try { e = JSON.parse(lines[i]); } catch { continue; }
+    if (e?.type === 'system' && e?.subtype === 'compact_boundary') return true;
+    if (e?.type === 'user' && e?.isCompactSummary === true) return true;
+  }
+  return false;
+}
+
+export { SUMMARY_PREFIX };

package/codexsession.mjs

@@ -0,0 +1,141 @@
+// Codex's thread store.
+//
+// Codex compacts by writing three things that have to agree, and all three were read off a real
+// thread that had compacted seven times:
+//
+//   1. a `compacted` entry in the rollout file, carrying the summary and the history that replaces
+//      the old one;
+//   2. a row of type contextCompaction in thread_items, whose item_json is nothing but a type and
+//      an id -- a marker, not a summary;
+//   3. thread_history_projection_state moved forward to the byte offset and ordinal of the entry
+//      just written.
+//
+// The third is the one that is easy to miss, and it is why writing the first two looks like it
+// worked and then changes nothing. thread_history_projection_state tracks how far the store has
+// consumed the rollout file: next_rollout_byte_offset is the size of the file, exactly, and
+// next_rollout_ordinal is the ordinal after the last entry read. The rollout file is the record;
+// the store is a projection of it. Append to the file without moving the projection and the entry
+// is simply unread.
+//
+// This writes all three, and it is opt-in, and it is opt-in because it opens Codex's database. It
+// never deletes: earlier items stay, as they stay after Codex's own compaction, and the marker is
+// what makes them unreachable.
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const uuid = () => crypto.randomUUID();
+
+function codexHome(env = process.env) {
+  return env.CODEX_HOME || path.join(env.HOME || '', '.codex');
+}
+
+/** The rollout file of the most recent thread: sessions/YYYY/MM/DD/rollout-<stamp>-<id>.jsonl */
+export function latestRollout(env = process.env, now = new Date()) {
+  const root = codexHome(env);
+  let newest = { file: '', mtime: 0 };
+  const walk = (dir, depth) => {
+    if (depth > 4) return;
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      const p = path.join(dir, e.name);
+      if (e.isDirectory()) walk(p, depth + 1);
+      else if (e.name.endsWith('.jsonl')) {
+        try {
+          const m = fs.statSync(p).mtimeMs;
+          if (m > newest.mtime) newest = { file: p, mtime: m };
+        } catch { /* vanished under us, keep looking */ }
+      }
+    }
+  };
+  walk(path.join(root, 'sessions'), 0);
+  return newest.file;
+}
+
+/**
+ * Writes a compaction into the thread Codex is working on. Returns what it wrote, or null when it
+ * wrote nothing -- which is never an error: the turn is still shortened on the wire either way.
+ */
+export async function writeCodexCompaction({ summary, env = process.env, now = Date.now() }) {
+  const text = String(summary || '').trim();
+  if (!text) return null;
+
+  let db;
+  try {
+    const { DatabaseSync } = await import('node:sqlite');
+    db = new DatabaseSync(path.join(codexHome(env), 'thread_history_1.sqlite'));
+  } catch {
+    return null;
+  }
+
+  try {
+    const thread = db.prepare(
+      'SELECT thread_id FROM thread_items GROUP BY thread_id ORDER BY MAX(rollout_ordinal) DESC LIMIT 1'
+    ).get();
+    if (!thread) return null;
+    const tid = thread.thread_id;
+
+    const turn = db.prepare(
+      'SELECT turn_id FROM thread_items WHERE thread_id = ? ORDER BY rollout_ordinal DESC LIMIT 1'
+    ).get(tid);
+    const turnId = turn?.turn_id || uuid();
+
+    // The ordinal follows the projection, not MAX(rollout_ordinal): an entry appended to the file
+    // moves the projection's ordinal on, and the two are not the same number.
+    const proj = db.prepare(
+      'SELECT next_rollout_byte_offset AS off, next_rollout_ordinal AS ord FROM thread_history_projection_state WHERE thread_id = ?'
+    ).get(tid);
+    const ordinal = proj?.ord ?? (db.prepare('SELECT MAX(rollout_ordinal) AS m FROM thread_items WHERE thread_id = ?').get(tid)?.m ?? 0) + 1;
+
+    const file = latestRollout(env);
+    if (!file) return null;
+
+    const itemId = uuid();
+    const entry = {
+      timestamp: new Date(now).toISOString(),
+      ordinal,
+      type: 'compacted',
+      payload: {
+        message: text,
+        // The summary doubles as the one message that survives, so the thread keeps something to
+        // answer from even if nothing else is carried over.
+        replacement_history: [{
+          type: 'message',
+          id: 'msg_' + uuid().replace(/-/g, '').slice(0, 24),
+          role: 'user',
+          content: [{ type: 'input_text', text }],
+        }],
+        window_number: 1,
+      },
+    };
+    const line = JSON.stringify(entry) + '\n';
+
+    // Appended in place. A rename would swap the file Codex holds open, and its next append
+    // would land on the old inode, taking everything written since with it.
+    fs.appendFileSync(file, line);
+    const size = fs.statSync(file).size;
+
+    db.prepare(
+      'INSERT INTO thread_items (thread_id, turn_id, item_id, rollout_ordinal, created_at_ms, item_json, item_type, updated_at_ordinal, started_at_ms, completed_at_ms) ' +
+      'VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)'
+    ).run(tid, turnId, itemId, ordinal, now, JSON.stringify({ type: 'contextCompaction', id: itemId }),
+      'contextCompaction', ordinal, now, now);
+
+    // The part that is easy to leave out, and without which the first two are unread.
+    db.prepare(
+      'UPDATE thread_history_projection_state SET next_rollout_byte_offset = ?, next_rollout_ordinal = ? WHERE thread_id = ?'
+    ).run(size, ordinal, tid);
+
+    db.close();
+    return { threadId: tid, ordinal, bytes: size, chars: text.length };
+  } catch {
+    try { db?.close(); } catch { /* already closed */ }
+    return null;
+  }
+}

package/idlecall.mjs

@@ -0,0 +1,67 @@
+// The summary call.
+//
+// One extra model call, made once, when a long conversation comes back after a pause. It is not
+// free and it is not fast, and both costs are the price of not paying for the history on every
+// turn of the new window.
+//
+// It is a separate call rather than a turn of the conversation because the answer serves two
+// readers with different needs: the person waiting for the answer to their own question, and the
+// agent that will read the summary next time. Folding them together would mean either the person
+// reads a summary instead of an answer, or the summary is a summary of a summary.
+//
+// The model it uses is a setting, and empty means the one this conversation is already talking
+// to. A cheaper model writes a cheaper summary and a worse one: the summary replaces the history,
+// so what it leaves out is gone. That is the reader's call to make, not this gateway's.
+
+import { clampSummary, summaryMessages } from './idlecompact.mjs';
+
+/** Asks for the summary. Returns the text, or '' when nothing usable came back. */
+export async function askSummary({ ir, policy, profile, mappedModel, model, build, fetchImpl = fetch, timeoutMs = 180000 }) {
+  const msgs = summaryMessages(ir, policy);
+  if (!msgs.length) return '';
+
+  const ir2 = { ...ir, messages: msgs, stream: false, tools: [], toolChoice: null };
+  const { url, headers, upBody } = build(profile, model, ir2);
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), timeoutMs);
+  try {
+    const res = await fetchImpl(url, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(upBody),
+      signal: ac.signal,
+    });
+    if (!res.ok) return '';
+    const raw = await res.text();
+    return clampSummary(answerText(raw, ir2), policy);
+  } catch {
+    // A summary that could not be produced is not a reason to fail the turn. The caller still
+    // shortens the request, because a shortened history is worth having even with nothing
+    // written to the session file.
+    return '';
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// The answer's text, from whichever shape came back.
+function answerText(raw, ir) {
+  let doc;
+  try { doc = JSON.parse(raw); } catch { return ''; }
+  if (Array.isArray(doc?.content)) {
+    return doc.content.filter(b => b?.type === 'text').map(b => b.text || '').join('\n');
+  }
+  if (doc?.choices?.[0]?.message?.content) return String(doc.choices[0].message.content);
+  if (Array.isArray(doc?.output)) {
+    let out = '';
+    for (const item of doc.output) {
+      if (typeof item?.text === 'string') out += item.text;
+      for (const c of item?.content || []) if (c?.type === 'output_text' || c?.type === 'text') out += c.text || '';
+    }
+    return out;
+  }
+  if (Array.isArray(doc?.candidates)) {
+    return doc.candidates.map(c => (c?.content?.parts || []).map(p => p.text || '').join('')).join('\n');
+  }
+  return '';
+}