llm-switcher 1.4.1 → 1.6.2

package/CHANGELOG.md

@@ -1,5 +1,102 @@
 # Changelog — LLM Switcher
 
+## Release 1.6.2 — 2026-10-08
+
+- **Per-Model Slot Target Thinking Effort:** Support granular reasoning effort configuration per model slot (`profile.modelEfforts`). Individual slot selectors in the dashboard allow setting target effort levels (`auto`, `none`, `low`, `medium`, `high`, `xhigh`, `max`) independently for each model tier (e.g. Sonnet, Opus, Haiku, Codex roles) with automatic fallback to profile-level defaults.
+- **Dedicated Idle Compaction Navigation & Collapsible View:** Separate Idle Compaction into its own sidebar menu (`#/compact`) with dedicated overview telemetry cards. Automatically collapse detailed configuration cards when inactive, and replace button-like unit badges with clean native typography and tooltips.
+- **Accurate Bifrost Passthrough Detection:** Refine Bifrost passthrough indicators to activate only for genuine intact-routed native prefix models, keeping reasoning effort selectors fully accessible for normal OpenAI/Anthropic/Vertex/Gemini endpoints.
+
+## Release 1.6.1 — 2026-10-08
+
+- **Durable Gateway Prefix Cache:** Replace external Claude Code and Codex transcript/database
+  writers with a private, durable gateway prefix cache under `STATE_DIR/idle-compact/`. Exact source-prefix,
+  caller/session/profile/context and generation guards preserve every newly appended turn and reject
+  stale summaries. Native client files (`~/.claude/projects/` and `thread_history_1.sqlite`) remain untouched.
+- **Reasoning and Tool Pairing Preservation:** Retain assistant decision and reasoning text
+  accompanying tool calls; preserve tool dependencies throughout the recent tail and forward
+  malformed or unsupported tool histories unchanged.
+- **Effort Mapping Ladder & Dynamic UI:** Introduce an 8-level effort ladder (`none`, `minimal`,
+  `low`, `medium`, `high`, `xhigh`, `max`, `ultra`) with automatic nearest-level equivalence mapping
+  (`mapEquivalentEffort`) when targeting upstreams with fewer levels (strict OpenAI, Anthropic, Gemini).
+  Add `profile.thinkingEffort` override setting with Web UI dropdown sync and automatic Bifrost passthrough hint.
+- **Pure CA Validation & Fail-safe TLS:** Introduce strict file validation for custom CA certificates
+  (`usableCACertificate`); automatically unsets loopback proxy when CA is missing, corrupt, or unreadable
+  so Codex connects directly via system root certificates instead of failing TLS during daemon startup.
+- **Consistent Idle-compaction Settings:** Validate all idle-compaction settings and budgets consistently.
+  An empty/null summary model makes no provider call; a configured summary model routes independently
+  with bounded timeout and visible diagnostics. Update dashboard and CLI controls accordingly.
+
+## 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.

package/README.md

