llm-switcher 1.6.0 → 1.6.3

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog — LLM Switcher
 
+## Release 1.6.3 — 2026-10-08
+
+- **Interactive Summarization Model Selection & Presets:** Replace raw text input for Idle Compaction's summarization model with a fully searchable combobox dropdown and quick 1-click preset chips. Users can pick directly from deterministic heuristic mode (`""`), slot aliases (`haiku`, `subagent`, `sonnet`, `main`), configured profile models (`zencore/*`, `codex/*`), and discovered catalog models, or type to filter in real-time. Selection automatically saves and updates active highlights across both light and dark themes.
+
+## 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

package/README.md

@@ -552,43 +552,50 @@ On Linux the unit is a systemd *user* service: it starts when you log in. To sta
 
 ### 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.
+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.
 
-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.
+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 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.
+| `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
 
@@ -808,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

@@ -550,43 +550,47 @@ Trên Linux, unit là service systemd *của user*: nó khởi động khi bạn
 
 ### 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.
+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.
 
-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.
+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 (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.
+| `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
 
@@ -805,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.