Codex Turn State Manager

A CLIProxyAPI (CPA) plugin that manages X-Codex-Turn-State values for Codex accounts.

Upstream returns X-Codex-Turn-State as a per-turn sticky-routing token. Observed behaviour suggests a value of a particular length (292 by default) can be reused across turns for a given (account, model) pair, giving more stable upstream routing. This plugin probes accounts on a schedule, binds harvested values per pair, injects them into outbound requests, and harvests fresh values from ordinary traffic responses.

This exploits undocumented behaviour. Codex documents the token as per-turn only. The plugin is therefore built to be switchable, invalidatable and self-healing: it can be turned off entirely, a bad binding is dropped automatically after a failed request, and a failure to inject never fails the request.

The full specification lives in docs/插件开发文档.md. Agent-facing working rules live in AGENTS.md.

对应设计文档 §6.1 阶段划分。本表是开发进度的唯一记录，完成一项就更新一次状态。

✅ 必须同时满足三条，缺一不可：

1. 组件自身代码完成；
2. 承载该产出验收标准的关键函数有单元测试，覆盖率不为 0（go test -coverpkg=./... 实测，不看感觉）；
3. 在开发 harness 中实跑验证过。

另外：依赖 CPA 真实回调行为（#5、#8）或依赖浏览器渲染（#9、#11）的部分，在真的被触发过之前不计入 ✅。这条针对的是「只能靠真实环境才能证伪」这件事，不是永久豁免——一旦该行为已经被实测过（例如注入已在真实流量上跑通、面板交互已在浏览器中点过），就按上面三条正常判定。

覆盖率口径：go test -coverpkg=./... -coverprofile=...（全仓 76.5%）。数字随代码变化，改完请重测，不要沿用旧值。

#0 不在设计文档 §6.1 的计划表内，是框架落地后暴露出来的前置项：它直接卡住 #5、#8 的最终验收。设计文档 §8「关键技术验证清单」的 12 项验证应当在这一步内完成。

go tool cover -func 实测的 0% 函数，按重要性排列：

另有未被任何地方调用的导出方法，属清理项而非缺口：app.TriggerProbe、app.ManagementAPI、app.DB、app.Correlation、intercept.RequestInjector.Correlation、intercept.CorrelationManager.Len。

探测   SUCCESS_TARGET  len=292  经代理直连上游        ✅ 真实实例
绑定   写入 SQLite → 内存快照 → 排定 TTL×85% 退避     ✅
注入   经 CPA 的请求带上注入头，账号识别无误           ✅ 真实流量
观测   请求管道计数（注入/捕获/账号未知/跳过/丢弃）     ✅ 真实流量
账号   套餐与额度取自上游响应头                        ✅ 真实流量（实测填入 plan=free 与 5h/周 用量）
自愈   失败请求 → 失效绑定 → 立即重探                  ⚠️ 有单测（ObserveCompletion 88.9%），未经真实失败触发

「自愈」一行是未被证伪而非已证明：真实失败请求没有发生过，request.complete 回调也还没在真实环境被观察到。

1. 补 #0 的两个回调单测（handleCompletion / handleResponseIntercept）——这是唯一还卡着 #0 的东西，补完即可转 ✅。
2. #9 面板收尾——交互已实测通过，剩下 GET /models 端点的测试与「浏览器项不计入 ✅」这条口径的取舍。
3. #8 调度干预的真实验证——需要多账号环境才能体现「优先选择持有 State 的账号」。

Requires Go 1.26+ (see go.mod) and, for the shared library, a C compiler with CGO_ENABLED=1. The Linux cross-build in make build-linux uses golang:1.26-bookworm.

make run

Then open http://127.0.0.1:8787/v0/resource/plugins/codex-turn-state-manager/ and sign in with the harness key devkey. That bare base path is a harness convenience — it redirects to /index.html. On a real CPA the entry point is /index.html directly, because CPA rejects a resource route whose path trims to empty.