@@ -550,6 +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 configurable pause can indicate that the provider's prompt cache is cold; it is a heuristic,
+not a guarantee about any provider's cache lifetime. This feature is off by default.
+
+For an identified Claude Code session, the gateway shortens an old prefix once after a sufficiently
+long pause. It stores the exact original prefix hash and its replacement in a private cache under
+`STATE_DIR/idle-compact`. Later requests reuse that prefix only while the original raw history still
+matches, and preserve every recent and newly appended turn unchanged. The cache survives gateway
+restarts. A native client compaction or edited prefix invalidates it safely. Client JSONL files and
+Codex SQLite databases are never read or modified by this feature.
+
+| Command | Behavior |
+| --- | --- |
+| `switch compact status` | Show settings |
+| `switch compact on` / `off` | Enable or disable Claude request compaction |
+| `switch compact codex on` / `off` | Opt Codex Responses requests into the same wire prefix cache; off by default |
+| `switch compact model <id>` | Explicitly choose a summary model |
+| `switch compact model none` / `default` | Disable summary calls; no fallback to the conversation model |
+| `switch compact idle <minutes>` | Pause threshold, default 15; allowed 1–1440 |
+| `switch compact min <KB>` | Minimum request size, default 64; allowed 8–4096 |
+
+An unset summary model (empty string or `null`) makes no model call. The deterministic replacement
+keeps earlier user and assistant text within the configured budgets, removes older tool payloads,
+and retains the recent tail with complete call/result pairs. With an explicit summary model, one
+background call summarizes only the replaced prefix and upgrades its cache generation. A late
+summary cannot overwrite a newer generation or remove turns that arrived while it was running.
+The summary model is mapped and its upstream format resolved independently of the main model.
+
+Caching requires an explicit session identifier: Claude session headers/metadata, or Codex session,
+thread or prompt-cache identity. Anonymous requests stay unchanged; shared opening prompts are not
+used as session identity. Cache scope includes the client, caller credential digest, profile,
+model, system/tools and compaction policy. Unsupported or malformed tool histories are forwarded
+unchanged. Cache failure or corruption also forwards the original request.
+
+The dashboard and `/api/idle-compact` use the same settings as the CLI. Supported fields are
+`enabled`, `codex`, `model`, `idleMinutes`, `minBytes`, `keepRecent`, `userChars`, `summaryMaxChars`,
+and `sessionLookbackHours`. The API rejects unknown fields and invalid budgets with HTTP 400.
+Additional bounds/defaults: `keepRecent` 1–100 (6), `userChars` 128–24000 (3000),
+`summaryMaxChars` 256–128000 (24000), and `sessionLookbackHours` 1–168 (72).
+The private cache keeps at most 256 records and expires idle clocks and prefix mappings after the
+configured lifetime. A later idle window may compact a larger prefix; ordinary appended turns
+reuse a stable prefix. Native Codex compaction remains Codex's own responsibility.
+
+When using intact, configure the profile with an authorized intact API key. Client User-Agent
+matching chooses the native protocol route; it does not replace upstream authentication.
+
 ### 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.
@@ -768,6 +815,7 @@ Because of this split, a provider fingerprint is never a rule in this gateway. I
 | `LLM_SWITCHER_BIFROST_RETRY_MS` | Time before the gateway asks intact again after a failed Bifrost lookup (default 30000 ms). |
 | `x-llm-profile: <key>` header (alias `x-profile`) or `?profile=<key>` | Route a single request through a specific profile. An unknown key returns HTTP 400 instead of silently falling back. |
 | `profile.thinkingMode` | `auto` (default, for gateways like intact or 9Router): restore stripped thinking, inject a `<think>` guide for non-reasoning models, send `thinking` + `reasoning_effort`. `native` (strict OpenAI APIs): send only `reasoning_effort` when the client asks, never touch the prompt, use `max_completion_tokens`. `off`: never send reasoning parameters. |