The harness boots the real application against an in-memory mock of the CPA host and serves the real Management API and admin panel, so the plugin can be developed without a CPA instance and without touching real accounts.

make run ARGS="-accounts 8 -listen 127.0.0.1:9000"

ARGS is appended after the defaults, so it can override any of them.

-stale-account seeds the first mock account with the leftovers CPA leaves after an expired cooldown — unavailable=true, status=error and a past next_retry_after — which is the shape that once made the panel report a healthy account as broken. It is off by default: a harness that starts with an account in error invites a false bug report from whoever next opens it.

make build          # development harness + C-ABI shared library
make build-dev      # harness only
make build-shared   # C-ABI .so / .dylib / .dll for the host OS

c-shared output cannot be cross-compiled by setting GOOS — build on the target OS and architecture. The shared library's base name must match the key CPA uses in plugins.configs (codex-turn-state-manager).

make test        # unit tests
make test-race   # the gate: probe workers and the API write concurrently
make vet
make fmt

CPA's plugin store reads a registry.json and installs from the releases it points at. Add this repository's registry as an extra source in CPA's config:

plugins:
  enabled: true
  store-sources:
    - "https://raw.githubusercontent.com/yangshoulai/codex-turn-state-manager/main/registry.json"

The plugin then appears in the store and installs in one step, landing at plugins/<goos>/<goarch>/codex-turn-state-manager-v<version>.so. The store writes the manifest back into plugins.configs.codex-turn-state-manager.store so it can offer updates later.

The official registry is always included; store-sources only adds to it.

Publishing a release is what makes the plugin installable — nothing is uploaded by hand. Push a version tag and the workflow does the rest:

git tag v0.1.0
git push origin v0.1.0

.github/workflows/release.yml then builds one archive per platform, generates checksums.txt, and creates the GitHub release. workflow_dispatch reruns a release for an existing tag and replaces its assets.

The artifact naming is a contract, not a convention. CLIProxyAPI looks up one exact asset name and rejects an archive that does not match, so all of this is enforced by make release-archive before anything is published:

Platforms built: linux/amd64, linux/arm64, darwin/amd64, darwin/arm64, windows/amd64. c-shared cannot be cross-compiled by setting GOOS alone, so each entry in the workflow matrix builds natively — both macOS architectures come from one runner because Apple's toolchain is a cross-compiler. Adding a platform is one entry in matrix.include; the archive name follows automatically.

make release-archive builds for the machine running it, so it needs a real version: pass VERSION= when the working tree is not on a tag.

registry.json describes the plugin. It omits install, which means github-release: the store reads this repository's latest release and derives the version from its tag. Keeping a version in the file too is a display fallback — the release tag is authoritative.

A direct install type is also supported if you would rather host artifacts somewhere other than GitHub Releases; it pins an explicit URL and sha256 per platform instead.

             ┌──────────────── CPA process ────────────────┐
             │                                             │
  request ──▶│ BeforeAuth ──▶ Scheduler ──▶ AfterAuth ──▶   │──▶ upstream
             │     │              │            │           │
             │     │ correlation  │ account    │ state     │
             │     └──────────────┴────────────┘ injection │
             │                                             │
             │  response headers ──▶ capture ──▶ binding    │
             └─────────────────────────────────────────────┘
                          ▲
             background ──┴── probe scheduler ──▶ proxy pool ──▶ upstream

Four runtime capabilities, all gated by one master switch:

With the master switch off, all six are bypassed and the plugin is a no-op on the request path.

The log is the one capability with no sub-switch of its own. It answers "what did the plugin do to my request", which is exactly the question an operator has when they have just turned one of the other four off.

State shape. The token carries its own block count and issue time. Ten blocks (292 characters) is the personal rule and twelve (332) the team rule; the plan decides which applies to an account.