+| `profile.thinkingEffort` | `auto` (default, caller/client controls effort), or an explicit override level: `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, `ultra`. Overrides client effort before routing upstream. Automatically maps to the nearest equivalent level accepted by the target upstream (e.g. OpenAI ceiling `high`, Anthropic `max`, Gemini budget bounds). In the Web UI, this selector dynamically hides with a guidance hint when Bifrost passthrough is active. |
 | `profile.endpoints.countTokens` | Override the Anthropic `count_tokens` URL. |
 | `profile.endpoints` | Override upstream URLs per format: `{ "openai-chat": "...", "anthropic": "...", "vertex": "https://.../models/{model}:{action}" }`. |
 | `CLAUDE_CONFIG_DIR` | Respected when locating Claude Code's `settings.json`. |

package/README.vi.md

@@ -548,6 +548,50 @@ 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
+
+Khoảng nghỉ đủ dài có thể là dấu hiệu cache của provider đã nguội. Đây là ngưỡng do bạn chọn,
+không phải bảo đảm cache đã hết hạn. Tính năng mặc định tắt.
+
+Với phiên Claude Code có định danh rõ ràng, gateway rút gọn một prefix cũ sau khoảng nghỉ và lưu
+ánh xạ giữa hash của prefix gốc với bản thay thế trong cache riêng `STATE_DIR/idle-compact`.
+Các request sau chỉ dùng lại khi prefix gốc khớp hoàn toàn, giữ nguyên mọi turn gần đây và turn
+mới thêm. Cache còn hiệu lực sau khi gateway khởi động lại. Nếu client tự compact hoặc sửa lịch
+sử cũ, ánh xạ hết hiệu lực. Tính năng không đọc hay sửa JSONL của client hoặc SQLite của Codex.
+
+| Lệnh | Hành vi |
+| --- | --- |
+| `switch compact status` | Xem cấu hình |
+| `switch compact on` / `off` | Bật hoặc tắt nén request Claude |
+| `switch compact codex on` / `off` | Bật riêng cache prefix cho request Responses của Codex; mặc định tắt |
+| `switch compact model <id>` | Chọn rõ model viết summary |
+| `switch compact model none` / `default` | Không gọi model summary; không dùng model của hội thoại làm dự phòng |
+| `switch compact idle <phút>` | Ngưỡng nghỉ, mặc định 15; phạm vi 1–1440 |
+| `switch compact min <KB>` | Kích thước request tối thiểu, mặc định 64; phạm vi 8–4096 |
+
+Không đặt model summary (chuỗi rỗng hoặc `null`) thì không gọi model nào. Bản rút gọn xác định
+sẵn giữ chữ của user và assistant trong ngân sách đã chọn, bỏ payload tool cũ và giữ tail gần
+nhất cùng đủ cặp call/result. Nếu có model summary, một lượt gọi nền chỉ tóm tắt prefix được
+thay thế rồi cập nhật generation cache. Summary đến muộn không ghi đè generation mới hơn và
+không mất các turn xuất hiện trong lúc chờ. Model summary được map và chọn format upstream riêng.
+
+Phải có định danh phiên rõ ràng: header/metadata phiên Claude, hoặc session, thread hay prompt
+cache key của Codex. Request không có định danh giữ nguyên; cùng câu mở đầu không được coi là
+cùng phiên. Phạm vi cache gồm client, digest credential của caller, profile, model, system/tool
+và policy nén. Lịch sử tool không được hỗ trợ hoặc sai cặp giữ nguyên; cache lỗi cũng gửi nguyên
+request gốc.
+
+Dashboard và `/api/idle-compact` dùng cùng cấu hình với CLI. Các field được nhận: `enabled`,
+`codex`, `model`, `idleMinutes`, `minBytes`, `keepRecent`, `userChars`, `summaryMaxChars` và
+`sessionLookbackHours`. API trả HTTP 400 cho field lạ hoặc ngân sách không hợp lệ.
+Các phạm vi/mặc định còn lại: `keepRecent` 1–100 (6), `userChars` 128–24000 (3000),
+`summaryMaxChars` 256–128000 (24000), `sessionLookbackHours` 1–168 (72).
+Cache riêng giữ tối đa 256 record, hết hạn theo thời gian đã cấu hình. Một khoảng nghỉ mới có
+thể nén prefix lớn hơn; các turn liên tiếp dùng lại prefix ổn định. Codex tự quản lý native compaction.
+
+Khi dùng intact, profile cần API key intact được cấp quyền. User-Agent chỉ chọn đường protocol
+gốc, không thay cho xác thực ở upstream.
+
 ### 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.
@@ -765,6 +809,7 @@ Nhờ cách chia này, fingerprint của provider không bao giờ là rule tron
 | `LLM_SWITCHER_BIFROST_RETRY_MS` | Thời gian trước khi gateway hỏi lại intact sau một lần tra cứu Bifrost thất bại (mặc định 30000 ms). |
 | Header `x-llm-profile: <key>` (tên khác `x-profile`) hoặc `?profile=<key>` | Định tuyến riêng 1 request qua profile chỉ định. Key không tồn tại trả HTTP 400 thay vì âm thầm dùng profile khác. |
 | `profile.thinkingMode` | `auto` (mặc định, cho gateway như intact hoặc 9Router): phục hồi thinking bị xoá, inject hướng dẫn `<think>` cho model không có reasoning, gửi `thinking` + `reasoning_effort`. `native` (API OpenAI nghiêm ngặt): chỉ gửi `reasoning_effort` khi client yêu cầu, không sửa prompt, dùng `max_completion_tokens`. `off`: không bao giờ gửi tham số reasoning. |
+| `profile.thinkingEffort` | `auto` (mặc định, client tự quyết định), hoặc đặt cố định mức override: `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, `ultra`. Ghi đè mức reasoning effort từ công cụ trước khi gửi lên upstream. Tự động ánh xạ về mức tương đương gần nhất mà upstream đích hỗ trợ (OpenAI trần `high`, Anthropic trần `max`, Gemini điều chỉnh `thinkingBudget`). Trên Web UI, tùy chọn này tự động ẩn cùng thông báo gợi ý khi profile bật chế độ Bifrost passthrough. |
 | `profile.endpoints.countTokens` | Ghi đè URL `count_tokens` của Anthropic. |
 | `profile.endpoints` | Ghi đè URL upstream theo từng format: `{ "openai-chat": "...", "anthropic": "...", "vertex": "https://.../models/{model}:{action}" }`. |
 | `LLM_SWITCHER_STATE_DIR` | Chuyển file launcher và log ra khỏi thư mục dữ liệu. Test dùng biến này; shim đọc thư mục đã đặt lúc cài shim. |