TTL runs from when the upstream minted the value, not from when the plugin stored it. The envelope carries an issue timestamp, so a value that spent most of its life before reaching us does not get a fresh hour — and one that arrives already past its TTL is recorded and dropped rather than displacing a binding that still works. Without this, a value harvested late would be injected until the upstream stopped honouring it, which looks like "it worked, then it stopped" with nothing in between.

State lifecycle. A binding is FRESH until 85% of its TTL has elapsed, then REFRESH_DUE (still injected, but scheduled for renewal), then EXPIRED. Default TTL is 60 minutes.

Only the right shape binds. A harvested value that is not the shape its account produces is recorded and discarded — never bound.

The shape is per plan, not one global length: the token is a version byte, an issue timestamp, and a run of ciphertext blocks, and the tier decides how many blocks. Ten blocks encode to 292 characters and are what personal accounts produce; twelve encode to 332 and are what Team and Business accounts produce. A Team value is a plus account's wrong length, so one target_state_length cannot describe both. The plugin reads the block count from the token itself, resolves the expected count from the account's plan (the plan on the response first, then the stored one), and only falls back to comparing against target_state_length when the plan is unknown — which is also the one case that setting governs.

The panel shows the resolved length on each account, so a probe log can be read against the rule actually being applied.

Least-recently-used proxy rotation. Each probe walks the pool in LRU order, up to max_proxies_per_probe nodes, stamping last_used_at before each request so concurrent probes never pick the same node. The walk stops early on a target hit, or on an account- or model-level error that another proxy could not fix.

Failure classification. Timeouts, connect errors, TLS errors and 407 are proxy faults. Upstream 400/401/403/429 are not, and never evict a healthy node — the walk stops on them instead.

Cooling is per account, not per proxy. The same node returns the target state length for one account and a non-target length for another, because the upstream decides per account — so a node-level cooldown lets one account's failures take a working node away from everyone else. Availability is therefore recorded per (account, proxy) pair: a node benched for one account is still selectable by every other, and a round ends for one account only when all of its nodes are benched. The node list shows how many accounts currently have each node benched; the 详情 button opens the per-account rows with a reset on each, and the section has a global reset.

Cooldown ladder. 1, 2, 4, 8, 16, 32 then 64 minutes, doubling and holding at the cap; at the cap the pair's counter resets so the next failure starts at a minute again, which is what keeps an outage longer than an hour from removing a pair permanently. Two things earn a cooldown: a proxy fault, and a response whose state length is not the target — the request succeeded, but this node is not yielding what that account needs.

Scanning is not probing. A one-minute scan only enqueues probes that are actually due; a non-target-length result backs off for minutes, not seconds.

A pair that keeps missing backs off further. The first few wrong-shaped answers retry at the base cadence — a transient deserves one — and the interval then doubles each round up to non_target_backoff_cap_min (default 30). A model that never yields the target shape would otherwise be re-probed every few minutes forever, and every round walks the pool, so the cost lands on the proxies rather than on the one pair that is never going to work. The run resets on any other outcome, so a model that starts working is retried at the base cadence immediately.

Self-healing. If a request that carried plugin-injected state fails with previous_response_not_found, a routing error, or a run of 5xx, the binding is dropped and re-probed — so a bad value cannot poison traffic for the rest of its TTL.

Set from the panel or the Management API. Defaults:

Time windows restrict when probing runs. Several windows may be configured, each with an optional day-of-week set; a window may cross midnight (22:00–06:00). With no enabled window, probing is unrestricted — a window that is disabled, entered wrong, or absent all mean 24/7 probing, so the panel's config line reports the scheduler's live decision (窗口 08:00–02:00（当前禁止探测）) rather than just counting rows.

The manual probe button on a model row ignores the window deliberately: it is an explicit request for one probe now, and a pair whose scheduled probing is off is exactly the one someone would want to test by hand. Its tooltip says so.

Windows are evaluated in the CPA process's local timezone, not yours. The panel renders probe timestamps in your browser's timezone, so the two can be a long way apart — a server on TZ=Pacific/Honolulu with a browser in UTC+8 differs by eighteen hours, and an 08:00–02:00 window then admits probes at 07:00 by the browser's clock while the server is looking at 13:00.

The config line states the clock the decision is made on, and names the gap when there is one:

窗口 08:00–02:00 · 服务器 14:45:38 HST（与浏览器相差 18 小时，窗口按服务器时间判定）

Set TZ on the CPA container if you want the window to follow your own hours:

environment:
  - TZ=Asia/Shanghai

Without it the window is interpreted wherever the process thinks it is, which on a VPS is frequently UTC or the host's default.

Proxy nodes are ordinary HTTP/HTTPS/SOCKS5 URLs.

All routes are under /v0/management/codex-turn-state-manager/ and require CPA's management auth.

Note the path is flat — there is no plugins/ segment. The host offers plugins BasePath /v0/management and resolves routes as <BasePath> + <Path>, so the plugin segment is ours to choose. Nested under plugins/ it would share a namespace with CLIProxyAPI's own plugin administration API, and third-party management front ends that treat plugins as a reserved segment would demand their own credentials before reaching it. Resource routes are the opposite: the host inserts /plugins/<id> there itself.

GET    /status                            # includes the live time-window decision
GET    /settings
PUT    /settings
GET    /time-windows
POST   /time-windows
PUT    /time-windows?id=…
DELETE /time-windows?id=…
GET    /models
GET    /accounts
POST   /accounts/sync
GET    /accounts/models?authIndex=…     # omit authIndex for every account at once
POST   /accounts/models/probe-now?authIndex=…&model=…
DELETE /accounts/models?authIndex=…&model=…
PUT    /accounts/models/probe?authIndex=…&model=…
GET    /bindings
DELETE /bindings?authIndex=…&model=…
GET    /bindings/history?authIndex=…&model=…&expand=1&limit=&offset=
DELETE /bindings/history?authIndex=…&model=…
GET    /proxy-nodes
PUT    /proxy-nodes
POST   /proxy-nodes/reset?nodeId=…&authIndex=…
POST   /proxy-nodes/reset-all
GET    /proxy-nodes/cooldowns?nodeId=…
GET    /probe-history?authIndex=&model=&limit=50&offset=0

Every dynamic segment is a query parameter, and that is a host constraint rather than a style choice. CPA dispatches management routes by exact path — :, * and .. are rejected at registration — so /bindings/{authIndex}/{model} is not registrable. The path must also carry the plugins/<pluginID> segment itself. GET /probe-history returns total alongside the page so the panel can paginate.

GET /status reports version, now, settings, the resolved capabilities, proxy counts, and pipeline: counters for requests reaching the injection stage, injections performed, accounts that could not be resolved, bindings missing, state captured from traffic, and self-healing invalidations. A header rewrite leaves no other trace, so these are how "is the plugin actually doing anything?" gets answered without logging every request. pipeline.lastHeaderInit is a snapshot of what the most recent response actually carried — which is how the reverse-bind limitation above was established.

The panel's own assets are served from /v0/resource/plugins/codex-turn-state-manager/, which bypasses management auth. The two cacheable assets carry a content hash in their route (/app.<hash>.js, /style.<hash>.css) and are served immutable; index.html keeps a stable address and is served no-cache, because it is what records which asset build is current. That pairing is what makes an update take effect immediately even behind a CDN that caches by file extension. Note the entry point is /index.html, not the bare base path: CPA rejects a resource route whose path trims to empty, so a bare / cannot be registered. Nothing secret is ever served from there: state values are returned as prefixes through the Management API, and the management key is held in page memory only.

state.db (SQLite, WAL) lives in the plugin data directory, with pre-migration backups under backups/. Schema changes are forward-only migrations with SHA-256 checksums; a database written by a newer plugin build refuses to start rather than risk corruption.

MIT — see LICENSE.