package/docs/session-2026-10-07-compaction.md

@@ -0,0 +1,224 @@
+# Báo cáo phiên làm việc — 2026-10-07
+
+> Bản ghi của một phiên làm việc, để đọc lại được về sau. Nó nói cả những gì đã kiểm chứng và
+> những gì **chưa**, và các mục trong bảng mục lục là các phần.
+
+Một phiên làm việc trên hai repo: **llm-switcher** (gateway ở phía client) và **intact** (gateway
+ở phía provider). Chủ đề xuyên suốt: **một hội thoại dài đáng tiền khi cache đã mất, và cách làm nó
+rẻ đi mà không phá client nào.**
+
+Trang này là bản ghi của những gì đã kiểm chứng, những gì đo được, và những gì **chưa** chứng
+minh được. Phần cuối là danh sách việc dở — có một mục đã biết là chưa xong và nói rõ ở đó.
+
+---
+
+## 1. Kết quả, theo thứ tự đã giao
+
+### intact — `5dddbbe`, `ba19457` · deploy `intact`, `intact-af`, `intact-ops`
+
+**a. 429 → retry với context đã rút gọn.**
+
+Giới hạn của provider tính theo token/phút, nên account kế tiếp gặp đúng cuộc hội thoại đó trước
+cùng bức tường. Tệ hơn: account kế tiếp **không có cache** cho prefix này, vì nó chưa từng thấy lượt
+trả lời đầu — lịch sử dài tốn tiền đầy đủ và không đổi lấy gì.
+
+Đo trên một hội thoại agent 32 KB: retry đi ra **10 KB, bớt 68%**.
+
+Hai cổng, và không có gì ngoài chúng:
+
+| Cổng | Vì sao |
+|---|---|
+| Provider ở chế độ round-robin **và** còn account sẵn sàng | Provider ghim một account thì không có chỗ nào nhận bản rút gọn; rút gọn chỉ là vứt lịch sử đi. Một account standby không tính là sẵn sàng — nó là phương án cuối. |
+| **429 thật** | `500` cũng được retry nhưng rút gọn không giúp: provider **hỏng**, không phải **đầy**. |
+
+**b. Codex compaction — trả đúng 1 `compaction` item.**
+
+Codex 0.160 gửi một `compaction_trigger` và chỉ nhận đúng một output item loại `compaction`. Provider
+trả lời như một completion thường thì cho 0 item, và Codex coi đó là lỗi chết **trước khi** nó thay
+lịch sử — thread giữ nguyên độ dài, mọi lần `resume` lại compact và chết y hệt. Tính năng báo
+`removed`, không tắt được.
+
+Kiểm chứng trên provider codex thật: **HTTP 200, đúng 1 compaction item**, cả stream lẫn non-stream.
+
+Ba điều không dễ thấy:
+- Mang theo setting của client. Responses của OpenAI từ chối request không có `store:false`, và từ
+  chối không có `stream:true` — nó sẽ từ chối đúng những account đang phục vụ mọi turn khác.
+- Account chỉ nói dạng stream thì một lần retry bật flag.
+- **Không bao giờ lưu summary rỗng.** Provider trả tool call sẽ nhận lỗi, vì summary rỗng thay cả
+  lịch sử bằng hư không.
+
+**c. Cổng xác thực nhận client chính thức của provider.**
+
+Codex nói chuyện với ChatGPT bằng credential của ChatGPT. Trỏ sang intact thì nó vẫn gửi credential
+đó, mà intact không kiểm được — intact chỉ biết key mình phát. Request mà intact sinh ra để phục
+vụ bị chặn ngay cửa.
+
+Miễn trừ hẹp **hai chiều**: chỉ route proxy `/v1/*`, không phải `/api/*` (nếu không, một
+User-Agent bịa sẽ mở usage, quota, error log, drift); và chỉ đúng provider khai báo tiền tố — client
+codex hỏi model claude thì **403**. Principal đó không có key, không admin, không model nào riêng;
+credential lấy từ kho intact đã lưu, không lấy từ caller.
+
+Hai lỗi test bắt được: `codex_cli_rs/` là của **TUI tương tác**, còn `codex exec` gửi
+`codex_exec/` — nên `BifrostUA` phải nhận nhiều tiền tố. Và một test đang **đòi từ chối** chính Claude
+Code thật — cái sai là test.
+
+### llm-switcher — `281f180` → `4423205`, 1.5.0 → 1.6.0
+
+**a. Nén hội thoại khi idle quá lâu (Claude Code).**
+
+Hội thoại để lâu thì mất cache. Thời gian giữ cache là việc riêng của từng provider:
+
+| Provider | Thời hạn |
+|---|---|
+| Anthropic | 5 phút mặc định, 1 giờ nếu request yêu cầu (`cache_control.ttl`) |
+| OpenAI | `prompt_cache_options.ttl` chỉ có `"30m"`; model cũ dùng `prompt_cache_retention`, `in_memory` ~5–10 phút |
+| Gemini | implicit caching không công bố thời hạn; explicit mặc định 1 giờ |
+| DeepSeek | tự động trên đĩa, không công bố thời hạn |
+
+Nên thời gian là **setting**, mặc định 15 phút.
+
+Hai quyết định:
+
+- **Nén một lần, không nén mọi lượt.** Đổi prefix mỗi lượt nghĩa là không lượt nào trúng cache,
+  và hội thoại bị tóm tắt đi đi lại.
+- **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, không chỉ lượt kích hoạt.
+
+Entry ghi ra đúng hai loại Claude Code tự ghi: `compact_boundary` và một entry `user` mang
+`isCompactSummary`. Entry cũ **vẫn còn** trong file — Claude Code cũng vậy sau khi nén 949k token —
+vì một transcript người ta vẫn đọc được đáng giá hơn một file nhỏ.
+
+**Kiểm chứng trên Claude Code thật:** 12 turn giả (~200 KB) + một boundary → `claude --resume` gửi
+**4 message, 80.567 byte** thay vì 13; có marker summary; **0** còn 4000 ký tự filler.
+
+**b. Dashboard.** Card trên trang Routes, đọc/ghi `/api/idle-compact` — **cùng key với `switch
+compact`**, nên trang và terminal không thể lệch nhau.
+
+**c. Nén cho Codex (1.6.0).** Xem mục 4.
+
+---
+
+## 2. Cách kiểm chứng
+
+| Cách | Kết quả |
+|---|---|
+| Test end-to-end có 429 thật, store thật, account thật | retry 32.532 → 10.473 byte |
+| Test Claude Code thật, đọc request nó gửi | 4 message, không còn turn cũ |
+| Gọi thẳng intact với `compaction_trigger`, provider codex thật | đúng 1 compaction item |
+| Cổng xác thực, 5 hành vi trên bản đang chạy | key thật 200 · UA lạ 401 · UA codex 200 · `/api/*` 401 · codex→claude 403 |
+| **Claude Code thật qua gateway đang chạy** | `idle compact h:bbd52533-4 [p1]: 9681 -> 3832 bytes` · `summary stored` · session file có `compact_boundary` + `isCompactSummary` · `compactMetadata` preTokens 2420 → postTokens 958 |
+| Suite | llm-switcher 704 pass · intact toàn bộ xanh · zencore 301 pass |
+
+---
+
+## 3. Những điều đoán sai rồi đính chính
+
+Ghi lại vì chúng là phần tốn thời gian nhất và có thể sai lại.
+
+1. **"Không có cách nào báo cho tool biết phải compact."** Sai. llm-switcher ngồi ở phía client, có
+   filesystem. Tôi đã nghĩ trong khuôn protocol rồi kết luận là không thể.
+2. **"Sao 1.4.0 chưa tải được?"** Đúng là registry-side propagation, không phải publish hỏng.
+3. **Remote compaction của Codex gắn với auth mode.** Sai: nó compact cục bộ cả khi auth là
+   ChatGPT và endpoint trỏ về intact. Nó gắn với **endpoint có phải backend ChatGPT thật không**.
+4. **Ghi vào file jsonl của Codex là đủ.** Sai: SQLite mới là nơi Codex đọc.
+5. **Viết hai nửa vào store là xong.** Sai: còn phải đẩy projection.
+
+---
+
+## 4. Cơ chế compaction của Codex — đã tìm ra đủ
+
+Một compaction của Codex là **ba ghi phải khớp nhau**, đọc từ một thread thật đã compact 7 lần:
+
+1. **rollout jsonl**: entry `{type:"compacted", payload:{message, replacement_history, …}}` — mang
+   nội dung tóm tắt.
+2. **`thread_history_1.sqlite` → `thread_items`**: hàng `item_type='contextCompaction'`, mà
+   `item_json` chỉ có `{"type":"contextCompaction","id":…}` — **chỉ là mốc, không có chữ summary**.
+3. **`thread_history_projection_state`**: `next_rollout_byte_offset` và `next_rollout_ordinal`.
+
+Mảnh thứ ba là cái dễ bỏ, và bỏ nó thì **trông y hệt thành công**. Bảng đó ghi store đã đọc tới đâu
+trong file: `next_rollout_byte_offset` **bằng đúng kích thước file** (đã đo: 3.722.618 byte =
+`os.path.getsize`), `next_rollout_ordinal` là ordinal sau entry cuối. **File là bản ghi, store là
+projection của nó.** Ghi thêm vào file mà không đẩy projection thì entry đó không bao giờ được đọc.
+
+Kiểm chứng: cài một compaction chứa `CON_VIET_4711` vào thread Codex thật → `resume` → Codex trả
+đúng `CON_VIET_4711`. Qua gateway: `contextCompaction 1` trong store, projection đã đẩy, log ghi
+`summary stored`.
+
+Ba lỗi chỉ chạy mới thấy:
+- Ordinal lấy từ **projection**, không phải `MAX(rollout_ordinal)` — hai số khác nhau.
+- Hàng marker cần `started_at_ms` và `completed_at_ms`; hàng của Codex có, để NULL thì không đọc được.
+- Hội thoại **không có message người dùng** thì không có conversation key → không làm gì, trông
+  như tính năng tắt chứ không phải input sai.
+
+---
+
+## 5. Bốn quy tắc đã đặt, và trạng thái
+
+| Quy tắc | Trạng thái |
+|---|---|
+| Chỉ dùng intact và llm-switcher, không đụng config Codex | **OK** — `~/.codex` không có file config nào; mọi test Codex chạy trong sandbox `CODEX_HOME` riêng |
+| Không tốn token account chính thức | **OK, sau khi sửa** — xem dưới |
+| 429 → compact | **OK** — intact, 4 test e2e |
+| Hết TTL cache → tự compact | **OK** — llm-switcher, test Claude Code thật |
+
+**Quy tắc 2 đã bị vi phạm và đã sửa.** Khi không đặt model summary, code gọi model của chính thread —
+với Codex đó là `gpt-5.6-sol` trên tài khoản ChatGPT chính thức, đúng thứ bị cấm. Tệ hơn: lượt
+summary chỉ dùng để ghi session file, nên không có gì để lưu — gọi model chỉ tốn tiền mà không đổi
+lấy gì. Nay **không gọi model nào trừ khi có đặt**; phần tiết kiệm không đổi vì request vẫn ra
+ngắn.
+
+---
+
+## 6. Lỗi của tôi trong phiên này
+
+- **Giết nhầm zencore.** Chọn port 8793 cho công cụ thử mà không kiểm tra port đó đã có dịch vụ
+  chạy. Đã khởi động lại và xác nhận khỏe, nhưng đó là lỗi của tôi.
+- **Trộn hai kiểu dữ liệu.** Đưa shape của IR vào body Messages, khiến body ra upstream sai định
+  dạng. Chỉ thấy khi đọc body thật ra ngoài.
+- **Ghi session file bằng rename.** Sẽ mất entry: Claude Code giữ file mở, append tiếp vào inode cũ.
+- **Bỏ qua kiểm tra ngược.** Viết xong rồi chỉ chạy test, không đọc lại code sạch sau những lần sửa.
+
+---
+
+## 7. Việc dở
+
+**Không còn mục nào trong bốn quy tắc.**
+
+Đã đóng trong phiên: validate Claude Code qua gateway thật. Còn ba lỗi của *công cụ thử*, không
+phải của tính năng — model thử không tồn tại ở intact; sandbox đặt `CLAUDE_CONFIG_DIR` chỉ cho
+Claude Code nên gateway tìm nhầm `~/.claude` thật; và hàm thử dọn đồ trước khi lượt summary xong.
+Cả ba đã sửa và chạy lại thành công.
+
+Còn một việc **không tự làm được**, vì nó nằm trên tài khoản của bạn: thu hồi token npm trong
+`/opt/hermes/.npmrc`. `id_token` OpenAI từng dán trong chat đã hết hạn từ lâu, không cần làm gì.
+
+Còn một điều **không xong**: Codex **không** dùng compaction của provider. `remote_compaction_v2` chỉ
+chạy khi Codex nói chuyện với backend ChatGPT thật; `CHATGPT_BASE_URL` bị bỏ qua, và các khoá tắt
+WebSocket không ăn. Để đi hết đường đó phải chặn TLS (`HTTPS_PROXY` + `SSL_CERT_FILE`), mà tôi
+không tự làm vì nó đổi niềm tin TLS của máy.
+
+Hệ quả đã ghi rõ trong tài liệu: cờ `idleCompact.codex` tắt mặc định, tiết kiệm đúng **một lượt**,
+và không có lời hứa nào rằng thread sẽ giữ ngắn.
+
+---
+
+## 8. Bàn giao
+
+| | |
+|---|---|
+| llm-switcher | `4423205`, 1.6.0, `main` |
+| intact | `ba19457`, `master` |
+| zencore | không đổi |
+| Service | `intact`, `intact-af`, `intact-ops`, `zencore` — đều `active` |
+| Gateway | llm-switcher, Claude Code → `claude-intact` |
+| Tính năng | `switch compact` — **tắt** |
+
+```
+switch compact on                                              # Claude Code
+switch compact on && switch compact model infron/deepseek/deepseek-v4-flash:free
+switch compact idle 30                                         # phút
+switch compact min 128                                         # KB
+```
+
+**Còn nợ bạn:** token npm và `id_token` từng dán trong chat — hai thứ đều nên thu hồi.