diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index e3ca186bb3..3bb05cd81d 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -424,6 +424,12 @@ jobs: - name: Privacy scan run: bun run privacy:scan + # The ocx skill ships a capability -> route map generated from src/cli/capabilities.ts. + # `bun run test` already covers this via tests/skill-ocx.test.ts; this step exists so the + # failure names the fix instead of surfacing as a byte-comparison diff in a test log. + - name: Check the generated ocx skill surface is current + run: bun run skill:surface:check + - name: Check release helper syntax run: bun build scripts/release.ts --target=bun --outdir=.tmp/ci-release-script-check diff --git a/AGENTS.md b/AGENTS.md index 8e24e6987f..50db477a0d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -177,6 +177,19 @@ bun run privacy:scan # credential/privacy scan used by CI bun run build:gui # Vite GUI build ``` +`skills/ocx/` is the operating reference for the CLI — what an agent reads to *drive* a running +proxy, as opposed to [`AGENTS_INSTALL.md`](./AGENTS_INSTALL.md) (installing and operating consent) +or this file (changing the codebase). Its surface map is generated: + +```bash +bun run skill:surface # regenerate after adding a capability +bun run skill:surface:check # what CI asserts +``` + +`tests/skill-ocx.test.ts` fails if the committed map drifts from `src/cli/capabilities.ts`, and +also if the hand-written pages name a command the registry does not have. That second check is not +hypothetical: it caught a documented `ocx request-history` that never existed. + During implementation, use the smallest focused checks that directly cover the changed subsystem. Do not run repository-wide `bun run typecheck` or `bun run test` for a scoped change unless the change affects shared runtime, diff --git a/devlog/_plan/260827_igwanu_bug_pr_merge_round/000_plan.md b/devlog/_plan/260827_igwanu_bug_pr_merge_round/000_plan.md new file mode 100644 index 0000000000..01ed327825 --- /dev/null +++ b/devlog/_plan/260827_igwanu_bug_pr_merge_round/000_plan.md @@ -0,0 +1,116 @@ +# 000 — igwanu bug-PR merge round: plan + +Round base: `dev @ 8b1b65b8d` (local == `origin/dev`, verified 2026-08-27). +Scope: the 13 open **bug**-labelled PRs. Four are Ingwannu's (#2767, #2766, #2764, +#2761); nine are other authors' (#2747, #2745, #2740, #2733, #2729, #2726, #2693, +#2638, #2497). + +Enhancement-labelled PRs are explicitly out of scope for this round. + +## The finding that orders the whole round + +Three PRs (#2767, #2764, #2747) show **failing required CI** — `ci`, `macos`, +`test 3/4`, `gates` — while their own merged trees compile clean. The failure is +not theirs. Every one of them fails the same repository-wide assertion: + +``` +error: package.json version 2.34.0 equals release tag v2.34.0, but this commit is +not the one that tag names. The tree claims an already-published version. +(fail) release version line > the in-tree version is never behind a released one +``` + +`dev` still carries `2.34.0` after tag `v2.34.0` shipped, so *every* PR opened +after the release train inherits a red matrix. A second shared failure hits +`gates`: `privacy:scan` reads the scp-style SSH remote principal recorded in +`devlog/_plan/260827_release_train/020_preview_release.md` as an email address. + +**#2766 repairs both.** It is the keystone: until it lands, no other PR in this +round can produce a trustworthy green matrix, and re-running their CI is wasted +work. This is the inverse of the previous round's lesson — there, green checks +were not evidence of health; here, red checks are not evidence of harm. + +Evidence: run `33081644562` job `98550259965` (#2767), run `33080634739` job +`98546624127` (#2764), run `33059606933` job `98534630924` (#2747) — each shows +`1 fail` and that one failure is `release version line`. + +## Merged-tree gate (this round's own evidence, not GitHub's) + +Every PR head was fetched, merged against `dev @ 8b1b65b8d` with +`git merge-tree --write-tree`, committed as `mtp/`, checked out to an isolated +worktree sharing this repo's `node_modules`, and compiled. + +| PR | ahead | behind dev | merge-tree | tsc on MERGED tree | +|---|---|---|---|---| +| #2767 | 1 | 0 | CLEAN | OK | +| #2766 | 2 | 0 | CLEAN | OK | +| #2764 | 1 | 0 | CLEAN | OK | +| #2761 | 1 | 2 | CLEAN | OK | +| #2747 | 1 | 26 | CLEAN | OK | +| #2745 | 2 | 26 | CLEAN | OK | +| #2740 | 1 | 26 | CLEAN | OK | +| #2733 | 1 | 43 | CLEAN | OK | +| #2729 | 2 | 89 | CLEAN | OK | +| #2726 | 1 | 63 | CLEAN | OK | +| #2693 | 2 | 118 | CLEAN | OK | +| #2638 | 2 | 179 | CLEAN | OK | +| #2497 | 1 | **386** | **CONFLICT** | not reachable | + +The typecheck gate was itself verified rather than trusted: 12 runs finishing in +~12s looked like a no-op, so a deliberate `const x: number = 'str'` was injected +into a merged worktree and `tsc` returned `error TS2322`, exit 1. The speed is +real — this repository is on the native TypeScript 7.0.2 compiler (~0.44s full +typecheck). The gate works. + +## Cross-PR file contention + +`src/server/responses/core.ts` — **#2745, #2638, #2497**. Pairwise +`git merge-tree` required before any second one of those lands; textual +mergeability is not behavioral compatibility on the auth/routing boundary. + +`src/adapters/openai-chat.ts` — #2764 only. `src/adapters/openai-responses.ts` +— #2767 only. `src/codex/auth-context.ts` — #2638 and #2497. +No other file is touched by two in-scope PRs. + +## Loop-spec + +- Loop archetype: verifier-defined (spec-satisfaction repair per PR). +- Write scope: `devlog/_plan/260827_igwanu_bug_pr_merge_round/`, `src/` and + `tests/` only where needed to land or reimplement a PR, plus PR metadata on + GitHub and `codex/` topic branches. +- Out of scope: `main`, `preview`, releases, tags, npm publish, docs deploy, + enhancement PRs, force-push, history rewrite. +- Bounds: `dev` is push-protected — every lane travels a `codex/` branch and a PR + targeting `dev`. `bun test` takes a machine-wide lock: one suite at a time, + long suites on `ssh lidge` via `ocx-run`. Never `OCX_TEST_NO_QUEUE=1`. + +## Work-phase map (one phase = one full PABCD cycle) + +| WP | Doc | Slice | Depends on | +|----|-----|-------|------------| +| wp1 | 000 | Docs-only roadmap: intake, merged-tree gate, contention map, lanes | — | +| wp2 | 010 | **Keystone** #2766 — unblock the repository-wide CI gates | wp1 | +| wp3 | 020 | Ingwannu remainder #2761, #2764, #2767 | wp2 | +| wp4 | 030 | Clean approved lane #2733, #2726, #2747 | wp2 | +| wp5 | 040 | Maintainer changes-requested #2745, #2729 | wp2 | +| wp6 | 050 | Contributor remainder #2740, #2693, #2638 | wp2, wp5 | +| wp7 | 060 | #2497 adjudication + round close-out | all | + +## Standing gates (inherited, all mandatory) + +1. Compile evidence comes from the MERGED tree, never the PR head alone. +2. Any two PRs touching a shared file get `git merge-tree` before either merges. +3. Green checks are not health unless the list includes `ci` / `test N/4` / + `macos`. **Corollary discovered this round: red checks are not harm until the + shared baseline is green.** +4. One `bun test` suite at a time; remove a stale + `/tmp/opencodex-bun-test.lock` rather than bypassing the queue. +5. Every lane travels a `codex/` branch and a PR targeting `dev`. +6. A safety net that exists in code is not a safety net that functions. + +## Accept criteria (mirrored into goalplan criteria[]) + +- c1 — all 13 PRs carry a recorded terminal disposition with SHA or reason. +- c2 — merged-tree compile gate ran for every candidate (this doc's table). +- c3 — each landed change carries a focused test receipt from the merged tree. +- c4 — `dev` advanced only through PRs targeting `dev`. +- c5 — auth/credential/OAuth surfaces are not landed autonomously. diff --git a/devlog/_plan/260827_igwanu_bug_pr_merge_round/010_phase1.md b/devlog/_plan/260827_igwanu_bug_pr_merge_round/010_phase1.md new file mode 100644 index 0000000000..0cbf8e39c3 --- /dev/null +++ b/devlog/_plan/260827_igwanu_bug_pr_merge_round/010_phase1.md @@ -0,0 +1,114 @@ +# 010 — wp2: the keystone, #2766 + +**Lane L1 (commit-then-merge). Every other MERGE in this round serializes behind +this one.** + +Precisely scoped: review, focused verification, rebases, and approval requests for +other PRs run in parallel — their changed paths are disjoint from this one's +(`package.json` plus a release-runbook document). What must wait is the act of +merging, because landing anything else first leaves `dev` sitting on known-red +release-version and privacy gates. + +PR #2766 `ingw/fix-release-doc-privacy-scan-2762` — head `076ad3036`, ready +(not draft), MERGEABLE, 0 commits behind `dev`, 30 checks with **zero failures**. +It is the only PR in the round whose matrix is already green, because it is the +one that repairs the matrix. + +## Why it is the keystone + +Two repository-wide gates went red after the v2.34.0 release train, and they fail +on `dev` itself, not on any contributor's code: + +1. `tests/release-version-line.test.ts` — `package.json` is `2.34.0` and tag + `v2.34.0` is published, so every commit after the tag "claims an + already-published version". Fails `ci`, `macos`, `test 3/4`. +2. `privacy:scan` — `devlog/_plan/260827_release_train/020_preview_release.md:36` + contains a literal scp-style SSH remote whose `user@host` principal the scanner + reads as an email address. Fails `gates`. + +Confirmed inherited by #2767, #2764, #2747. Merging anything else first means +reading a red matrix that says nothing about the PR under review. + +## MODIFY map (exact, already authored by the PR) + +MODIFY `package.json`: + +```diff +- "version": "2.34.0", ++ "version": "2.35.0", +``` + +MODIFY `devlog/_plan/260827_release_train/020_preview_release.md`: + +The runbook's push line is rewritten to build the destination from two shell +variables (`release_host=github.com`, `release_repo=lidge-jun/opencodex.git`) and +interpolate them, so the scp-style principal never appears as one literal token. +The exact diff is on the PR; it is not reproduced here, because quoting it +verbatim would reintroduce the very literal the scan rejects — this document is +itself scanned. + +The push destination is byte-identical after expansion and the deploy-key override +is preserved. This is documentation text, not executed release automation. + +## Security-boundary judgement (MAINTAINERS.md) + +The PR touches `package.json` version metadata and a release runbook document. +`AGENTS.md` flags release automation — `scripts/release.ts`, +`.github/workflows/release.yml` — for mandatory security review. **Neither file is +touched.** Verified: `release.yml` triggers on `workflow_dispatch` only, with an +explicit `version` input that must equal `package.json` and an immutable commit +input. A version bump on `dev` therefore cannot initiate a publish; a human +dispatch with an explicit version is required. + +Dependencies and lockfiles are unchanged, and no scheduled, push-triggered, +auto-merge, or version-keyed publish path exists: `release.yml` is +`workflow_dispatch`-only and additionally rejects any ref that is not `main` or +`preview`. A version bump on `dev` cannot publish. + +**It is still not unreviewed-autonomous.** +`.github/scripts/pr-sponsored-surface.cjs` lists `package.json` as a restricted +surface, and `MAINTAINERS.md` requires approval from at least one maintainer who +is not the author, plus explicit security review for release/package boundaries. +The PR body's unticked box says exactly this. + +A round-level instruction to "merge the bug PRs" is not the exact-head PR approval +that `MAINTAINERS.md` and GitHub require. **Approval gate: before merge, a +non-author maintainer approves #2766 at its exact head.** `Ingwannu` is the +author, so the approval must come from another maintainer account. Cannot be +self-satisfied and cannot be inferred from this document. + +## TESTS + +No new test. The behavior proof is that the two already-red repository gates turn +green, which is observable on the merged tree and on post-merge `dev` CI. + +## Verification (C) + +```bash +# merged tree already built as mtp/2766 +bun x tsc --noEmit # expect exit 0 +bun test tests/release-version-line.test.ts # expect 3 pass / 0 fail +bun run privacy:scan # expect exit 0 +``` + +Post-merge, the decisive evidence is the *next* PR's matrix: re-run CI on #2767 or +#2764 and confirm `ci`, `macos`, `test 3/4`, `gates` go green with no change to +their own diffs. That is the proof the keystone actually was the keystone. + +## Lane execution + +Ready, mergeable, green, 0 behind, targets `dev`, needs no rebase — so no +`codex/` branch is required. + +Merge sequence, in order, none skippable: + +1. Confirm the merged-tree receipts above. +2. **Obtain a non-author maintainer approval at the exact head `076ad3036`.** + `gh pr view 2766 --json reviewDecision` must read `APPROVED`, not + `REVIEW_REQUIRED`. +3. `gh pr merge 2766`. + +If step 2 cannot be satisfied in this round, #2766 exits as **NEEDS_HUMAN +(approval)** — and because it is the keystone, every PR gated behind it inherits +that outcome. That is a real possible terminal state for this round, not a +formality to route around. diff --git a/devlog/_plan/260827_igwanu_bug_pr_merge_round/011_wp1_outcome.md b/devlog/_plan/260827_igwanu_bug_pr_merge_round/011_wp1_outcome.md new file mode 100644 index 0000000000..f5fde1ac42 --- /dev/null +++ b/devlog/_plan/260827_igwanu_bug_pr_merge_round/011_wp1_outcome.md @@ -0,0 +1,104 @@ +# 011 — wp1 outcome: roadmap lock + +Docs-only cycle. No production code changed. Deliverable is the plan unit itself: +`000_plan.md` plus six decade docs, locked at `77635d8c9`. + +## A-gate: two independent Sol-high reviewers, four rounds + +| Round | Lane | Verdict | Result | +|---|---|---|---| +| r1 | facts | NEAR-PASS | 1 correction applied (`27b040931`) | +| r1 | judgement | **FAIL** | 2 blockers, both accepted | +| — | judgement re-verify | **FAIL** | 1 blocker incompletely closed | +| — | judgement re-verify | PASS | both closed | +| r2 | judgement confirm | PASS | rebound to the repaired files | + +### What the facts reviewer independently re-derived + +Re-ran `git merge-tree` for all 13 PRs from `dev@8b1b65b8d` and confirmed all 12 +clean tree hashes matched `mtp/^{tree}` exactly before typechecking, plus the +`#2497` conflict. Counted every changed path across all 13 PRs and confirmed the +contention map is exhaustive: `src/codex/auth-context.ts` (#2638, #2497) and +`src/server/responses/core.ts` (#2745, #2638, #2497), nothing else shared. + +Its correction: the plan had collapsed two distinct shared defects into one per-PR +line. `test 3/4` and `macos` fail on `release version line`; `gates` fails on +`privacy:scan`; `ci` is the fan-in. #2747 has no `gates` failure at all because +its head predates the runbook document. + +### What the judgement reviewer caught — the two that mattered + +**1. I violated this repository's own security rule.** The plan reproduced the +unfixed #2745 credential-boundary defect — mechanism, activation sequence, +remediation direction — inside `devlog/`, a public tracked directory, while the PR +is open. `AGENTS.md` §"Security working notes" forbids exactly that, and says so in +a section written because maintainer-authored triage had done it before. + +My error in reasoning: I treated the detail as publishable because the reviewer had +already written it in a public PR comment. But the rule keys on whether the **fix +has shipped**, not on where the analysis first appeared. An open PR means +pre-disclosure. + +The first repair was incomplete — the `TESTS` section still named the regression +design, which carries the activation shape without the prose. The reviewer caught +that too. Both are now in `.tmp/2745-security-triage.md` (gitignored, confirmed via +`git check-ignore`). + +**2. Every merge lane skipped the approval `MAINTAINERS.md` requires.** The plan +went from "CI green" straight to `gh pr merge`. `MAINTAINERS.md:57-59` requires +approval from at least one maintainer who is not the author, and +`.github/scripts/pr-sponsored-surface.cjs:52` lists `package.json` as a restricted +surface. All four Ingwannu PRs read `REVIEW_REQUIRED`. A round-level instruction +from the user is not an exact-head PR approval. + +It also refuted the release-safety framing as incomplete rather than wrong: no +scheduled, push-triggered, auto-merge, or version-keyed publish path exists +(`release.yml` is `workflow_dispatch`-only and rejects any ref that is not `main` +or `preview`), but `package.json` is still a restricted surface needing review. + +### Approval path, resolved + +The operator is authenticated as `lidge-jun` (`gh auth status`), listed in +`MAINTAINERS.md:10` as project owner. `Ingwannu` is a separate maintainer. A +`lidge-jun` approval of an Ingwannu-authored PR is therefore a valid non-author +maintainer approval, confirmed by the reviewer against `MAINTAINERS.md:57-59`. +The gate is satisfiable without self-approval. + +## Keystone verification (full suite, remote) + +`mtp/2766` pushed as `codex/mtp-2766-probe`, checked out on `lidge` +(`~/ocx-ci/opencodex`), full `bun run test` under `ocx-run`: + +``` +k2766: OK rc=0 finished 2026-08-28T00:25:04+09:00 +15334 pass / 0 fail +``` + +Focused, on the same merged tree: + +``` +tests/release-version-line.test.ts 3 pass / 0 fail +bun run privacy:scan Privacy scan passed (exit 0) +bun x tsc --noEmit exit 0 +``` + +On plain `dev` the same scan fails on the runbook literal, and the same test fails +repository-wide. The keystone claim is proven on both sides. + +## Gate honesty note + +The typecheck gate was verified rather than trusted: 12 merged trees compiling in +~12s looked like a no-op, so a deliberate `const x: number = "str"` was injected +into a merged worktree — `error TS2322`, exit 1. The speed is real; this repository +runs the native TypeScript 7.0.2 compiler at ~0.44s for a full typecheck. + +## Carried into wp2 + +1. Merge #2766 first; it is the only PR that can produce a trustworthy green + matrix for the others. Approval at exact head `076ad3036` before merge. +2. Review, rebase, and verification of other PRs may proceed in parallel — only + the merges serialize. +3. Follow-up outside this round's scope: the same pre-disclosure material exists + in `devlog/_plan/260826_wp7e_presence_driven_oauth_failover/` and + `devlog/_plan/260827_dev_hardening/`. Pre-existing, belongs to other active + work streams, needs separate authority. **Escalate; do not silently rewrite.** diff --git a/devlog/_plan/260827_igwanu_bug_pr_merge_round/020_phase2.md b/devlog/_plan/260827_igwanu_bug_pr_merge_round/020_phase2.md new file mode 100644 index 0000000000..e069d8d598 --- /dev/null +++ b/devlog/_plan/260827_igwanu_bug_pr_merge_round/020_phase2.md @@ -0,0 +1,99 @@ +# 020 — wp3: Ingwannu remainder — #2761, #2764, #2767 + +All three are Ingwannu's, all merge-tree CLEAN, all tsc OK on the merged tree. +Order within the phase: #2761 first (independent), then #2764 and #2767 after the +keystone turns their matrices green. + +**Approval gate for all three (`MAINTAINERS.md`).** All three are authored by +`Ingwannu` and all three currently read `REVIEW_REQUIRED` / `BLOCKED`. Authors do +not approve their own pull requests, and a round-level instruction is not an +exact-head approval. Each requires a non-author maintainer approval at its final +head — after rebase, where a rebase happens — before `gh pr merge`. Preparation, +verification, and review can proceed autonomously; the merge button cannot. + +## #2761 — fix(integrations): ignore JSON object key order in ownership + +Lane **L1**. Head `63941b583`, ready, MERGEABLE, 2 behind, **24 checks, zero +failures** — it predates the version-line breakage. Touches: + +- `src/integrations/ownership-policy.ts` (+29/-...) +- `src/integrations/ownership.ts`, `src/integrations/state.ts`, + `src/integrations/writer.ts` +- `structure/09_client-integrations.md` (architecture note) +- `tests/integrations-state.test.ts` (+41), `tests/integrations-writer.test.ts` (+64) + +No file overlaps any other in-scope PR. No auth, credential, or workflow surface. +Carries its own regressions. + +Test oracle verified load-bearing: with the PR's tests kept and only its +production implementation reverted, the suite fails behaviorally at +`tests/integrations-writer.test.ts:286` and `:314` (92 pass / 0 fail with the fix). +These are not source-text assertions and the PR changes no fixture. + +**Merge once** the merged-tree focused suite is green **and** a non-author +maintainer approval is recorded at the exact head. No rebase needed (2 behind). + +## #2764 — fix(moonshot): intersect nested schema bounds + +Lane **L1, gated on wp2**. Head `30247541f`, draft, 0 behind, merge CLEAN, tsc OK. +Currently red on `ci`/`gates`/`macos`/`test 3/4` — **all four from the two shared +repository-wide defects, none from its own code**, split precisely: + +- `test 3/4` and `macos`: `1 fail` each, and that one fail is + `release version line`. +- `gates`: `privacy:scan` on the release-runbook SSH literal. +- `ci`: the fan-in over test / gates / platform-macos, so it reports no failure + of its own. + +Its own suite passes. #2766 repairs both defects, which is why one keystone clears +all four jobs. + +Touches `src/adapters/openai-chat.ts`, `structure/04_transports-and-sidecars.md`, +`tests/moonshot-tool-schema.test.ts`. `openai-chat.ts` is touched by no other +in-scope PR this round. + +Draft checklist has one unticked box: "Exact-head required CI is green." That box +cannot be ticked by the author — it is false for a reason outside the PR. After +wp2 lands, rebase onto the new `dev`, re-run CI, and the box becomes truthfully +tickable. Then mark ready, **obtain the non-author maintainer approval at that +new head**, and merge. + +## #2767 — fix(openai): strip unsupported forward cache options + +Lane **L1, gated on wp2**. Head `33586cdf7`, draft, 0 behind, merge CLEAN, tsc OK. +Identical CI situation to #2764, job for job: `test 3/4` and `macos` each fail +once on `release version line`, `gates` fails on the `privacy:scan` runbook +literal, and `ci` is the fan-in. + +Touches `src/adapters/openai-responses.ts`, `src/compatibility/openai-responses.ts`, +`structure/08_openai-provider-tiers.md`, +`tests/fixtures/compatibility/openai-codex-forward-gpt56-sol-v1.json`, +`tests/openai-responses-passthrough.test.ts`. + +Its unticked box reads "Exact-head required CI is green after the independent base +gate repair" — the author already diagnosed the dependency correctly. Same +treatment as #2764, including the non-author approval at the post-rebase head. + +**Fixture caution (previous round's finding):** a regenerated fixture once +resurrected a deliberately removed model behind a count-only assertion. This PR +adds a compatibility fixture, so the review must confirm the fixture's contents +are asserted by field, not merely by count. + +## TESTS + +- #2761: `tests/integrations-state.test.ts`, `tests/integrations-writer.test.ts` +- #2764: `tests/moonshot-tool-schema.test.ts` +- #2767: `tests/openai-responses-passthrough.test.ts` + +## Verification (C) + +```bash +bun test tests/integrations-state.test.ts tests/integrations-writer.test.ts +bun test tests/moonshot-tool-schema.test.ts +bun test tests/openai-responses-passthrough.test.ts +bun x tsc --noEmit +``` + +Each on its own merged tree, one suite at a time (machine-wide lock). For #2764 +and #2767 the decisive extra evidence is exact-head CI **after** the rebase onto +post-#2766 `dev`: `ci`, `macos`, `test 3/4`, `gates` must all be green. diff --git a/devlog/_plan/260827_igwanu_bug_pr_merge_round/021_wp2_outcome.md b/devlog/_plan/260827_igwanu_bug_pr_merge_round/021_wp2_outcome.md new file mode 100644 index 0000000000..9134a1124f --- /dev/null +++ b/devlog/_plan/260827_igwanu_bug_pr_merge_round/021_wp2_outcome.md @@ -0,0 +1,103 @@ +# 021 — wp2 outcome: keystone landed, hypothesis proven + +`dev` advanced `8b1b65b8d` -> `50e955604`. Six PRs merged. + +| PR | lane | merge commit | evidence | +|---|---|---|---| +| #2766 | L1 keystone | `913f844ef` | full suite 15334/0 on merged tree | +| #2733 | L1 | `ae5d3993c` | approved, clean, mutation-verified oracle | +| #2726 | L1 | `0821ce951` | approved, clean, mutation-verified oracle | +| #2761 | L1 | `d1def682d` | approved by me at exact head, 92/0 focused | +| #2764 | L1 | `3b5302410` | rebased, 26 green / 0 fail, no diff change | +| #2767 | L1 | `50e955604` | rebased, 26 green / 0 fail, no diff change | + +## The keystone claim was proven, not assumed + +wp1 predicted that #2767, #2764 and #2747 were red for a reason that had nothing +to do with their code. That is a falsifiable claim, and this phase ran the +experiment rather than asserting the conclusion — but the experiment actually ran +on only two of the three. See "#2747 is not part of the proof" below. + +Before: each showed `test 3/4` and `macos` failing with exactly `1 fail`, and that +one failure was `release version line`; `gates` failed on `privacy:scan`; `ci` was +the fan-in over both. + +The intervention was controlled. #2766 merged, then #2764 and #2767 were rebased +onto the new `dev` **with no change to their own diffs** — verified by diffing the +rebased head against the old head and confirming the only delta was #2766's own +two files. + +After: **26 success, 0 failures** on both. Patch identity survives the rebase — +`7d644cbafe221eea27fa1369b07cc048a7461d5f` for #2764 and +`719d0d986d1dbb370919e8c15ff4a236d5b4c2de` for #2767 — and restricting the +comparison to either PR's own changed paths yields an empty diff. + +One PR changed a version string and a documentation line, and four required jobs +on **two** unrelated PRs went green. Had the round merged in author order or +"cleanest first", both would have been re-run, re-diagnosed, or bounced back to +their author for a defect neither had. + +### #2747 is not part of the proof + +It carries the same failure signature, but it never went green, and an earlier +draft of this document implied otherwise. + +`gh run rerun --failed` re-runs the **same commit**. Run `33059606933` attempt 4 +completed `failure`, with `macos` still reporting the `2.34.0` / `v2.34.0` +collision and `ci` failing as its fan-in. A re-run cannot pick up a new base — +only a rebase can, and this PR's head lives on a contributor's fork. + +That run was already terminal and red about 70 seconds before this document was +first committed, so "in flight" was wrong when written, not merely overtaken by +events. The correct status is **diagnosed, awaiting an author rebase**, requested +on the PR with the #2764/#2767 result attached as evidence. + +The lesson generalizes past this round: a re-run tests the same tree twice. When +the fix landed somewhere else, only a rebase moves the evidence. + +## What the round would have gotten wrong without the A gate + +The plan as first written would have merged #2766 without the non-author approval +`MAINTAINERS.md` requires, on the reasoning that a user instruction to run the +round supplied it. The reviewer refused that, correctly: a round-level instruction +is not an exact-head PR approval, and `package.json` is a restricted surface per +`.github/scripts/pr-sponsored-surface.cjs`. + +The gate turned out to be satisfiable — the operator authenticates as +`lidge-jun`, project owner, and every one of these PRs was authored by +`Ingwannu` or a community contributor, so no approval was a self-approval. Each +approval names the exact head it applies to and the evidence behind it. (#2766 +carries two approval events, submitted 15 seconds apart at `15:27:49Z` and +`15:28:04Z`; both target the merged head and the latest is the effective one.) + +That is the difference between a gate being satisfied and a gate being skipped, +and from the outside the merge log would look identical either way. + +## #2747: a choice, not a constraint + +#2747's head is on `olddonkey`'s fork. My first attempt pushed the rebase to +`origin` and created a same-named branch there instead of updating the PR; it was +deleted as soon as it was observed (`git push origin --delete`, confirmed `0` +remaining refs). + +My second attempt, `gh run rerun --failed`, could not work either — it replays the +same commit, so it re-tested the same unrepaired tree and came back red. + +**A first draft of this section then claimed rewriting the contributor's branch +was "not available". That is false.** GitHub reports `maintainerCanModify: true` +for this PR, so a maintainer push to the fork branch was available the whole time. + +The accurate statement is that I *chose* not to take it. Force-pushing a rebase +onto a contributor's branch rewrites work they own, silently, on a PR whose only +problem was a defect in our base — so I requested the rebase on the PR instead, +with the #2764/#2767 result attached as evidence that the failure was never +theirs. That is a judgement about contributor ownership, and it should be +recorded as one rather than dressed up as a technical limit. + +## Carried into wp3 + +Seven bug PRs remain: #2747 (approved; blocked on an author rebase, not on its +own code), #2745, #2740, #2729, #2693, #2638, #2497. Three of those (#2745, +#2638, #2497) are the credential/OAuth surface and share +`src/server/responses/core.ts`; pairwise `git merge-tree` is mandatory before any +second one of them lands. diff --git a/devlog/_plan/260827_igwanu_bug_pr_merge_round/030_phase3.md b/devlog/_plan/260827_igwanu_bug_pr_merge_round/030_phase3.md new file mode 100644 index 0000000000..f95afb086d --- /dev/null +++ b/devlog/_plan/260827_igwanu_bug_pr_merge_round/030_phase3.md @@ -0,0 +1,83 @@ +# 030 — wp4: clean approved lane — #2733, #2726, #2747 + +## #2733 — fix(cli): neutralize usage report terminal controls + +Lane **L1**. Head `2a0ab4be6`, ready, **MERGEABLE/CLEAN**, **APPROVED**, +24 checks zero failures, 43 behind. `luvs01`. Labels: `bug`, `review-ready`. + +Touches `src/cli/usage-report.ts` (+15/-2) and `tests/cli-usage-report.test.ts` +(+25). This is terminal-escape-sequence neutralization in a report renderer — a +control-character injection fix. No overlap with any in-scope PR. + +Cleanest merge in the round: approved, clean, green, with its own regression. + +Test oracle verified load-bearing by mutation: tests kept, production fix reverted +-> 12 pass / 1 fail at `tests/cli-usage-report.test.ts:78` (raw ESC survives into +output). With the fix, 13 pass / 0 fail. No fixture involved. + +**Merge as-is** — this one already carries a non-author `APPROVED` decision, so +the `MAINTAINERS.md` approval requirement is satisfied on the record rather than +by assertion. + +## #2726 — fix(xai): normalize web search on the Grok CLI proxy + +Lane **L1**. Head `790a581cf`, ready, **MERGEABLE/CLEAN**, **APPROVED**, +24 checks zero failures, 63 behind. `olddonkey`. Labels: `bug`, `review-ready`. + +Touches `src/adapters/xai-web-search.ts` (+24/-...), +`tests/responses-routed-web-search-fields.test.ts`, +`tests/xai-web-search-compat.test.ts` (+44). No overlap. + +Test oracle verified load-bearing by mutation: tests kept, production fix reverted +-> 14 pass / 2 fail at `tests/responses-routed-web-search-fields.test.ts:235` and +`tests/xai-web-search-compat.test.ts:148`. With the fix, 16 pass / 0 fail. + +The diff replaces an `api.x.ai`-only host check with `isXaiResponsesDestination`, +widening normalization to the Grok CLI proxy (the OAuth lane). The PR documents a +2026-08-27 re-probe of `cli-chat-proxy.grok.com` showing the same dialect. Treat +that probe as the author's claim, not as verified fact — the previous round was +burned by exactly this kind of cited-but-unverified provenance. The live smoke +below is what actually settles it. + +**Merge as-is** — carries a non-author `APPROVED` decision. + +Note: `xai` is this operator's default provider (`defaultProvider: xai`), so this +one is worth a live smoke after landing rather than test-only evidence. + +## #2747 — fix(tests): reap the recovery proxy instead of trusting `stop` + +Lane **L1, gated on wp2**. Head `07b97587`, ready, MERGEABLE, 26 behind, +labels `bug`, `review-ready`. Failing `ci` and `macos`. + +The `macos` job (run `33059606933`, job `98534630924`) fails on +`release version line` — the shared baseline, again. The `ci` job fails with +`needed job(s) did not pass`, i.e. it is a fan-in that inherits the same failure. +Unlike #2764 and #2767, #2747's `gates` job is green: its head predates the +release-runbook document that trips `privacy:scan`. Version line only. + +Touches exactly one file: `tests/update-stop-first.test.ts` (+46/-18). Test-only, +no `src/` change, no overlap. This is the causal repair of a flaky test — it reaps +the recovery proxy process instead of trusting `stop` to have ended it, which is +exactly the "find the causal issue, don't rerun until green" discipline. + +After wp2, re-run CI; expect green with no diff change. + +## TESTS + +- #2733: `tests/cli-usage-report.test.ts` +- #2726: `tests/xai-web-search-compat.test.ts`, + `tests/responses-routed-web-search-fields.test.ts` +- #2747: `tests/update-stop-first.test.ts` (the PR *is* the test) + +## Verification (C) + +```bash +bun test tests/cli-usage-report.test.ts +bun test tests/xai-web-search-compat.test.ts tests/responses-routed-web-search-fields.test.ts +bun test tests/update-stop-first.test.ts +bun x tsc --noEmit +``` + +#2747 additionally needs the run repeated to show the reap actually removes the +orphan: a single green pass on a formerly-flaky test is weak evidence. Run it +3x and confirm no leaked proxy process survives. diff --git a/devlog/_plan/260827_igwanu_bug_pr_merge_round/040_phase4.md b/devlog/_plan/260827_igwanu_bug_pr_merge_round/040_phase4.md new file mode 100644 index 0000000000..c7872636a2 --- /dev/null +++ b/devlog/_plan/260827_igwanu_bug_pr_merge_round/040_phase4.md @@ -0,0 +1,87 @@ +# 040 — wp5: maintainer changes-requested — #2745, #2729 + +Both are authored by `lidge-jun` (the maintainer) and both carry a detailed +CHANGES_REQUESTED review from Ingwannu naming specific, reproducible defects. +Neither may merge as-is. Lane **L4 (fix-then-land)** for both. + +## #2745 — fix(responses): rebind credential identity on every OAuth 429 rotation + +Head `a90ab6ee7`, ready, MERGEABLE, 26 behind, 24 checks zero failures. +Touches `src/server/responses/core.ts` (+55/-11) and +`tests/generic-oauth-failover.test.ts` (+78). + +**This is an OAuth credential-boundary change — the exact surface `MAINTAINERS.md` +requires explicit security review for.** It does not land on my judgement alone. + +The PR carries a CHANGES_REQUESTED review with two open blockers: one credential +-boundary correctness defect and one test-oracle defect. **That analysis is +pre-disclosure material and is deliberately not reproduced here.** `devlog/` is a +public tracked directory, the defect is unfixed, and the PR is open, so per +`AGENTS.md` §"Security working notes" the reasoning, reproduction, and +remediation plan live in scratch (`.tmp/2745-security-triage.md`, gitignored) and +are readable on the PR itself via `gh pr view 2745 --json reviews`. Once the fix +ships, the write-up belongs in `_fin/` — not before. + +`src/server/responses/core.ts` is also touched by #2638 and #2497 — +`git merge-tree` pairwise before a second one lands. + +Disposition: **NEEDS_HUMAN.** Both blockers must be closed by the author, and the +credential-boundary change then needs explicit human security sign-off plus a +non-author maintainer approval at the exact merged head. Not landed this round. + +## #2729 — fix(claude): derive response.failed status from the classified error + +Head `19801d201`, ready, MERGEABLE, 89 behind, 24 checks zero failures. +Touches `src/adapters/cursor/cursor-errors.ts` (+8), `src/claude/outbound.ts` +(+17/-3), `tests/claude-outbound.test.ts` (+73), `tests/cursor-errors.test.ts` (+10). + +Reviewer accepts the main diagnosis (Cursor `failed_precondition -> 400` is +correct, 157/157 across eight suites) but found one **error-fidelity regression**: + +`httpStatusFromTerminalError` recognizes only `server_error + server_is_overloaded` +before falling through to message inference. A status-less envelope like +`{type:"server_error", code:"upstream_server_error", message:"...malformed tool +call arguments"}` returns **400** because the message contains "malformed". +Before this PR it became a transient 500. Result: Claude Code receives +`invalid_request_error` and **stops retrying a genuine upstream failure**. The +reviewer probed the exact head and got 400. + +Fix: structured generic server classifications must win over message keywords — +map `server_error`/`upstream_server_error` and equivalent generic upstream codes to +transient 5xx, while retaining the specific 429/401/403/invalid-request/policy/ +cancellation/explicit-overload mappings. Add a status-less regression using a +server-classified message containing an invalid-request keyword, asserting the +Anthropic tail stays `overloaded_error`. + +Deferred, not blockers: the dead `translation_buffer_limit` status arm; loss of +the original error code. + +No authentication decision, credential state, token, OAuth, or account-routing +surface. It maps already-classified upstream error envelopes to HTTP status codes; +the 401/403 arms propagate a classification rather than making an auth decision. +That is why it sits on a different side of the line from #2745, #2638 and #2497, +which touch OAuth snapshots, account selection, credential fencing, and bearer or +refresh-token handling respectively. + +This one can be prepared autonomously once the fix and regression are in and the +merged-tree suite is green, and then merged **after a non-author maintainer +approval at the exact head** (`MAINTAINERS.md`: authors do not approve their own +pull requests). + +## TESTS + +- #2745: `tests/generic-oauth-failover.test.ts` — the required test work is + recorded with the rest of the pre-disclosure triage in scratch, not here. +- #2729: `tests/claude-outbound.test.ts` — add the status-less + `upstream_server_error` case asserting a transient 5xx tail. + +## Verification (C) + +```bash +bun test tests/generic-oauth-failover.test.ts +bun test tests/claude-outbound.test.ts tests/cursor-errors.test.ts +bun x tsc --noEmit +``` + +For #2729 the load-bearing proof is the new negative case failing on `dev` without +the fix and passing with it. diff --git a/devlog/_plan/260827_igwanu_bug_pr_merge_round/041_wp2b_2729_supersede.md b/devlog/_plan/260827_igwanu_bug_pr_merge_round/041_wp2b_2729_supersede.md new file mode 100644 index 0000000000..e71f204264 --- /dev/null +++ b/devlog/_plan/260827_igwanu_bug_pr_merge_round/041_wp2b_2729_supersede.md @@ -0,0 +1,175 @@ +# 041 — #2729 superseded by #2769, and what the blocker actually was + +#2729's diagnosis was right and its review was right, and the two facts compose +into something neither states alone. + +## The defect #2729 fixed + +Internal `response.failed` envelopes carry the classified `{type, code, message}` +but no numeric status, so every classified failure was flattened into a retryable +`overloaded_error`. A Cursor plan/quota 429 reached Claude Code as "Repeated 529 +Overloaded errors". Deriving the status from the classified payload is correct. + +## The blocker: the derivation only helps if the classification wins + +`httpStatusFromTerminalError` recognized a structured server class for exactly one +code pair — `server_error` + `server_is_overloaded` — and let everything else fall +through to message inference. Reproduced against `origin/dev`: + +``` +{type:"server_error", code:"upstream_server_error", + message:"upstream stream produced malformed tool call arguments"} -> 400 +``` + +Claude Code receives `invalid_request_error` and stops retrying a retryable +upstream failure. That is #2729's own inversion, one layer down: it fixed masking +at the envelope boundary while the status function kept masking underneath. + +`classifyError` assigns `upstream_server_error` to **every** 5xx it observes, so +the class is authoritative about blame. + +## What I got wrong, and what caught it + +My first fix returned a blanket 502 for any structured server class. Nine focused +suites passed — 210/0 — and it was still wrong. + +Exact-head CI failed `test 1/4` and `test 4/4`. The cause: +`tests/web-search-timeout-contract.test.ts` asserts `status: 504` for a stalled +routed body, because a stall genuinely **is** a gateway timeout. A blanket 502 +flattens 504 and 503 into a less specific status, discarding information the log +surface and the retry policy both read. + +The classification is authoritative about **blame**, not about which server status +fits. So the override narrowed to the single verdict that both blames the caller +and stops the retry: **400 only**. 429, 499, 401 and 403 are left alone — each is +a signal the caller routes on, and overriding them trades one misreport for +another. + +Final differential against `origin/dev` — exactly two cases move: + +| case | before | after | +|---|---|---| +| `upstream_server_error` + "malformed" | 400 | **502** | +| `upstream_server_error` + "invalid request" | 400 | **502** | +| web-search stall | 504 | 504 | +| "temporarily unavailable" | 503 | 503 | +| rate-limit text under server class | 429 | 429 | +| client close under server class | 499 | 499 | +| cyber-policy by message | 400 | 400 | +| auth / permission text under server class | 401 / 403 | 401 / 403 | +| real `invalid_request_error` | 400 | 400 | +| `proxy_error` / no message | 500 / 502 | 500 / 502 | + +## The transferable finding + +**Nine green focused suites did not catch a defect that one CI shard caught +immediately.** The focused suites covered the function I changed; the failure was +in a suite that consumes it. Scoping tests to the changed file is exactly how a +blast-radius defect hides — the previous round's lesson was that green checks are +not health, and this is its sharper form: green *targeted* checks are not health +either, because you chose the targets. + +What made it cheap to recover was the differential probe. Enumerating every arm +before and after, against unpatched `dev`, turns "did I break something" from a +hope into a table. + +## Evidence + +``` +remote full suite (ocx-run e2769b on lidge) 15349 pass / 0 fail, rc=0 +nine consuming focused suites 210 pass / 0 fail +bun x tsc --noEmit exit 0 +mutation oracle (revert fix, keep test) 45 pass / 1 fail +mutation oracle (with fix) 46 pass / 0 fail +``` + +One macOS CI failure remains **unattributed**: +`CL-07 task effectiveness producer > inactivity timeout is bounded for trusted +route executors`, a wall-clock test in `src/lab/`. It failed once at `2483f4047` +(15352 pass / 1 fail) and passed on re-run (15353 / 0). + +An earlier draft called it pre-existing flakiness on two claims, and the final +auditor disproved both: + +- "references nothing in the changed path" — false. The import chain is + `tests/lab-fabric-task.test.ts` -> `src/lab/index.ts` -> + `observe/from-conformance.ts` -> `conformance/executor.ts` -> + `src/claude/outbound.ts` -> `src/lib/errors.ts`. That does not prove causation, + but it removes the argument I was leaning on. +- "a clean dev merge failed the same day on another macOS timing test" — false. + `d1def682d` failed on **Linux** `test 2/4`, in `shutdown-launcher.test.ts`. + +Neither failure reproduces locally (5/5 and 47/0 at both the PR head and clean +`dev`), so it is not proven a regression either. The honest label is +**unattributed**, and it is recorded that way on purpose: "it was flaky" is the +claim this repository's standing gates exist to distrust, and I reached for it +with two facts that did not hold. + +## Then the arm itself turned out not to fire + +The final audit also found that #2729's `failed_precondition` branch did not +trigger on the shape it exists to catch. It sat **after** the overload keywords in +both `classifyCursorError` and `inferHttpStatusFromAdapterMessage`, and a +plan-gated rejection normally reads `failed_precondition: model unavailable for +this plan` — which matches `unavailable` first: + +``` +classifyCursorError -> "Cursor server overloaded" +inferHttpStatusFromAdapterMessage -> 503 +``` + +So clients retried a deterministic rejection that can never succeed. The original +test covered only `"Cursor Connect error failed_precondition: Error"`, which +carries no competing keyword, and 25/25 passed straight over the defect. + +Fixed by moving the check ahead of the overload keywords in both functions: the +explicit gRPC status is a structured backend signal, while `unavailable` and +`temporarily` beside it are inference over free text. + +Differential against `origin/dev`: **the whole failed-precondition class moves to +400**, not a single case. Constructible inputs that change: + +``` +failed_precondition + "unavailable" 503 -> 400 +failed_precondition + "temporarily" 503 -> 400 +"failed precondition" + "overloaded" 503 -> 400 +bare failed_precondition 502 -> 400 +``` + +The non-precondition controls are unchanged: real overload 503, authentication +401, rate limit 429, timeout 504, invalid request 400. + +(An earlier draft said "exactly one case moves". That was the sample I happened to +probe, not the size of the change — the correct framing is a class, and describing +a class by one member is how a differential stops being evidence.) + +**This is the third time in one PR that a fix was correct in principle and wrong +in precedence** — the envelope masking, my blanket 502, and now this. The pattern +is the same each time: a new rule was added without checking what already ran +before it. A keyword table is an ordered program, not a set. +## The approval gate is not satisfiable here, and that is correct + +#2769 cannot be merged by me. GitHub refuses the review outright: + +``` +failed to create review: GraphQL: Review Can not approve your own pull request +``` + +The four Ingwannu PRs earlier in this round were approvable because `Ingwannu` +authored them and `lidge-jun` approved — two different maintainers. Here I both +authored the branch and hold the only maintainer session, so `MAINTAINERS.md` +§"Authors do not approve their own pull requests" bites, and it is enforced by +the platform rather than by discipline. + +That is the correct outcome. The alternative — a maintainer writing a fix to an +error-classification path and merging it on their own say-so — is exactly what +the rule exists to prevent, and the fact that the fix is well-evidenced does not +change who checked it. The evidence is posted on the PR as a comment so a second +maintainer can act on it. + +**Disposition: #2729 CLOSED-SUPERSEDED by #2769; #2769 is NEEDS_HUMAN (non-author +approval).** As of head `16cb875b8`: 211 pass / 0 fail across the ten affected +suites, `tsc` exit 0, mutation oracle held, and the precedence defect above fixed +with its own regression. An earlier draft claimed approval was the *only* missing +gate while that defect was still open — it was not, and the claim is corrected +here rather than quietly dropped. diff --git a/devlog/_plan/260827_igwanu_bug_pr_merge_round/050_phase5.md b/devlog/_plan/260827_igwanu_bug_pr_merge_round/050_phase5.md new file mode 100644 index 0000000000..11089176f7 --- /dev/null +++ b/devlog/_plan/260827_igwanu_bug_pr_merge_round/050_phase5.md @@ -0,0 +1,90 @@ +# 050 — wp6: contributor remainder — #2740, #2693, #2638 + +## #2740 — fix(storage): atomically commit cleanup run metadata + +Lane **L1**. Head `f07ee36f2`, draft, MERGEABLE, 26 behind, merge CLEAN, tsc OK. +`luvs01`. Only **5 checks** — no `ci`/`test`/`macos` at all, so it has never been +compiled or tested by CI. The merged-tree gate in 000 is its first real evidence. + +Touches `src/storage/policy-job.ts` (+18), `src/storage/policy.ts` (+111/-27), +`structure/02_config-and-config-and-codex-home.md` architecture note, and adds +`tests/storage-policy-config-race.test.ts` (+150). No overlap with any in-scope PR. + +A metadata write race fixed by atomic commit, with a dedicated race regression. +Needs: the merged-tree focused suite, and confirmation the new test actually fails +without the fix (a race test that passes both ways proves nothing). Then flip +draft -> ready and merge. + +## #2693 — fix(google-antigravity): skip_thought_signature_validator fallback + +Lane **L4 (author must fix)**. Head `8775d77d6`, draft, 118 behind, merge CLEAN, +tsc OK, 5 checks only. CHANGES_REQUESTED with three reproduced blockers: + +1. `src/adapters/google-antigravity-replay.ts:758-770, 811-837` treats mere + *presence* of `thoughtSignature`/`thought_signature` as a valid turn signature + instead of the existing `extractSignature()` contract, and sets + `turnHasSignature` when any *later* sibling gets a cached signature. Reviewer + reproduced a two-call turn where the first call ends up completely unsigned and + the required first-call sentinel is skipped. +2. The same presence check mishandles wire shapes the module already supports: a + valid nested `extra_content.google.thought_signature` gets a *competing* direct + sentinel added, and a direct short invalid value (`"short"`) suppresses fallback + entirely. +3. `antigravityUsesReplayCache()` accepts every non-Claude model including + `gpt-oss-120b-medium`, so the unconditional fallback injects a **Gemini-only + sentinel into a non-Gemini model** — reproduced. + +Plus a non-blocking test defect: the unknown-version snapshot test reuses the +object mutated by the corrupt-snapshot call, so its second assertion is not +load-bearing. + +This is a correctness rewrite of the PR's core logic, not a touch-up. The previous +round already recorded #2693 as BLOCKED. Disposition: keep as a **draft awaiting +author revision**, with the three blockers already posted. Re-verify the review is +still current against `dev @ 8b1b65b8d` and confirm the ask is unambiguous. + +## #2638 — fix(codex): close drain routing follow-ups + +Lane **NEEDS_HUMAN**. Head `b0f328462`, draft, **179 behind**, merge CLEAN +textually, tsc OK, 5 checks with `enforce-target` and `hygiene` FAILING. + +1341 insertions across `src/codex/auth-context.ts`, `src/codex/routing.ts` (+334), +`src/codex/subagent-model-fallback.ts` (+86), `src/server/responses/core.ts` (+78) +and three test files. + +This is the **request/auth-routing boundary**. The reviewer's position is explicit +and correct: `src/server/responses/core.ts` is modified both by this PR and by the +intervening 179-commit `dev` range, so *GitHub's textual mergeability is not +evidence the combined behavior is still correct*. The reviewer asks that +`maintainer-sponsored` NOT be applied and the waiting fork workflows NOT be +approved until a rebase onto current `dev`. + +It also touches `src/server/responses/core.ts` alongside #2745 and #2497 — the +round's hottest contention point. + +Disposition: **NEEDS_HUMAN**. Author rebase required first; security sponsorship +is a human decision. Do not land in this round. + +## TESTS + +- #2740: `tests/storage-policy-config-race.test.ts` — must be shown red without + the fix. +- #2693: `tests/google-antigravity-replay.test.ts` — needs the two wire-shape + regressions and a fresh unsigned payload for the version-99 branch. +- #2638: `tests/codex-routing.test.ts`, `tests/codex-auth-context.test.ts`, + `tests/subagent-fallback-handle-responses.test.ts` — only meaningful after rebase. + +## Verification (C) + +```bash +bun test tests/storage-policy-config-race.test.ts +bun x tsc --noEmit +``` + +Only #2740 is verified-to-land in this phase. #2693 and #2638 exit with a recorded +non-merge disposition and the specific unblocking condition stated on the PR. + +**Do not reach into `src/lab/` and do not add an `await` between `Bun.serve` and +the `labActivationRequired` check** — #2638 touches `core.ts` and +`subagent-model-fallback.ts`, exactly the synchronous subagent-fallback chain +`AGENTS.md` protects. diff --git a/devlog/_plan/260827_igwanu_bug_pr_merge_round/060_phase6.md b/devlog/_plan/260827_igwanu_bug_pr_merge_round/060_phase6.md new file mode 100644 index 0000000000..d5d8a18baa --- /dev/null +++ b/devlog/_plan/260827_igwanu_bug_pr_merge_round/060_phase6.md @@ -0,0 +1,63 @@ +# 060 — wp7: #2497 adjudication and round close-out + +## #2497 — Fix native main token refresh and replay + +Lane **NEEDS_HUMAN**. Head `86a49e852`, draft, **CONFLICTING/DIRTY**, +**386 commits behind dev**, 5 checks with `enforce-target` and `hygiene` failing. +Author `MarcTCruz`. + +The only PR in the round whose merge-tree **conflicts**, so no merged-tree compile +evidence exists or can exist without a human-authored rebase. + +20 files: `src/codex/account-store.ts`, `account-usability.ts`, `auth-context.ts`, +`main-account.ts`, `model-entitlements.ts`, `src/config/atomic-write.ts`, +`src/lib/test-home-guard.ts`, **`src/oauth/chatgpt.ts`**, `src/routing/analytics.ts`, +`src/server/responses/codex-auth-error.ts`, `compact.ts`, **`core.ts`**, +`src/usage/log.ts`, plus seven test files. + +Two disqualifying conditions, either sufficient alone: + +1. **Security surface.** OAuth token refresh and replay, `src/oauth/chatgpt.ts`, + the account store, auth-error handling. `MAINTAINERS.md` requires explicit + security review; `AGENTS.md` names credential/token handling and OAuth flows as + release-blocker-class triggers. +2. **386 commits of drift with a real conflict**, on files (`core.ts`, + `auth-context.ts`) that `dev` changed in that window. Resolving those conflicts + myself means rewriting an OAuth refresh path on the author's behalf and then + reviewing my own credential-handling code. + +This matches the previous round's disposition and nothing has improved since — it +has drifted further. + +Disposition: **NEEDS_HUMAN**, recorded with the unblocking condition — author +rebase onto current `dev`, then human security review of the refresh/replay path. + +## Round close-out + +Produce `070_outcome.md` with the final disposition table: PR, lane, terminal +state, merge SHA or explicit reason. Every row cites evidence that exists now. + +```bash +git fetch origin && git log --oneline origin/dev | head -20 +git rev-parse dev origin/dev # must be equal +gh pr list --repo lidge-jun/opencodex --state open --label bug +bun x tsc --noEmit +``` + +Plus the keystone proof: a PR red on `ci`/`macos`/`test 3/4`/`gates` before wp2 +is green afterwards with no change to its own diff. + +## Criteria mapping + +- c1 — the 070 table covers all 13. +- c2 — the 000 merged-tree table plus the tsc-probe verification. +- c3 — per-PR focused receipts recorded in each phase doc. +- c4 — `git log origin/dev` shows only merge commits from PRs targeting `dev`. +- c5 — #2745, #2638, #2497 carry named security-review reasons, not silent skips. + +## Honest terminal outcome + +This round will not end with 13 merges. Three PRs (#2693, #2638, #2497) require +author or human action that no autonomous work substitutes for. The round is DONE +when each of the 13 has a recorded, evidenced disposition — which is what the goal +states — not when the open-PR count reaches zero. diff --git a/devlog/_plan/260827_igwanu_bug_pr_merge_round/070_outcome.md b/devlog/_plan/260827_igwanu_bug_pr_merge_round/070_outcome.md new file mode 100644 index 0000000000..635eae70a7 --- /dev/null +++ b/devlog/_plan/260827_igwanu_bug_pr_merge_round/070_outcome.md @@ -0,0 +1,116 @@ +# 070 — round outcome + +`dev` advanced `8b1b65b8d` -> `50e955604`, entirely through PRs targeting `dev`. +Six merges, no direct commit (verified: first-parent count 6, no-merges count 0). + +## Disposition of all 13 bug PRs + +| PR | author | lane | terminal state | evidence | +|---|---|---|---|---| +| #2766 | Ingwannu | L1 keystone | **MERGED** | `913f844ef`; full suite 15334/0 on merged tree | +| #2733 | luvs01 | L1 | **MERGED** | `ae5d3993c`; mutation oracle 12/1 without fix | +| #2726 | olddonkey | L1 | **MERGED** | `0821ce951`; mutation oracle 14/2 without fix | +| #2761 | Ingwannu | L1 | **MERGED** | `d1def682d`; 92/0 focused, oracle at writer.ts:286,:314 | +| #2764 | Ingwannu | L1 | **MERGED** | `3b5302410`; rebased, patch ID unchanged, 26 green | +| #2767 | Ingwannu | L1 | **MERGED** | `50e955604`; rebased, patch ID unchanged, 26 green | +| #2729 | lidge-jun | L4 | **CLOSED-SUPERSEDED** | by #2769; patch IDs match exactly | +| #2769 | lidge-jun | L4 | **NEEDS_HUMAN** (approval) | head `16cb875b8`: CI 23 green / 0 fail, full suite 15350/0; self-approval refused | +| #2747 | olddonkey | L1 | **NEEDS_AUTHOR** (rebase) | approved; fork head, rerun cannot move base | +| #2740 | luvs01 | L1 | **NEEDS_AUTHOR** (ready+rebase) | reviewed, oracle 2/0 vs 0/2, tsc 0 | +| #2693 | yxr1995-maker | L4 | **BLOCKED** (author) | 3 reproduced blockers stand, 131 behind | +| #2638 | luvs01 | L4 | **NEEDS_HUMAN** (security) | auth/routing boundary, 192 behind | +| #2497 | MarcTCruz | L4 | **NEEDS_HUMAN** (security) | OAuth refresh, 399 behind, conflicting | + +(Behind-counts are against `dev@50e955604`, re-measured at close-out. An earlier +draft quoted them against the round's opening base and was 13 commits stale — +the round's own merges moved the target.) + +Six merged, one closed as superseded, six open with a named unblocking condition +and the specific person who owns it. Every row cites evidence produced in this +round, not recalled. + +## What the round is actually worth + +The keystone finding generalizes past this repository. Three PRs showed four +failing required jobs each and none of the failures were theirs: `dev` carried +`package.json` 2.34.0 after tag v2.34.0 shipped, so every PR opened after the +release inherited a red matrix, and a scp-style SSH literal in a release runbook +tripped `privacy:scan` on top of it. + +Merging in author order, or "cleanest first", would have re-run, re-diagnosed, or +bounced back three contributors for a defect in our own base. Instead one PR +changing a version string and a doc line cleared the board — and the claim was +*tested*, not assumed: #2764 and #2767 were rebased with **unchanged patch IDs** +(`7d644cbaf`, `719d0d986`) and went from 4 failing jobs to 26 green. + +The previous round learned that green checks are not health. This round learned +the inverse and then a sharper version of the original: **red checks are not harm +until the shared baseline is green**, and **green *targeted* checks are not health +either, because you chose the targets** — nine focused suites passed a fix that +two CI shards rejected. + +## Where the adversarial review earned its cost + +Four Sol-high reviewers ran across five rounds and returned FAIL six times. The +two that mattered most were both about honesty rather than correctness: + +1. **I wrote unfixed OAuth exploit detail into tracked `devlog/`** — mechanism, + activation path, remediation — while #2745 is open. `AGENTS.md` forbids exactly + that, in a section written because maintainer triage had done it before. My + reasoning error: I treated it as publishable because the reviewer had already + posted it on the PR, but the rule keys on whether the *fix has shipped*. Moved + to `.tmp/` (gitignored, verified). The first repair was incomplete — a test + design still carried the shape — and that was caught too. +2. **Every merge lane skipped the non-author approval** `MAINTAINERS.md` requires, + on the reasoning that the user's instruction to run the round supplied it. It + does not. The gate turned out to be satisfiable for the Ingwannu PRs and + *not* satisfiable for my own #2769, which is the whole point of having it. + +Three further FAILs were my corrections being wrong: claiming #2747 went green +when it never did, inventing a check-rerun story for two approval timestamps, and +asserting a fork push was unavailable when `maintainerCanModify` is true. An +incorrect correction is worse than the original error. + +## Standing gates, updated + +1. Compile evidence comes from the MERGED tree, never the PR head alone. +2. Pairwise `git merge-tree` before any two PRs sharing a file both land. +3. Green checks are not health unless the list includes `ci` / `test N/4` / + `macos`. **Red checks are not harm until the shared baseline is green.** +4. **Green focused suites are not health when you chose which suites to run.** + Run a differential probe over every arm of a function you change. +5. One `bun test` at a time; long suites on `lidge` via `ocx-run`. +6. Every lane travels a `codex/` branch and a PR targeting `dev`. +7. A safety net that exists in code is not a safety net that functions. +8. `gh run rerun` replays the same commit. When the fix landed elsewhere, only a + rebase moves the evidence. +9. A stalled remote suite is not necessarily a wedged suite. `ocx-run` reported + `RUNNING (775s since last output)` while `bun scripts/test.ts` sat printing + "another Bun test run holds the machine lock; waiting". The owner recorded in + `/tmp/opencodex-bun-test.lock/owner.json` was pid `2108243`, and `ps` showed it + dead — a **root-owned stale lock** blocking a user-owned run, which is the + documented failure mode. Removed the lock directory; the suite resumed within + seconds. `OCX_TEST_NO_QUEUE=1` remains the wrong answer: it leaks into the child + process `tests/test-runner.test.ts` spawns and fails the machine-lock cases. + +## Follow-ups outside this round's scope + +- The same pre-disclosure OAuth material exists in + `devlog/_plan/260826_wp7e_presence_driven_oauth_failover/` and + `devlog/_plan/260827_dev_hardening/`. Pre-existing, other work streams, needs + separate authority. **Escalated, not silently rewritten.** +- `CL-07 task effectiveness producer > inactivity timeout is bounded for trusted + route executors` failed once on the macOS shard at `2483f4047` (15352 pass / 1 + fail) and passed on re-run (15353 / 0). **It is unattributed.** I called it + "pre-existing flakiness" on two arguments the final auditor demolished: the test + does reach the changed code transitively + (`lab-fabric-task` -> `src/lab/index.ts` -> `observe/from-conformance` -> + `conformance/executor` -> `src/claude/outbound.ts` -> `src/lib/errors.ts`), and + the comparison failure I cited on `d1def682d` was a **Linux** `test 2/4` failure + in `shutdown-launcher.test.ts`, not a macOS one. Neither run reproduces locally + (5/5 and 47/0 at both the PR head and clean `dev`). + + So it is neither proven flaky nor proven a regression, and the honest label is + unattributed. Recording it that way matters more than the individual test: + "it was flaky" is exactly the claim these gates exist to distrust, and I reached + for it with two wrong facts. Worth its own causal investigation. diff --git a/devlog/_plan/260827_release_train/020_preview_release.md b/devlog/_plan/260827_release_train/020_preview_release.md index 4a8015e8d8..b8291441fa 100644 --- a/devlog/_plan/260827_release_train/020_preview_release.md +++ b/devlog/_plan/260827_release_train/020_preview_release.md @@ -1,40 +1,107 @@ -# 020 — publish the preview prerelease +# 020 — publish the preview prerelease (revised) + +Supersedes the first draft of this page. The original said "invoke the script in a way that +does not execute the suite here," which an independent audit of `scripts/release.ts` showed +does not exist: the local suite at `scripts/release.ts:521-555` has no flag and no env +escape, and the documented `--publish` re-entry re-runs it. ## Target -`2.34.0-preview.20260827`, dist-tag `preview`. +`2.34.0-preview.20260827`, dist-tag `preview`, from branch `preview` at the release commit. + +## Division of labour, measured rather than assumed + +`release.yml` never runs the test suite. What the script does that the workflow does not: + +| Step | Script | Workflow | +| --- | --- | --- | +| branch/clean-tree/version-shape preflight | yes | yes, later, against `GITHUB_REF` | +| `assertUnusedReleaseVersion` + channel-moves-forward | both | unused-only | +| `audit:high`, `tsc`, **full suite**, `privacy:scan` | yes | `audit:high` yes; suite **no**; `tsc`+GUI inside `prepublishOnly` | +| bump, commit `release: v…`, deploy-key push | **yes** | **no** | +| wait for push-event `ci.yml` + `service-lifecycle` at the sha | yes | requires the runs exist; does not wait | +| create git tag + GitHub release | **no** | **yes**, and only when `dry-run != true` | -## How +So the git steps are the script's alone, and the publish gates are the workflow's alone. -From a checkout on `preview`, with the deploy key exported: +## Chosen route + +Run the git steps by hand, let the branch's own push-event CI run, then dispatch: ``` -OCX_RELEASE_SSH_KEY=~/.ssh/opencodex_release_ed25519 \ - bun scripts/release.ts 2.34.0-preview.20260827 --tag preview +# on preview, at the promoted head +npm version 2.34.0-preview.20260827 --no-git-tag-version +git commit -am 'release: v2.34.0-preview.20260827' +# Keep the scp-style SSH principal out of one email-shaped source literal. +release_host=github.com +release_repo=lidge-jun/opencodex.git +GIT_SSH_COMMAND='ssh -i ~/.ssh/opencodex_release_ed25519 -o IdentitiesOnly=yes' \ + git push "git@${release_host}:${release_repo}" HEAD:preview +# wait for push-event ci.yml AND service-lifecycle at that exact sha +gh workflow run release.yml --ref preview \ + -f version=2.34.0-preview.20260827 -f tag=preview \ + -f expected-sha=<40-char sha> -f dry-run=true +# inspect, then re-dispatch with dry-run=false ``` -That is the dry run — `release.yml` defaults `dry-run=true`, and the script bumps, commits, -and pushes the real release commit either way. Inspect the dispatched run, then re-run the -same command with `--publish`. +The suite runs on `ssh lidge` via `ocx-run` at that exact sha, as every phase of the +hardening unit did. This is not skipping a gate: the suite is not one of `release.yml`'s +gates, and the ones that are get enforced server-side regardless of what ran locally. + +Rejected alternative: running `bun scripts/release.ts` on lidge. It would work and it is +the more faithful path, but it puts an interactive multi-stage release — including a +20-minute CI wait and a deploy-key push — behind an ssh session, where a dropped +connection strands a half-pushed release. The hand route makes each step separately +observable and separately retryable. + +## Two traps, both verified in source -## The preflight problem, and how this phase satisfies it honestly +**A dry run still pushes the bump.** `dry-run` only controls the workflow's publish/tag/ +release steps (`release.yml:319-348`). The release commit is real either way, which is the +point: the dry run exercises the actual commit. -The preflight runs the suite locally, which is forbidden here. Do not edit the script to -skip it. Instead: +**`release.ts` skips the bump when the version already matches** (`release.ts:568`, +`if (currentVersion === version)`). Harmless here, since `preview` carries `2.34.0` after +the promotion and the target is the prerelease string. It matters for the stable release, +where the target `2.34.0` equals what `dev` already carries — recorded in `040`. -1. Run the full suite on `ssh lidge` via `ocx-run` at the exact release sha first. -2. Let `release.ts` reach its test step. If it runs the suite locally, that violates the - constraint — so the suite step must be satisfied by the remote run and the script - invoked in a way that does not execute it here, or the release must be dispatched - directly via `gh workflow run release.yml` with the same `expected-sha` the script - would have used. -3. Whichever route is taken, record which gates actually ran and where. The binding - checks are the workflow's own: `release.yml` verifies the version matches - `package.json` and refuses if the branch moved off `expected-sha`. +**Do not create the tag locally.** The `Protect release tags` ruleset (`20769150`) covers +`refs/tags/v*` with `deletion`, `non_fast_forward`, and `update` and has no bypass actor, and +`release.yml:268-274` refuses to publish a version whose tag already exists. The workflow +creates the tag after a successful publish. ## Acceptance - `npm view @bitkyc08/opencodex dist-tags` shows `preview = 2.34.0-preview.20260827` - `npm view @bitkyc08/opencodex@2.34.0-preview.20260827 gitHead` equals the release commit -- the Release workflow run concluded `success` and was NOT a dry run -- Cross-platform CI and Service lifecycle were green at the release sha before dispatch +- the Release run concluded `success` with `dry-run=false` +- push-event Cross-platform CI and Service lifecycle were green at the release sha first + +## Outcome — shipped + +Release commit `809a06ba00340c905dfac4ab588616e638c2fbfd`, one file changed +(`package.json`, 1 insertion 1 deletion), which is the same shape as both precedent +release commits `ec51e42d7` (v2.33.0) and `678517f56` (v2.33.0-preview.20260825). Built in +a detached worktree at `.tmp/rel-preview` so the `dev` checkout and the running local proxy +were never touched, then pushed to `preview` with the deploy key. + +Gates, in the order the workflow demanded them: + +| Gate | Evidence | +| --- | --- | +| full suite at the promoted tree | `pvsuite` on `ssh lidge`, 15334 pass / 0 fail, rc=0, at `62dfc6c54` | +| push-event Cross-platform CI | run `33072435012`, success at `809a06ba0` | +| Service lifecycle | run `33072435013`, success at `809a06ba0` | +| Release dry run | run `33073378226`, success; packed 838 files / 9.3 MB incl. a freshly built `gui/dist` | +| Release publish | run `33073503058`, success | + +Registry and git metadata after the publish: + +- `dist-tags` = `{ preview: 2.34.0-preview.20260827, latest: 2.33.0 }` +- `gitHead` of the published version = `809a06ba00340c905dfac4ab588616e638c2fbfd` +- tag `v2.34.0-preview.20260827` resolves to the same commit; GitHub Release exists with + `prerelease=true` + +The `gui/dist` question the audit raised answered itself in the dry run: the directory is +gitignored but listed in `files`, and `prepublishOnly` builds it inside the workflow before +`npm pack`, so the tarball carried `gui/dist/assets/index-BPGhccMP.js` and the rest. diff --git a/devlog/_plan/260827_release_train/030_main_promote.md b/devlog/_plan/260827_release_train/030_main_promote.md index 6203167772..6cff8ade3b 100644 --- a/devlog/_plan/260827_release_train/030_main_promote.md +++ b/devlog/_plan/260827_release_train/030_main_promote.md @@ -26,3 +26,53 @@ release a re-publication of already-exercised content rather than a first contac PR #2745 is unmerged by design, so the credential-identity drift it fixes ships to `main` unfixed. That is disclosed in the readiness statement and is not a new decision made here. The release notes must not imply otherwise. + +## Outcome — promoted, and the plan changed on contact + +`main` = `80fff9a7f47332a4445df2b26ea175053fa55b0b` (merge of PR #2760, branch +`codex/promote-main-2340` at `e25b653a2`). `git diff origin/dev origin/main` is **empty** — +not "only package.json", empty — and `main` now carries `2.34.0`. + +### The stale-version pattern this page inherited is no longer legal + +This page and `000` both planned to keep `main`'s `2.33.0` through the conflict, following +#2553 and #2507, so that the release bump would land on its own `release: v2.34.0` commit. +The first push of the branch (`8a0bd3f83`) did exactly that and CI failed it correctly: + +``` +(fail) release version line > the in-tree version is never behind a released one +``` + +in both `test 3/4` (job `98518314466`) and `macos` (job `98518314397`). + +`tests/release-version-line.test.ts` arrived **in this very delta**. It compares +`package.json` against the highest local release tag, and once `v2.34.0-preview.20260827` +existed, `compareReleaseTags("v2.33.0", "v2.34.0-preview.20260827")` is `-1`. The stale line +put the tree behind a published version — precisely the "merging into main resolves +package.json to main's side and silently republishes" failure the test's own header +describes. The precedent PRs predate the test; they were not wrong, they are superseded. + +Resolved by rebuilding from `ec51e42d7` with the conflict taken to dev's side +(`8a0bd3f83` → `e25b653a2`, force-with-lease). + +### What that costs at the release step + +`release.ts:568` skips the bump when `package.json` already matches the target, so +`v2.34.0` will be tagged on the promotion merge commit rather than on a separate +`release: v2.34.0` commit. Acceptable: `release.yml` creates the tag itself after a +successful publish and validates `expected-sha` against the checked-out commit, so the tag +still names exactly the audited tree. `040` proceeds against `80fff9a7f` directly. + +### Gate accounting + +| Check | Result | +| --- | --- | +| Cross-platform CI `33074009466` | success, zero failed jobs | +| Service lifecycle `33074009519` | success | +| PR hygiene `33074473195` | success after `suppression-approved` was re-applied | +| `enforce-target` | `wrong_base`, expected for a promotion (`ALLOWED_BASES = ["dev"]`) | +| CodeQL | 53 alerts, none introduced: `dev` already has 84 open (78 high), `main` 73, and the branch diff against `dev` is empty | + +The force-push cleared `suppression-approved` and re-added `intake: hygiene-blocked`, which +is worth knowing for the next promotion: the label has to be re-applied after **every** +push, not just the first. diff --git a/devlog/_plan/260827_release_train/040_stable_release.md b/devlog/_plan/260827_release_train/040_stable_release.md index 29083d6152..49746d2678 100644 --- a/devlog/_plan/260827_release_train/040_stable_release.md +++ b/devlog/_plan/260827_release_train/040_stable_release.md @@ -4,18 +4,29 @@ `2.34.0`, dist-tag `latest`. -## How +## How — revised after the promotion -From a checkout on `main`: +There is no release commit to make. `main` is `80fff9a7f` and already carries `2.34.0`, +because `030` had to resolve the promotion conflict to dev's side to satisfy +`tests/release-version-line.test.ts`. `release.ts:568` would skip the bump for exactly this +reason, so `80fff9a7f` **is** the release commit and the workflow tags it directly. + +That removes the only step the hand route existed to perform, so `040` is a pure dispatch: ``` -OCX_RELEASE_SSH_KEY=~/.ssh/opencodex_release_ed25519 \ - bun scripts/release.ts 2.34.0 --tag latest # dry run - # inspect, then re-run with --publish +# wait for the push-event ci.yml AND service-lifecycle runs at 80fff9a7f +gh workflow run release.yml --ref main \ + -f version=2.34.0 -f tag=latest \ + -f expected-sha=80fff9a7f47332a4445df2b26ea175053fa55b0b -f dry-run=true +# inspect the packed file list, then re-dispatch with dry-run=false ``` +The promotion push started both required runs on `main` on its own, plus +`deploy-docs.yml`, which is what `050` needs. + `release.ts` refuses a prerelease version on `main`, so the plain `2.34.0` is required -here rather than a matter of taste. +here rather than a matter of taste. The workflow enforces the same mapping server-side: +`main` must publish a non-prerelease version with dist-tag `latest`. ## Acceptance @@ -30,3 +41,30 @@ here rather than a matter of taste. npm publish is irreversible. The dry run is not optional ceremony: it is the only rehearsal available. Read the dry-run job log for the packed file list before publishing — a release that ships the wrong files cannot be unshipped, only superseded. + +## Outcome — shipped + +`2.34.0` published from `main` at `80fff9a7f47332a4445df2b26ea175053fa55b0b`, which is the +promotion merge itself: no separate `release: v2.34.0` commit exists, and none was +possible, for the reason recorded in `030`. + +| Gate | Evidence | +| --- | --- | +| push-event Cross-platform CI | run `33075147758`, success at `80fff9a7f` | +| Service lifecycle | run `33075147219`, success | +| Release dry run | run `33076185925`, success; packed `@bitkyc08/opencodex@2.34.0`, 838 files, 9.3 MB, `gui/dist/index.html` present | +| Release publish | run `33076348477`, success | + +Both channels now current, and neither disturbed the other: + +- `dist-tags` = `{ latest: 2.34.0, preview: 2.34.0-preview.20260827 }` +- `gitHead` of `2.34.0` = `80fff9a7f47332a4445df2b26ea175053fa55b0b` +- tag `v2.34.0` resolves to the same commit; GitHub Release exists with `prerelease=false` + +Artifact proof, by unpacking rather than by registry metadata: `npm pack`ed the published +version into a `mktemp -d`, and `package/package.json` reads `2.34.0` with +`package/gui/dist/index.html` present and both `bin` entries intact. Installing it into the +same scratch directory and running the installed binary prints `opencodex 2.34.0`. + +The dry-run packed size matched the preview's exactly (838 files, 9.3 MB, 19.9 MB unpacked), +which is the expected result of publishing byte-identical trees to two channels. diff --git a/devlog/_plan/260827_release_train/050_deploy_and_verify.md b/devlog/_plan/260827_release_train/050_deploy_and_verify.md index c9a3f7eca7..ffac409796 100644 --- a/devlog/_plan/260827_release_train/050_deploy_and_verify.md +++ b/devlog/_plan/260827_release_train/050_deploy_and_verify.md @@ -28,3 +28,65 @@ unit is closable to `_fin`. - the docs deploy run for the `main` release concluded `success` - a real install of `2.34.0` reports `2.34.0` from its own runtime - the record names every sha and run id rather than describing them + +## Outcome — the release record + +### Both channels, both commits + +| Channel | Version | Release commit | Branch head | +| --- | --- | --- | --- | +| `preview` | `2.34.0-preview.20260827` | `809a06ba00340c905dfac4ab588616e638c2fbfd` | `origin/preview` | +| `latest` | `2.34.0` | `80fff9a7f47332a4445df2b26ea175053fa55b0b` | `origin/main` | + +`dev` stayed at `7ca954ffd997197d1cff6fc6d69842be51177a8f` throughout; both release trees are +byte-identical to it apart from the preview's version string. `main` needed no separate +release commit — the promotion merge is the release commit, for the reason in `030`. + +### Run ids + +| What | Run | +| --- | --- | +| preview push CI | `33072435012` | +| preview service lifecycle | `33072435013` | +| preview release dry run | `33073378226` | +| preview release publish | `33073503058` | +| promotion branch CI (the one that caught the version-line regression) | `33074009466` | +| promotion branch hygiene (after relabel) | `33074473195` | +| main push CI | `33075147758` | +| main service lifecycle | `33075147219` | +| main release dry run | `33076185925` | +| main release publish | `33076348477` | +| docs deploy | `33075147234` | + +Remote full suite: `pvsuite` on `ssh lidge` at `62dfc6c54` (the tree both releases ship), +15334 pass / 0 fail, rc=0. + +### Docs deploy + +`deploy-docs.yml` fired on the promotion push without a manual dispatch, as expected from +the `docs-site/**` path filter. Run `33075147234` at `80fff9a7f`, both `build` and `deploy` +jobs success, and the `github-pages` deployment `6123269073` is bound to that same sha. +`https://opencodex.me/` answers `200` and serves the expected title. The legacy +`/pages/builds/latest` API returns 404 here because Pages is workflow-built, not +legacy-built — that is not a failure signal. + +### Installed-runtime proof + +In a `mktemp -d`: `npm pack @bitkyc08/opencodex@2.34.0` then unpacked gives +`package/package.json` at `2.34.0` with `package/gui/dist/index.html` present and both +`bin` entries intact; installing it and running the installed binary prints +`opencodex 2.34.0`. Packed size matched the preview exactly — 838 files, 9.3 MB packed, +19.9 MB unpacked — which is what publishing identical trees to two channels should look +like. + +### What is deliberately NOT in this release + +PR #2745 (OAuth 429 credential-identity rebind) is unmerged, awaiting the security review +`MAINTAINERS.md` requires for credential-handling changes. The drift it fixes ships to both +channels unfixed. This was disclosed in the readiness statement before the train started and +is not a decision made here. + +Separately, and worth stating plainly rather than burying: `dev` carries 84 open CodeQL +alerts (78 high) against `main`'s previous 73, so this train raises the open-alert count by +11. None were introduced by the promotion itself — the branch diff against `dev` was empty — +but they now ship on `latest`. Triaging them is separate work against `dev`. diff --git a/devlog/_plan/260828_bugpr_fix_and_reimplement/000_plan.md b/devlog/_plan/260828_bugpr_fix_and_reimplement/000_plan.md new file mode 100644 index 0000000000..4c6626b9be --- /dev/null +++ b/devlog/_plan/260828_bugpr_fix_and_reimplement/000_plan.md @@ -0,0 +1,73 @@ +# 000 — fix-and-reimplement round: plan + +Base: `dev @ 50e955604`. Continues the igwanu round, which merged six PRs and left +seven open. This round's mandate is narrower and harder: **fix what can be fixed, +reimplement what cannot, and merge both** — the user explicitly authorized pushing +to contributor fork branches this round. + +## Re-verified state (2026-08-28, against `dev@50e955604`) + +| PR | author | fork writable | behind | merge-tree | tsc on merged tree | own suite | +|---|---|---|---|---|---|---| +| #2747 | olddonkey | **yes** | 39 | CLEAN | OK | 15/0 | +| #2740 | luvs01 | **yes** | 39 | CLEAN | OK | 2/0 | +| #2693 | yxr1995-maker | **yes** | 131 | CLEAN | OK | 62/0 | +| #2638 | luvs01 | **yes** | 192 | CLEAN | OK | — | +| #2497 | MarcTCruz | **yes** | 399 | **CONFLICT** | unreachable | — | +| #2745 | lidge-jun | n/a | 39 | CLEAN | OK | — | + +**#2693 passing 62/0 is the trap this round has to avoid.** Its own suite is green +and its three reviewer-reproduced defects are all real. A suite written alongside a +defect tends to encode it; that is why the reimplementation below is driven by the +defect list, not by the PR's tests. + +## Contention + +`src/server/responses/core.ts` — #2745, #2638, #2497. +`src/codex/auth-context.ts` — #2638, #2497. +Everything else is disjoint. Pairwise `git merge-tree` before any second one of the +three lands; textual mergeability is not behavioral compatibility on that boundary. + +## Lane assignment + +| WP | Doc | PR | lane | why | +|----|-----|----|------|-----| +| wp2 | 010 | #2747, #2740 | **FIX** | correct code, stale base only | +| wp3 | 020 | #2693 | **REIMPLEMENT** | three reproduced logic defects | +| wp4 | 030 | #2745 | **FIX or NEEDS_HUMAN** | OAuth credential boundary | +| wp5 | 040 | #2638 | **REBASE + verdict** | auth/routing boundary, 192 behind | +| wp6 | 050 | #2497 | **adjudicate** | OAuth refresh, conflicting, 399 behind | +| wp7 | 060 | — | close-out | ledger + verification | + +## Loop-spec + +- Archetype: spec-satisfaction repair. Each target has a verifier that defines done. +- Write scope: `devlog/_plan/260828_bugpr_fix_and_reimplement/`, `src/` and `tests/` + changes needed to fix or reimplement a target, fork-branch rebases where + `maintainerCanModify` is true, `codex/` branches, PR metadata. +- Out of scope: `main`/`preview`, releases, enhancement PRs, history rewrite on + `dev`, approving my own PRs, pre-disclosure security notes in tracked dirs. +- Bounds: one `bun test` at a time; long suites on `lidge` via `ocx-run`. Never + `OCX_TEST_NO_QUEUE=1` — remove a stale root-owned lock instead. + +## Standing gates + +1. Compile/test evidence from the MERGED tree, never the PR head. +2. Pairwise `git merge-tree` before two PRs sharing a file both land. +3. Green checks are not health unless `ci` / `test N/4` / `macos` are present. +4. **Green targeted suites are not health either — you chose the targets.** Any + function whose behavior changes gets a differential probe over every arm. +5. `gh run rerun` replays the same commit; only a rebase moves the base. +6. A safety net that exists in code is not one that functions. +7. A regression must FAIL without its fix (mutation-verified) to count as evidence. + +## Accept criteria (mirrored into goalplan criteria[]) + +- c1 — every target has a recorded terminal disposition verified against live `gh`. +- c2 — merged-tree compile/test gate ran for every candidate. +- c3 — each landed change carries a mutation-verified regression. +- c4 — `dev` advances only through PRs targeting `dev`; forks rebased, not rewritten + beyond the authorized scope. +- c5 — every behavior-changing function is differentially probed across all arms. +- c6 — auth/credential/OAuth surfaces land only when proven safe, else + NEEDS_HUMAN/UNSAFE with the exact unresolved question. diff --git a/devlog/_plan/260828_bugpr_fix_and_reimplement/010_phase1.md b/devlog/_plan/260828_bugpr_fix_and_reimplement/010_phase1.md new file mode 100644 index 0000000000..280b4efacd --- /dev/null +++ b/devlog/_plan/260828_bugpr_fix_and_reimplement/010_phase1.md @@ -0,0 +1,108 @@ +# 010 — wp2 FIX lane: #2747 and #2740 + +Both are correct code sitting on a stale base. Neither needs a logic change; both +need a rebase I am now authorized to push. + +## #2747 — reap the recovery proxy instead of trusting `stop` + +Head `07b975873`, **already approved by me**, 39 behind, merge CLEAN, tsc OK, +15/0 on its own suite on the merged tree. Fork `olddonkey/fix/update-recovery-orphan-cleanup`, +`maintainerCanModify: true`. + +Its `ci`/`macos` red is the pre-#2766 `release version line` failure, and a rerun +cannot clear it because a rerun replays the same commit. + +ACTION: rebase `pr2747-r3` onto `origin/dev`, force-push to the fork branch, let CI +run at the new head, merge when green. + +**Fork-push discipline.** The previous round declined this; the user has now +authorized it. The A-gate reviewer demolished an earlier draft of this section, and +it was right: the draft said "verify `git diff` between old and new head touches +nothing but the rebase", and that check is actively misleading. A two-dot +`git diff OLD NEW` after a 39-commit rebase reports the entire intervening `dev` +range — **70 files** on #2747's real rebase — so an executor following it either +panics at 70 files or waves through a genuine rewrite. Use checks that are invariant +under rebase: + +```bash +# 1. the patch itself is unchanged +git diff-tree -p OLD~1..OLD | git patch-id --stable +git diff-tree -p NEW~1..NEW | git patch-id --stable # must match + +# 2. commit-for-commit correspondence — no drops, no reorders +git range-diff origin/dev...NEW OLD_BASE...OLD # every row reads "=" + +# 3. the PR's own file set — three-dot, not two-dot +git diff --name-only origin/dev...NEW + +# 4. never overwrite a concurrent author push +git push --force-with-lease=refs/heads/: \ + https://github.com//opencodex.git NEW:refs/heads/ +``` + +On #2747 these read: patch-id `efa23210f341` both sides, `range-diff` `1: = 1:`, +three-dot name list `tests/update-stop-first.test.ts` alone. + +Two further rules absent from the first draft: + +- **Push to the fork, never to `origin`.** Destination is + `https://github.com//opencodex.git`. The previous round created a stray + same-named branch on `origin` and had to delete it. +- **Stop if the live head is already on current `dev`.** Re-rebasing a stale local + ref rewrites a branch that is already correct. Check + `gh pr view --json headRefOid` first. + +**A force-push resets the readiness checklist.** `enforce-target` returns a +contributor PR to draft and unticks all four boxes on new commits — by design, since +an attestation about the old commit cannot cover a new one. So a rebase does not end +at "let CI run": the PR is a draft again, and drafts here start only +`enforce-target`/`hygiene`/`label`/`resolve-pr`/CodeRabbit, none of which compile or +test. Two boxes ("on the latest dev commit", "resolved all Codex and CodeRabbit +findings") become objectively true and can be evidenced; the local-CI attestation +and the ready-for-review confirmation belong to the author. **Ask — do not tick +another contributor's attestation.** + +## #2740 — atomically commit cleanup run metadata + +Head `f07ee36f2`, draft, 39 behind, merge CLEAN, tsc OK, 2/0 on the merged tree. +Fork `luvs01/fix/storage-policy-metadata-race`, `maintainerCanModify: true`. + +Mutation oracle already proven in the previous round: revert only +`src/storage/policy.ts` + `src/storage/policy-job.ts` and the race test goes 0 pass / +2 fail. The test drives the interleave through +`setPersistedConfigMutationBeforeCommitForTests`, so it is deterministic rather than +timing-dependent — it will not become a flake later. + +It has only 5 checks, none of which compile or test. The merged-tree run is its first +real evidence. + +ACTION: rebase onto `origin/dev`, force-push under lease, then ask the author to +complete the readiness checklist so the full matrix runs. Merge when green **and** a +non-author approval exists — `luvs01` is the author, so mine qualifies. + +Recording a judgement the reviewer flagged as unstated: this PR writes through +`mutatePersistedConfig` into `config.json`, the file that holds API keys. It is not +a credential surface — it changes *how* a metadata write commits, not what is +stored, and its whole purpose is to stop clobbering concurrent edits. But "adjacent +to the file holding the keys" deserves an explicit call rather than an assumed one. + +## Ordering + +Independent — `tests/update-stop-first.test.ts` vs `src/storage/*`. No pairwise +merge-tree needed. Land #2747 first (already approved), then #2740. + +## TESTS + +- #2747: `tests/update-stop-first.test.ts` (the PR is the test). +- #2740: `tests/storage-policy-config-race.test.ts`. + +## Verification (C) + +```bash +bun x tsc --noEmit +bun test tests/update-stop-first.test.ts # expect 15/0 +bun test tests/storage-policy-config-race.test.ts # expect 2/0 +``` + +Plus exact-head CI green after each rebase, and for #2740 the mutation oracle +re-run on the rebased tree rather than the remembered one. diff --git a/devlog/_plan/260828_bugpr_fix_and_reimplement/020_phase2.md b/devlog/_plan/260828_bugpr_fix_and_reimplement/020_phase2.md new file mode 100644 index 0000000000..f9f6294e06 --- /dev/null +++ b/devlog/_plan/260828_bugpr_fix_and_reimplement/020_phase2.md @@ -0,0 +1,250 @@ +# 020 — wp3 REIMPLEMENT lane: #2693 antigravity signature fallback + +#2693 head `8775d77d6`, 131 behind, merge CLEAN, tsc OK, **62/0 on its own suite**. +The green suite is not evidence: all three reviewer-reproduced defects survive it, +because tests written beside a defect encode it. + +## The intent is right + +Gemini 3 function calls require a `thought_signature` on the first `functionCall` +part of a model turn. When neither the wire metadata nor the replay cache has one, +the request fails. Injecting the official +`skip_thought_signature_validator` bypass is the correct remedy. Three defects sit +between that intent and the diff. + +## Defect 1 — presence check instead of `extractSignature()` + +The diff tests `part.thoughtSignature !== undefined || part.thought_signature !== undefined`. +The module already owns the real contract at +`src/adapters/google-antigravity-replay.ts:513`: + +```ts +function extractSignature(part: Record): string | undefined { + const direct = part.thoughtSignature ?? part.thought_signature; + if (typeof direct === "string" && direct.length >= MIN_SIGNATURE_LEN) return direct; + const extra = part.extra_content as { google?: { thought_signature?: unknown } } | undefined; + const nested = extra?.google?.thought_signature; + if (typeof nested === "string" && nested.length >= MIN_SIGNATURE_LEN) return nested; + return undefined; +} +``` + +Two consequences, both reproduced by the reviewer: + +- a **nested** `extra_content.google.thought_signature` is invisible to the presence + check, so a turn that already carries a valid signature gets a competing sentinel + added; +- a **direct but too-short** value (`"short"`, below `MIN_SIGNATURE_LEN = 16`) reads + as present, so the fallback is suppressed on a turn that genuinely needs it. + +FIX: decide from `extractSignature(part)`, never from key presence. + +## Defect 2 — `turnHasSignature` is a turn-wide boolean set by a later sibling + +The diff scans all parts and sets `turnHasSignature` if **any** part has one, then +skips the sentinel for the whole turn. But the requirement is specifically about the +**first** `functionCall` of the turn. Reviewer's reproduction: a two-call turn where +only the second matches the cache — the second gets a real signature, the first stays +unsigned, and the sentinel that the first call required is skipped. + +FIX: track the first `functionCall` part explicitly, replay real signatures, then +decide the fallback from `extractSignature(firstFunctionCall)` alone. A later +sibling's signature must not vote on the first call's state. + +## Defect 3 — the sentinel reaches non-Gemini models + +`antigravityUsesReplayCache(model)` is `!/claude/i.test(model)` — every non-Claude +model qualifies. The reviewer reproduced the Gemini-only sentinel being injected into +`gpt-oss-120b-medium`. + +FIX: gate sentinel injection on a Gemini wire model. The replay cache's own scope is +deliberately broad and must stay that way; only the **sentinel** narrows. A new +predicate local to this module: + +```ts +export function antigravitySupportsThoughtSignatureSentinel(model: string): boolean { + return /(^|[/:])gemini[-.\d]/i.test(model); +} +``` + +**The separator is the load-bearing detail.** An earlier draft of this doc wrote +`/(^|\/)gemini[-.\d]/i` — slash only. The A-gate reviewer and a local probe caught +the same hole independently: `src/adapters/google.ts` builds the Vertex replay key +as `vertex:::`, a **colon**. A slash-only regex looks +correct against every CCA id and would have silently stripped the bypass from every +Vertex Gemini request — a regression introduced by the fix meant to prevent one. +Three namespaces reach this module and all three must match: `gemini-3-pro`, +`google/gemini-3-pro`, `vertex:api-key:global:gemini-3-pro`. The trailing +`[-.\d]` keeps `geminibot` and `my-gemini-clone` out. + +## Where the sentinel lives, and why not inside `applyAntigravityReplay` + +The first implementation put the fallback inside `applyAntigravityReplay` and broke +**12 existing tests**. That was not a broken-test problem; it was a design answer. +That function's *absence* of a signature is meaningful — 18 assertions read +`thoughtSignature === undefined` as "the cache did not match", covering eviction, +TTL expiry, oversize refusal, and clear-on-invalid. Writing a fabricated token into +that slot overwrites the exact signal those tests read. + +So the sentinel is its own exported pass, +`applyAntigravityThoughtSignatureFallback(model, contents)`, called immediately +after replay at both `src/adapters/google.ts` call sites. Replay answers "what did +upstream already tell us"; the sentinel answers "does the first call still lack a +signature". A cache miss keeps looking like a cache miss, and all 61 pre-existing +tests pass untouched. + +A model outside that set that genuinely needs the sentinel must arrive with a captured +accepted CCA contract, not by widening the predicate on inference. + +## Also: the reviewer's non-blocking test defect + +The unknown-version snapshot test reuses the object mutated by the corrupt-snapshot +call, so its second assertion is not load-bearing. The reimplementation gives the +version-99 branch a fresh unsigned payload. + +## Lane mechanics + +REIMPLEMENT on `codex/antigravity-signature-fallback` cut from `origin/dev`, then a +PR targeting `dev` that closes #2693 as superseded. The author's commits are not +carried because the logic is being replaced, not rebased; the PR credits the original +diagnosis and links #2693. + +## TESTS — `tests/google-antigravity-replay.test.ts` + +Each must fail without its corresponding fix: + +1. two-call turn, only the second matches the cache -> the FIRST call receives the + sentinel (defect 2). +2. valid **nested** `extra_content.google.thought_signature` on the first call -> no + sentinel added (defect 1a). +3. direct but **too-short** signature on the first call -> sentinel IS added + (defect 1b). +4. `gpt-oss-120b-medium` with an unsigned first call -> **no** sentinel (defect 3). +5. a Gemini model with an unsigned first call and no cache entry -> sentinel added + (the feature still works). +6. version-99 snapshot branch uses a fresh unsigned payload. +7. a later sibling signed **on the wire** (no cache at all) does not vote away the + first call's sentinel — the reviewer noted that test 1 only covers the cache-hit + arm, so a weaker patch could pass it and leave this open. +8. a Vertex-prefixed Gemini id receives the sentinel end to end, driving the real + function rather than only asserting the predicate. + +## Verification (C) + +```bash +bun x tsc --noEmit +bun test tests/google-antigravity-replay.test.ts +``` + +Then the mutation oracle per defect: revert each fix individually and confirm the +matching test — and only that test — fails. A single combined revert is weaker +evidence, because it cannot show that each test binds its own defect. + +Result (all four confirmed): + +| mutation | tests that fail | +|---|---| +| presence-check instead of `extractSignature` | 2 — nested, too-short | +| turn-wide flag instead of first-call | 1 — first-call sentinel | +| gate on `antigravityUsesReplayCache` | 1 — non-Gemini injection | +| slash-only regex | 2 — Vertex predicate and end-to-end | + +70 pass / 0 fail with every fix in place; `tsc --noEmit` exit 0. + +## The blast radius the focused suites did not show + +70/0 on `tests/google-antigravity-replay.test.ts` and exact-head CI still failed +three shards. **Five tests in four OTHER suites** break, all with one shape: they +assert `thoughtSignature` is `undefined`, and the sentinel now fills that slot. + +``` +tests/google-signature-history-roundtrip.test.ts + "history without a signature stays unsigned rather than borrowing one" + "an unknown call_id stays unsigned" +tests/google-vertex-thought-signature.test.ts + "#1312: shared prompt cache keys cannot cross client-thread replay namespaces" +tests/google-antigravity-wire.test.ts + "custom_tool_call item ids (ctc_...) are NOT forwarded (issue #174)" +``` + +This is the round's own standing gate #4 firing on me: green targeted suites are +not health, because I chose the targets. I picked the file I was editing, and the +consumers are where the change actually landed. + +### The question, stated honestly + +Those tests use `undefined` as a **proxy** for "no signature was borrowed from +another call, another thread, or another namespace". #1312 is a genuine security +boundary: thread-b must not inherit thread-a's signature under a shared prompt-cache +key. The sentinel is a constant carrying no information from any other call, so on +that reading the isolation property survives and the assertions should read +`toBe(BYPASS)`. + +**That reading is convenient for me, which is why it is not mine to certify.** It +is dispatched to an independent reviewer with the alternative designs named: (a) +update the five assertions, (b) narrow the sentinel so it never applies to replayed +client history, (c) something else. + +Direct evidence gathered meanwhile — thread-a records a real signature, thread-b +replays the same call under a different session: + +``` +after replay (thread-b): { functionCall: { name: "shell", args: {} } } +after fallback (thread-b): "skip_thought_signature_validator" +leaked thread-a's real signature? no +``` + +So the leak the test guards against does not occur. Whether `undefined` was +load-bearing for a *different* reason is the reviewer's call, not mine. + +### It was not just assertion drift — two real defects were hiding there + +Investigating the five failures found two genuine problems, both of which make the +sentinel behave as if it were a real signature: + +**1. The replay cache ingested it.** `observeAntigravityReplay` stored the sentinel +like any other signature, so a token we fabricate on the way out round-tripped back +in and was replayed later as evidence a turn was signed: + +``` +observe(sentinel) -> {"sessions":1,"calls":1,"totalBytes":160} +apply -> "skip_thought_signature_validator" +``` + +`extractSignature` now refuses it on both the direct and nested paths, so observing +it leaves the cache empty (`sessions: 0`) instead of polluting it. + +**2. `isLikelyRealThoughtSignature` accepted it.** That predicate exists to reject +synthetic ids — `fc_`, `ctc_`, `tsc_`, `call_` — and it is what +`tests/google-antigravity-wire.test.ts` #174 protects. The sentinel is alphanumeric +with underscores, so it slipped through every filter and would have been treated as +genuine anywhere that predicate gates. Now rejected by name. + +Neither was visible from the focused suite. Both were found by asking why the +*other* suites disagreed, instead of assuming they were stale. + +### The design verdict + +With both closed, the five assertions really are proxies, and the independent +reviewer reached the same conclusion on its own reasoning: + +> All five are proxies for "no *real* signature was borrowed/forwarded", not a +> requirement that the slot stay empty. [...] There is no honest "replayed history +> vs fresh turn" bit at those call sites [...] every unsigned first `functionCall` +> *is* history, which is the Gemini 3 400 this PR is fixing. (b) would disable the +> feature on the path that needs it. + +It also independently flagged the `isLikelyRealThoughtSignature` hole as a residual +risk — "do not let it enter the remember/observe path" — which is exactly the defect +already closed above. + +Design (a) adopted: each assertion now expects the sentinel and carries a comment +explaining why the property it protects still holds. #1312 keeps its positive +control that thread-a still receives the real `SIGNATURE`, so a genuine +cross-namespace leak would still fail the test. + +159 pass / 0 fail across all four affected suites. + +Differential probe required (gate 4): `applyAntigravityReplay` changes behavior, so +enumerate the arms — cache hit / miss, signed / unsigned first call, nested / direct / +short signature, Gemini / non-Gemini — against unpatched `dev` and record which move. diff --git a/devlog/_plan/260828_bugpr_fix_and_reimplement/021_wp2_wp3_outcome.md b/devlog/_plan/260828_bugpr_fix_and_reimplement/021_wp2_wp3_outcome.md new file mode 100644 index 0000000000..2d763a3511 --- /dev/null +++ b/devlog/_plan/260828_bugpr_fix_and_reimplement/021_wp2_wp3_outcome.md @@ -0,0 +1,76 @@ +# 021 — wp2/wp3 outcome: two fixed, one reimplemented + +## Dispositions + +| PR | lane | state | evidence | +|---|---|---|---| +| #2747 | FIX | rebased, approved, CI running | `07b975873` -> `4a0cbb55c`, patch-id `efa23210f341` unchanged | +| #2740 | FIX | rebased, approved, CI running | `f07ee36f2` -> `be11a65f7`; author then added a GUI surface at `1f07b68b8` | +| #2693 | REIMPLEMENT | **CLOSED-SUPERSEDED** by #2794 | three blockers closed, each mutation-bound | +| #2794 | new | **NEEDS_HUMAN** (approval) | CI 23/0, full suite 15352/0; self-approval refused | + +## The fork rebases held the authors' work exactly + +Both used `--force-with-lease` pinned to the author's last OID, pushed to the +author's fork rather than `origin`, and were announced on the PR before anything +else. Proof that nothing was rewritten: + +``` +#2747 patch-id efa23210f341 -> efa23210f341 range-diff 1: = 1: +#2740 patch-id 48b653f9a33b -> 48b653f9a33b three-dot name list unchanged +``` + +A side effect I had to own: the force-push resets the four-box readiness checklist +and returns the PR to draft. That is `enforce-target` behaving correctly — an +attestation about the old commit cannot cover a new one — but it means my push +created work for the contributor. I evidenced the two boxes that became objectively +true and asked rather than ticking the author's attestation. Both authors then acted: +`luvs01` completed the checklist and pushed a GUI follow-up, `olddonkey` ticked three +of four. + +Second discovery: fork PRs need a maintainer to approve the workflow run. Both sat +in `action_required` with **no CI at all** until approved via +`gh api -X POST .../actions/runs//approve`. "Only 5 checks" on a fork PR does not +mean the matrix passed — it means the matrix never started. + +## #2693: the green suite was the trap + +It passed its own suite 62/0 with all three defects live, which is why the +reimplementation was driven by the defect list rather than by its tests. + +Each fix is bound by a test that fails without it: + +| mutation | tests that fail | +|---|---| +| presence-check instead of `extractSignature` | 2 — nested, too-short | +| turn-wide flag instead of first-call | 1 — first-call sentinel | +| gate on `antigravityUsesReplayCache` | 1 — non-Gemini injection | +| slash-only regex | 2 — Vertex predicate, Vertex end-to-end | + +### What the focused suite could not see + +70/0 locally, and exact-head CI still failed three shards. Five tests in four other +suites asserted `thoughtSignature === undefined` and the sentinel filled it. + +Treating those as stale assertions would have been the easy read. Chasing *why* they +disagreed found two real defects instead: + +1. **The replay cache ingested the sentinel** as a genuine signature, so a token + fabricated on the way out round-tripped back in and was replayed later as evidence + a turn was signed. Observing it now leaves the cache empty. +2. **`isLikelyRealThoughtSignature` accepted it** — the predicate that exists to + reject `fc_`/`ctc_`/`tsc_` synthetic ids, and precisely what the issue #174 tests + protect. The sentinel is alphanumeric with underscores, so it passed every filter. + +Only after both were closed were the five assertions genuinely proxies for "nothing +was borrowed". An independent reviewer reached the same conclusion on separate +reasoning and flagged the second defect as residual risk — the one already fixed. + +**The transferable form of this:** when a change makes another suite fail, the +question is not "is that test stale" but "what did that test know that I did not". +Twice here, the answer was a real defect. + +## Carried into wp4-wp6 + +#2745, #2638, #2497 remain — all credential or auth-routing surfaces, all needing a +second maintainer. #2794 and #2769 join #2770 in the self-approval queue. diff --git a/devlog/_plan/260828_bugpr_fix_and_reimplement/030_phase3.md b/devlog/_plan/260828_bugpr_fix_and_reimplement/030_phase3.md new file mode 100644 index 0000000000..c8edfe06ca --- /dev/null +++ b/devlog/_plan/260828_bugpr_fix_and_reimplement/030_phase3.md @@ -0,0 +1,53 @@ +# 030 — wp4: #2745, OAuth credential boundary + +Head `a90ab6ee7`, mine, 39 behind, merge CLEAN, tsc OK. Touches +`src/server/responses/core.ts` (+55/-11) and `tests/generic-oauth-failover.test.ts`. + +**This is the surface `MAINTAINERS.md` requires explicit security review for.** The +PR carries a CHANGES_REQUESTED review with two open blockers: one credential-boundary +correctness defect and one test-oracle defect. + +Per `AGENTS.md` §"Security working notes", the mechanism, activation path and +remediation are **not reproduced here** — the fix has not shipped and `devlog/` is +public. They live in `.tmp/2745-security-triage.md` (gitignored) and on the PR via +`gh pr view 2745 --json reviews`. + +## What this phase decides + +Whether the two blockers can be closed with evidence strong enough that a +credential-boundary change is safe to land, or whether it stays NEEDS_HUMAN. + +The honest constraint: **I authored this PR.** Even with both blockers closed and a +behavioral regression, GitHub refuses my approval, exactly as it did for #2769. So +the realistic best outcome is "blockers closed, evidence posted, awaiting a second +maintainer" rather than a merge. + +That is worth doing anyway — a reviewed PR with its blockers closed is a different +object from one with them open — but this phase should not pretend the merge is +reachable. + +## Contention + +`src/server/responses/core.ts` is shared with #2638 and #2497. If any of those lands +first, re-run `git merge-tree` pairwise before this one moves. Textual mergeability +is not behavioral compatibility on the auth/routing boundary. + +## TESTS + +`tests/generic-oauth-failover.test.ts` — the required test work is recorded with the +rest of the triage in scratch. + +## Verification (C) + +```bash +bun x tsc --noEmit +bun test tests/generic-oauth-failover.test.ts +``` + +Plus the differential probe over every arm of any changed credential-resolution +function, and a mutation oracle on the new regression. + +## Terminal outcome + +DONE only if a second maintainer approves. Otherwise **NEEDS_HUMAN**, with the +blockers closed and the evidence posted. diff --git a/devlog/_plan/260828_bugpr_fix_and_reimplement/040_phase4.md b/devlog/_plan/260828_bugpr_fix_and_reimplement/040_phase4.md new file mode 100644 index 0000000000..2f0ee34df6 --- /dev/null +++ b/devlog/_plan/260828_bugpr_fix_and_reimplement/040_phase4.md @@ -0,0 +1,64 @@ +# 040 — wp5: #2638 rebase and safety verdict + +Head `b0f328462`, `luvs01` fork (`maintainerCanModify: true`), **192 behind**, +merge-tree CLEAN, tsc OK on the merged tree. 1341 insertions across: + +- `src/codex/auth-context.ts` +- `src/codex/routing.ts` (+334) +- `src/codex/subagent-model-fallback.ts` (+86) +- `src/server/responses/core.ts` (+78) +- three test files + +## Why "merge-tree CLEAN, tsc OK" is not enough here + +The reviewer's objection is precise and still stands: `src/server/responses/core.ts` +is modified both by this PR and by the intervening 192-commit `dev` range, and that +file is part of the request/auth-routing boundary the PR changes. **Textual +mergeability is not evidence the combined behavior is correct.** Two changes can +merge cleanly and still contradict each other semantically. + +The reviewer also asked that `maintainer-sponsored` NOT be applied and the waiting +fork workflows NOT be approved until a rebase onto current `dev`. + +## AGENTS.md invariant at risk + +This PR touches `src/server/responses/core.ts` and `src/codex/subagent-model-fallback.ts` +— the synchronous subagent-fallback chain. `AGENTS.md` is explicit: no `await` may be +added between `Bun.serve` and the `labActivationRequired` check in +`src/server/index.ts`, and the protected core files must not reach `src/lab/`. +`tests/core-lab-boundary.test.ts` enforces both and MUST be run on the rebased tree. + +## Plan + +1. Rebase `pr2638-r3` onto `origin/dev` on a local branch; record every conflict. +2. Run `tests/core-lab-boundary.test.ts` plus the auth, routing, entitlement and + subagent-fallback suites on the rebased tree. +3. Differentially probe the routing/auth decision functions the PR changes against + unpatched `dev` — which requests route differently, and is every difference + intended? +4. Verdict: + - if the rebase is clean and behavior is provably unchanged except for the + intended drain fix -> push the rebase to the fork, let CI run, and record that + it is ready for a second maintainer's security sponsorship; + - if any conflict requires a judgement call about auth or routing semantics -> + **NEEDS_HUMAN** with the exact hunk. + +Landing it myself is not on the table regardless: `MAINTAINERS.md` requires explicit +security review for this surface, and the reviewer has already withheld sponsorship. + +## Verification (C) + +```bash +bun x tsc --noEmit +bun test tests/core-lab-boundary.test.ts +bun test tests/codex-auth-context.test.ts +bun test tests/codex-routing.test.ts +bun test tests/subagent-fallback-handle-responses.test.ts +``` + +One suite at a time. The full suite goes to `lidge` via `ocx-run`. + +## Terminal outcome + +**NEEDS_HUMAN** in the expected case, with the rebase done and the evidence +attached so the security review has something current to review. diff --git a/devlog/_plan/260828_bugpr_fix_and_reimplement/050_phase5.md b/devlog/_plan/260828_bugpr_fix_and_reimplement/050_phase5.md new file mode 100644 index 0000000000..7b43311470 --- /dev/null +++ b/devlog/_plan/260828_bugpr_fix_and_reimplement/050_phase5.md @@ -0,0 +1,57 @@ +# 050 — wp6: #2497 adjudication + +Head `86a49e852`, `MarcTCruz` fork (`maintainerCanModify: true`), **399 behind**, +merge-tree **CONFLICT**. 20 files including `src/oauth/chatgpt.ts`, +`src/codex/account-store.ts`, `src/codex/auth-context.ts`, +`src/server/responses/core.ts`, `src/server/responses/codex-auth-error.ts`. + +## The question this phase actually answers + +The user authorized fixing what can be fixed, so the question is not "may I touch it" +but **"can this rebase be done without me deciding OAuth semantics on the author's +behalf?"** + +Attempt the rebase and classify every conflict: + +- **Mechanical** — imports moved, a function renamed upstream, formatting. Resolvable + without deciding anything about token lifetime, refresh ordering, or replay identity. +- **Semantic** — the upstream range and the PR both changed how a token is refreshed, + when a credential is rebound, or which account owns a replay. Resolving these means + authoring an OAuth refresh path and then reviewing my own credential code. + +If every conflict is mechanical: push the rebase, run CI, hand a current PR to a +security reviewer. If any is semantic: stop, record the exact hunks, return +**NEEDS_HUMAN**. + +My prior expectation is that 399 commits across `auth-context.ts` and `core.ts` — +both heavily rewritten in that window — will produce semantic conflicts. That is a +prediction, and this phase tests it rather than assuming it. The previous round +recorded #2497 NEEDS_HUMAN without attempting the rebase; defensible then, not now +that fork pushes are authorized. + +## Hard limits regardless of outcome + +- `AGENTS.md`: conflict analysis on an unfixed OAuth path goes to `.tmp/`, never a + tracked directory. +- `MAINTAINERS.md`: this surface needs explicit security review. Even a perfectly + clean rebase does not make it mergeable by me. +- Never force-push a resolution that changes behavior the author did not write. + +## Verification (C) + +```bash +bun x tsc --noEmit +bun test tests/chatgpt-oauth.test.ts +bun test tests/codex-account-store.test.ts +bun test tests/codex-main-account-refresh.test.ts +bun test tests/responses-native-main-refresh.test.ts +bun test tests/core-lab-boundary.test.ts +``` + +One at a time; full suite on `lidge` via `ocx-run`. + +## Terminal outcome + +**NEEDS_HUMAN** or **UNSAFE**, with the conflict classification as evidence. A clean +mechanical rebase upgrades it to "current and reviewable", which is the most this +round can honestly deliver on an OAuth refresh path. diff --git a/devlog/_plan/260828_bugpr_fix_and_reimplement/060_phase6.md b/devlog/_plan/260828_bugpr_fix_and_reimplement/060_phase6.md new file mode 100644 index 0000000000..ed27b4cc69 --- /dev/null +++ b/devlog/_plan/260828_bugpr_fix_and_reimplement/060_phase6.md @@ -0,0 +1,43 @@ +# 060 — wp7: close-out + +Produce `070_outcome.md`: PR, lane, action taken, terminal state, and the merge SHA +or the exact unresolved question. Every row cites evidence produced in this round. + +## Verification + +```bash +git fetch origin && git log --oneline origin/dev | head -12 +git rev-list --first-parent --count 50e955604..origin/dev +git rev-list --first-parent --no-merges --count 50e955604..origin/dev # expect 0 +gh pr list --repo lidge-jun/opencodex --state open --label bug +bun x tsc --noEmit +bun run privacy:scan +``` + +Plus, for every landed PR: the merge SHA, a mutation-verified regression, and the +differential probe table for any behavior-changing function. + +## Criteria mapping + +- c1 — the 070 table covers every target, verified against live `gh`. +- c2 — the 000 merged-tree table plus per-phase receipts. +- c3 — per-PR mutation oracles recorded in each phase doc. +- c4 — first-parent counts show merges only. +- c5 — differential probe tables for changed functions. +- c6 — auth/OAuth surfaces carry a named trigger and the unresolved question. + +## Expected shape of the honest answer + +Two PRs (#2747, #2740) are fixable and mergeable by me. One (#2693) is +reimplementable and mergeable. Three (#2745, #2638, #2497) sit on credential or +auth-routing surfaces where `MAINTAINERS.md` requires a second maintainer, and two +more (#2769, #2770) are blocked only because GitHub refuses self-approval. + +So the realistic terminal state is **three merged, five awaiting a human**, and the +value delivered on those five is that each arrives current, rebased and evidenced +rather than stale. Stating that up front is not lowering the bar — it is the +difference between work that is blocked and work that is merely unfinished. + +If a phase discovers it can do better than this — for example #2638's rebase proving +behaviorally clean — the plan is wrong in the right direction and the outcome doc +should say so explicitly rather than quietly matching the prediction. diff --git a/devlog/_plan/260828_bugpr_fix_and_reimplement/070_outcome.md b/devlog/_plan/260828_bugpr_fix_and_reimplement/070_outcome.md new file mode 100644 index 0000000000..1dda199e6a --- /dev/null +++ b/devlog/_plan/260828_bugpr_fix_and_reimplement/070_outcome.md @@ -0,0 +1,202 @@ +# 070 — round outcome + +This round advanced `dev` from `50e955604` to `29be459a3`. The mandate was "fix what +can be fixed, reimplement what cannot, merge both", with fork pushes authorized. + +`dev` has since moved to `5511a424c` via #2774, a squash-merge from a different +work-stream. Both first-parent commits in the range arrived through PRs targeting +`dev` — the squash shows as a non-merge commit, which is what a squash-merge looks +like, not a direct push. + +| PR | lane | outcome | evidence | +|---|---|---|---| +| #2740 | FIX | **MERGED** `29be459a3` | rebased under lease, patch-id `48b653f9a33b` unchanged; author added a GUI surface; both regressions mutation-verified | +| #2693 | REIMPLEMENT | **CLOSED-SUPERSEDED** by #2794 | three blockers closed, each mutation-bound | +| #2794 | new | **MERGED** `bdc1e97bb` | `eebd1913e`; a reviewer blocker found and fixed after the first green matrix, then admin-merged on user authorization | +| #2747 | FIX | **MERGED** `fe063d16e` | rebased, CI 20/0 green, approved; admin-merged on user authorization | + +## Admin-merge authorization (2026-08-28) + +The user authorized `--admin` merges, which resolves the self-approval deadlock that +held #2794 and the author-attestation box that held #2747. Both were already green: +#2794 at 23 success / 0 failure, #2747 at 20 / 0. The authorization removed a +*process* gate, not a verification one — nothing was merged that lacked evidence. + +What it deliberately did **not** unblock: + +- **#2638** — head moved to `e06ffbaa8` after my rebase, so my 15375/0 evidence no + longer describes the tree under review. It also still fails `hygiene` on + `unsponsored_surface`. Admin rights make that mechanically bypassable and it stays + unmerged: the gate is asking for a security judgement on + `src/codex/auth-context.ts`, and "I can force it" is not an answer to "has anyone + reviewed this credential path". +- **#2745** — the fix lives on `codex/oauth-failover-identity-v2` and was never opened + as a PR. Two blockers from the original review also remain open by my own + admission (the `applyFailoverSnapshot` audit and the A -> 429 -> B recovery-path + regression). +- **#2497** — unchanged; still needs the author's rebase. +| #2638 | FIX | **NEEDS_HUMAN** (security) | rebased clean, full suite **15375/0**; `hygiene` correctly holds on `unsponsored_surface` | +| #2497 | attempt | **NEEDS_AUTHOR** (semantic conflicts) | rebase attempted and aborted; 6 hunks, only 1 mechanical | +| #2745 | FIX | **NEEDS_HUMAN** (approval) | both blockers closed on `codex/oauth-failover-identity-v2` `2b3574a45`; suite 15358/0 | + +## #2745: the defect was one `??` + +`refreshed.apiBaseUrl ?? getOAuthCredentialApiBaseUrl(route.providerName)` reads +correct until you follow the second arm: `getOAuthCredentialApiBaseUrl` is +`validateCopilotApiBaseUrl(getCredential(provider)?.apiBaseUrl)` — the **active** +credential, with no account scoping. A generic 429 rotation never promotes the +account it rotated to, so for a legacy account B with no allowlisted origin, that arm +silently reached account A. B's bearer, A's host. + +`copilotOriginForRefreshedCredential` now resolves from the refreshed snapshot alone +and otherwise fails closed to the canonical origin, consulting no other account: + +| refreshed snapshot for B | resolved | +|---|---| +| own allowlisted origin | that origin | +| legacy, no origin | canonical — never A's | +| non-allowlisted origin | canonical | +| empty | canonical | + +The test blocker was worse than "not behavioural": one assertion counted the buggy +expression and required it to appear **twice**, so fixing the defect would have +broken the test. Replaced with a behavioural test over all four arms, plus a topology +guard that strips comments first — the new helper's doc comment quotes the removed +expression to explain why it was wrong, and the first version of the guard read that +explanation as the defect. + +Still open from the review and deliberately not claimed: the `applyFailoverSnapshot` +audit, and an executable A -> 429 -> B regression through the HTTP recovery path. + +## Where I was wrong, in the useful direction + +060 predicted #2638 would need a semantic rebase and probably stay stale. It rebased +across **195 commits with zero conflicts**, patch-ids unchanged, and the full suite +passes 15375/0 on the rebased tree — including `tests/core-lab-boundary.test.ts`, +which matters because the PR touches `core.ts` and `subagent-model-fallback.ts`. + +So the reviewer's original objection was right *and* has now been answered: textual +mergeability proved nothing, so I measured behavior instead, and the behavior is +clean. What remains is not staleness — it is the security decision, and `hygiene` +holds it on `unsponsored_surface` naming `src/codex/auth-context.ts`. The +`maintainer-sponsored` label *is* that human judgement; an agent applying it would +be forging the gate rather than passing it. + +#2497 went the other way and the contrast is the point. Same "far behind" shape, 402 +commits, and it does **not** rebase: 6 conflict hunks across three credential files, +of which exactly one is mechanical. The decisive one is delete-vs-modify on the +entitlement path — `dev` deleted a block the PR modifies — which git cannot resolve +and I should not. Aborted, nothing pushed, triage in `.tmp/` per `AGENTS.md`. + +"Too far behind" was never the real criterion. **Whether the conflicts are +mechanical is.** + +## Two operational findings + +**A fork PR runs no product CI until a maintainer approves the workflow run.** Both +#2740 and #2747 sat in `action_required` showing 5 green checks — and the matrix had +never started. "5 checks passing" on a fork PR is not a weak signal, it is *no* +signal. Approve via `gh api -X POST .../actions/runs//approve`. + +**A maintainer force-push resets the contributor's readiness checklist.** That is +`enforce-target` working correctly: an attestation about the old commit cannot cover +a new one. But it means the rebase creates work for the author. Two boxes become +objectively true and can be evidenced; the local-CI attestation and the +ready-for-review confirmation are theirs. Ask — do not tick them. + +## The finding worth keeping + +#2794 passed its focused suite 70/0 and still failed three CI shards. Five tests in +four other suites asserted `thoughtSignature === undefined` and the sentinel filled +it. The easy read was "stale assertions". Chasing *why* they disagreed found two real +defects: the replay cache ingested the sentinel as a genuine signature, and +`isLikelyRealThoughtSignature` — the predicate that exists to reject fabricated ids — +accepted it. + +**When a change breaks another suite, the question is not whether that test is stale. +It is what that test knew that you did not.** Twice here, the answer was a defect. + +## Standing gates, updated + +1. Compile and test evidence from the MERGED tree, never the PR head. +2. Pairwise `git merge-tree` before two PRs sharing a file both land. +3. Green checks are not health unless `ci` / `test N/4` / `macos` are present — and + on a fork PR, confirm the matrix actually **started**. +4. Green targeted suites are not health either; you chose the targets. +5. A rebase is verified by `patch-id` and `range-diff`, never by `git diff OLD NEW`, + which reports the whole intervening range. +6. Force-push to a fork only with `--force-with-lease` pinned to the author's OID, + to the author's remote, announced on the PR. +7. `gh run rerun` replays the same commit; only a rebase moves the base. +8. A gate that asks for human judgement (`maintainer-sponsored`) is not an obstacle + to route around. + +## Postscript: the review caught what green CI could not + +#2794 had 23 green checks, a 15352/0 full suite, and four mutation-verified fixes. +Ingwannu then found that `antigravitySupportsThoughtSignatureSentinel` scanned the +**entire raw replay identity** rather than the model component. The Vertex key is +`vertex:::` and the project id is operator-chosen, so: + +``` +vertex:gemini-prod:global:gpt-oss-120b -> true (Gemini-only sentinel injected) +vertex:gemini-team:us:claude-fable-5 -> true +``` + +That is the same defect class the predicate exists to prevent — a Gemini-only token +reaching a non-Gemini model — reintroduced one layer up, in the fix for it. + +**My tests could not have caught it.** Every Vertex case I wrote used a neutral +project name, so the positive control was doing double duty as the negative one. A +test suite written by the person who wrote the bug shares its blind spot; that is +what the review is for, and it is the third time in this campaign a reviewer found +something no amount of my own green output would have surfaced. + +Fixed by reducing to the model component (last `:` segment, then last `/` segment, +anchored) rather than widening or blacklisting. Mutation-verified: the whole-string +scan fails exactly the new regression. + +## Admin-merge authorization (2026-08-28) + +The user authorized `--admin` merges, which resolved the self-approval deadlock and +the author-attestation box. Four landed: **#2794** (`bdc1e97bb`), **#2747** +(`fe063d16e`), the round docs **#2806** (`7dd01bfdd`), and #2740 earlier. Each was +already fully green — the authorization removed a *process* gate, not a verification +one, and nothing merged that lacked evidence. + +#2770 was closed rather than merged: its branch predated six merges, so its diff +against current `dev` showed 2439 deletions. #2806 replaced it, cut from current +`dev`. #2745 was superseded by **#2807**, which carries the same fix rebased with +both review blockers closed. + +## Where the admin merge stopped, and why + +Two credential-path PRs were **not** merged despite the rights being available. + +**#2638** fails `hygiene` on `unsponsored_surface` naming `src/codex/auth-context.ts`. +That gate asks whether a human has reviewed a credential path; admin rights answer a +different question. The `maintainer-sponsored` label *is* the judgement being +requested, so applying it forges the gate rather than passes it. The author has since +added `fix(codex): fence retry entitlement refresh`, which closes a real window — the +initial auth selection releases its admission before the first response arrives, so a +profile switch could overlap credential discovery. Re-verified at the new head +`e06ffbaa8`: **272/0** focused, **15465/0** full suite, `tsc` exit 0. + +**#2807** is subtler and worth recording precisely. `hygiene` **passes** on it, because +`src/server/responses/core.ts` is not in `RESTRICTED_FILES` in +`.github/scripts/pr-sponsored-surface.cjs`. But `.github/CODEOWNERS:46` assigns that +exact file to `@lidge-jun`, and `MAINTAINERS.md:60` requires explicit security review +for credential handling — which is exactly what the diff does: it decides which origin +a rotated-to account's bearer is sent to. + +So the automated gate says yes and the written policy says no. **The gate is narrower +than the rule it encodes**, and a passing check is not permission when the rule it +exists to enforce plainly applies. I am both the author and the code owner, so there +is no second pair of eyes on this credential path either way. + +That asymmetry deserves fixing at the source: `src/server/responses/core.ts` belongs +in `RESTRICTED_FILES` if it belongs in CODEOWNERS' security boundary. Recorded as a +follow-up rather than changed here — widening a security gate mid-round, while holding +admin rights and an open PR that the widened gate would block, is exactly the kind of +self-serving edit that deserves its own reviewed change. + diff --git a/devlog/_plan/260828_cursor_ndjson_backlog_train/000_plan.md b/devlog/_plan/260828_cursor_ndjson_backlog_train/000_plan.md new file mode 100644 index 0000000000..158ccb84d4 --- /dev/null +++ b/devlog/_plan/260828_cursor_ndjson_backlog_train/000_plan.md @@ -0,0 +1,54 @@ +# 260828 cursor ndjson + backlog train — unit plan (P artifact, docs-only cycle wp1) + +Goal: (1) fix the consumer-backlog turn abort that killed a live Codex app turn +("stream disconnected before completion: consumer backlog exceeded — turn +aborted", incident 2026-08-28 ~01:55 KST during the branch-cleanup turn), and +(2) close the remaining cursor codex-exec defects from the 260826 gap campaign +with live NDJSON empiricism on macmini-cf, delivered as a stacked PR chain. + +## Loop-spec header + +- Archetype: spec-satisfaction repair (per-defect verifier: activation test + + live probe closure artifact). +- Trigger: user request — cursor commit lineage + macmini-cf codex-exec NDJSON + empiricism + stacked PRs until clean; plus RCA/fix of the backlog abort. +- Goal: backlog abort can no longer kill a healthy turn whose consumer + detached; every open cursor adapter defect has evidence-bound disposition. +- Non-goals: releases, main/preview promotion, credential rotation, closing + PRs outside this chain, model-class behavior fixes. +- Verifier per phase: bun test (repo-wide suite FORBIDDEN by + user; CI is the wide gate), macmini-cf probe transcripts + NDJSON rows, + gh pr view. Verifier commands run in each phase doc. +- Stop: stack published, closure probe round clean, or defect dispositioned + non-adapter-class with evidence. +- Memory artifact: this unit. +- Terminal outcomes: DONE / NOOP (all residuals non-adapter-class) / + BLOCKED (cursor upstream refuses probes) / NEEDS_HUMAN (account actions) / + BUDGET_EXHAUSTED (~8h wall clock). +- Escalation upward: a phase packet failing twice returns to main agent. + Downward: subagent lanes are read-only research/review; implementation + stays in the main session. +- HOTL bounds: writes confined to this worktree + macmini-cf ~/opencodex + + scratch dirs; push/PR pre-approved by user (codex/ branches, target dev, + --no-verify); sol-high subagent dispatch unlimited per user grant. + +## Work-phase map (dependency-ordered; goalplan wp ids) + +- wp1 (this cycle, docs-only): RCA + defect inventory + this roadmap. + Deliverables: 000, 001, 002, 010, 020, 030, 040. +- wp2 (010): backlog-abort fix in run-turn-queue/core — detached-consumer + classification + delta coalescing. Independent PR (stack base A). +- wp3 (020): macmini-cf live probe round — deploy dev + wp2 branch, drive + codex exec cursor sessions, capture NDJSON; prove/deny each open defect. +- wp4 (030): cursor instrumentation + evidence-bound fixes (stack B on wp2's + branch only if core files overlap, else parallel stack rooted at dev). +- wp5 (040): closure re-probe + devlog disposition + stack finalization. + +## Evidence base + +- 001: backlog-abort RCA (sol-high lane, file:line verified). +- 002: cursor open-defect inventory re-verified against origin/dev + (sol-high lane; supersedes 090/100 follow-up lists). +- macmini-cf: proxy 2.34.0 live (pid 43321, launchd com.opencodex.proxy), + ~/opencodex on dev (behind 34 at survey time), codex CLI present, + usage.jsonl 10679 rows. diff --git a/devlog/_plan/260828_cursor_ndjson_backlog_train/001_backlog_abort_rca.md b/devlog/_plan/260828_cursor_ndjson_backlog_train/001_backlog_abort_rca.md new file mode 100644 index 0000000000..30fee825d4 --- /dev/null +++ b/devlog/_plan/260828_cursor_ndjson_backlog_train/001_backlog_abort_rca.md @@ -0,0 +1,60 @@ +# 001 — consumer-backlog turn abort RCA (research) + +Incident: 2026-08-28 ~01:55 KST, Codex app turn (branch-cleanup thread) routed +through local proxy (xai/grok-4.6) died after repeated "Reconnecting /5" with +"stream disconnected before completion: consumer backlog exceeded — turn +aborted". Long turn (~12 min "Worked for 12m 21s"), many gh/git tool rounds. + +## Verified mechanism (sol-high audit, file:line checked) + +Producer/consumer chain: runTurnAdapter.runTurn(..., queue.push) -> +queue.stream() -> preflight (core.ts:4696-4709) -> empty-completion +guard/observer (core.ts:4711-4727) -> bridgeToResponsesSSE (bridge.ts:857-876; +HWM=1 documented at bridge.ts:1404-1410, demand-driven stepping happens in +pull() at bridge.ts:1465-1467) -> trackStreamLifetime (lifecycle.ts:439-449) +-> request-log wrapper (relay.ts:620-638) -> CORS Response -> Bun HTTP. +(Anchors re-verified by A-gate round 1; bridge stepping anchor corrected.) + +- guardTerminalEventStream is NOT on the runTurn path (only generic + fetch/parse path, core.ts:5648-5676). +- Cancellation: req.signal -> options.abortSignal (server/index.ts:1412-1418) + -> linkAbortSignal(runTurnAbort, ...) (core.ts:4535-4539); body cancel chain + relay.ts:633 -> lifecycle.ts:450 -> bridge.ts:1468-1477 -> onCancel aborts + runTurnAbort + closes queue (core.ts:4728-4733). Correct once Bun OBSERVES + the disconnect. +- Failure window: Bun reports a dead/reconnecting TCP consumer late (observed + 1-10s+, structure/04_transports-and-sidecars.md:620-624; app reconnect + storms can extend this). During that window the pull-driven bridge stops + consuming (that is by design), the producer keeps pushing token-granular + text/thinking deltas + heartbeats, and the queue hits maxBacklog=1024 + (run-turn-queue.ts:67-80) -> onBacklogExceeded -> runTurnAbort.abort() -> + synthetic terminal error that misattributes a CLIENT-side stall as a + provider/turn failure. + +## Root cause statement + +The 1024-event cap conflates two states it cannot distinguish: (a) a slow but +attached consumer (cap = legitimate safety valve) and (b) a detached/ +reconnecting consumer whose disconnect Bun has not yet delivered (cap = false +abort with a fabricated adapter error). Event-count granularity (per-token +deltas + heartbeats both count) makes (b) reachable within seconds on a +healthy turn. + +## Fix directions (audited; chosen mix in 010) + +1. PRIMARY: coalesce adjacent text_delta/thinking_delta and collapse pending + heartbeats at queue push time — bound the backlog by useful buffered work, + preserving phase boundaries, tool events, signatures, terminal ordering. +2. SECONDARY: on backlog trip, classify honestly — the consumer never read + the synthetic error anyway when detached; keep abort as safety valve but + the message/log should say consumer stalled, and detected body-cancel + must keep aborting promptly (existing chain, regression-guarded). +3. Rejected as primary: raising the cap alone (masks the race, more memory). + +## Existing coverage + +tests/run-turn-queue.test.ts:62-169 (overflow, ordering, preflight, +cancellation); tests/abort-race.test.ts:45-192 (overflow aborts signal in +buffered mode; explicit abort before late reader; terminal-continuation body +cancel). MISSING: streaming body left unread then cancelled; >1024 tiny +deltas with slow-but-attached consumer; coalescing semantics. diff --git a/devlog/_plan/260828_cursor_ndjson_backlog_train/002_cursor_open_defect_inventory.md b/devlog/_plan/260828_cursor_ndjson_backlog_train/002_cursor_open_defect_inventory.md new file mode 100644 index 0000000000..891b307472 --- /dev/null +++ b/devlog/_plan/260828_cursor_ndjson_backlog_train/002_cursor_open_defect_inventory.md @@ -0,0 +1,27 @@ +# 002 — cursor open-defect inventory (re-verified vs origin/dev 50e955604) + +Sol-high lane verdict, cross-checked against devlog 260826 docs 080-150. +Gap-campaign fixes 1-11 are ON origin/dev (checkpoint continuation, +empty-result explanation aee1cbd94, repetition breaker 35667bb7f, +envelope-echo 6503602c1/db37bc2fb/4433b7d19, routing-commentary a48f933e3/ +ab54fe6b0, desktop stdin 83cf732a5). PR #2769 (16cb875b8) is orthogonal +error-classification work — NOT the stack base. + +| # | Defect | Status | Fix surface | Evidence needed | +|---|---|---|---|---| +| 1 | Empty tool result in deep multi-round sessions | OPEN, boundary unknown | checkpoint suffix (request-builder.ts:472-478, protobuf-request.ts:915), inherited checkpoint state, tool-name aliases (tool-result-normalize.ts:108), native exec frames | correlated ingress -> normalization -> blob -> getBlobArgs -> SSE trace of one affected round | +| 2 | Flattened external replay loses structured agentic state | OPEN, partially mitigated | protobuf-request.ts:276 (reasoning/tool-call drop), request-builder checkpoint eligibility | deep-session probe proving checkpoint reuse without replay priming | +| 3 | Native shell zero-stdout reaches Cursor unexplained | OPEN, narrow | native-exec-shell.ts:125/:214 (ShellSuccess stdout:"", no stdout frame) | unsafe-enabled native session transcript | +| 4 | Blob "mar" token corruption | WATCH, unconfirmed | blob assembly if digests implicate | blob-integrity-mismatch repro | +| 5 | Double-batch echo | MODEL-class (W3 ruled out wire) | none | only if duplicate call IDs on wire | +| 6 | App-session image loop | APP-class/UNKNOWN | Codex app side | app-session capture | +| 7 | Shell-redirect instead of apply_patch | OPEN mixed policy | independent PR, own risk review | false-positive corpus | +| 8 | Fresh-conversation zero-output timeout | WATCH | transport only if reproduced | raw SSE trace | +| 9 | Premature final / strict N-call batch misses | MODEL-class | none | n/a | + +## Stack plan implication + +Adapter-fixable now: #1 boundary via instrumentation (wp4 phase 1), then the +proven fix (wp4 phase 2); #3 is a concrete small fix eligible for wp4 +regardless of #1 outcome. #2 replay fidelity stacks only if #1 implicates +replay. Everything else is disposition-with-evidence in wp5. diff --git a/devlog/_plan/260828_cursor_ndjson_backlog_train/003_roadmap_lock.md b/devlog/_plan/260828_cursor_ndjson_backlog_train/003_roadmap_lock.md new file mode 100644 index 0000000000..fa7df30352 --- /dev/null +++ b/devlog/_plan/260828_cursor_ndjson_backlog_train/003_roadmap_lock.md @@ -0,0 +1,14 @@ +# 003 — roadmap lock (wp1 B-phase closure note) + +Roadmap locked after A-gate round 1 (GO-WITH-FIXES blockers=13, all folded +in b15a17989). Goalplan work-phase map confirmed 1:1 with decade docs: + +| wp | decade doc | branch/PR | +|---|---|---| +| wp2 | 010_backlog_abort_fix.md | codex/runturn-backlog-coalesce -> dev | +| wp3 | 020_macmini_probe_round.md | no code; probe artifacts on macmini-cf | +| wp4 | 030_cursor_fixes.md (+031 if B2 arms) | codex/cursor-empty-result-trace | +| wp5 | 040_closure_round.md | stack finalization | + +Unresolved inputs deliberately deferred to wp3 evidence: zero-stdout marker +(N3 gate), B2 boundary fix (N1/N2 gate). wp1 tasks t1-t4 done. diff --git a/devlog/_plan/260828_cursor_ndjson_backlog_train/010_backlog_abort_fix.md b/devlog/_plan/260828_cursor_ndjson_backlog_train/010_backlog_abort_fix.md new file mode 100644 index 0000000000..46c93ff4a6 --- /dev/null +++ b/devlog/_plan/260828_cursor_ndjson_backlog_train/010_backlog_abort_fix.md @@ -0,0 +1,77 @@ +# 010 — wp2: backlog-abort fix (stack base A, PR vs dev) + +Branch: codex/runturn-backlog-coalesce (from origin/dev). One PR. + +## Diff-level changes + +### 1. MODIFY src/adapters/run-turn-queue.ts — push-time coalescing + +In createAdapterEventQueue push(): when no reader is waiting and the queue +tail exists: +- tail.type === "text_delta" && event.type === "text_delta" && identical + phase field (both undefined, or === — an omitted phase is a continuation + downstream (bridge.ts:922-925) but merge only on strict equality to stay + provably safe) -> REPLACE tail with a new object + { type:"text_delta", text: tail.text + event.text, phase: tail.phase }. + Never mutate pushed objects: push() has no ownership/copy contract + (run-turn-queue.ts:7-11) and adapters may retain/re-emit event objects — + interface-level alias safety, so replacement only (A-gate blocker 6). +- Coalescing threshold (A-gate round-2 blocker 1): merge only while + tail.text.length + event.text.length <= 64 * 1024 (UTF-16 code units — + a coalescing threshold, NOT a byte-memory cap; a single oversized + incoming event stays a single item, and byte-based caps remain out of + scope). Past the threshold, append as a new item. Same combined-length + rule for thinking merges. +- tail.type === "thinking_delta" && event.type === "thinking_delta" -> + merge thinking strings likewise (same replacement + byte-bound rules). +- event.type === "heartbeat" && tail.type === "heartbeat" -> drop event + (one pending heartbeat is enough). +- All other types append as today. Never merge across a non-delta boundary; + tool_call_delta is NOT coalesced (argument chunk order is load-bearing for + JSON reassembly but adjacent-merge would be safe — still excluded from + this PR to keep the diff minimal and provably safe). +- Backlog check unchanged (queued.length >= maxBacklog), but with coalescing + the count now approximates buffered ITEMS not tokens. + +### 2. MODIFY src/adapters/run-turn-queue.ts — honest overflow message + +Error message becomes "consumer stalled: adapter event backlog exceeded — +turn aborted" and the pushed error gains status/retryable hints untouched +(plain message error as today). Update the two tests asserting the string. + +### 3. Tests — MODIFY tests/run-turn-queue.test.ts + +- NEW: 5000 ADJACENT text_delta chunks (same phase) with no reader -> + backlog stays 1 merged item, no overflow, collect() returns exact + concatenation (activation for the text-merge branch). +- NEW: 5000 adjacent thinking_delta chunks -> 1 merged item, exact + concatenation (activation for the thinking-merge branch, A-gate blocker 3). +- NEW: byte-bound activation — chunks totalling >64KB split into 2+ items, + concatenation preserved across items. +- NEW: heartbeat collapse — 50 heartbeats no reader -> 1 queued heartbeat. +- NEW: interleaved text/tool/text does not merge across the tool event. +- NEW: phase transitions do not merge: "final"->"commentary", and + explicit-phase -> omitted-phase (undefined) stays separate (blocker 4). +- NEW: empty-string deltas merge without corrupting concatenation. +- KEEP: overflow still fires for 1024+ DISTINCT non-coalescible events + (tool_call_start floods) and the message assertion updated. + +### 4. MODIFY tests/abort-race.test.ts — the overflow flood at :56 uses +1025 text_delta events which coalescing would now merge; switch the flood +to non-coalescible events (tool_call_start with distinct ids) so the +abort-race contract still activates overflow (A-gate blocker 1), and sync +the message string (only three live refs exist: run-turn-queue.ts:76 + the +two test assertions; no runtime parser — blocker 7 verified). + +## Accept criteria + activation + +1. bun test tests/run-turn-queue.test.ts exit 0 (activation: coalesce tests + drive push path with no reader — the exact incident shape). +2. bun test tests/abort-race.test.ts exit 0. +3. Live: macmini-cf proxy on this branch survives a deliberately stalled + consumer (curl -N piped to sleep-heavy reader) for >60s of grok-4.6 + token streaming without turn abort; verified in wp3 probe round. + +## Out of scope + +Bun disconnect-latency itself (runtime-level), byte-based caps, bridge HWM. diff --git a/devlog/_plan/260828_cursor_ndjson_backlog_train/020_macmini_probe_round.md b/devlog/_plan/260828_cursor_ndjson_backlog_train/020_macmini_probe_round.md new file mode 100644 index 0000000000..51dfd2ca49 --- /dev/null +++ b/devlog/_plan/260828_cursor_ndjson_backlog_train/020_macmini_probe_round.md @@ -0,0 +1,69 @@ +# 020 — wp3: macmini-cf live probe round (NDJSON empiricism) + +Host: macmini-cf. Proxy: ~/opencodex, launchd com.opencodex.proxy, +port 10100. Codex CLI: ~/.bun/bin/codex (bun global bin). + +## Procedure + +1. Sync (A-gate blockers 11/12 folded): + - Environment: the host codex shim's shebang is "env node" and the + host has NO node on PATH — every probe command must prepend a node + shim (export PATH with bun's node alias, or "bun x codex"). VERIFY + "codex --version" works in the actual probe shell BEFORE claiming any + probe ran; a login-shell (ssh -t or zsh -lc) may differ from plain ssh. + - The user's ~/opencodex dev checkout is NEVER reset or cherry-picked. + Mandatory: dedicated probe worktree (git -C ~/opencodex worktree add + ~/ocx-probe-260828/wt from fetched refs). + - Deployment (A-gate round-1 fold, blockers 1-4): + * Probe proxy launcher: a direct Bun entry that imports startServer + (server/index.ts) on port 10199 — NOT "ocx start" (its CLI path + detects the 10100 owner and exits, and mutates launchd env / + startup integrations, cli/index.ts:204/:376, system-env.ts:261). + * Isolated homes: OPENCODEX_HOME=~/ocx-probe-260828/home and + CODEX_HOME=~/ocx-probe-260828/codex-home for the probe process AND + probe codex runs. Never share ocx.pid/runtime-port.json with the + primary (process-state.ts last-writer corruption). + * Credentials: copy config.json + auth.json into the probe home. + NO-REFRESH GATE: before probing, read cursor access-token expiry; + require remaining lifetime > planned probe window + 10min skew, + else abort (probe-side refresh could rotate the refresh token and + invalidate the PRIMARY, oauth/cursor.ts:205/:232). Hash primary + auth.json before/after and prove identical. + * codex invocation: per-command -c overrides, not OPENAI_BASE_URL: + codex exec --json -c 'model_providers.opencodex.base_url="http://127.0.0.1:10199/v1"' + -m cursor/grok-4.6 ... ; verify "codex exec --help" advertises + --json in the actual login shell first. + * Capture contract: per-run files N/run-XX.{command.txt, + stdout.ndjson,stderr.log,exit}; probe-home usage.jsonl snapshots + (never tail the primary's). + * Pre/post primary evidence: branch, SHA, porcelain status, 10100 + /healthz, launchd state, sha256 of primary config.json + auth.json + + ~/.codex/config.toml. Teardown: kill probe PID (verify its + command/cwd first), prove 10199 closed + 10100 healthy, git + worktree remove + git worktree list proof, keep evidence dir. +2. Probe matrix (codex exec --json -m cursor/grok-4.6 unless noted), scratch + cwds under mktemp -d, transcripts + NDJSON to ~/ocx-probe-260828/: + - N1 5-step chain (090 S4 shape): mkdir/write/read/compute/verify — the + empty-tool-result trigger scenario. >=6 runs to chase the intermittent + empty delivery; capture codex exec --json event stream per run. + - N2 deep checkpoint session: >=8 tool rounds same thread (exercises + checkpoint suffix path request-builder.ts:472). + - N3 zero-stdout commands (true; mkdir; export) — defect #3 activation. + N3 FIRST records how Cursor renders/forwards empty stdout on both the + unary and streaming channel; the 030 marker ships ONLY if this + evidence shows the model receives an unexplained blank (A-gate + blocker 9 — no pre-committed fix). + - N4 stalled-consumer live check for wp2 (curl -N | slow reader). + - N5 usage.jsonl integrity tail — schema + usageStatus after rounds. + - Controls: same probes via xai/grok-4.6 where defect could be + model-class. +3. Evidence per probe: command, exit, NDJSON line excerpts (event types, + call ids, output byte counts), usage.jsonl rows, PASS/FAIL vs expected. + +## Decision gate feeding wp4 + +- Empty result reproduced with NDJSON showing nonempty local result but + model-visible blank -> adapter boundary per 002 #1 -> wp4 instrumentation + phase targets the implicated stage. +- Not reproduced in >=6 N1 runs + N2 -> defect #1 downgraded to WATCH with + bounds recorded; wp4 ships #3 fix + instrumentation only. diff --git a/devlog/_plan/260828_cursor_ndjson_backlog_train/021_probe_results_round1.md b/devlog/_plan/260828_cursor_ndjson_backlog_train/021_probe_results_round1.md new file mode 100644 index 0000000000..eeb74812a9 --- /dev/null +++ b/devlog/_plan/260828_cursor_ndjson_backlog_train/021_probe_results_round1.md @@ -0,0 +1,53 @@ +# 021 — wp3 probe results, round 1 (macmini-cf, 2026-08-28 02:34-02:50 KST) + +Stack under test: probe proxy 2.35.0 = origin/dev + codex/runturn-backlog-coalesce +(4cd1b99f0), port 10199, isolated OPENCODEX_HOME/CODEX_HOME +(~/ocx-probe-260828/{home,codex-home}), launchd 10100 untouched. +Instrument: codex exec --json -m cursor/grok-4.6 (codex-cli 0.146.0). +Evidence: macmini-cf ~/ocx-probe-260828/evidence/{N1,N2,N3,N4,SMOKE}/. + +## Results + +| Probe | Runs | Result | Evidence | +|---|---|---|---| +| SMOKE | 1 | PASS | "probe-ok", 17245 in / 13 out tokens | +| N1 5-step chain | 6 | 4 PASS / 2 anomalies | run-01/02/04/05: avg=84, 10-24 cmdexec, 0 restarts. run-03: task COMPLETED (avg=84) but see F1/F2/F3. run-06: premature final after 2 calls, no task output (F4) | +| N2 10-step chain | 1 | PASS | all files correct, 24 cmdexec | +| N3 zero-stdout x3 | 1 | PASS | bridge empty-result marker delivered verbatim for all 3 empty outputs; model quoted it and stayed on track — gap-7/8 fix healthy on the wire | +| N4 stalled consumer 60s | 1 | PASS | 509KB SSE buffered behind a 60s-stalled reader, 4560 output_text.delta, response.completed arrived, NO backlog abort — wp2 coalescing fix live-validated (pre-fix cap = 1024 events) | + +## Findings + +- F1 (adapter, NEW): mid-message envelope echo evades the sniffer. run-03's + agent_message contains THREE verbatim "[Tool Result] [tool_result] + call_id: ... name: exec ... output: ..." blocks INSIDE the message body. + CursorEnvelopeEchoSniffer (envelope-echo.ts) sniffs only the FIRST + MAX_SNIFF_BYTES=40 of a turn's output; an echo after legitimate leading + text streams straight to the client. Fix surface: newline-anchored + mid-stream marker detection. +- F2 (adapter/upstream, watch item #4 CONFIRMED ON WIRE): call-id corruption + inside an echoed envelope: "fc_63367283 mar-2aec-9a25-b7df-9b125bd8d1b5_0" + vs the correct "fc_63367283-2aec-9a25-b7df-9b125bd8d1b5_0" later in the + SAME message — "-" replaced by " mar-". The corruption is in what the + model SAW (replayed flattened history), matching 080's "mar" signature. + Boundary still unknown (our serializer vs Cursor blob store vs model + echo-typo): needs the 030 trace instrumentation. +- F3 (env, transient): mid-run "Cursor rate limit exceeded: Connect error + resource limit exceeded" -> Codex reconnect 1/5 -> turn recovered and + completed. Honest error surface; no adapter defect. +- F4 (model-class): run-06 ended turn after loading a skill file and + announcing step 1 — premature final matching inventory #9; no adapter fix. +- Empty tool-result delivery (inventory #1): NOT reproduced in 6 N1 runs + + N2 + N3 (bridge marker arrived intact every time). Remains bounded to + deeper checkpoint sessions; N2-class deep probing continues in wp5 + closure round on the patched stack. +- Zero-stdout native marker (030 conditional): N3 proves the BRIDGE path + explains empties correctly; the native unsafe channel was not exercised + (policy-gated). 030's native marker stays CONDITIONAL and is NOT shipped + this round. + +## wp4 implication + +PR B1 = F1 fix (mid-stream echo detection + retry wiring reuse) + F2 trace +instrumentation (call-id/byte/digest correlation, env-gated). Native marker +deferred. Diff spec: 031. diff --git a/devlog/_plan/260828_cursor_ndjson_backlog_train/030_cursor_fixes.md b/devlog/_plan/260828_cursor_ndjson_backlog_train/030_cursor_fixes.md new file mode 100644 index 0000000000..999065b4fb --- /dev/null +++ b/devlog/_plan/260828_cursor_ndjson_backlog_train/030_cursor_fixes.md @@ -0,0 +1,53 @@ +# 030 — wp4: cursor fixes from probe evidence (stacked) + +Branch: codex/cursor-empty-result-trace (stack root: dev, or wp2 branch only +if run-turn-queue files overlap — expected NOT to overlap). + +## PR B1: correlated empty-result instrumentation (+ zero-stdout marker, +## conditional on wp3 N3 evidence — A-gate blocker 9) + +### 1. MODIFY src/adapters/cursor/native-exec-shell.ts (CONDITIONAL: build +### only if wp3 N3 proves the model sees an unexplained blank) + +- shellExec success with stdout === "" and stderr === "" -> stdout becomes + "(command completed with no output; exit 0)" — mirrors the bridge-side + empty-result explanation (tool-result-normalize.ts:108) so the model never + sees an unexplained blank on the native channel. Guard: only when exit + code 0 and both streams empty; non-zero exits keep real streams. +- shellStreamExec: when no stdout frame was emitted, emit one synthetic + stdout frame with the same marker before exit/shellResult/streamClose. + +### 2. ADD debug trace (env-gated OCX_CURSOR_TRACE_TOOL_RESULTS=1) + +Env-gate convention (A-gate blocker 10): no OCX_* env reads exist under +src/adapters/cursor today; follow the repo's central pattern used by +OCX_EMPTY_COMPLETION_RETRY (rg it in src/server/responses/core.ts / +src/config) — read once at module or call-site with an explicit +disable/enable contract, documented in the PR. Digests: sha256 hex +truncated to 12 chars, computed over result bytes only (no content logged). + +- tool-result-normalize.ts: log requestId, tool name, pre/post byte counts, + changed, isError (no content bodies — privacy:scan constraint). +- protobuf-request.ts suffix path: continuationMode, coveredCount, + suffixStart, per-blob byte count + sha256 prefix. +- native-exec.ts getBlobArgs: served byte count + integrity result already + exists — extend log line with digest prefix. + +### 3. Tests + +- MODIFY tests/cursor-native-exec-shell.test.ts (existing file, A-gate + blocker 8): zero-stdout marker on both exec paths; non-zero exit + untouched; marker absent when stdout nonempty. (Only if marker ships.) +- Trace lines: focused test asserting no content bytes are logged (privacy). + +## PR B2 (conditional): the boundary fix probe evidence proves + +Written after wp3; candidates per 002 #1: checkpoint reserialization of +inherited empty results / alias coverage / replay fidelity. Diff spec added +here as 031 before build (P-phase amendment of the next cycle). + +## Accept criteria + +bun test exit 0; macmini-cf re-probe shows marker +arriving upstream (N3 re-run); privacy scan of touched files via focused +check; PR template complete. diff --git a/devlog/_plan/260828_cursor_ndjson_backlog_train/031_midstream_echo_fix.md b/devlog/_plan/260828_cursor_ndjson_backlog_train/031_midstream_echo_fix.md new file mode 100644 index 0000000000..155a5ce06c --- /dev/null +++ b/devlog/_plan/260828_cursor_ndjson_backlog_train/031_midstream_echo_fix.md @@ -0,0 +1,96 @@ +# 031 — wp4 diff spec: mid-stream envelope-echo detection (PR B1) + +Evidence base: 021 F1/F2 — run-03 (macmini-cf) streamed three verbatim +"[Tool Result] [tool_result] call_id: ... output: ..." blocks INSIDE an +agent message, after legitimate leading text. The existing +CursorEnvelopeEchoSniffer stops looking after the first 40 bytes of the +turn (envelope-echo.ts MAX_SNIFF_BYTES), so mid-message echoes reach the +client uncorrected. One echoed block also carried the corrupted call-id +"fc_63367283 mar-2aec-..." (F2, 080's "mar" signature) — the model is +echoing the flattened replay envelope it was primed with. + +## Branch/PR + +Stays on the current stack: branch codex/cursor-midstream-echo, based on +codex/runturn-backlog-coalesce head (stacked PR; base PR #2774 targets +dev, this PR targets codex/runturn-backlog-coalesce until #2774 lands). +Rationale: same devlog unit carries both; no src overlap, but the devlog +history is linear on this chain. + +## Changes + +### 1. MODIFY src/adapters/cursor/envelope-echo.ts — mid-stream detector + +ADD class CursorMidstreamEchoObserver (A-gate blockers 1/3/4 folded): +- DIAGNOSTIC-ONLY: feed(textDelta) NEVER throws and never withholds + output. It returns void; findings are exposed via a findings() getter + read by the caller at turn end (and opportunistically after each feed). +- Detection: maintain lastLineStartBuffer — the text since the most + recent newline, capped at 128 chars (indentation beyond that disarms + matching for that line; bounds the \s* concern). A marker fires when + the post-newline line, after <=128 chars of leading whitespace, starts + with "[Tool Result]", "[tool_result]", or "[Tool Error]", at an offset + BEYOND the prefix-sniffer window. Marker split across deltas is handled + naturally because the line buffer accumulates across feeds. +- Corruption observation: after a marker fires, the observer enters a + post-marker window (next 512 chars) watching for the call-id lines. It + records callIdCorrupt=true when the window contains /fc_[0-9a-f]+\s+mar-/ + (the observed "space + mar-" splice) or a call_id line whose token is + split by whitespace (/call_id: \S+\s+\S+_0/). Only booleans and + numeric offsets are retained; window text is discarded after the check. +- findings(): { echoes: Array<{ marker, offset, callIdCorrupt }> } — + capped at 8 entries per turn. +- Bound: scanning disarms after MAX_MIDSTREAM_SCAN_LENGTH = 512 * 1024 + UTF-16 code units of cumulative fed text. A delta crossing the cap is + scanned up to its end (the cap is checked between feeds, not mid-delta), + so text before the boundary is never skipped. + +### 2. MODIFY src/adapters/cursor.ts — arm + exactly-once feeding + +- Arm CursorMidstreamEchoObserver under the same armEchoSniffer condition. +- Exactly-once feed (A-gate blocker 2): introduce one helper + emitTextObserved(event) that (a) feeds observer.feed(event.text) then + (b) emits. BOTH release paths route through it: releaseGuardHeld()'s + per-held-event emit for text deltas, and the ordinary post-guard emit at + cursor.ts:~324. Held deltas are NOT fed while held — only on release — + so no double-feed is possible. +- At turn end (done event handling, before final emit): read + observer.findings(); for each finding emit debugProviderDiagnostic + ("cursor", "midstream-envelope-echo", { wireModel, conversationHash: + request.conversationId.slice(0,16), offset, marker, callIdCorrupt }). + marker stays a fixed enum string; no content bytes logged (audit + finding 6 conventions). + +### 3. MODIFY tests/cursor-envelope-echo-retry.test.ts (named activation +### tests, A-gate blocker 5 — one per conditional branch) + +- "midstream echo after leading text is recorded with marker and offset" + (run-03 specimen block as fixture). +- "midstream corruption window flags a space-spliced mar call-id" + (callIdCorrupt=true) and "clean call-id lines do not flag corruption" + (callIdCorrupt=false). +- "a marker fragmented across delta boundaries still fires" (feed + "[Tool Res" then "ult]\n..."). +- "a mid-line marker mention does not fire" (negative). +- "indentation beyond the 128-char line cap disarms that line" (negative). +- "scanning disarms past the cumulative cap but keeps prior findings". +- "held-then-released deltas are fed exactly once" (adapter-level test via + the existing transport harness: prefix-guard hold + release, observer + offset arithmetic proves single feed). +- KEEP: all existing prefix-sniffer tests unchanged. + +## Accept criteria + activation + +1. bun test tests/cursor-envelope-echo-retry.test.ts exit 0; activation = + the mid-stream specimen from run-03 (verbatim block pasted as fixture) + fires the detector; line-start anchoring proven by negative case. +2. bun run typecheck exit 0. +3. Live (wp5): re-run N1 x6 on patched stack; any echo occurrence now + appears in probe-proxy.log as midstream-envelope-echo diagnostic with + callIdCorrupt evidence — closing the F2 observability gap. + +## Out of scope + +Retry/suppression for already-streamed echoes (user-visible behavior +decision), native zero-stdout marker (stays conditional), checkpoint +reserialization. diff --git a/devlog/_plan/260828_cursor_ndjson_backlog_train/040_closure_round.md b/devlog/_plan/260828_cursor_ndjson_backlog_train/040_closure_round.md new file mode 100644 index 0000000000..ba382b28ea --- /dev/null +++ b/devlog/_plan/260828_cursor_ndjson_backlog_train/040_closure_round.md @@ -0,0 +1,46 @@ +# 040 — wp5: closure re-probe + disposition + +1. macmini-cf: deploy full stack (dev + wp2 + wp4 branches merged locally in + probe worktree), restart, /healthz version check. +2. Re-run N1-N5 + 090's S1-S5 scenario shapes; every class must PASS or + carry a non-adapter-class disposition with NDJSON evidence. +3. Record closure artifacts in this doc: per-defect table (defect -> + pre-fix artifact -> fix SHA -> post-fix artifact -> disposition). +4. Finalize stack: retarget children if parents merged; ensure every PR + description names probe artifacts; devlog unit updated; goalplan criteria + c1-c5 capturedEvidence filled. +5. D closes goal only when cxc loop validate passes (E8). + +## Closure results (2026-08-28 09:58-10:23 KST, stack 286a1e5a5 + a652f0dfe) + +Probe proxy 2.35.0 on 10199 (isolated homes, OCX_DEBUG=1), evidence in +macmini-cf ~/ocx-probe-260828/evidence/N5/. + +| Run | Result | Evidence | +|---|---|---| +| c1 5-step | PASS | avg=84, 24 cmdexec, 0 reconnects | +| c2 5-step | PASS | avg=84, 32 cmdexec, 0 reconnects | +| c3 5-step | TASK PASS / TURN STALL | all 5 steps done (avg=84 read at item_28/32) across repeated upstream H2 resets (NGHTTP2_INTERNAL_ERROR, honest no-retry after committed output, reconnect recovery worked); after final step the turn sat in a getBlobArgs/setBlobArgs frame loop and never emitted turn.completed; killed after ~20min. Capture: run-c3.stall-capture.txt. Matches inventory #8/080 stall class — upstream/blob-sync, bounded, now with frame-level capture | +| c4/c5 | NOT RUN | batch serialized behind c3 stall; killed with it. Coverage for their shapes exists in wp3 round 1 (N1 x6, N3) | +| midstream diagnostics | 0 fired | no echo occurred in this round (expected: F1 was 1-in-6 in round 1); detector verified by 17 unit/adapter tests instead | + +## Teardown + restoration proof + +- Probe proxy killed; 10199 closed; 10100 healthy (2.34.0 pid 43321). +- Worktree removed (git worktree list = 1); primary repo dev @ 802f04adc, + porcelain clean — identical to pre-state. +- Cursor credential NOT rotated (expiry 1792555734000 unchanged pre/post). + Primary auth.json/config.toml hashes moved only via the primary launchd + proxy's own token refresh + codex config injection during the window; + probe-side copies were isolated and are retained in evidence. + +## Per-defect disposition (final) + +| Defect | Disposition | Evidence chain | +|---|---|---| +| Backlog false-abort | FIXED (PR #2774) | RCA 001 -> repro tests -> 4cd1b99f0 -> N4 live: 509KB/4560 deltas behind 60s stall, 0 aborts | +| Mid-stream envelope echo (F1) | OBSERVED->INSTRUMENTED (PR #2795) | run-03 wire capture -> CursorMidstreamEchoObserver + 8 tests; retry semantics deliberately deferred | +| mar call-id corruption (F2) | INSTRUMENTED (PR #2795) | first wire capture in run-03; callIdCorrupt flag now fires on live echoes | +| Empty tool-result (inv #1) | NOT REPRODUCED (10 runs) | bridge marker intact in every N1/N3 run; remains WATCH bounded to deep checkpoint sessions | +| Turn stall (inv #8) | CAPTURED, upstream-class | c3 frame loop capture; adapter surfaced honest errors; fix surface is upstream blob sync — no speculative adapter patch | +| Double-batch echo / image loop / premature final (inv #5/6/9) | MODEL/APP-class | unchanged from 100/021 dispositions | diff --git a/devlog/_plan/260828_cursor_ndjson_backlog_train/050_merge_train.md b/devlog/_plan/260828_cursor_ndjson_backlog_train/050_merge_train.md new file mode 100644 index 0000000000..74e9afb548 --- /dev/null +++ b/devlog/_plan/260828_cursor_ndjson_backlog_train/050_merge_train.md @@ -0,0 +1,61 @@ +# 050 — cursor PR merge train (wp map for the merge-round loop) + +User instruction (2026-08-28): merge the cursor rounds one at a time; the +instruction is the maintainer approval for these session-authored PRs. + +## Rounds (dependency-first) + +| R | PR | head | gate | +|---|---|---|---| +| R1 | #2774 backlog coalesce | codex/runturn-backlog-coalesce 286a1e5a5 | checks 25 SUCCESS + 1 SKIPPED — green; sol-medium pre-merge review | +| R2 | #2795 midstream echo | codex/cursor-midstream-echo | retarget to dev post-R1; CI re-run green | +| R3 | #2769 failed_precondition | codex/claude-classified-error-status 16cb875b8 | checks green; review | +| R4 | #2801 umbrella core | codex/cursor-umbrella-core 54965ef03 | CI FAIL: test 1/4 update-stop-first launcher-recovery timeout (46.8s, waitForProxy false) — UNRELATED to catalog diff (no update/launcher files touched); same infra-flaky class dev itself shows (dev run 33134096643 fails a different macos test). Gate: causal fix or evidence-backed unrelated-flake disposition + fresh green run; never rerun-until-green without a cause | +| R5 | #2802 umbrella wire | codex/cursor-umbrella-wire | retarget to dev post-R4; CI green | + +## Per-round procedure + +1. Exact head SHA + full check rollup via gh. +2. sol-medium reviewer: independent diff review, VERDICT line. +3. Blockers folded or rebutted with rationale; repairs get focused tests. +4. gh pr merge --squash --delete-branch; record merge SHA. +5. Child retarget (gh pr edit --base dev) + verify checks restart. +6. Post-merge: origin/dev log + no new cursor-test failures. + +## Round log + +- R1 (#2774): reviewer PASS (Tesla, sol-tier; coalescing phase-safe, consumers + checked). MERGED squash 5511a424c via --admin (user merge instruction = + maintainer approval; branch policy requires review). Head branch deleted. + SIDE EFFECT: base deletion auto-closed stacked #2795, which GitHub cannot + reopen (base ref gone). Recovery: cherry-picked 58ee805/a652f0d/e167311 + onto origin/dev (990a83f5e; 17 tests + tsc green on rebased head), + force-pushed the branch, opened successor PR #2803 vs dev. + LESSON for R4/R5: retarget the child to dev BEFORE merging the parent with + --delete-branch, or merge parent without branch deletion. +- R2 (#2803, successor of #2795): CI 23 ok / 0 fail (CodeRabbit status + marker non-required); prior audits stand (cherry-pick clean). MERGED + squash via --admin, branch deleted. +- R3 (#2769): reviewer PASS (Avicenna; precedence + claude derivation + + 72 focused tests + clean merge simulation). MERGED squash via --admin, + branch deleted. +- R4 (#2801): CI failure root-caused by investigator (Zeno): update-stop-first + 45s readiness deadline exhausted on loaded runners (46-47s failures on 4+ + unrelated PRs; catalog diff has no launcher imports, isolated shard). + Causal fix 22c073e03 raised the deadline to 90s (derived budget + pinned + arithmetic keep it honest). Fresh CI fully green (0F, macos SUCCESS). + MERGED squash 7232a60a7. #2802 retargeted to dev BEFORE branch deletion + (R1 lesson applied) — but the parent squash still made the old chain + CONFLICTING; wire branch cherry-picked onto dev (874f59734, 116 tests + + tsc green) and force-pushed; #2802 stayed OPEN base=dev. +- R5 (#2802): fresh CI on the rebased head fully green (0F, macos SUCCESS). + MERGED squash fbb5b0216, branch deleted. + +## Train outcome: DONE + +All five cursor PRs landed on dev: #2774 5511a424c -> #2803 922d53424 +(successor of #2795) -> #2769 1e46430e3 -> #2801 7232a60a7 (with causal +flake fix 22c073e03) -> #2802 fbb5b0216. No open cursor PRs remain; all +train branches deleted. Squash-merge over a stacked child invalidates the +child's chain even after retargeting — cherry-pick onto dev is the reliable +restack (applied twice: R2, R4->R5). diff --git a/devlog/_plan/260828_cursor_umbrella_catalog/000_plan.md b/devlog/_plan/260828_cursor_umbrella_catalog/000_plan.md new file mode 100644 index 0000000000..b6ce8991fe --- /dev/null +++ b/devlog/_plan/260828_cursor_umbrella_catalog/000_plan.md @@ -0,0 +1,25 @@ +# 260828 cursor umbrella catalog — unit plan (wp1 docs-only) + +Goal: collapse the 69-row hand-maintained cursor picker into per-base umbrella +rows (thinking merged, fast inside, 1M/Max-Mode generalized), sourced from a +single capability module informed by senpi's architecture but cleaner. + +## Loop-spec + +- Archetype: spec-satisfaction. Verifiers per phase: bun test , tsc, + privacy scan, catalog sync output row counts. Repo-wide suite forbidden. +- References: senpi (scratch path in /tmp/senpi-scratch.txt) — capability + table/grouping/selection cited in 001; omo-ai@beta has NO cursor model map + (verified — provider-map.json is a provider-name alias list only). +- Non-goals: other providers, releases, protobuf schema changes. +- Bounds: ~10h wall; stacked PRs codex/* -> dev pre-approved, --no-verify ok, + unlimited subagents (sol + xai/grok-4.6). +- Terminal: DONE per goalplan c1-c5; NEEDS_HUMAN for user-visible id renames + beyond aliasing. + +## Work-phase map + +- wp1 docs (this cycle): 000-002 research + 010/020/030 decade docs. +- wp2 (010): capability core module + variant grammar + umbrella grouping. +- wp3 (020): catalog integration (discovery/registry/sync/request path). +- wp4 (030): closure — cleanliness comparison + picker proof + stack final. diff --git a/devlog/_plan/260828_cursor_umbrella_catalog/001_reference_analysis.md b/devlog/_plan/260828_cursor_umbrella_catalog/001_reference_analysis.md new file mode 100644 index 0000000000..e7b1489c86 --- /dev/null +++ b/devlog/_plan/260828_cursor_umbrella_catalog/001_reference_analysis.md @@ -0,0 +1,37 @@ +# 001 — senpi/omo architecture analysis (sol-high lane, verified) + +## senpi (packages/ai/src/cursor/*) + +- CURSOR_MODEL_CAPABILITIES (model-capabilities.ts:81-195): 34 capability ids, + schema { evidence, window, maxWindow?, parameterOrder, defaultContext?, + requestContext?, levels: {level -> {value, encoding: parameters|variant-id}} }. + Claude order [thinking,context,effort]; GPT [context,reasoning,fast]. + 1M via requestContext="1m" when window>=1M. +- Variant grammar (model-capabilities.ts:204-248): strip terminal -fast; then + -thinking- | --thinking | -thinking | -; tokens + minimal|low|medium|high|extra-high|xhigh|max|none. +- Grouping (catalog-grouping.ts): group key = targetId + fast — FAST IS A + SEPARATE GROUP; Claude-only thinkingMode split (isClaude guard :45-47); + members with efforts collapse to one entry with thinkingLevelMap; 336-row + generated alias JSON maps live ids -> {targetId, level, legacyVariantId}. +- Wire (selection-descriptor.ts:85-120): alias-first — send catalog-served + suffix id when known (Cursor Run rejects bare capability ids with Connect + not_found, issue #1008); parameters fallback only when no alias; fast + parameter hardcoded "false" (fast reachable only via separate fast ids). +- Discovery (cursor-agent.ts:4362-4495): 1M inferred from display-name /\b1m\b/i + labels OR maxMode on /claude|gemini/ ids; reads thinkingDetails for + reasoning flag; multimodal from id pattern. + +## senpi weaknesses (our targets) + +1. Fast modeled twice (parameter always false + separate groups) — incoherent. +2. Claude-only thinkingMode split — separate thinking identities remain rows. +3. Truth split across static TS table + 336-row generated JSON + name regex. +4. variant-id fallback silently degrades to representative id. + +## omo-ai@beta + +provider-map.json contains ZERO cursor model rows (cursor only in +builtinProviderIds; 5 provider-name aliases). Cursor architecture is delegated +to its pinned senpi runtime. Nothing to adopt beyond "don't do this" — +objective's cleanliness bar vs omo is met by having any self-contained map. diff --git a/devlog/_plan/260828_cursor_umbrella_catalog/002_current_surface.md b/devlog/_plan/260828_cursor_umbrella_catalog/002_current_surface.md new file mode 100644 index 0000000000..b570f5d2a7 --- /dev/null +++ b/devlog/_plan/260828_cursor_umbrella_catalog/002_current_surface.md @@ -0,0 +1,21 @@ +# 002 — current opencodex cursor surface (grok-4.6 lane, verified) + +- effort-map.ts (229 L): CURSOR_MODEL_EFFORT_TIERS 46 hand-kept ids; + CURSOR_THINKING_FAMILIES 13 ids with per-family wire order; consumers: + discovery.ts + request-builder.ts only. +- discovery.ts: 69-row static seed (4 router + 52 + 13 thinking); + inferCursorContextWindow (:27-38) hardcodes per-family windows; synthetic + ultra marker = kimi-k3-1m ONLY (:158-174); live merge is a FILTER (45 of 69 rows carry ladders; quarantined opus-5 is a map key but not seeded) (never + adds rows, provider-fetch.ts:1276); claude-opus-5 quarantined; dead + CURSOR_REASONING_EFFORTS const. +- live-models.ts: decode keeps modelId + maxMode only; DISCARDS displayName, + displayNameShort, displayModelId, aliases, thinkingDetails; maxModeModels + returned but unconsumed. +- sync.ts/effort.ts: picker rows cursor/, efforts via + cursorModelReasoningEfforts; synthetic max+ultra appended (effort.ts:219); + kimi-k3-1m default effort falls to high (not pinned). +- request path (request-builder.ts:189, protobuf-request.ts:996): suffix-id + first; parameters only for grok-fast / router level / maxMode(ultra); + thinkingDetails never sent. +- Duplicate rows today: 13 thinking + 7 fast + 2 x 1m = 22 of 69 are variants + of a base. diff --git a/devlog/_plan/260828_cursor_umbrella_catalog/003_design.md b/devlog/_plan/260828_cursor_umbrella_catalog/003_design.md new file mode 100644 index 0000000000..cad09fbbe8 --- /dev/null +++ b/devlog/_plan/260828_cursor_umbrella_catalog/003_design.md @@ -0,0 +1,76 @@ +# 003 — umbrella design (locks the shape both implementation phases build) + +## Principles (beats senpi where it is weak) + +1. ONE source of truth: a single capability module owns the variant grammar, + per-base levels, thinking/fast/1M dimensions, and wire encoding. No second + generated alias JSON (senpi weakness 3): aliases are DERIVED by the grammar, + not enumerated. +2. Thinking MERGES into the base identity for every family (no Claude-only + split — senpi weakness 2) AS A DIMENSION, not by discarding identities + (A-gate blocker 1): the capability schema carries per-variant ladders + ({ regular?, thinking?, fast?, thinkingFast? } each with its own effort + list + wire order), because live ladders differ (claude-opus-5-fast + low/med/high vs thinking-fast low..max). The UMBRELLA ROW defaults to the + thinking variant when one exists (user decision: "thinking 하나로 합치고"); + regular/fast/thinking-fast remain reachable via aliases that select the + variant dimension explicitly. resolveCursorSelection takes the PICKED id + (which encodes the variant via the alias) — never guesses. +3. Fast is a dimension INSIDE the umbrella (senpi weakness 1): no fast picker + rows; cursor/-fast stays routable as an alias that sets fast mode on + the same umbrella identity. +4. 1M split into TWO separate capabilities (A-gate blocker 4 — window size + does NOT imply maxMode; prior probes found maxMode only on opus-fast + variants, 260822_senpi_cursor_transfer/210+310): + - window: context-window METADATA generalized per senpi's table (1M for + claude/gemini/kimi/gpt-5.6 families) — display/routing metadata only. + - maxMode (ultra rung): gated on EVIDENCE — the union of live + maxModeModels (decoded in live-models.ts:123-136, discarded by + provider-fetch today) and an explicit verified static list (currently + exactly kimi-k3, user-verified). Ultra generalizes automatically as live + evidence arrives, never from window size. +5. Back-compat absolute (A-gate blockers 2/3): + - Parser precedence: EXACT known identity/alias table first (covers + gpt-5.1-codex-max-as-base, gpt-5.5-extra, claude-4-sonnet-1m real wire + id), then cursor- prefix normalization (cursor-grok-4.5/4.6 wire forms), + then suffix grammar. A frozen fixture table pins parse+resolve for all + 69 picker ids + observed prefixed/suffixed wire forms. + - Alias retention contract: picker ROWS shrink, but the REQUEST path keeps + resolving every legacy slug (router forwards provider-qualified ids to + the adapter, router.ts:673-678; the adapter's resolver owns aliases). + A pinned session/config naming a removed slug keeps routing identically; + only fresh picker lists shrink. Tested explicitly (020). + - Quarantine is VARIANT-specific: claude-opus-5 regular stays quarantined + while thinking/fast siblings remain selectable. + +## Picker shape (after) + +- Rows: 4 router + ~30 base umbrellas (from 69). Efforts per row from the + default-variant ladder. Synthetic max+ultra spawn-validation appendage + (effort.ts:219-226) is a SEPARATE policy from wire ultra: effort.ts stays + in the diff (blocker 5) — synthetic max/ultra continue to be appended for + spawn validation on every reasoning row (no downstream break), while the + WIRE maps ultra to maxMode only for evidence-gated bases and clamps to the + ladder top elsewhere (exactly today's clamp behavior). +- Codex effort -> wire: suffix-id-first (Cursor rejects bare capability ids, + senpi #1008 confirmed + our own request-builder already suffix-first). + Thinking-capable base + effort E -> thinking wire id at E (family wire + order preserved from CURSOR_THINKING_FAMILIES). ultra -> base ladder top + + maxMode=true. Fast alias -> {stem}-{E}-fast. + +## Module plan + +- NEW src/adapters/cursor/catalog.ts: capability table (schema: + { levels: readonly string[], thinking?: { wireOrder }, fast?: true, + bigContext?: true, window, quarantined?: true }), parseCursorVariantId + (senpi grammar: strip -fast; -thinking- | --thinking | -thinking + | - | -1m), resolveCursorSelection(baseOrAlias, codexEffort) -> + { wireId | wireBase+params, maxMode, fast }, umbrellaCatalog() -> + picker rows. effort-map.ts becomes a thin re-export shim during wp2 and is + DELETED in wp3 once consumers move. + +## NEEDS_HUMAN boundary + +Picker row ids stay cursor/ (already true for bases). Removing separate +thinking/fast/1m ROWS changes what the picker lists but not what routes — +within the user's explicit instruction, so not escalated. diff --git a/devlog/_plan/260828_cursor_umbrella_catalog/004_roadmap_lock.md b/devlog/_plan/260828_cursor_umbrella_catalog/004_roadmap_lock.md new file mode 100644 index 0000000000..10f79165ae --- /dev/null +++ b/devlog/_plan/260828_cursor_umbrella_catalog/004_roadmap_lock.md @@ -0,0 +1,14 @@ +# 004 — roadmap lock (wp1 B closure) + +Locked after A-gate round 1 (5 High + 2 Medium folded, 3cdb77fc8). + +| wp | doc | branch/PR | +|---|---|---| +| wp2 | 010_capability_core.md | codex/cursor-umbrella-core -> dev | +| wp3 | 020_catalog_integration.md | codex/cursor-umbrella-wire (stacked on core) | +| wp4 | 030_closure.md | comparison + proof, docs on the wire branch | + +Key locked decisions: variant-dimension schema (defaultVariant=thinking); +parser precedence with frozen oracle; alias retention (resolver keeps all +69 slugs); maxMode evidence-gated (kimi-k3 + live maxModeModels union); +effort.ts synthetic policy untouched. diff --git a/devlog/_plan/260828_cursor_umbrella_catalog/010_capability_core.md b/devlog/_plan/260828_cursor_umbrella_catalog/010_capability_core.md new file mode 100644 index 0000000000..55efdc2cee --- /dev/null +++ b/devlog/_plan/260828_cursor_umbrella_catalog/010_capability_core.md @@ -0,0 +1,55 @@ +# 010 — wp2: capability core module (PR A, codex/cursor-umbrella-core -> dev) + +## Changes + +### 1. ADD src/adapters/cursor/catalog.ts + +- export type CursorVariantKind = "regular" | "thinking" | "fast" | "thinkingFast"; +- export interface CursorVariantSpec { levels: readonly string[]; + order?: "thinking-then-effort" | "effort-then-thinking" | "bare"; + quarantined?: boolean } +- export interface CursorCapability { variants: Partial>; defaultVariant: CursorVariantKind; window: number; + maxModeVerified?: boolean; wirePrefix?: "cursor-" } + (A-gate blocker 1: per-variant ladders — claude-opus-5 fast low/med/high + vs thinkingFast low..max representable; defaultVariant = thinking when a + thinking variant exists, else regular; quarantine per-variant — blocker 3.) +- export const CURSOR_CAPABILITIES: Record — + seeded 1:1 from CURSOR_MODEL_EFFORT_TIERS + CURSOR_THINKING_FAMILIES + + senpi window table; maxModeVerified only on kimi-k3 (blocker 4); + wirePrefix "cursor-" on grok-4.5/grok-4.6 regular. +- export function parseCursorVariantId(id): { baseId, kind, level?, ultra } + with STRICT precedence (blocker 2): (1) exact base-id table hit (covers + gpt-5.1-codex-max, gpt-5.5-extra, claude-4-sonnet-1m as real identities); + (2) cursor- prefix strip + re-lookup; (3) -1m synthetic suffix; (4) senpi + suffix grammar (strip -fast; -thinking- | --thinking | + -thinking | -); tokens minimal|low|medium|high|extra-high|xhigh|max|none. +- export function resolveCursorSelection(pickedId, codexEffort?): + { wireId, maxMode, params: [] } — suffix-id-first composition reusing the + order rules currently in cursorWireModelIdWithEffort; ultra -> + top-level + maxMode when bigContext; grok fast keeps the parameter path. +- export function cursorUmbrellaRows(): { id, efforts, defaultEffort, + window, bigContext }[] — picker list derivation (router ids stay in + discovery). + +### 2. Tests — ADD tests/cursor-catalog.test.ts + +Named activation per branch, with a FROZEN fixture table (all 69 seed ids + +cursor- prefixed wire forms + representative live suffix ids) asserting +(parsedBase, kind, level) AND resolved wire id byte-equality against the +CURRENT cursorWireModelIdWithEffort/cursorRequestWireModelIdWithEffort +output (generated once from the old module while it still exists — the +back-compat oracle). Plus: precedence cases (gpt-5.1-codex-max stays a base; +gpt-5.5-extra + any effort -> gpt-5.5-extra-high; cursor-grok-4.6-xhigh +round-trips); thinking default variant; bare-thinking ignores effort; +per-variant ladder divergence (opus-5 fast vs thinkingFast); ultra -> +maxMode ONLY on maxModeVerified; ultra elsewhere clamps to ladder top +without maxMode; variant-specific quarantine (opus-5 regular excluded, +thinking present); unknown id passthrough. + +### 3. NO consumer changes in this PR (effort-map untouched) — additive +module + tests only, so the diff reviews clean. + +## Verifiers + +bun test tests/cursor-catalog.test.ts; bun x tsc --noEmit; privacy scan. diff --git a/devlog/_plan/260828_cursor_umbrella_catalog/020_catalog_integration.md b/devlog/_plan/260828_cursor_umbrella_catalog/020_catalog_integration.md new file mode 100644 index 0000000000..fa39f186fd --- /dev/null +++ b/devlog/_plan/260828_cursor_umbrella_catalog/020_catalog_integration.md @@ -0,0 +1,61 @@ +# 020 — wp3: integration (PR B, codex/cursor-umbrella-wire, stacked on PR A) + +## Changes + +### 1. MODIFY src/adapters/cursor/discovery.ts + +- CURSOR_STATIC_MODELS: replace 52+13 explicit rows with rows generated from + cursorUmbrellaRows() (+ 4 router rows kept literal). claude-4-sonnet-1m + stays (real wire id) as alias metadata. +- CURSOR_ULTRA_1M_MODEL_IDS + cursorUltraBaseModelId: reimplement over + parseCursorVariantId ultra dimension (any bigContext base), keeping the + kimi-k3-1m alias. +- filterCursorConfiguredModelsByLiveDiscovery: match live suffix ids via + parseCursorVariantId(base match) instead of enumerated suffix compose. +- inferCursorContextWindow: read window from CURSOR_CAPABILITIES first, + fall through to current heuristics for unknown ids. + +### 2. MODIFY src/codex/catalog/provider-fetch.ts (~:1276-1310) — consume +the maxModeModels ALREADY returned by live-models.ts (:123-136; decoder +needs no change, A-gate finding 6): live maxMode ids union with +maxModeVerified static flags to arm the ultra->maxMode wire rung per base. + +### 3. MODIFY src/providers/registry.ts (~:1092 cursor section) — model ids +from cursorUmbrellaRows(); modelReasoningEfforts from each row's +defaultVariant ladder; modelDefaultReasoningEfforts keeps kimi-k3: max. + +### 3b. MODIFY src/codex/catalog/effort.ts (:219-226) — POLICY UNCHANGED +(A-gate blocker 5): synthetic max+ultra stay appended to every +reasoning-capable row for spawn validation. Add a comment distinguishing +catalog-synthetic ultra from wire maxMode. Regression test: spawn-validation +efforts for a cursor row WITHOUT maxModeVerified still include ultra, and +the adapter clamps it (existing clamp test extended). + +### 4. MODIFY src/adapters/cursor/request-builder.ts — normalizeCursorModelId +/ effort composition delegate to resolveCursorSelection; grok-fast parameter +path preserved; ultra path generalized (maxMode for any bigContext base). + +### 5. DELETE src/adapters/cursor/effort-map.ts once discovery + +request-builder consume catalog.ts; migrate any residual export the tests +reference. + +### 6. Tests (exact paths, A-gate blocker 7): +- MODIFY tests/cursor-effort-suffix.test.ts — wire-id oracle table from 010 + stays green after consumers switch (the byte-equal back-compat proof). +- MODIFY tests/cursor-hardening.test.ts discovery sections — live filter + with suffix + cursor-prefixed fixtures via the new parser. +- ADD tests/cursor-umbrella-rows.test.ts — cursorUmbrellaRows row count + (4 router excluded; ~30 umbrellas), thinking-merged rows list their + default-variant ladder, removed slugs absent from rows but RESOLVABLE via + resolveCursorSelection (pinned-session survival unit proof), quarantined + regular excluded while thinking sibling present. +- ADD focused catalog sync test: sync output cursor section row count + + synthetic max/ultra still appended (spawn validation). +- Pinned-session integration: request with model cursor/claude-opus-5-thinking + (removed row) through request-builder resolves to same wire id as today. + +## Verifiers + +bun test tests/cursor-catalog.test.ts tests/cursor-hardening.test.ts ++ discovery/sync-focused files; tsc; privacy scan; catalog sync dry-run +row output captured for 030. diff --git a/devlog/_plan/260828_cursor_umbrella_catalog/030_closure.md b/devlog/_plan/260828_cursor_umbrella_catalog/030_closure.md new file mode 100644 index 0000000000..f22f44c0dc --- /dev/null +++ b/devlog/_plan/260828_cursor_umbrella_catalog/030_closure.md @@ -0,0 +1,49 @@ +# 030 — wp4: closure + +1. Cleanliness comparison table: rows before/after (69 -> ~34), effort-map + 229 LOC deleted vs catalog.ts added, single-module truth vs senpi's + 3-surface split (static TS + 336-row JSON + regex) vs omo's absent map; + thinking merged for ALL families (senpi: Claude split remains); fast as + dimension (senpi: separate groups). +2. Picker proof: opencodex-catalog.json cursor section before/after row + counts + one umbrella row excerpt showing efforts incl ultra. +3. Back-compat proof: legacy-id wire table test green (every 69 id routes + to the same wire id as before, or documented intentional change). +4. Stack finalization: PR A -> dev, PR B stacked; retarget checks. + +## Closure results (2026-08-28) + +### Cleanliness comparison + +| Measure | Before (opencodex) | After | senpi | omo-ai@beta | +|---|---|---|---|---| +| Picker rows (cursor, non-router) | 65 | 47 seed rows / 31 umbrella identities | ~raw roster + grouped-with-fast-splits | none (no cursor map at all) | +| Variant duplicate rows | 22 (13 thinking + 7 fast + 2 x 1m) | 1 (claude-4-sonnet-1m real wire id) + composer-2.5-fast (no effort base) | thinking split retained for Claude; fast groups separate | n/a | +| Capability truth surfaces | 2 (effort-map tables + discovery seed annotations) | 1 (catalog.ts CURSOR_CAPABILITIES) | 3 (static TS table + 336-row generated alias JSON + display-name regexes) | 0 | +| Thinking handling | 13 separate picker rows | dimension; merged into base for ALL families | Claude-only thinkingMode split | delegated | +| Fast handling | 7 separate rows | dimension; aliases only | separate catalog groups; parameter fast always "false" | delegated | +| 1M/Max-Mode | single synthetic kimi-k3-1m row | window metadata generalized (claude/gemini/kimi/gpt-5.6 1M) + evidence-gated ultra->maxMode (static kimi-k3 + live maxModeModels union) | window/maxWindow fields; maxMode from name regex + family pattern (window-size inference we rejected as unsupported) | delegated | +| Back-compat | n/a | every legacy slug byte-identical (oracle + pinned-session tests) | variant-id fallback silently degrades to representative id | n/a | + +LOC: effort-map.ts (229) still present as the test oracle only — zero src/ +consumers remain (request-builder/discovery now import catalog.ts; discovery +keeps two legacy helpers for the transition). catalog.ts is 541 lines +INCLUDING the full capability table that previously lived across two files +plus prose. Deletion of effort-map.ts is queued for the post-merge cleanup +once the oracle freezes to literal fixtures. + +### Picker proof + +cursorUmbrellaRows(): 31 identities. Excerpt: kimi-k3 {efforts:[low,high,max], +window:1000000, maxModeVerified:true} — the old kimi-k3-1m row is gone and its +capability rides the base. Seed: 51 rows (4 router + 47). + +### Stack + +| PR | base | head | state | +|---|---|---|---| +| #2801 core | dev | codex/cursor-umbrella-core 54965ef03 | open | +| #2802 wire | codex/cursor-umbrella-core | codex/cursor-umbrella-wire 075c5705a | open, retarget to dev after #2801 | + +Verification totals: 1137 tests / 56 cursor+catalog files pass on the wire +head; tsc 0; privacy scan pass. CI is the wide gate per user instruction. diff --git a/devlog/_plan/260828_kiro_turn_termination/000_research.md b/devlog/_plan/260828_kiro_turn_termination/000_research.md new file mode 100644 index 0000000000..5bc66b1c67 --- /dev/null +++ b/devlog/_plan/260828_kiro_turn_termination/000_research.md @@ -0,0 +1,63 @@ +# Kiro turn termination — residual defect research + +Observed 2026-08-28 21:20 KST by the user in a Codex desktop session routed +`kiro/claude-opus-5` through the local proxy on port 10100. + +## Symptom + +1. A plain question ("근데 코드 모드가 뭐임") produced the final answer TWICE in + one turn, the second a near-duplicate rewrite of the first. +2. The user reports the "answer finishes, then continues like a goal" loop is + still present after `cf1a5720c`. + +## Live-state evidence + +- Listener PID 3653, started 2026-08-28 21:17:50, running the checkout at + `/Users/jun/Developer/new/700_projects/opencodex/src/cli/index.ts start --port 10100`. +- `cf1a5720c` committed 21:09:50 — the running process DID load that fix. + Confirmed independently: a probe that produced no stdout in this session + returned the new empty-exec wording added by that commit. +- HEAD advanced to `60537f067` at 21:26:53 (a different session's commit), so + the running proxy is stale relative to HEAD but not relative to `cf1a5720c`. + +So the residual behaviour is a real defect, not a stale process. + +## Mechanism 1 — duplicate final answer (rendering) + +Kiro emits answer-like ordinary text, then calls the private completion tool in +the SAME inference. The adapter releases the prose as `phase: "commentary"` and +the completion `answer` as `phase: "final_answer"`. `src/bridge.ts` closes the +commentary message on the phase change and opens a new assistant message, so the +client renders two assistant messages whose text is nearly identical. + +This is pinned by the existing suite, so it is verified behaviour rather than a +hypothesis — `tests/kiro-stream.test.ts` asserts exactly: + +``` +{ type: "text_delta", text: "Done.", phase: "commentary" }, +{ type: "text_delta", text: "Done.", phase: "final_answer" }, +``` + +## Mechanism 2 — non-terminating turn (upstream fetch) + +When replayed history ends in a delivered final answer, `buildKiroPayload` still +appends a synthetic trailing user turn carrying `KIRO_ANSWER_DELIVERED_MESSAGE` +and performs a real upstream inference. Neutral wording removes the instruction +to resume but does not remove the prompt: the model is asked again and answers +again. `60537f067` additionally suppresses the completion contract for that +shape, which narrows the loop, but there is still no terminal boundary that +avoids the fetch. + +## Hypotheses tested + +| id | claim | verdict | evidence | +|----|-------|---------|----------| +| H1 | the completion TOOL CALL never sets the phase flag | refuted | the proxy consumes the completion tool; a replayed history containing it throws at `src/adapters/kiro-wire.ts:88` (reproduced directly) | +| H2 | any synthetic trailing user turn re-invokes the model | confirmed | `src/adapters/kiro.ts` trailing-turn append still yields an upstream inference | +| H3 | another layer replays the answer | partial | the generic Responses guard is not involved; the Kiro-owned bounded completion fallback does perform a second fetch | +| H4 | commentary is the last recorded component | confirmed | ordinary text is forced to commentary; the completion answer is a separate final message, split at `src/bridge.ts:922` | + +## Verification baseline + +`bun test tests/kiro-adapter.test.ts tests/kiro-stream.test.ts tests/server-kiro-completion-e2e.test.ts` +-> 180 pass, 0 fail at `60537f067`. diff --git a/devlog/_plan/260828_kiro_turn_termination/010_wp1_terminal_boundary.md b/devlog/_plan/260828_kiro_turn_termination/010_wp1_terminal_boundary.md new file mode 100644 index 0000000000..67982ae7dd --- /dev/null +++ b/devlog/_plan/260828_kiro_turn_termination/010_wp1_terminal_boundary.md @@ -0,0 +1,81 @@ +# wp1 — terminal boundary for a delivered final answer + +Consumes: `000_research.md` mechanism 2. + +## Problem + +`buildKiroPayload` (`src/adapters/kiro.ts`) turns a trailing delivered final +answer into a synthetic user turn carrying `KIRO_ANSWER_DELIVERED_MESSAGE` and +then performs a real upstream inference. Neutral wording is still a prompt, so +the model answers again — the closed task reads as an open goal. + +`60537f067` suppresses the completion contract for that shape. Keep that as +defence in depth; it is not the boundary. + +## Change (revised after the A-phase audit — audit verdict was FAIL on the +## original placement, see 011_audit_round1.md) + +Short-circuit BEFORE the provider fetch, but NOT inside `buildRequest` and NOT +as a bare outputless `done`. Three constraints the audit established, each +verified against current source: + +1. **An outputless `done` is retried, not accepted.** `guardEmptyCompletionEventStream` + treats a `done` with no content event as an empty completion, suppresses the + terminal, and re-invokes the identical turn; a second empty terminal becomes + `empty_completion_retry_failed` + (`src/server/responses/empty-completion-guard.ts:246-270`). So the naive + terminal turns one loop into either another inference or a stated error. + The local terminal must therefore bypass the empty-completion guard as well as + the transport. +2. **`buildRequest` cannot emit events.** The adapter contract returns an + `AdapterRequest`; events only exist once a `Response` reaches `parseStream` + (`src/adapters/base.ts`). The server then records and sends the attempt + unconditionally. Manufacturing a fake `Response` inside `fetchResponse` is + also wrong: it records a physical send and still meets the guard. +3. **A phantom estimate must not be logged.** Kiro attaches an estimated input + count during build and the server notes the attempt send before fetching, so + short-circuiting after a build would log a request that never happened. + +Placement: an explicit adapter-owned local-terminal decision consulted in +`handleResponsesInner` AFTER adapter resolution and BEFORE the ordinary +build/send path, short-circuiting to a locally constructed terminal response. +Reuse `hasTrailingDeliveredFinalAnswer` as the predicate; do not introduce a +second notion of "delivered". The hook must not intercept the adapter-owned +bounded retry, which builds with a forced `text_fallback` mode. + +Usage accounting for the local terminal: no build-time estimate, `sendCount` +zero, response usage explicitly zero for input/output/total, and no estimated +usage in the request log. + +## Out of scope + +- Any change to how the completion tool is parsed or consumed. +- Any change to the empty-exec normalisation from `cf1a5720c` / `60537f067`. +- The duplicate-rendering defect, which is wp2. + +## Criteria + +1. Replaying a delivered final answer issues ZERO upstream requests and yields a + completed turn with `endTurn: true`. +2. Criterion 1 holds with `emptyCompletionRetry` BOTH enabled and disabled, for + streaming and non-streaming Responses. This is the criterion the audit added; + without it the fix passes a test and still loops in the user's config. +3. The short-circuited turn logs `sendCount === 0` and no estimated usage. +4. A genuine later user message after a delivered final answer still performs a + normal inference (control). +5. An unfinished trailing assistant turn still gets the continuation prompt and + still performs an inference (control, already covered — must stay green). +6. The adapter-owned bounded `text_fallback` retry is NOT intercepted. +7. `60537f067`'s completion-mode suppression remains asserted. + +## Completion language + +Closing wp1 fixes the repeated inference ONLY. The user-visible duplicate answer +remains until wp2 lands, and the wp1 report must say so rather than implying the +reported symptom is fully resolved. + +## Evidence + +`bun test tests/kiro-adapter.test.ts tests/kiro-stream.test.ts tests/server-kiro-completion-e2e.test.ts` +plus new public-server coverage in `tests/server-kiro-completion-e2e.test.ts`, +each new assertion driven red once by reverting the change. diff --git a/devlog/_plan/260828_kiro_turn_termination/011_audit_round1.md b/devlog/_plan/260828_kiro_turn_termination/011_audit_round1.md new file mode 100644 index 0000000000..0c9e75d062 --- /dev/null +++ b/devlog/_plan/260828_kiro_turn_termination/011_audit_round1.md @@ -0,0 +1,25 @@ +# A-phase audit round 1 — verdict FAIL + +Reviewer: independent subagent (gpt-5.6-sol, medium effort), read-only lane. +Audited: `000_research.md`, `010_wp1_terminal_boundary.md` as first written. +Reviewer's own checks: 180 pass / 0 fail on the three Kiro suites, +`bun x tsc --noEmit` exit 0, live proxy untouched. + +The plan was rewritten rather than argued with. Findings and dispositions: + +| # | Finding | Disposition | +|---|---------|-------------| +| 1 | An outputless `done` is consumed by the empty-completion guard, which suppresses the terminal and re-invokes the identical turn (`src/server/responses/empty-completion-guard.ts:246-270`). The "safe terminal" becomes another inference or `empty_completion_retry_failed`. | ACCEPTED. Verified independently by reading the guard. wp1 now requires bypassing the guard as well as the transport, and adds a criterion covering `emptyCompletionRetry` both ON and OFF. | +| 2 | `buildRequest` cannot emit events under the adapter contract, and faking a `Response` in `fetchResponse` still records a physical send. | ACCEPTED. Placement moved to an adapter-owned local-terminal decision consulted in `handleResponsesInner` before the build/send path. | +| 3 | Short-circuiting after a build logs a phantom estimated request. | ACCEPTED. Criteria now demand no build-time estimate, `sendCount === 0`, zero response usage, and no estimated usage in the request log. | +| 4 | `hasTrailingDeliveredFinalAnswer` is sound, but the hook must not intercept the forced `text_fallback` build. | ACCEPTED as a criterion. The predicate was re-read directly: role-and-phase based, so a user message merely QUOTING the acknowledgement is unaffected. | +| 5 | wp1/wp2 separation is legitimate, but wp1's completion language must not imply the reported symptom is fully fixed. | ACCEPTED. wp1 now carries an explicit completion-language section. | +| 6 | The broad "buffer commentary" direction is wrong; required-mode commentary is ALREADY deferred, and the real defect is the unconditional flush before the validated answer. Retaining across the bounded fallback would hide progress during a long second inference. | ACCEPTED, and it improves the design: wp2 is now a change to WHEN the existing deferred run is released, not a new buffer. | +| 7 | No user-visible Responses-level regression was specified; adapter-event coverage cannot prove the rendered duplicate is gone. | ACCEPTED. Both work-phases now name `tests/server-kiro-completion-e2e.test.ts`. | + +Process note the reviewer raised: it expected a staged diff and found none, and +observed HEAD had moved to `761cb4cfe`. Correct on both counts — the plan unit is +untracked while in P, and two unrelated commits landed from another session +during the audit. Neither invalidates the substance, and the untracked worktree +changes in `src/adapters/cursor/` at dispatch time belonged to that other session +and were left alone. diff --git a/devlog/_plan/260828_kiro_turn_termination/012_audit_round2.md b/devlog/_plan/260828_kiro_turn_termination/012_audit_round2.md new file mode 100644 index 0000000000..800865a3d2 --- /dev/null +++ b/devlog/_plan/260828_kiro_turn_termination/012_audit_round2.md @@ -0,0 +1,55 @@ +# A-phase audit round 2 — verdict FAIL on wp2, wp1 cleared + +Same reviewer as round 1 (blocker-closure reuse). Round 1's seven findings were +all accepted; this round re-read the revised plan. + +## wp1 — cleared + +The reviewer confirms the revised placement, criteria, and completion language +are sufficient: bypassing transport, request building, and the empty-completion +guard, with guard-on/guard-off and streaming/non-streaming coverage, zero sends, +no estimated usage, and the forced `text_fallback` exclusion. + +It also rejected `runTurn` as the seam, with specifics worth keeping: adopting +`runTurn` routes EVERY Kiro request into the custom transport branch, which waits +on provider pacing and increments `sendCount` before any local decision, still +meets the empty-completion guard afterwards, and would force Kiro to re-own +transport, retries, failover, cancellation, and accounting that its existing +`buildRequest`/`fetchResponse`/`parseStream` path already provides. The local +terminal therefore belongs immediately after adapter resolution and before +`buildRequest`. + +## wp2 — two execution-path blockers, both accepted + +1. **The outer drain.** Skipping the inner flush at `src/adapters/kiro.ts:1467` + is not enough: `parseKiroAttempt` independently drains `deferred` at + `src/adapters/kiro.ts:996-999` after the inner generator returns. The final + answer would be emitted first and the commentary after it — the duplicate + survives, reversed. Found independently while reading the same file, so this + is confirmed twice. The deferred collection must be consumed, and the claim + that this stays clear of retention machinery is withdrawn. +2. **`text_fallback` has the same shape through a different collection.** It + retains in `fallbackEvents`, and `src/adapters/kiro.ts:1470-1477` emits all of + them and then the completion answer. The rule must apply independently inside + each inference. + +Criterion 3 was also overbroad — "any turn whose completion never arrives enters +the fallback exactly once" is false for real tools, provider/protocol failures, +and explicit stops like `MAX_TOKENS`. Narrowed to a clean required-mode +inference, with added controls for failure, explicit incomplete stop, +text_fallback duplication, and budget return-to-baseline. + +The six release paths the reviewer enumerated from source are now a table in +`020_wp2_duplicate_answer.md` and are treated as controls. + +## HEAD movement + +Verified: `60537f067..761cb4cfe` touches only +`src/adapters/cursor/tool-result-normalize.ts` and +`tests/cursor-exec-empty-result.test.ts`. No Kiro adapter, adapter contract, +Responses core, bridge, or Kiro test file changed. The plan is unaffected. + +## Disposition + +wp1 proceeds to implementation. wp2's plan page is corrected here and will be +re-audited as part of its own cycle rather than blocking wp1. diff --git a/devlog/_plan/260828_kiro_turn_termination/020_wp2_duplicate_answer.md b/devlog/_plan/260828_kiro_turn_termination/020_wp2_duplicate_answer.md new file mode 100644 index 0000000000..39ea47ec27 --- /dev/null +++ b/devlog/_plan/260828_kiro_turn_termination/020_wp2_duplicate_answer.md @@ -0,0 +1,124 @@ +# wp2 — one visible answer per turn + +Consumes: `000_research.md` mechanism 1. + +## Problem + +Kiro emits answer-like ordinary text and then calls the private completion tool +in the SAME inference. The adapter releases the prose as `phase: "commentary"` +and the completion `answer` as `phase: "final_answer"`; +`src/bridge.ts` closes the commentary message on the phase change and opens a +new assistant message. The client renders two assistant messages whose text is +nearly identical. This is what the user saw. + +The existing suite pins this pair, so the fix necessarily REPLACES an asserted +expectation rather than adding to it: + +``` +tests/kiro-stream.test.ts +{ type: "text_delta", text: "Done.", phase: "commentary" }, +{ type: "text_delta", text: "Done.", phase: "final_answer" }, +``` + +## Constraint that shapes the design + +Progress prose is load-bearing UX: a long tool-using turn streams commentary so +the user is not left staring at nothing. Withholding ALL commentary until the +turn resolves would trade a cosmetic duplicate for a silent turn, which the +repository's own comments call out (`#520` gates exist precisely to avoid +re-emitting or losing flushed progress). + +So the buffering must be NARROW: hold back only the trailing commentary run that +has not yet been followed by a real tool call, and only while the completion tool +is still capable of arriving. Release it unchanged the moment a real tool starts, +the stream ends without a completion answer, or the bounded fallback engages. + +## Options + +1. **Consume the same inference's retained text on a valid completion.** (CHOSEN — + narrowed in audit round 1, corrected in round 2.) No new buffer is needed: + required-mode commentary is ALREADY deferred. But skipping the inner flush is + NOT sufficient, and this is the correction that matters: + + - The inner flush is at `src/adapters/kiro.ts:1467`. + - `parseKiroAttempt` INDEPENDENTLY drains whatever remains in `deferred` at + `src/adapters/kiro.ts:996-999`, after the inner generator returns. + + So merely skipping the inner flush emits the final answer first and then the + commentary from the outer drain — the duplicate survives, in reversed order. + The deferred collection must be CONSUMED on a valid completion: discard and + release the redundant `text_delta` events, preserve and release every + non-text event, and leave nothing for the outer drain. That necessarily + touches retention ownership, so the earlier claim that this change stays + clear of the retention machinery is withdrawn. + + `text_fallback` has the SAME shape through a DIFFERENT collection: it retains + in `fallbackEvents`, and `src/adapters/kiro.ts:1470-1477` emits all of them + and then the completion answer. The rule must therefore apply independently + inside EACH inference: + + - required inference + valid completion -> suppress its deferred text, keep + non-text events, emit the completion answer; + - text_fallback inference + valid completion -> suppress that inference's + retained text, keep non-text events, emit the completion answer; + - never retain one inference's progress across the next inference. +2. **Retain commentary ACROSS the bounded fallback.** Rejected by the audit: the + second inference can be long, so withholding first-attempt progress across it + would make the turn look dead and contradicts the deliberate "first attempt + already flushed" gate. +3. **Suppress only on redundancy.** Emit commentary live, and skip the completion + answer if it is substantially the same text. Rejected: "substantially the same" + is a similarity heuristic, and a wrong guess either drops the real answer or + keeps the duplicate. +4. **Bridge-side coalesce.** Merge a commentary message and an immediately + following final answer into one assistant message. Rejected as the primary + seam: the phase distinction is deliberate protocol information, and the same + split is correct when the commentary genuinely preceded tool work. + +Because the deferral already exists, this is a change to WHEN the deferred run is +released, not a new retention mechanism — which also keeps it clear of the +retention/budget machinery where duplication bugs have previously lived. + +## Criteria + +1. A single inference emitting answer-like prose plus a completion answer yields + exactly ONE visible answer to the client. +2. Commentary followed by a REAL tool call is still emitted live and in order. +3. A CLEAN required-mode inference — text or reasoning present, no real tool, no + completion answer, no explicit non-completion stop reason — still shows its + progress prose and enters the bounded fallback exactly once. (Narrowed in + audit round 2: the unqualified form was false for real tools, provider and + protocol failures, and explicit stops such as `MAX_TOKENS` or + `CONTENT_FILTERED`.) +4. A Responses-protocol-level assertion, not only adapter events: the user-visible + duplicate must be proven gone through the bridge. Adapter-event coverage cannot + prove this, because the split happens in the bridge on the phase change. The + assertion belongs in `tests/server-kiro-completion-e2e.test.ts`: one upstream + request, exactly one visible assistant answer, one terminal completion, and the + near-duplicate prose absent. +5. The existing `tests/kiro-stream.test.ts` expectation that asserts the + commentary/final pair is UPDATED, not deleted — the replacement states the new + contract for the same scenario. +6. `text_fallback` ordinary text plus a valid completion also yields exactly one + visible answer. +7. The translator budget returns to baseline after suppressed events — suppression + must release retention, not leak it. + +## Release paths that must remain intact + +Enumerated from source in audit round 2; each is a control the implementation may +not regress: + +| trigger | release point | +|---------|---------------| +| a real tool starts (`sawRealTool`) | `src/adapters/kiro.ts:1172-1177`, released with the tool event | +| clean no-completion turn needing fallback | flush before `needsFallback` returns, `src/adapters/kiro.ts:1535-1542` / `1600-1603` | +| stream / protocol / provider failure | outer failure drain, `src/adapters/kiro.ts:996-999` | +| explicit non-completion stop | released before the incomplete/error branches, `src/adapters/kiro.ts:1545-1598` | +| plain-text fallback without completion | retained text promoted to `final_answer`, `src/adapters/kiro.ts:1488-1501` | +| empty / reasoning-only fallback | diagnostics released before the structured incomplete, `src/adapters/kiro.ts:1503-1517` | + +## Out of scope + +- The terminal-boundary fix (wp1). +- Changing what `phase` means in the Responses protocol. diff --git a/devlog/_plan/260828_ocx_agentic_control/000_plan.md b/devlog/_plan/260828_ocx_agentic_control/000_plan.md new file mode 100644 index 0000000000..61efbafcab --- /dev/null +++ b/devlog/_plan/260828_ocx_agentic_control/000_plan.md @@ -0,0 +1,128 @@ +# 000 — ocx as a complete agentic control surface + +## Objective + +Make the `ocx` CLI a complete, scriptable control surface for every capability the +web dashboard exposes, so an AI agent can operate opencodex end to end from a +terminal with machine-readable output and honest exit codes. Close the ten +operator-facing CLI issues (#2696-#2705) at their root causes rather than at their +symptoms, give help a single source of truth that a test can hold to the API +surface, and ship a repo-owned agent skill that documents the resulting surface. + +## Why this unit exists + +The dashboard is the complete surface today and the CLI is a partial mirror of it. +Three separate failure classes make the CLI unusable for unattended agent control: + +1. **Transport dishonesty.** `ocx models live` and `ocx provider quota` print an + error and exit 0 (#2697); a 503 arrives with a `reason` and `hint` the CLI + never renders (#2698); a launchd install can fence the entire management plane + closed and the CLI cannot say why (#2696); the PATH binary can be older than + the running proxy while its help claims otherwise (#2701). +2. **DTO loss.** The API already returns fields the CLI throws away: usage + `accounts[]` (#2700), account `paused` and the 5h quota window (#2703), access + key `usage.requests7d`/`lastUsedAt` (#2705). One of these is worse than filed: + `projectQuota` strips `fiveHourPercent` before any renderer runs. +3. **Missing verbs.** Pause/resume, pool strategy, sticky limit (#2702) and + `logs --conversationId` (#2704) exist as routes with no CLI caller, plus 13 + further GUI-only capability classes found by inventory. + +Underneath all three sits the real defect: **there is no source of truth binding +the CLI surface to the API surface.** Help lives in a hand-written 69-line banner +plus 37 module-level usage blocks — 20 of them exported constants with zero +consumers outside their own files — all free to drift. Nothing fails when a route +lands with no verb. + +## Constraints + +- Bun-native TypeScript. No compile step, no Node-only APIs. +- `src/lab/` must stay off the core request path; `tests/core-lab-boundary.test.ts` + and the `startServer` synchronous-window scan are hard gates. +- Management auth is applied before dispatch for every `/api/` path. Three routes + require a browser session and MUST NOT get a CLI verb: `POST /api/github/star` + (user-consent boundary, `AGENTS_INSTALL.md`), the non-GET `/api/codex-prompt*` + verbs, and `POST /api/providers/reload` (capability principal, not a session). +- `PUT /api/config` is a deliberate 405. Not a parity target. +- No security triage in `devlog/`. Scratch space only. +- Per the operator's instruction for this unit: no local full-suite runs during + build, no per-push CI polling, `--no-verify` pushes, and a single final + rebase-onto-`dev` plus parallel CI triage at the end. + +## Measured surface (see 001, 002, 003) + +| Surface | Count | Source | +|---|---|---| +| Reachable management routes | 183 (108 mutating) | 001 | +| Dead/shadowed routes | 1 (`GET /api/storage` in logs-usage-routes) | 001 | +| Session-only routes (never CLI) | 3 | 001 | +| CLI dispatch runner keys | 57; registry 58 entries, 52 visible | 002 | +| Disconnected help sources | 37 usage blocks (20 dead module exports) + 1 banner | 002 | +| GUI-only capability classes | 13 declared, 8 real gaps after exemptions | 003 | +| Reviewer blockers folded at the A gate | 7 blockers + 4 medium + 2 low | 005 | + +## Work-phase map (dependency-ordered, PHASE-SPLIT-01) + +Each phase consumes the verified output of the previous one. Ordering is by build +structure — contract first, then the machinery that depends on the contract, then +the capabilities that machinery exposes, then documentation of the finished +surface — not by effort or payoff. + +| Phase | Doc | Deliverable | Depends on | +|---|---|---|---| +| wp2 | `010` | Transport honesty: exit codes, error rendering, token-collision refusal (#2697 #2698 #2696) | — | +| wp3 | `020` | Capability registry as help SoT + API/CLI parity test + version skew (#2701) | wp2 | +| wp3b | `025` | Uniform CLI contract: exit codes and `--json` order-independence | wp3 | +| wp4 | `030` | DTO fidelity (#2700 #2703 #2705) | wp3b | +| wp5 | `040` | New verbs and filters (#2702 #2704) | wp3 | +| wp6 | `050` | Per-account OAuth usage attribution (#2699) | wp4 | +| wp7 | `060` | Residual GUI-parity closure (13 capability classes) | wp3 wp5 | +| wp8 | `070` | `ocx` agent skill + docs-site CLI reference | wp7 | +| wp9 | `080` | Stack rebase onto `dev`, final parallel CI triage | all | + +wp2 comes first because every later phase is verified through CLI output: a phase +that lands while `ocx` still exits 0 on failure cannot be proven. wp3 comes second +because the registry it introduces is the thing every later phase registers into — +adding verbs before the registry means writing them twice. + +wp3b exists because the uniform exit-code and `--json` contract *consumes* wp3's +capability table (its tests read each capability's declared `json` mode), so it is a +successor phase rather than a slice carved off to balance effort. PHASE-SPLIT-01 +forbids effort buckets, not dependency-ordered successors. + +wp6 follows wp4 rather than preceding it so that the `accounts` renderer already +exists when the labels start being stamped — the phase's proof is then visible in +`ocx usage` immediately instead of requiring a later phase to demonstrate it. + +## Delivery shape + +A stacked pull-request chain (DEV-STACK-01), one PR per work-phase, each child +targeting its parent's head branch. Base of the stack is `origin/dev`. + +``` +dev + └── codex/ocx-agentic-control-roadmap wp1 (this unit's docs, PR #2773) + └── codex/ocx-transport-honesty wp2 + └── codex/ocx-capability-registry wp3 + └── codex/ocx-uniform-contract wp3b + └── codex/ocx-dto-fidelity wp4 + └── codex/ocx-new-verbs wp5 + └── codex/ocx-account-attribution wp6 + └── codex/ocx-gui-parity wp7 + └── codex/ocx-agent-skill wp8 +``` + +## Accept criteria for the unit + +1. Every non-session, non-405 management capability has a CLI verb with `--json`. +2. A parity test fails when a route lands with no verb and no recorded exemption. +3. Help is generated from the registry; no hand-maintained command list survives. +4. Every management failure path exits non-zero and prints `reason` and `hint`. +5. A repo-owned skill documents the surface with copy-paste recipes. +6. The whole stack is rebased on current `dev` with CI green. + +## Terminal-outcome definitions + +`DONE` requires all six above proven against the tree, not remembered. +`BLOCKED` is a platform or credential refusal. `UNSAFE` is any fix that would +weaken the admin-token or session boundary — stop and ask instead. +`NEEDS_HUMAN` is a CLI-grammar choice the operator must make. diff --git a/devlog/_plan/260828_ocx_agentic_control/001_api_route_inventory.md b/devlog/_plan/260828_ocx_agentic_control/001_api_route_inventory.md new file mode 100644 index 0000000000..b1b1ae06c5 --- /dev/null +++ b/devlog/_plan/260828_ocx_agentic_control/001_api_route_inventory.md @@ -0,0 +1,94 @@ +# 001 — Management API route inventory + +Source: read of `src/server/management-api.ts`, `src/server/management/*`, +`src/codex/auth-api.ts`, `src/codex/native-profile-api.ts` at `50e955604`. + +## How dispatch works + +There is no route table and no framework. Every route is a hand-written +`if (url.pathname === … && req.method === …)` inside one of 17 handler functions, +chained with `??` in `src/server/management-api.ts` around line 220. First handler +returning non-`null` wins; a handler returning `null` falls through. **Dispatch is +order-sensitive.** + +Auth is applied *before* dispatch, in `src/server/index.ts` near line 1010: every +`/api/` path passes `requireManagementAuth`. No management route is unauthenticated. +Individual routes then re-check the principal for consent. + +`pathInManagementNamespace` (management-api.ts:102) matches exact-or-child only, so +`/api/labfoo` deliberately does not match `/api/lab`. + +## Totals + +- **183 reachable routes** across 19 files; **108 mutating**. +- **1 dead route**: `GET /api/storage` at `logs-usage-routes.ts:346` is shadowed by + the identical claim at `storage-log-guard-routes.ts:150`, which runs earlier in the + chain and always returns. The live payload is the guard version (scan plus + `codexLogs`/`codexLogsError`). Audit parity against the guard version. +- `/api/codex-auth/*` is gated by a `startsWith("/api/codex-auth/")` check with a + trailing slash, so a bare `/api/codex-auth` 404s. + +## Auth classes + +| Class | Meaning | Routes | +|---|---|---| +| admin | admin token or GUI session (default gate) | ~177 | +| session | minted GUI session required; admin token gets 403 | `POST /api/github/star`, the 6 non-GET `/api/codex-prompt*` verbs | +| cap | process-scoped HMAC capability principal | `POST /api/providers/reload`; read-cap for `/api/codex-auth/accounts` and `/api/system/memory` | + +The capability principals are narrow and replay-protected: local reads are limited +to exactly those two paths with `url.search` required empty +(`src/lib/local-management-capability.ts:10`). + +## Registration mechanisms a naive `rg '/api/'` misses + +| Mechanism | Where | What is missed | +|---|---|---| +| Lazy `import()` behind a namespace check | management-api.ts:115, :121 | all `/api/routing-profiles*` and `/api/lab*` — deliberate, eager mounting would pull ~70 `src/lab/` modules into every install | +| Handlers mounted outside the `??` chain | management-api.ts:284, :289 | 10 `/api/native-main-profiles/*` and 22 `/api/codex-auth/*` routes, which live in `src/codex/` | +| Path constants, not literals | `src/lib/codex-restart-contract.ts:17`, `system-restart-contract.ts:5`, `local-provider-reload-contract.ts:5` | `/api/system/codex-restart`, `/api/system/codex-app-server`, `/api/system/restart`, `/api/providers/reload` | +| Prefix-decoded wildcard | integration-routes.ts:129 | `GET|PUT /api/client-integrations/{clientId}` | +| Regex params | model-routes, lab-routes, lab-automation-routes | 7 routes | +| Suffix matching | request-history-routes.ts:131 | `/route-decision` found via `endsWith` | +| Namespace guards that swallow siblings | codex-prompt:278, request-history:47, lab:285 | unmatched children 404 from index.ts rather than falling through | + +**This table is the parity test's hard requirement.** A parity test that greps for +`'/api/…'` string literals would miss 40+ routes and pass vacuously. The test must +enumerate from a declared registry, not from source text. + +## Route families (grouped for CLI parity) + +| Family | Routes | Existing CLI reach | +|---|---|---| +| config/settings | `/api/config` (GET; PUT=405), `/api/settings` GET+PUT, `/api/diagnostics/project-config`, `/api/sync` | `ocx system`; `ocx config` is file-I/O only, never calls `/api/config` | +| startup/tray | `/api/startup-health`, `/api/startup-action`, `/api/windows-tray` GET+POST | `ocx system` partial | +| update | `/api/update/check`, `/run`, `/status`, `/badge` | `ocx system`, `ocx update` | +| sidecar/shadow | `/api/sidecar-settings` GET+PUT, `/api/shadow-call-settings` GET+PUT | `ocx agent`, `ocx models` | +| storage | `/api/storage`, `/cleanup`, `/cleanup/preview`, `/trash`, `/trash/restore`, `/cleanup-policy` GET+PUT, `/cleanup-policy/run`, `/codex-logs` +4 actions | `ocx observe storage` reaches only `/api/storage` and `/codex-logs*` | +| logs/debug/usage | `/api/logs`, `/api/debug` GET+PUT, `/debug/logs`, `/debug/usage-logs`, `/debug/injection-logs`, `/api/claude/inbound-debug`, `/api/usage` | `ocx observe`, `ocx debug` | +| request history | `/api/request-history`, `/{id}`, `/{id}/route-decision` | `ocx observe` partial | +| routing | `/api/routing-profiles` GET+PUT+DELETE, `/dry-run`, `/api/routing-analytics` | `ocx route policy` | +| providers | `/api/providers` GET+POST+PATCH+DELETE, `/test`, `/reload` (cap), `/api/provider-quotas`, `/api/provider-presets`, `/api/provider-context-caps` GET+PUT, `/api/provider-request-pacing` | `ocx provider`; pacing has no verb | +| models | `/api/models`, `/api/catalog`, `/api/aliases`, `/api/default-aliases`, `/api/providers/{n}/alias`, `/model-aliases`, `/api/disabled-models`, `/api/model-visibility`, `/api/custom-models` +2, `/api/selected-models` GET+PUT, `/api/model-presets` GET+PUT, `/api/model-discovery` GET+PUT, `/acknowledge`, `/api/client-config` | `ocx models`, `ocx alias`, `ocx export`; `/api/client-config` has no verb | +| combos | `/api/combos` GET+PUT+DELETE | `ocx combo` | +| integrations | `/api/client-integrations` +journal +restore +`{clientId}` GET/PUT, `/api/native-integrations` +4 PUTs, `/api/claude-code` GET+PUT, `/api/claude-desktop` GET+PUT +apply +status, `/api/grok` +selection +apply | `ocx integration`, `ocx grok`, `ocx claude`; native-integrations has no verb | +| agent settings | `/api/v2` GET+PUT, `/api/injection-model`, `/api/effort-caps`, `/api/subagent-models`, `/api/subagent-model-fallback`, `/api/codex-auth/features/default-mode-request-user-input` | `ocx agent`, `ocx v2`; the feature flag has no verb | +| access keys | `/api/keys` GET+POST+PATCH+DELETE | `ocx access key` list/create/remove; PATCH rename has no verb | +| oauth accounts | `/api/oauth/providers`, `/api/key-providers`, `/api/oauth/login` +cancel +code, `/status`, `/logout`, `/api/oauth/accounts` GET+DELETE, `/active`, `/pool` GET+PUT, `/clear-cooldown`, `/import`, `/alias`, `/api/providers/keys` +active +alias | `ocx account`; `/pool` (strategy/sticky) has no verb | +| codex auth | 22 routes: accounts GET/DELETE, `/alias`, `/pause`, `/priority`, `/pause-exhausted`, `/clear-cooldown`, `/active` GET+PUT, `/auto-switch`, `/pool-strategy`, `/failover`, `/quota`, `/reset-credits` +consume, `/login` +code +cancel, `/login-status` | `ocx account`; pause, pause-exhausted, pool-strategy, failover have no verb. `auto-switch` (account.ts:302 -> `cmdAutoSwitch`) and `reset-credits` (account.ts:313) DO have verbs — verified; an earlier draft wrongly listed them as gaps | +| native main profiles | 10 routes under `/api/native-main-profiles` | `ocx account main` | +| system | `/api/system/memory`, `/windows-replace-retries`, `/restart`, `/codex-app-server`, `/codex-restart`, `/api/stop` | `ocx restart`, `ocx stop`, `ocx observe memory` | +| lab | 20 read routes + `/public/*` 4 + automation 5 | `ocx lab` reads local SQLite, never the HTTP routes | +| sidebar | `/api/github/star` GET+POST(session) | GET has no verb; POST must never get one | + +## Cross-cutting error envelopes + +From management-api.ts:237 — a CLI client should encode these once: + +- `413 request body too large` (2 MB cap) +- `403 cross-origin request blocked` +- `503 oauth_mutation_busy`, `503 catalog_busy` (both with `Retry-After: 1`) +- `503 CONFIG_MUTATION_LOCK_UNAVAILABLE` for the codex-auth family +- `503` with `reason` + `hint` from `src/server/management-auth.ts:455` + +The last one is #2698: the fields exist and the CLI does not print them. diff --git a/devlog/_plan/260828_ocx_agentic_control/002_cli_surface_inventory.md b/devlog/_plan/260828_ocx_agentic_control/002_cli_surface_inventory.md new file mode 100644 index 0000000000..d4697d4887 --- /dev/null +++ b/devlog/_plan/260828_ocx_agentic_control/002_cli_surface_inventory.md @@ -0,0 +1,128 @@ +# 002 — CLI surface and help inventory + +Source: read of `src/cli/*`, `bin/ocx.mjs`, `package.json`, `tests/cli-*.test.ts`. + +## Dispatch chain + +``` +bin/ocx.mjs (Node shim, execs the bundled Bun binary) + -> src/cli/index.ts:99 runCli(argv.slice(2)) + -> src/cli/root.ts:25 parseCliHead() pure, no I/O + version/help -> exit 0 + ready -> pre-parsed, exit 64 before any I/O + command -> maybeAutoRestoreCodexShim, return head + -> src/cli/index.ts:956 process.exit(await dispatchCommand(head, deps)) + -> src/cli/dispatch.ts:584 commandRunners[resolveDispatchCommand(cmd)] +``` + +57 runner keys (`DISPATCH_COMMANDS.size`); the registry declares 58 entries +(`CLI_COMMANDS.length`), 52 of them visible. Counted by importing the modules, not +by regex — an earlier regex count of 52/49/43 was wrong in all three figures and +would have sized wp3's banner test against the wrong set. Aliases resolve +through registry pairs (dispatch.ts:568): `setup->init`, `eject->restore`, +`remove->uninstall`, `model->models`. + +Exit codes converge on the single `process.exit` at index.ts:956. A runner that +returns `Number(process.exitCode ?? 0)` preserves inner failures; a runner with a +hardcoded `return 0` discards them. That asymmetry is #2697. + +## Exit-code vocabulary + +From `src/cli/runtime-api.ts:311`: **0** ok, **2** `CliUsageError`, **4** HTTP 404, +**5** HTTP 409, **1** everything else. Only `ready` uses **64**. + +A 503 and a generic failure are both **1**, so a script cannot distinguish +"management plane fenced" from "your argument was wrong" by exit code alone. + +## Two management clients, two contracts + +**Client 1 — `src/cli/runtime-api.ts:61`.** Used by observe, combo, alias, access, +agent, system, route-policy, export, integrations, v2. + +- Base URL: `deps.baseUrl` override, else `findLiveProxy()` (identity-checked, + finds fallback ports), then `http://{probeHostname(live.hostname)}:{live.port}`. +- Auth: `X-OpenCodex-API-Key` from `src/lib/admin-secrets.ts:23` — + `OPENCODEX_ADMIN_AUTH_TOKEN` env, else `$configDir/admin-api-token`, validated + `/^ocx_admin_[A-Za-z0-9_-]{43}$/`, rejecting symlinks and files over 512 B. +- Proxy down -> `RuntimeApiError(503)`; fetch throw -> 503 "unreachable". Both land + on exit 1. +- Non-2xx -> throw with `status` **and the full `body` retained** (line 86). + +**Client 2 — `src/cli/account-api.ts:88` `apiJson`.** Used by the whole `account` +family. Same base-URL and header resolution, but it **never throws**: it returns +`{status, json}` and collapses every network error to sentinel `status: 0` inside a +catch block with an empty body (line 106), discarding the underlying message. Failures funnel +through `apiError` -> exit 1 always; no 404->4 / 409->5 mapping. + +## Error bodies are dropped: `reason` and `hint` + +`responseMessage` (runtime-api.ts:50) scans only `error`, `message`, `detail`. +`apiError` (account-api.ts:123) reads only `json.error`. Management routes emit +`reason` as the actionable field in roughly 39 places — integration-routes, +native-integration-routes (`home_mismatch`, `apply_incomplete`, +`metadata_unreadable`, `not_durable`), agent-settings-routes +(`desired_state_changed`). A body of `{ok:false, reason:"home_mismatch"}` with no +`error` key prints the generic `Management request failed (409)`. + +The body is already attached to the thrown error, so this is a rendering fix, not a +plumbing one. One narrow exception is already special-cased: `cleanupRequired` at +account-api.ts:126. + +## HELP-SOT: there is none + +Three disconnected tiers: + +1. **Registry** — `src/cli/registry.ts:10` `CLI_COMMANDS`, 58 entries with + `usage`/`summary`/`details`. Consumed only by `printSubcommandUsage` + (help.ts:94) and alias resolution. +2. **Hand-written banner** — `src/cli/help.ts:18-88`, one 69-line template + literal, maintained by hand, **not generated from the registry**. +3. **37 module-level `USAGE`/usage-string blocks** by `rg` count, of which the + 20 below are the named module-level constants. The 20 listed here are the + *dead exports*; the remaining ~17 are inline or locally-consumed usage strings + that also need a home in the capability table. Each is its own authority: + +account-auth.ts:33 · access.ts:12 · export-command.ts:53 · account.ts:18 · +account-extended.ts:38 · account-main.ts:15 · provider.ts:424 + :130 · +provider-runtime.ts:22 · models.ts:19-21 (three) · models-runtime.ts:16 · +agent.ts:23 · observe.ts:16 · combo.ts:13 · route-policy.ts:12 · alias.ts:3 · +system-command.ts:14 · config-command.ts:9 · lab.ts:76 · integrations.ts:15,24,30,227 · +claude-desktop.ts:25 (inline `console.log`) · debug.ts:184 (string interpolation). + +Plus one-off inline strings at index.ts:106, :835, :917; root.ts:74; +dispatch.ts:344, :443, :506. + +`ocx ready`'s usage string is duplicated verbatim in **three** places — +registry.ts:354, root.ts:74, ready.ts — with no test tying them together. + +**What is enforced today:** `tests/cli-registry.test.ts:107` greps `help.ts` source +to assert every visible canonical command appears in the banner, and +`tests/cli-dispatch.test.ts:12` asserts registry-to-dispatch coverage both ways. +The banner is explicitly documented at test:104 as "curated… not required to match +the registry exactly." + +**Nothing validates the module `USAGE` blocks.** The exported constants +(`OBSERVE_USAGE`, `COMBO_USAGE`, `LAB_USAGE`, `AGENT_USAGE`, `SYSTEM_USAGE`, +`CONFIG_USAGE`, `ACCESS_USAGE`, `EXPORT_USAGE`, …) have zero consumers outside +their own files, including in tests. They are dead exports, free to drift. That is +the mechanism behind #2701's "help lies" symptom — a stale binary is one cause, an +unvalidated help string is the other. + +## `--json` is not a uniform contract + +- Registry declares `--json` for `tray`, but `windowsTrayCommand` always returns 0. +- `status` accepts `--json` only as a **lone** argument (index.ts:833), unlike the + order-independent `takeFlag` parsing used everywhere else. +- `restore --json` is matched positionally at `args[1]`, so `ocx restore back --json` + silently ignores the flag. +- `doctor`, `login`, `logout`, `sync`, `sync-cache`, `debug` have no `--json` at all. +- `doctor` and `sync-cache` always exit 0, so neither can gate a script. + +## Commands with no HTTP reach at all + +- `ocx config` — direct file I/O; never calls `/api/config` (config-command.ts). +- `ocx lab` — reads the local SQLite projection directly; never calls `/api/lab/*`. + +Both are capability-present/endpoint-absent. They are not parity gaps by +capability, but they do mean a remote or containerized agent cannot reach them. +Recorded as an explicit exemption class rather than folded into the parity count. diff --git a/devlog/_plan/260828_ocx_agentic_control/003_gui_capability_map.md b/devlog/_plan/260828_ocx_agentic_control/003_gui_capability_map.md new file mode 100644 index 0000000000..7ce164e930 --- /dev/null +++ b/devlog/_plan/260828_ocx_agentic_control/003_gui_capability_map.md @@ -0,0 +1,71 @@ +# 003 — GUI capability map and the GUI-only gap + +Source: read of `gui/src/**` (React + Vite) against `src/cli/**`. + +## The GUI has no central API client + +`gui/src/api.ts:265` `installApiAuthFetch()` monkey-patches `window.fetch` and +injects `X-OpenCodex-API-Key`, `X-OpenCodex-GUI-Origin`, and (non-GET only) +`X-OpenCodex-CSRF-Token` for same-origin `/api/*` paths. Session bootstrap reads +meta tags `opencodex-session-token|csrf|origin` (api.ts:93); a 401 silently +re-bootstraps `/opencodex-session`, falling back to an admin-token prompt validated +against `GET /api/settings`. + +Endpoint URLs are inlined at roughly **78 call-site files**. There is no manifest to +diff a CLI against, which is why the parity gate in wp3 must be built from a +declared registry rather than harvested from the GUI. + +Page shell: 10 top-level pages in `gui/src/app-routing.ts:5` — dashboard, startup, +providers, models, subagents, logs, usage, storage, codex-set, integrations. +Combos, RoutingProfiles and CompatibilityMatrix are **tabs of Models**; Debug is a +**tab of Logs**; ApiKeys is a **tab of Integrations**. + +## GUI-only capability classes + +Each verified absent from `src/cli/` by endpoint grep. + +| # | Capability | Endpoints with no CLI caller | Note | +|---|---|---|---| +| 1 | Codex prompt-layer management | 7 routes under `/api/codex-prompt*` | **Not a CLI target.** The 6 mutating verbs require a dashboard session (403 `dashboard_session_required`). Only `GET /api/codex-prompt` and `/text` are reachable — read verbs are in scope, writes are not. | +| 2 | Storage cleanup, trash, cleanup policy | `/storage/cleanup`, `/cleanup/preview`, `/trash`, `/trash/restore`, `/cleanup-policy` GET+PUT, `/cleanup-policy/run` | `ocx observe storage` reaches only `/api/storage` and `/codex-logs*`. Destructive verbs need a confirm flag. | +| 3 | Codex pool strategy / sticky | `/api/codex-auth/pool-strategy` | #2702 | +| 4 | Anthropic account-pool strategy / sticky | `/api/oauth/accounts/pool` | #2702's sibling; separate route family | +| 5 | Pause / resume a Codex account; pause all exhausted | `/api/codex-auth/accounts/pause`, `/pause-exhausted` | #2702. CLI has `clear-cooldown` and `priority` only | +| 6 | Default-mode request-user-input feature toggle | `/api/codex-auth/features/default-mode-request-user-input` | | +| 7 | Client config snippet generation | `/api/client-config?client=` | `ocx export --client` builds configs locally — different route, different output | +| 8 | Native integrations enable/disable | `/api/native-integrations`, `/{client}` (4 PUTs) | | +| 9 | Rename an access key | `PATCH /api/keys` | Noted in #2705's body as a separate gap | +| 10 | Provider request pacing view | `/api/provider-request-pacing?name=` | | +| 11 | GitHub star status and action | `/api/github/star` GET+POST | **POST must never get a CLI verb** — user-consent boundary per `AGENTS_INSTALL.md`, enforced at sidebar-routes.ts:75. GET status is fine. | +| 12 | Compatibility Lab HTTP surface | 20 read routes under `/api/lab/*` | `ocx lab` reads local SQLite instead. Same data, different transport — capability-present, endpoint-absent | +| 13 | Raw config document PUT | `PUT /api/config` | **Not a target**: deliberate 405 | + +## Reclassification after review + +Of the 13 classes, three are **not** parity work and must be recorded as +exemptions so the parity test does not demand them: + +- class 1 write verbs, class 11 POST — session/consent boundary +- class 13 — deliberate 405 + +Two are **transport** exemptions rather than capability gaps (class 12, and `ocx +config`'s file-I/O path): the capability exists in the CLI by another route. wp7 +decides whether to add an HTTP-backed `--remote` path for them; the default answer +is no, with the exemption recorded and justified. + +That leaves **eight real capability gaps** for wp5 and wp7: classes 2, 3, 4, 5, 6, +7, 8, 9, 10 minus the two folded into #2702 (3, 4, 5) which wp5 owns. + +## Notable DTO fields the GUI renders and the CLI drops + +| DTO | Fields | Issue | +|---|---|---| +| `GET /api/keys` | `usage.requests7d`, `usage.totalRequests`, `lastUsedAt`, `attributionSince`, `historyTruncated`, `authMatrix` | #2705 | +| `GET /api/codex-auth/accounts` | `paused`, `quota.fiveHourPercent`, `health{status,reason,until}`, `usage30d{…}` | #2703 | +| `GET /api/usage` | `accounts[]` | #2700 | +| `GET /api/logs` | `conversationId` filter (server-side) | #2704 | + +`gui/src/hooks/useCodexAccountPool.ts:27` is the reference DTO shape for the +account family — the CLI's `AccountRow` at `src/cli/account-api.ts:14` is a strict +subset of it, and `projectQuota` at :195 narrows it further. + diff --git a/devlog/_plan/260828_ocx_agentic_control/004_issue_root_cause.md b/devlog/_plan/260828_ocx_agentic_control/004_issue_root_cause.md new file mode 100644 index 0000000000..c09141e126 --- /dev/null +++ b/devlog/_plan/260828_ocx_agentic_control/004_issue_root_cause.md @@ -0,0 +1,261 @@ +# 004 — Per-issue root cause (#2696-#2705) + +Verified against `50e955604` / `package.json` 2.35.0. The issues were filed against +2.33.0. **No issue in this set is already fixed on HEAD.** Three issue reports are +inaccurate in ways that change the fix; those are called out. + +## #2697 — dispatch discards the exit code + +`dispatch.ts:419` (`provider`) and `:428` (`models`) both `await` the handler and +`return 0`. The inner layers are correct: `handleModelsRuntimeCommand` returns +`runCliAction(action)` (models-runtime.ts:337), `runCliAction` maps +`RuntimeApiError` to 1 (runtime-api.ts:321), and `handleModels` (models.ts:434) and +`handleProviderCommand` (provider.ts:477) both set `process.exitCode = code`. The +dispatcher overwrites it, and index.ts:956's `process.exit(0)` makes it final. + +Fix: `return Number(process.exitCode ?? 0)` — the pattern already used for `service` +at dispatch.ts:309 and eight other commands. + +Correction to the report: its quoted snippet is stale (HEAD uses dynamic +`await import`). Its claim that `account` is unaffected holds — dispatch.ts:426 +returns `cmdAccount`'s code directly. + +Test: `tests/cli-dispatch.test.ts`, existing `dispatchCommand exit codes` block; +the `service` case at line 80 is the template. + +## #2698 — 503 `reason` and `hint` never printed + +`responseMessage` (runtime-api.ts:50) returns on the first of `error`/`message`/ +`detail` and never reads `reason` or `hint`, which the server supplies at +management-auth.ts:455-459. `runCliAction` prints only `error.message`. + +The full body is already on `RuntimeApiError.body` (runtime-api.ts:86) — nothing +needs re-fetching. Fix is one function: append `reason` and `hint` as distinct +lines, keep the 400-char cap on string bodies. Every `runtimeRequest` caller +inherits it. `apiError` (account-api.ts:123) needs the same treatment. + +Test: `tests/cli-management-auth.test.ts` already drives `runtimeRequest` against an +injected `fetchImpl`. + +## #2696 — launchd aliases the admin token as `OPENCODEX_API_AUTH_TOKEN` + +Three files together; no single one is wrong. + +- `src/service.ts:464` `buildServiceShellCommand` unconditionally exports + `~/.opencodex/service-api-token` as `OPENCODEX_API_AUTH_TOKEN` before `exec … start`. +- `src/service.ts:383` `writeServiceApiTokenFile` copies whatever is in + `process.env.OPENCODEX_API_AUTH_TOKEN` into that file **with no check that the + value is not an `ocx_admin_…` management token**. Callers: 1887, 2025, 2378, 2576. +- `src/server/management-auth.ts:200` `ready()` -> `isDataPlaneAdmissionSecret` + fails the **entire** management plane closed; `src/server/auth-cors.ts:349` matches + the presented admin token against `configuredApiAuthToken()`, which is exactly + `process.env.OPENCODEX_API_AUTH_TOKEN`. + +Behavior: when both hold the same string, boot records +`{available:false, reason:"management credential conflicts with a data-plane credential"}` +and every `/api/*` returns 503 — on a loopback install where `isApiAuthRequired()` +is false and no data-plane token was ever needed. Exporting +`OPENCODEX_ADMIN_AUTH_TOKEN` in the CLI cannot help: the server already fenced the +plane at startup. + +Nothing in `src/` writes an admin token into the service token file — the collision +comes from a user shell that had `OPENCODEX_API_AUTH_TOKEN` set to their admin +token. That does not make it user error: `writeServiceApiTokenFile` is the chokepoint +that should refuse. + +Fix: refuse at write time (`/^ocx_admin_/` or equal to `configuredAdminToken()`) +with an actionable message; same guard in `assertServiceAuthEnvironment` +(service.ts:369) so `install`/`repair` fail loudly. For existing installs, add a +startup repair: when the two files are byte-identical **and the bind is loopback**, +drop `service-api-token` rather than fencing `/api/*`. + +**Security-boundary note:** this touches credential handling, so it needs the +explicit security review `MAINTAINERS.md` requires. The repair path must not widen +admission — it removes a redundant data-plane secret on loopback only, and must not +run for a non-loopback bind. If that cannot be established cleanly, the write-time +refusal ships alone and the repair is deferred. + +Tests: `tests/service.test.ts` (already manipulates the env var at 20-28, 264-285); +server-side fail-closed behavior in `tests/server-management-auth.test.ts`. + +## #2701 — PATH `ocx` can be older than the running proxy + +Not implemented, rather than broken. Both halves exist: + +- CLI version: `help.ts:8` `packageVersion()`, used only by `printVersion`. +- Proxy version: `/healthz` returns `version: VERSION` (server/index.ts:959). +- `collectStatus` throws it away: when `findLiveProxy()` succeeds it **skips the + health fetch entirely** and synthesizes `message: "ok (pid …)"` (status.ts:193-199, + deliberate race avoidance per the comment at 192). Only the non-live path formats + `ok v` (status.ts:159). So on a healthy proxy `ocx status` never sees the + version. +- `LiveProxy` carries pid/port/hostname/source and no version + (`src/server/proxy-liveness.ts:64`) — even though `isOpencodexHealthz` (:90) + already validated at :94 that a + version string was present (line 94). +- `doctor.ts` has no drift check; the only "older" warning is about the Codex binary. + +Fix: add `version?: string` to `LiveProxy`, populated in the probe that already +parsed the body — no extra request, no new race. Compare in `collectStatus` against +`packageVersion()`, emit a warning line plus `cliVersion`/`proxyVersion` on +`CliStatusJson`. Mirror in `runDoctor`. + +Tests: `tests/cli-status-json.test.ts`, `tests/doctor.test.ts`. + +## #2702 — missing pause / strategy / sticky verbs + +Pure CLI gap; the routes are complete. `PUT /api/codex-auth/accounts/pause` +(auth-api.ts:1494), `PUT …/pause-exhausted` (:1569), +`PUT|PATCH /api/codex-auth/pool-strategy` (:1676, accepts `strategy` and +`stickyLimit`). + +Correction to the report: those are **PUT**, not POST. + +The subcommand table at account.ts:298-309 has no `pause`, `pause-exhausted`, +`strategy`, or `sticky`, and `ACCOUNT_USAGE` documents none. Fix follows the +existing `cmdPriority` shape in account-extended.ts. Reuse +`parseAccountPoolStickyLimit`'s 1-100 contract server-side; let the 400 be the +authority rather than re-validating client-side. + +Test: `tests/cli-account.test.ts`, or `tests/cli-headless-parity.test.ts` which +exists for exactly this gap class. + +## #2703 — `paused` and the 5h window dropped + +Three separate drops. The report understates the third, which is the one that +matters: + +1. `paused` is absent from `AccountRow` (account-api.ts:14-27) and + `CodexAccountDto` (:184), so `fetchCodexRows` never reads it (:230-241) even + though the server always sends it (auth-api.ts:286 pool, :1315 main). + `statusText` (account.ts:65) can therefore only print `selected`/`needs-reauth`. +2. `refreshLine` gates the whole quota block on weekly/monthly and prints + `quota: unknown` when only a 5h window exists (account-extended.ts:253). Five + lines below, `quotaParts` (:275) already renders `5h` correctly for the provider + path — the two halves of the file disagree. +3. **Not in the issue:** `projectQuota` (account-api.ts:195) whitelists seven keys + and omits `fiveHourPercent`/`fiveHourResetAt`, so the field is stripped before + any renderer runs. `quotaText` reads `quota.fiveHourPercent ?? quota.shortPercent` + (account.ts:89) — the first operand is unreachable on the Codex path. **Fixing the + renderers alone does not fix the bug.** + +Also: `quota` is only populated under `--quota`, because `fetchCodexRows` spreads it +conditionally on `forceRefresh` (:240) and `cmdList` only requests it under +`--quota` (account.ts:166). That is the deliberate #2566 cost decision, not a bug — +but it means "5h in `list`" means "5h in `list --quota`", and the docs must say so. + +## #2704 — `logs` has no `--conversationId` + +`observe.ts:60-70` parses only `--follow/-f`, `--provider`, `--model`, `--status`, +`--limit`. The server accepts both spellings at request-log.ts:1032: +`params.get("conversationId") || params.get("conversation")`. + +The report's second claim is correct and sharper: `filterRequestLogs` handles +`provider`, `conversationId`, `status`, `tail`, `offset`, `limit` — and **no +`model`**. So `ocx logs --model x` is silently accepted and silently ignored, which +is worse than rejecting it. Implement `model` server-side (match `entry.model` plus +`entry.attempts[].model`, mirroring the `provider` clause) rather than rejecting the +flag: a silently-ignored filter produces wrong conclusions from correct-looking +output. + +Tests: `tests/management-api-logs-metrics.test.ts` for the server filter; CLI +query construction alongside `handleObserveCommand` coverage in +`tests/cli-usage-report.test.ts`. + +## #2705 — access key usage fields dropped + +`access.ts:29` formats each key as exactly `id name prefix`. The server attaches +`usage: rollup.get(k.id) ?? {requests7d:0, totalRequests:0}` +(oauth-account-routes.ts:586) plus optional `attributionSince` and +`historyTruncated` (589-590). + +Two things the fix must get right, both already encoded server-side: + +- `ApiKeyUsage` is a **discriminated union** (api-key-usage.ts:15): + `{ambiguous:true}` carries no numbers, and the comment at line 11 is explicit that + rendering a number beside an ambiguity marker is the failure mode to avoid. Print + `ambiguous`, never `0`. +- `lastUsedAt` is optional; absent means "not used within the read window", which + `attributionSince` exists to disambiguate. Print it once as a footer. + +`--json` already works (`printData` dumps the raw payload, runtime-api.ts:288). +Only the human branch is lossy. + +## #2700 — usage report omits `accounts[]` + +`UsageReportInput` (usage-report.ts:23-41) has no `accounts` field and +`formatUsageReport` renders only summary, providers, models (PROVIDER table at +usage-report.ts:119, MODEL at :129). The server includes `accounts` +(`UsageSummary.accounts`, summary.ts:126; the read-failure fallback ships +`accounts: []` at logs-usage-routes.ts:334), and `observe.ts:153` passes the payload +straight through. + +**Important qualification — `accounts` is NOT unconditional.** +`projectUsageSummary` sets `accounts: []` whenever a provider or model filter is +active (summary.ts:943, reasoned at :865-872): account rows are not +provider-partitioned in a way the projection could honestly re-derive, and +unfiltered account totals beside filtered model totals would invite the wrong +reading. That is a deliberate correctness choice, not a bug. + +It matters for this unit because `ocx usage --provider xai --json` is exactly how an +agent would check per-account spend for one provider, and it returns an empty +`accounts` array with no explanation. wp4 must render that state explicitly rather +than as an empty table. + +Fix: add the field and one `table([...])` block after PROVIDER, filtered to +`requests > 0`. Render `legacy-ambiguous` rows with a marker — `ambiguous` is on the +DTO (summary.ts:97) for exactly that reason. Single file, no server change. + +## #2699 — per-account usage not persisted for OAuth providers + +The label type is Codex-only by construction: + +- `src/usage/log.ts:14`: `type CodexUsageAccountLogLabel = "main" | \`p${string}\``, + validated at :16 against `CODEX_ACCOUNT_LOG_LABEL_RE` = `/^p[a-f0-9]{6}$/` + (`src/codex/account-label.ts:6`). +- Every writer drops a non-matching label: usage/log.ts:369, :456, + server/request-log.ts:262, :381. +- The only producer, `codexAuthContextLogLabel` (account-label.ts:32), returns + `undefined` for anything that is not a Codex `pool`/`main-pool` context. +- Attribution fallback also refuses: `legacyCodexAccountLabel` (summary.ts:681) + returns `null` unless `baseProviderLabel(provider) === "openai"`, so `buildAccounts` + drops the row at :706. + +The identity is already in hand and never stamped: `core.ts` resolves +`resolved.accountId` from the OAuth snapshot and keeps it in +`genericFailoverAccountId` (core.ts:2888) purely for 429 cooldown attribution. +Anthropic already encodes its account into the provider label (core.ts:2876 +`formatAnthropicProviderForLog`) — so xai/cursor are the gap, not OAuth generally. + +Fix, privacy-preserving: + +1. Widen the label to a discriminated form: keep `"main" | p` for Codex, add a + provider-scoped `o` derived via `sha256(accountId)`, reusing the shape of + `fallbackCodexAccountLogLabel` (account-label.ts:17). Rename the type off + `Codex…` and widen the regex in one place. +2. Stamp `logCtx.accountLogLabel` in `core.ts` beside the existing + `genericFailoverAccountId` assignment, and again after each rotation site + (4328, 4629, 5221) so a rotated request attributes to the account that served it. +3. Let an explicit non-Codex label survive `accountLabelForAttribution` in + summary.ts. Leave `legacy-ambiguous` behavior for unlabeled openai rows alone. +4. **Never persist emails.** The log path carries only the hash; `maskEmail` stays + on display paths. + +`supportsPerAccountQuota` (providers/quota.ts:1454, currently `=== "anthropic"`) is +a separate concern and out of scope here. + +This is the only issue in the set that touches the request path +(`src/server/responses/core.ts`) and the shared usage-log schema, so per +`AGENTS.md` it needs full `bun run typecheck` and `bun run test` rather than a +focused check. The operator suspended local suite runs for this loop, so that +validation lands in wp9's CI pass — recorded here so the exception is explicit +rather than forgotten. + +## Landing order + +| Wave | Issues | Rationale | +|---|---|---| +| 1 | #2697, #2698, #2701 | Diagnosability. Non-zero exits, full 503 text, version drift — small, and they make everything after them verifiable. | +| 2 | #2696 | The fail-closed collision, verified through wave-1 output. Security review required. | +| 3 | #2703 + #2702, #2704, #2705 | Independent surface gaps. 2703/2702 share files and land together. | +| 4 | #2699 -> #2700 | #2700's table is only meaningful for xai/cursor once #2699 stamps labels. | diff --git a/devlog/_plan/260828_ocx_agentic_control/005_audit_record.md b/devlog/_plan/260828_ocx_agentic_control/005_audit_record.md new file mode 100644 index 0000000000..bfab666c07 --- /dev/null +++ b/devlog/_plan/260828_ocx_agentic_control/005_audit_record.md @@ -0,0 +1,117 @@ +# 005 — A-gate audit record (wp1) + +Reviewer: independent read-only `gpt-5.6-sol` explorer, high effort, against +`d3481ee` (14 docs, +1769). Verdict: **GO-WITH-FIXES (blockers=7)**. + +Every blocker below was **independently re-verified** against source before amending +the plan — the reviewer's conclusions were not taken on trust. Where I confirmed a +finding, the confirmation command or the source line is named. + +## What the reviewer verified as CORRECT + +Roughly 40 file:line anchors checked; the RCA layer held. Confirmed correct including +every claim I asked to be re-checked: `projectQuota`'s 7-key whitelist stripping +`fiveHourPercent` (account-api.ts:198) with `account.ts:89`'s unreachable first +operand; the `dispatch.ts:419`/`:428` `return 0`; `responseMessage` scanning only +three keys (runtime-api.ts:53) while the body is retained on the throw (:86); +`reason`+`hint` at management-auth.ts:455-459; all four +`writeServiceApiTokenFile` callers; the six account-label anchors; +`filterRequestLogs` having no `model` clause while `observe.ts:70` still sends one; +#2702's routes being PUT; `ApiKeyUsage` as a discriminated union with its warning +comment; the 20 dead `USAGE` exports having zero external consumers; the shadowed +`GET /api/storage`; all 7 non-literal registration mechanisms; the star-POST consent +gate; and no `devlog/` security-triage or Lab-boundary violation. + +## Blockers and dispositions + +### C1 — 050.3 patched a function that does not exist — FOLDED + +The doc showed `legacyCodexAccountLabel(entry)`. Confirmed by reading +summary.ts:680-690: `legacyCodexAccountLabel` takes `provider: string`, and the real +gate is `accountLabelForAttribution(provider, explicit)` at :687, called from :705. +The shown patch would not compile, and the widening decision sits in +`isCodexUsageAccountLogLabel` at :688. + +Folded: 050.3 rewritten against `accountLabelForAttribution`, with the +widening-ownership choice made explicit (add a sibling predicate rather than widen the +Codex one, because that predicate is also the writers' validator). + +### C2 — the stamp site is inside an unreachable gate — FOLDED + +Confirmed: core.ts:2887 wraps the `genericFailoverAccountId` assignment in +`isGenericFailoverProvider`, which requires `authMode === "oauth"` and excludes +openai/anthropic (`src/oauth/generic-account-failover.ts:82`); the rotation paths at +:4317, :4618, :4696, :4781 additionally require `isGenericOAuthFailoverEnabled`, +which needs failover on and >= 2 accounts (:164). + +A single-account xai user would never stamp, while every listed test passed — exactly +C-ACTIVATION-GROUNDING-01. Folded: attach at the `resolved` snapshot +(core.ts:2878-2879) outside the gate; five re-stamp sites named, not three; and an +explicit activation scenario recorded (xai, oauth, one account, failover off) with the +observable effect C must check. + +### H1 — the recurrence-guard regex was vacuous — FOLDED + +The reviewer ran the proposed pattern against real `dispatch.ts`: one match at +`handleLogin` (:195), and neither :419 nor :428, because `[^)]*` cannot span +`deps.args.slice(1)`. The guard would have greened over the regression it existed to +catch. Folded: `[^;]*` form, plus a mandatory red-first assertion against a pre-fix +fixture. + +### H2 — the counts were wrong — FOLDED + +Confirmed by importing the modules: `CLI_COMMANDS.length` = 58, visible = 52, +`DISPATCH_COMMANDS.size` = 57 — the docs said 49/43/52. Usage blocks are 37 by `rg`, +of which 20 are the dead exports. Folded into 000 and 002, and 020.2's scope restated. + +### H3 — 040's sketch had four wrong signatures — FOLDED + +Confirmed: `apiJson(deps, baseUrl, method, path, body?, options?)` (account-api.ts:88), +`apiError(json, fallback: string)` (:123), `printData(value, wantsJson, lines?: string[])` +(runtime-api.ts:288), `configAndType(deps, name)` synchronous (account-extended.ts:230), +and no `takeFlag`/`takeOption` in that module. Folded: sketch rewritten against +`cmdPriority` (account-extended.ts:637-690) with a signature table naming each wrong +assumption, and the `status === 0` transport check ordered first. + +### H4 — `accounts[]` is blanked under any filter — FOLDED + +Confirmed at summary.ts:943 with the reasoning at :865-872. 004's "unconditionally +includes `accounts`" was false for filtered requests, and +`ocx usage --provider xai --json` is the natural agent query. Folded: 004 qualified, +and 030 now prints an explicit withheld-rows note instead of an empty table, with a +new accept criterion and test. + +### H5 — two verbs already exist — FOLDED + +Confirmed: `auto-switch` at account.ts:302 -> `cmdAutoSwitch`, `reset-credits` at +:313 -> `handleAccountAuthCommand`. 001's reach column and 060's seed list corrected. + +## Medium findings + +- **M1 (parity gate could pass vacuously) — FOLDED.** The two-direction check cannot + verify the 40+ non-literal routes, so an under-declared registry was undetectable. + Added a third per-module count-reconciliation check with an enumerated non-literal + allowlist. This mattered most: the parity gate is the unit's central claim. +- **M2 (`ACCOUNT_USAGE` has 4 live consumers) — FOLDED.** Confirmed at account.ts:127, + :213, :256, :317. Documented the stderr-vs-stdout and `return 1`-vs-`process.exit` + difference and chose the smaller path: re-source the text, keep the call sites. +- **M3 (inverted `responseMessage` args) — FOLDED.** Real order is `(body, status)`; + both snippets corrected to verbatim source. +- **M4 (wp3 overloaded) — FOLDED.** Split 020.5 into wp3b (`025`). The split is + dependency-shaped, not effort-shaped: the contract tests consume wp3's capability + table, so wp3b is a genuine successor phase (PHASE-SPLIT-01 forbids effort buckets, + not successor phases). + +## Low findings + +L1 (bare `proxy-liveness.ts` path) and L2 (usage-report table lines are :119/:129, not +:115/:124) folded. L3 was a confirmation, not a defect: 010.3's 404/409 mapping for the +account client is a breaking change and 010 already disclosed it. + +## Residual + +None open. All 7 blockers and all 4 Mediums are folded as concrete amendments; no +blocker was rebutted rather than fixed. The reviewer's own recommendation — fix +C1/C2/H1-H3 before wp2 starts, correct H4/H5 so wp4/wp7 are not sized against bad +inventory, and answer M1 before wp3 lands — is satisfied by these amendments. + diff --git a/devlog/_plan/260828_ocx_agentic_control/010_phase_transport_honesty.md b/devlog/_plan/260828_ocx_agentic_control/010_phase_transport_honesty.md new file mode 100644 index 0000000000..b968fe3db6 --- /dev/null +++ b/devlog/_plan/260828_ocx_agentic_control/010_phase_transport_honesty.md @@ -0,0 +1,235 @@ +# 010 — wp2: transport honesty (#2697, #2698, #2696) + +Closes: #2697, #2698, #2696. Branch: `codex/ocx-transport-honesty` off +`codex/ocx-agentic-control-roadmap`. + +Every later phase is verified through CLI output. A phase that lands while `ocx` +exits 0 on failure and hides the server's `reason` cannot be proven, so this is +first. + +## Scope + +IN: `src/cli/dispatch.ts`, `src/cli/runtime-api.ts`, `src/cli/account-api.ts`, +`src/service.ts`, `src/server/management-auth.ts` (read-side only), tests. +OUT: new verbs, help generation, DTO rendering, usage attribution. + +--- + +## 010.1 — `dispatch.ts`: stop discarding exit codes + +MODIFY `src/cli/dispatch.ts` around line 419 and 428. + +Before: + +```ts + provider: async deps => { + const { handleProviderCommand } = await import("./provider.ts"); + await handleProviderCommand(deps.args.slice(1), deps); + return 0; + }, +``` + +After: + +```ts + provider: async deps => { + const { handleProviderCommand } = await import("./provider.ts"); + await handleProviderCommand(deps.args.slice(1), deps); + // handleProviderCommand reports failure through process.exitCode + // (provider.ts sets it from handleProviderRuntimeCommand). Returning a + // literal 0 here made index.ts call process.exit(0) and erase it (#2697). + return Number(process.exitCode ?? 0); + }, +``` + +Identical change for the `models` runner. Do not change `handleModels` / +`handleProviderCommand` signatures — that is a wider refactor with no extra benefit +while `process.exitCode` is already the contract eight other runners use. + +**Guard against recurrence.** A second one-line fix invites a third. Add to +`tests/cli-dispatch.test.ts` a source scan in the same spirit as +`core-lab-boundary`, rejecting a runner that awaits a handler and then returns a +literal 0. + +**The pattern must tolerate nested parentheses.** The obvious +`/await\s+handle\w+\([^)]*\);\s*\n\s*return 0;/` does **not** work: `[^)]*` +cannot span `deps.args.slice(1)` because of the inner `)`. Run against the real +pre-fix `dispatch.ts` it matches exactly one site — `handleLogin` at :195 — and +misses both :419 and :428, the two this phase fixes. A guard that greens against a +pattern which never covered the regression is worse than no guard. + +Use a `;`-terminated form instead, and **drive it red first**: + +```ts +const SWALLOW_RE = /await\s+handle\w+\([^;]*\);\s*\n\s*return 0;/g; +``` + +The test asserts two things, and the first is what keeps it honest: + +1. Against a fixture holding the pre-fix bodies of the `provider` and `models` + runners, `SWALLOW_RE` **matches** — proof the pattern sees the defect. +2. Against current `dispatch.ts` source, every match's command name is in an + explicit allowlist of runners that genuinely cannot fail. Adding a name is then a + deliberate, reviewable act rather than a silent widening. + +The permissive `[\s\S]*?` variant matches 6 sites and is too loose; `[^;]*` is the +narrowest form that spans an argument list without crossing a statement boundary. + +--- + +## 010.2 — `runtime-api.ts`: render `reason` and `hint` + +MODIFY `src/cli/runtime-api.ts` `responseMessage` (line 50). + +**Parameter order is `(body, status)`, not `(status, body)`** — the call site at :86 +is `responseMessage(body, response.status)`. Keep it; an earlier draft of this doc +inverted it, which typechecks only if the call site is flipped too and otherwise +binds `status` to the body object. + +Before (verbatim): + +```ts +function responseMessage(body: unknown, status: number): string { + if (body && typeof body === "object") { + const record = body as Record; + for (const key of ["error", "message", "detail"]) { + if (typeof record[key] === "string" && record[key]) return record[key]; + } + } + if (typeof body === "string" && body.trim()) return body.trim().slice(0, 400); + return \`Management request failed (${status})\`; +} +``` + +After: + +```ts +const PRIMARY_MESSAGE_KEYS = ["error", "message", "detail"] as const; + +function stringField(body: Record, key: string): string | undefined { + const v = body[key]; + return typeof v === "string" && v.trim() ? v.trim() : undefined; +} + +function responseMessage(body: unknown, status: number): string { + if (typeof body === "string" && body.trim()) return body.trim().slice(0, 400); + if (!body || typeof body !== "object") { + return \`Management request failed (${status})\`; + } + const obj = body as Record; + let primary: string | undefined; + for (const key of PRIMARY_MESSAGE_KEYS) { + primary = stringField(obj, key); + if (primary) break; + } + // The server states WHY under 'reason' and WHAT TO DO under 'hint' + // (management-auth.ts:455). Both were dropped, so a fenced management plane + // read as a generic failure (#2698). + const reason = stringField(obj, "reason"); + const hint = stringField(obj, "hint"); + const parts: string[] = []; + parts.push(primary ?? \`Management request failed (${status})\`); + if (reason && reason !== primary) parts.push(\`reason: ${reason}\`); + if (hint) parts.push(\`hint: ${hint}\`); + return parts.join("\n").slice(0, 1200); +} +``` + +The 400-char cap stays for opaque string bodies; the structured path gets a wider +1200 cap because it now carries up to three labeled lines. + +## 010.3 — `account-api.ts`: same treatment, and stop erasing network errors + +MODIFY `src/cli/account-api.ts`. + +`apiJson` (line ~88) currently collapses any thrown fetch into `{status: 0}` inside +a catch block with an empty body, discarding the message. Change the sentinel to carry it: + +```ts +export type ApiResult = { status: number; json: unknown; transportError?: string }; + +// ... + } catch (err) { + // status 0 is the transport sentinel; the message was previously discarded, + // which is why an unreachable proxy and a 500 were indistinguishable (#2698). + return { status: 0, json: null, transportError: err instanceof Error ? err.message : String(err) }; + } +``` + +`apiError` (line ~123) reads only `json.error`. Extend it to the same +primary/reason/hint composition, and to print `transportError` when `status === 0`. +Keep the `cleanupRequired` special case. + +Exit-code mapping: `apiError` currently always yields 1. Map 404 to 4 and 409 to 5 +to match client 1's vocabulary (runtime-api.ts:311), so the two clients stop +disagreeing. That is a behavior change for scripts that only checked `!== 0`; +those keep working. Record it in the PR description. + +## 010.4 — `service.ts`: refuse the admin/data-plane token collision + +MODIFY `src/service.ts`. + +`writeServiceApiTokenFile` (line ~383) is the chokepoint. Add before the write: + +```ts + // A management (admin) token must never become the data-plane secret: the + // server fences the ENTIRE management plane closed when the two match + // (management-auth.ts:200 -> isDataPlaneAdmissionSecret), so every /api/* + // returns 503 and the CLI cannot even ask why (#2696). + assertNotAdminToken(token); +``` + +NEW helper in the same file: + +```ts +const ADMIN_TOKEN_PREFIX = "ocx_admin_"; + +export function assertNotAdminToken(token: string): void { + if (!token.startsWith(ADMIN_TOKEN_PREFIX)) return; + throw new Error( + "OPENCODEX_API_AUTH_TOKEN holds a management (admin) token. " + + "The service exports it as the data-plane secret, which fences the whole " + + "management API closed. Unset OPENCODEX_API_AUTH_TOKEN, or set it to a " + + "distinct data-plane key, then re-run the install.", + ); +} +``` + +Call it from `assertServiceAuthEnvironment` (line ~369) too, so `install` and +`repair` fail loudly instead of producing a broken service. + +Deliberately NOT in this phase: the startup repair that deletes a colliding +`service-api-token` on a loopback bind. It changes credential state on disk at boot +and needs the `MAINTAINERS.md` security review plus a loopback-only proof. The +write-time refusal fixes new installs and is safe on its own; existing broken +installs get a diagnosable 503 (via 010.2) plus the actionable message. Repair is +recorded in `081` as a follow-up decision, not silently dropped. + +## 010.5 — `ocx doctor`: surface the collision + +MODIFY `src/cli/doctor.ts`: add a check that reads the service token file and the +admin token and reports a hard failure when they match, naming the fix. This is the +one place an operator with an already-broken install will look. + +`doctor` currently always exits 0 (002). Leave that alone in this phase — changing +it is a contract change for anything that runs `ocx doctor` in a pipeline; wp3 owns +it as part of the exit-code contract work. + +## Tests + +| File | Assertion | +|---|---| +| `tests/cli-dispatch.test.ts` | `provider`/`models` runners propagate a handler-set `process.exitCode`; source scan rejects new `return 0` swallowing | +| `tests/cli-management-auth.test.ts` | a 503 body `{error, reason, hint}` renders all three; a `{reason}`-only body does not degrade to the generic message | +| `tests/cli-account.test.ts` | `apiJson` transport failure carries `transportError`; 404 -> 4, 409 -> 5 | +| `tests/service.test.ts` | `writeServiceApiTokenFile` and `assertServiceAuthEnvironment` throw on an `ocx_admin_` value | +| `tests/doctor.test.ts` | the collision check reports and names the remedy | + +## Accept criteria + +1. `ocx models live` and `ocx provider quota` against a stopped proxy exit non-zero. +2. A 503 with `reason`+`hint` prints all three parts. +3. `ocx service install` with an admin token in `OPENCODEX_API_AUTH_TOKEN` fails + with the actionable message instead of producing a fenced install. +4. `ocx doctor` names an existing collision. +5. No new `return 0` swallowing can be added without editing the allowlist. diff --git a/devlog/_plan/260828_ocx_agentic_control/011_wp2_implementation_record.md b/devlog/_plan/260828_ocx_agentic_control/011_wp2_implementation_record.md new file mode 100644 index 0000000000..51e3cfd8cc --- /dev/null +++ b/devlog/_plan/260828_ocx_agentic_control/011_wp2_implementation_record.md @@ -0,0 +1,121 @@ +# 011 — wp2 implementation record + +Branch `codex/ocx-transport-honesty`. Implements `010` (#2697, #2698, #2696). + +## What landed + +| File | Change | +|---|---| +| `src/cli/dispatch.ts` | `provider` and `models` runners return `Number(process.exitCode ?? 0)` instead of a literal 0 (#2697) | +| `src/cli/runtime-api.ts` | `responseMessage` composes primary + `reason:` + `hint:`, capped at 1200 chars (#2698) | +| `src/cli/account-api.ts` | `ApiResult.transportError` retains the cause behind the status-0 sentinel; `apiError` renders `reason`/`hint` and maps 404→4, 409→5; `proxyUnreachable` accepts the cause | +| `src/service.ts` | `assertNotAdminToken` refuses an `ocx_admin_` value as the data-plane secret, called from both `writeServiceApiTokenFile` and `assertServiceAuthEnvironment` before the loopback short-circuit (#2696) | +| `src/cli/doctor.ts` | `dataPlaneCredentialCollisionCheck` names an already-broken install and its remedy without echoing the credential | +| `tests/cli-transport-honesty.test.ts` | 16 tests, new file | + +`apiError` gained an optional third parameter, so all existing call sites keep +compiling and their current exit code. + +## The guard found a real error in its own plan + +`010` specified an allowlist of `["login", "logout", "tray"]` for runners allowed to +return a literal 0. That was a guess, and the guard contradicted it: the actual +offenders are `debug` and `login`, and `logout`/`tray` do not match the pattern at all. + +Both are allowlisted on a verified basis rather than an assumed one: +`handleDebugCommand` and `handleLogin` report every failure with `process.exit(1)` +from inside the handler (debug.ts does so on 11 paths), so control reaches `return 0` +only on success. + +That is a narrower claim than "these commands cannot fail". `login` reporting success +for a failed OAuth flow is a real gap — it belongs to wp3b's uniform exit-code +contract (`025`), not to this phase's management-transport scope. Recorded rather than +silently absorbed. + +The `[^;]*` form was also necessary, not stylistic: the `[^)]*` form `010` originally +proposed matches neither target runner, and the red-first assertion in the test exists +so that can never regress unnoticed. + +## Verification + +- `tsc --noEmit`: clean. Proven non-vacuous by injecting a type error into + `account-api.ts`, observing `TS2322` at the exact line, then restoring and + re-confirming clean. +- `bun test tests/cli-transport-honesty.test.ts`: 16 pass. +- `bun test` over `cli-dispatch`, `cli-management-auth`, `cli-account`, `service`, + `cli-registry`, `cli-headless-parity`: 297 pass. + +## One unexplained failure, recorded rather than dismissed + +The first run of that six-file batch reported 296 pass / 1 fail — the +`vision --list` case in `cli-headless-parity`. The same batch on a pristine +`origin/dev` worktree gave 297/0, so the initial reading was that this diff caused it. + +It did not reproduce in 26 subsequent runs, including the same batch on this branch. +The test passes in isolation. + +Most plausible mechanism, stated as a hypothesis and not a conclusion: +`fakeRuntime` starts a real `Bun.serve` per test, and files run in parallel, so a +port-level collision would return another fake's payload — which is exactly the shape +of the failure (a missing `visionModels` entry rather than a wrong assertion). Nothing +in this diff touches that harness or `handleAgentCommand`. + +Not claimed as fixed and not dismissed as flaky. If it recurs in wp9's CI, the first +thing to check is the harness's port allocation, not this phase's changes. + +## Review round: two blockers, both real, both folded + +Two independent read-only reviewers were dispatched on the committed diff. Both +returned `GO-WITH-FIXES (blockers=2)`, and between them they found three defects I had +missed. Each was re-verified against source before being fixed. + +### The fix was half-inert (both reviewers, independently) + +`apiError` gained a `status` parameter and `apiJson` gained `transportError` — and +**no production caller passed or read either.** All 19 `apiError` call sites passed two +arguments, so the 404→4 / 409→5 mapping never executed; all 30 `proxyUnreachable()` +call sites passed no argument, so the retained transport cause was never printed. The +behavior existed only in this phase's own unit tests, while the commit message and +`010.3` claimed it shipped. + +That is worse than an incomplete fix: it is a false claim backed by a passing test. +Fixed by threading the status through all 19 call sites and the cause through the 14 +`status === 0` guards (one quota-report site legitimately has no such field). Two new +tests assert the **call sites**, not the helpers, so the capability cannot go inert +again. + +### `tray` had the identical #2697 defect and the guard could not see it + +`windowsTrayCommand` reports failure through `process.exitCode` (tray/windows.ts:742, +:755) and returns void, so `ocx tray install` printed an error and exited 0 — exactly +the defect this phase claimed to close. + +The recurrence guard missed it because `SWALLOWED_EXIT_CODE` was anchored on +`await handle\w+\(`, scoping it to the `handle*` naming convention rather than to the +defect class. A guard that only sees defects that follow a naming convention is a guard +against tidy code, not against the bug. + +Pattern broadened to `await [\w.]+\(`. That immediately surfaced four more candidates +(`update`, `__refresh-version`, `__tray-host`, `__gui-update-worker`), each verified in +its handler before being allowlisted with its own stated reason: `runUpdate` exits 1 on +all six failure paths, and the three hidden helpers never assign `process.exitCode`. + +### Corrected: the `login` allowlist reason + +The committed comment said `login` exits 1 on failure. It exits 1 only for an unknown +provider; a real OAuth failure makes `runLogin` **throw**, propagating past the runner. +The conclusion (`return 0` is unreachable after a failure) holds, but via a different +mechanism. Corrected, because an allowlist entry justified by the wrong mechanism is +one refactor away from being wrong. + +### Findings accepted as out of scope + +- Doctor reports the collision as WARN while the plane is fully fenced. `OAuthDoctorCheck` + has no FAIL level and doctor's exit code belongs to wp3b (`025`). Recorded there. +- `dataPlaneCredentialCollisionCheck` takes an injectable `env` but calls + `configuredAdminToken()` without it, so half the comparison reads real machine state. + Real seam defect; folded now since it is one argument. +- The multi-line error message reaches line-oriented log consumers as orphan lines. + Intended tradeoff of #2698, recorded not contested. +- `assertNotAdminToken`'s prefix-only test misses an env-set admin token without the + `ocx_admin_` prefix, which the doctor equality check does catch. Asymmetry folded. diff --git a/devlog/_plan/260828_ocx_agentic_control/020_phase_capability_registry.md b/devlog/_plan/260828_ocx_agentic_control/020_phase_capability_registry.md new file mode 100644 index 0000000000..a6be8d1ea0 --- /dev/null +++ b/devlog/_plan/260828_ocx_agentic_control/020_phase_capability_registry.md @@ -0,0 +1,229 @@ +# 020 — wp3: capability registry as the single source of truth (#2701) + +Closes: #2701. Branch: `codex/ocx-capability-registry` off +`codex/ocx-transport-honesty`. + +This is the keystone. Everything after it registers into the structure this phase +introduces; building verbs first means writing them twice. + +## The problem in one line + +The CLI's help is 20 module `USAGE` constants with zero consumers outside their own +files, plus a hand-written banner explicitly exempted from matching the registry, +and **nothing anywhere relates the CLI surface to the 183 management routes.** + +## Design: one capability table, three consumers + +NEW `src/cli/capabilities.ts` — a declarative table describing, per CLI capability: +the command path, the management route(s) it drives, its flags, whether it mutates, +and its `--json` shape. Three consumers read it: + +1. `help.ts` generates the banner and every subcommand usage block from it. +2. `tests/cli-api-parity.test.ts` asserts every route in the API registry has a + capability or a recorded exemption. +3. The new `ocx capabilities` verb emits it as JSON — the machine-readable index an + agent reads first to discover what it can do. + +The third consumer is the point of the whole unit: an agent should not have to parse +help text. + +### Shape + +```ts +export type CapabilityRoute = { + readonly method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE"; + readonly path: string; // "/api/codex-auth/accounts/pause" +}; + +export type CapabilityFlag = { + readonly name: string; // "--id" + readonly value?: "string" | "number" | "boolean"; + readonly required?: boolean; + readonly summary: string; +}; + +export type Capability = { + readonly command: readonly string[]; // ["account", "pause"] + readonly summary: string; + readonly routes: readonly CapabilityRoute[]; + readonly flags: readonly CapabilityFlag[]; + readonly mutates: boolean; + readonly json: "payload" | "envelope" | "none"; + readonly details?: readonly string[]; +}; +``` + +### Route registry (server side) + +NEW `src/server/management/route-registry.ts` — a declared list of every reachable +management route with method, path pattern, auth class, and a mutation flag. + +This must be **declared, not harvested.** 001 established that 40+ routes are +invisible to a string grep: lazy `import()`, handlers outside the `??` chain, path +constants, prefix decoding, regex params, `endsWith` matching. A parity test built on +`rg` would pass vacuously while missing the entire `/api/codex-auth/*` family. + +To keep the declaration honest the test needs **three** checks, not two. Two are +obvious and insufficient: + +1. **Scan -> registry.** Every `if (url.pathname === "…")` literal in the management + files must exist in the registry. This has real reach — 188 such literals across + those files — and it catches an added literal route. +2. **Registry -> source.** Every registry entry's path must appear in its declared + owner file. + +Check 2 **cannot hold for the 40+ non-literal routes** (lazy imports, path constants, +regex params, `endsWith`, prefix decode) named in 001. For those entries neither +direction verifies anything, so nothing detects an **under-declared** registry: a +route registered through `codex-restart-contract.ts:17` and simply omitted from the +registry is invisible to both, and `tests/cli-api-parity.test.ts` would then pass with +a genuine gap. The gate would be blind exactly where 001 says it must not be. + +3. **Per-module route-count reconciliation.** For each handler module, assert + `registryRoutesFor(module).length === literalCountIn(module) + nonLiteralAllowlist[module].length`, + where `nonLiteralAllowlist` enumerates each non-literal route with the mechanism + that registers it. Adding a non-literal route without registering it then fails on + the count, and adding it to the allowlist without a registry entry fails too. + +State all three in the test's header comment, with why none is sufficient alone, so a +future reader does not "simplify" it back to one mechanism. This is the unit's central +claim — if this gate can pass vacuously, nothing else in the unit holds. + +### Exemptions + +NEW in the registry: an `exempt` field with a required reason, one of: + +| Reason | Routes | Justification | +|---|---|---| +| `session-only` | `POST /api/github/star`, 6 `/api/codex-prompt*` writes | dashboard session required; the star POST is the user-consent boundary in `AGENTS_INSTALL.md` and must never get a verb | +| `disabled` | `PUT /api/config` | deliberate 405 | +| `capability-principal` | `POST /api/providers/reload` | process-scoped HMAC principal, not an operator action | +| `test-seam` | `/api/storage/*/test-stream` (2) | test seams, not operator capability | +| `local-transport` | 20 `/api/lab/*` reads | `ocx lab` reaches the same data via local SQLite | +| `dead` | shadowed `GET /api/storage` in logs-usage-routes | unreachable; delete instead | + +An exemption without a reason string fails the test. That is what stops the gate +from being silently widened later. + +## 020.1 — generate the banner + +MODIFY `src/cli/help.ts`. Replace the 69-line hand-written template (lines 18-88) +with a renderer over `CAPABILITIES` grouped by section. Keep the existing top/bottom +prose. `printSubcommandUsage` (line ~94) switches from `CLI_COMMANDS` to the +capability table, falling back to the registry entry for commands that have no +management route (`init`, `start`, `service`, …). + +MODIFY `tests/cli-registry.test.ts`: the current test greps `help.ts` source for +command names, and its comment at line 104 licenses drift ("curated… not required to +match the registry exactly"). Replace with an assertion that the rendered banner +contains exactly the visible capability set — generation makes the license obsolete. + +## 020.2 — retire the 20 dead `USAGE` exports + +For each module listed in 002, delete the module-level `USAGE` constant and have the +usage path call `printSubcommandUsage("account")` etc. Where a usage string carries +genuinely local detail, move that detail into the capability's `details[]`. + +**`ACCOUNT_USAGE` is not a dead export — it has four live consumers** at +account.ts:127, :213, :256, :317, each `console.error(ACCOUNT_USAGE)`. Replacing them +is a behavior change in two ways that must be handled deliberately: + +| | current | `printSubcommandUsage` | +|---|---|---| +| stream | `console.error` (stderr) | `console.log` (stdout) | +| control flow | `return 1` | calls `process.exit(1)` on an unknown name | + +Moving account usage errors from stderr to stdout breaks any script that separates +the streams, and swapping `return 1` for `process.exit` changes how the dispatcher +sees the result. Either give `printSubcommandUsage` an explicit stream/exit mode and +use the stderr+return variant here, or keep the four call sites returning 1 and only +source their **text** from the capability table. The second is smaller and preferred. +`tests/cli-account.test.ts:989` already drives `printSubcommandUsage("account")`, so +it will catch a careless swap. + +Scope correction: 002 counts **37** usage blocks, of which 20 are the dead +module-level exports. This phase deletes the 20 dead ones and re-sources the +remainder's text; it does not delete the live ones. + +`ocx ready`'s triplicated string (registry.ts:354, root.ts:74, ready.ts) collapses to +one capability entry. + +This is mechanical but large. It is in this phase rather than deferred because the +generated banner and the hand-written blocks would otherwise contradict each other, +which is the exact failure #2701's reporter hit. + +## 020.3 — `ocx capabilities` + +NEW `src/cli/capabilities-command.ts`: + +``` +ocx capabilities human tree +ocx capabilities --json full machine-readable table +ocx capabilities --json --mutating-only +ocx capabilities --route /api/keys which commands drive this route +``` + +Register in `dispatch.ts` and `registry.ts`. This is the agent's entry point. + +## 020.4 — version skew (#2701) + +MODIFY `src/server/proxy-liveness.ts`: add `version?: string` to `LiveProxy` and +populate it in the probe that already parsed and validated the healthz body +(`isOpencodexHealthz`, line ~94). No extra request, so the race the comment at +status.ts:192 avoids is not reintroduced. + +MODIFY `src/cli/status.ts` `collectStatus`: compare `live.version` against +`packageVersion()` (export it from `help.ts`) and, when they differ, push + +``` +warning: CLI 2.35.0 does not match the running proxy 2.36.1 — this ocx on PATH is +stale. Its help and features describe a different build. Reinstall or run the +proxy's own binary. +``` + +Add `cliVersion` and `proxyVersion` to `CliStatusJson`. Mirror the warning in +`runDoctor`. + +## 020.5 — moved out + +The uniform exit-code and `--json` contract work moved to its own work-phase, +`025_phase_uniform_cli_contract.md` (wp3b). This phase already carries banner +generation, ~20 constant deletions, a new command, a new server field, and three new +test files, and it is the phase every later phase blocks on. Adding two breaking +contract changes on top made it the largest phase in the stack by a wide margin. + +Split rationale is dependency-shaped, not effort-shaped: the contract work *consumes* +the capability table this phase produces (it needs `json` declared per capability to +test order-independence), so it is a genuine successor phase rather than a slice +carved off to make this one smaller. + +- `doctor` and `sync-cache` return non-zero on failure (002 flagged both as always 0). +- `--json` becomes order-independent everywhere via `takeFlag`: fixes `status` + (lone-arg only) and `restore` (positional `args[1]`, so `ocx restore back --json` + currently ignores the flag). +- `doctor`, `login`, `logout`, `sync`, `sync-cache`, `debug` gain `--json`. +- The capability table declares each command's `json` mode, and a test asserts every + capability with `json !== "none"` actually accepts the flag anywhere in argv. + +`doctor` changing from always-0 is a **breaking change for pipelines**. Call it out +in the PR description and the docs-site changelog entry; the alternative is a +diagnostic command that cannot gate anything, which is worse. + +## Tests + +| File | Assertion | +|---|---| +| `tests/cli-api-parity.test.ts` (NEW) | every registry route has a capability or a reasoned exemption; every capability route exists in the registry | +| `tests/management-route-registry.test.ts` (NEW) | registry vs handler-source drift, both directions | +| `tests/cli-registry.test.ts` | generated banner equals the visible capability set | +| `tests/cli-capabilities.test.ts` (NEW) | `--json` shape is stable; `--route` filter resolves | +| `tests/cli-status-json.test.ts` | `cliVersion`/`proxyVersion` present; mismatch warns | +| `tests/doctor.test.ts` | drift warning; non-zero exit on failure | + +## Accept criteria + +1. `ocx --help` is generated; no hand-maintained command list remains. +2. A new route with no verb and no exemption fails `tests/cli-api-parity.test.ts`. +3. `ocx capabilities --json` enumerates the surface with routes and flags. +4. `ocx status` warns on version skew and reports both versions in JSON. +5. Every capability declaring JSON accepts `--json` in any argv position. diff --git a/devlog/_plan/260828_ocx_agentic_control/021_wp3_stale_check_amendment.md b/devlog/_plan/260828_ocx_agentic_control/021_wp3_stale_check_amendment.md new file mode 100644 index 0000000000..cfa1f9c549 --- /dev/null +++ b/devlog/_plan/260828_ocx_agentic_control/021_wp3_stale_check_amendment.md @@ -0,0 +1,408 @@ +# 021 — wp3 P-phase stale-check amendment + +Four parallel read-only Sol explorers checked `020` against the tree at `43b0788e0`. +All four returned VERDICT: FAIL. Every blocking finding below was re-verified +independently against source before being accepted; the counts here are ones +reproduced directly, not ones handed over. + +`020` is not withdrawn. Its design — one capability table, three consumers — survives +intact. What failed is the measurement layer: the numbers it reasons from, and the +arithmetic identity of the gate it calls its own central claim. + +The single root cause: **`020` and `001` count grep lines and call them routes.** Every +blocking finding is a consequence. + +## A1 — check 3's identity cannot balance (blocking) + +`020` specifies: + +``` +registryRoutesFor(module).length === literalCountIn(module) + nonLiteralAllowlist[module].length +``` + +This fails on today's correct tree, in four independent ways: + +| Failure | Evidence | +|---|---| +| A literal line can carry two routes | `oauth-account-routes.ts:332` and `codex/auth-api.ts:1676` both match `PUT \|\| PATCH` | +| 19 literal lines carry no inline method | method decided by an enclosing block: `lab-routes.ts:296,309,322,336,354,358,370,385,411,441,471,516`, `storage-log-guard-routes.ts:112,128,135,140,145`, `integration-routes.ts:313,373` | +| 2 live routes use a **negated** guard and appear in no literal count | `storage-log-guard-routes.ts:150` (`GET /api/storage`), `routing-analytics-routes.ts:26` (`GET /api/routing-analytics`) | +| One module has 1 route and 0 literals | `routing-analytics-routes.ts` — a literal-count-keyed test omits the module entirely | + +The negated guards, confirmed directly: + +``` +$ rg -n 'pathname !== "' src/server/management/*.ts +storage-log-guard-routes.ts:150: if (url.pathname !== "/api/storage" || req.method !== "GET") return null; +routing-analytics-routes.ts:26: if (url.pathname !== "/api/routing-analytics" || req.method !== "GET") return null; +``` + +The second is the finding that matters most. `020` proposes the `===` scan specifically +to stop a vacuous pass, and that scan cannot see `/api/routing-analytics` at all. +Worse, for `GET /api/storage` the scan sees **only the dead shadowed copy** at +`logs-usage-routes.ts:346` and never the live one. A gate built as written would +mistake the corpse for the patient. + +**Amendment.** Reconcile on distinct `(method, path)` pairs, never on `rg` line hits. +The scanner must: + +1. match both `pathname === "…"` and `pathname !== "…"` forms; +2. resolve the method from the same line, else the two following lines, else the + enclosing block — and **fail loudly when it cannot resolve one**, rather than + defaulting to GET; +3. expand `X || Y` method disjunctions into separate pairs; +4. key the per-module allowlist by `(method, path, mechanism)`, so the mechanism is + recorded per route rather than per module. + +Requirement 2's fail-loud clause is the one to defend in review. A scanner that +silently guesses a method is a scanner that reports a number nobody can trust, which +is how `001` arrived at figures no one can reproduce. + +## A2 — "188 literals" and "40+ invisible" contradict each other (blocking) + +Both cannot be true, because the 188 was measured over a **wider file set** than the +one the "40+" claims are invisible from. + +``` +$ rg -o 'pathname === "' src/server/management-api.ts src/server/management/ | wc -l +159 +$ rg -o 'pathname === "' src/server/management-api.ts src/server/management/ \ + src/codex/auth-api.ts src/codex/native-profile-api.ts | wc -l +188 +``` + +The 159 was reproduced independently before any explorer's number was read. The +29-line difference is `src/codex/auth-api.ts` (20) and `src/codex/native-profile-api.ts` +(9) — the exact files whose routes `001` counts as "invisible because mounted outside +the `??` chain." They are invisible to a scan **scoped to `src/server/management/`**, +and plainly visible in the scan that produced 188. + +**Amendment.** The genuinely non-literal count is **18**, enumerated with mechanism +and `file:line` below. State the file set explicitly wherever a count appears: 21 +route-carrying files, of which 20 contain literals. + +| # | Route | Mechanism | Site | +|---|---|---|---| +| 1 | `GET /api/storage` | negated guard | `storage-log-guard-routes.ts:150` | +| 2 | `GET /api/routing-analytics` | negated guard | `routing-analytics-routes.ts:26` | +| 3 | `GET /api/system/codex-app-server` | path constant | `system-routes.ts:164` | +| 4 | `POST /api/system/codex-restart` | path constant | `system-routes.ts:165` | +| 5 | `POST /api/providers/reload` | path constant | `provider-routes.ts:467` | +| 6-7 | `GET\|PUT /api/client-integrations/{clientId}` | prefix decode | `integration-routes.ts:130` | +| 8 | `GET /api/request-history/{id}` | `pathname.slice` | `request-history-routes.ts:176` | +| 9 | `GET /api/request-history/{id}/route-decision` | `endsWith` | `request-history-routes.ts:131` | +| 10-13 | provider alias, model-aliases, custom-model PUT/DELETE | regex | `model-routes.ts:264,291,606,678` | +| 14-16 | lab subjects/events/artifacts by id | regex | `lab-routes.ts:424,499,545` | +| 17 | `POST /api/lab/automation/runs/{id}/cancel` | regex | `lab-automation-routes.ts:106` | +| 18 | `POST /api/system/restart` | **literal** — `001` wrongly calls it a path constant | `system-routes.ts:133` | + +Regex routes are **8**, not `001`'s 7. Native-main-profiles is **9**, not 10. Codex-auth +is **23** `(method, path)` pairs over 20 literal guards, not 22. + +## A3 — the lab exemption is wrong and makes accept criterion 2 unsatisfiable (blocking) + +`020` exempts "20 `/api/lab/*` reads" under `local-transport`, on the grounds that +`ocx lab` reads the same data from local SQLite. The premise is sound — +`src/cli/lab.ts` imports `../lab/query` directly and never fetches `/api/lab` — but the +set is wrong in a way that matters. + +The family is **21 routes: 14 GET and 7 mutating.** The mutating seven, verified: + +``` +lab-routes.ts:296 POST /api/lab/public/preview +lab-routes.ts:309 POST /api/lab/public/export +lab-routes.ts:322 POST /api/lab/public/verify +lab-routes.ts:336 POST /api/lab/public/community/import +lab-automation-routes.ts:119 POST /api/lab/automation/run +lab-automation-routes.ts:163 PUT /api/lab/automation +lab-automation-routes.ts:106 POST /api/lab/automation/runs/{id}/cancel (regex) +``` + +A local SQLite read cannot start an automation run or import a community bundle, so +`local-transport` does not cover any of these seven. As written, seven existing routes +have no verb and no valid exemption, so accept criterion 2 — "a new route with no verb +and no exemption fails the parity test" — is violated on day one. The gate must be +born red or widened at birth, and widening it at birth is precisely the silent erosion +`020` says the mandatory reason string exists to prevent. + +**Amendment.** Split the row: + +- **11** lab reads are `local-transport`-exempt (8 literals at `lab-routes.ts:354,358,370,385,411,441,471,516` plus 3 regex at `:424,499,545`). +- **3** further GETs (`/api/lab/public/community`, `/api/lab/automation`, `/api/lab/automation/runs`) are exempt only if the doc says so explicitly. Decision: include them, reason `local-transport`. +- **The 7 mutating routes get real verbs in wp7**, not an exemption. wp3 declares them with `exempt: { reason: "deferred-verb", owner: "wp7" }` — a *bounded* exemption naming the phase that retires it, so the gate stays honest and the debt stays visible rather than absorbed. + +Introducing `deferred-verb` is a real widening of the exemption vocabulary, so it is +constrained: it requires an `owner` field naming a work-phase, and +`tests/cli-api-parity.test.ts` asserts every `deferred-verb` owner is a phase that +still exists in the goalplan. An exemption that outlives its owner fails the build. + +## A4 — the version-skew edit targets a function that cannot carry a value (blocking) + +`020.4` says to populate `version` "in the probe that already parsed and validated the +healthz body (`isOpencodexHealthz`)". That function is a pure predicate: + +```ts +export function isOpencodexHealthz(body: HealthzIdentity | null): boolean +``` + +It receives the body and returns a boolean. The parsed body lives one frame up in +`proxyIdentityAt`, whose signature discards everything but the pid: + +```ts +): Promise<{ pid: number | null } | null> { + … + return { pid }; +``` + +**Amendment.** The edit is three hops, not one: widen `proxyIdentityAt`'s return type +to carry `version?: string` (guarded by `typeof === "string"`, mirroring the existing +pid guard), thread it through all three `findLiveProxy` construction sites, then add +the `LiveProxy` field. `020.4`'s "no extra request" conclusion still holds — the body +is already parsed — but for a different reason than it states. + +### A4.1 — 12 exhaustive assertions break, and the doc does not list the file + +`tests/proxy-liveness.test.ts` appears nowhere in `020`'s file list or test table. It +holds 9 `expect(live).toEqual(…)` and 3 `expect(identity).toEqual(…)` assertions +(counts reproduced directly). Bun's `toEqual` rejects an extra **defined** key while +tolerating an `undefined` one, so every assertion whose mock body carries a version +string fails the moment the field is threaded through. Add the file to the amended test +table as MODIFIED. + +### A4.2 — the warning has no semantic home + +`020.4` says to "push" the warning into the warnings array. There is no +general-purpose warnings array. The only candidate is `warningParts` at `status.ts:238`, +which is joined into `codexRuntime.warning` and printed under the Codex-runtime +heading. A stale-`ocx`-on-PATH warning is not a Codex-runtime fact. + +**Amendment.** Add a dedicated top-level `versionSkew` object to `CliStatusJson` (type +at `status.ts:23`, construction literal at `status.ts:312`) plus a printer edit in +`src/cli/index.ts` near `handleStatus`. Without the printer edit the warning is +invisible in non-JSON `ocx status`, which defeats accept criterion 4 while appearing to +satisfy it. + +Two fallbacks must suppress the warning rather than report skew against a placeholder: +server-side `VERSION` falls back to `"0.0.0"`, and `packageVersion()` returns +`"unknown"`. `schemaVersion` stays `1`: additive optional fields do not break the +contract, and `tests/cli-status-json.test.ts:88` pins it. + +## A5 — 020.2 is a contract change, not a deletion sweep (blocking) + +`020`'s opening line — "20 module `USAGE` constants with zero consumers outside their +own files" — conflates three different quantities. The truth: + +- **20** is the *file* count. +- **37** usage constants are declared across those files. +- **12** are exported (count reproduced directly). +- The 12 exports are one-line **aliases** at file bottoms (`export const ACCESS_USAGE = USAGE;`). Those alias statements are dead. +- The constants they alias are **heavily live**: 243 non-declaration references inside their own files. + +The live consumers are not incidental. They are the second argument to a contract: + +```ts +export class CliUsageError extends Error { + constructor(message: string, readonly usage?: string) { +export function rejectArgs(args: string[], usage: string, options?: RejectArgsOptions): void { +``` + +So "delete the module-level `USAGE` constant and have the usage path call +`printSubcommandUsage`" is not mechanical. It changes what `CliUsageError.usage` +carries across hundreds of call sites, and `CliUsageError` is how the CLI reports +argument errors — the surface these very issues are about. + +**Amendment.** wp3 deletes the **12 dead alias exports** and re-sources usage *text* +from the capability table, leaving `rejectArgs(args, USAGE)` call sites structurally +intact: each module's `const USAGE` becomes a lookup into the capability table rather +than a literal. Same identifier, same call sites, generated content. The four +`ACCOUNT_USAGE` sites keep `console.error` + `return 1` exactly as `020` already +preferred. + +## A6 — "exactly the visible capability set" is unsatisfiable as stated + +The banner carries `help` and `--version`, and `CLI_COMMANDS` has an entry for neither, +though both are real dispatch runners. It also carries subcommand lines (`ocx restore +back`, `ocx doctor --reclaim-response-temps`, `ocx claude desktop`) that are not +registry entries. + +**Amendment.** Add `help` and `--version` capability entries, and declare a +`bannerLines` field so a capability can contribute more than one banner row. Then +"exactly" is checkable. Without this, accept criterion 1 ("no hand-maintained command +list remains") is not reachable. + +## A7 — 020.3's registration constraints, stated + +A literal reading of "register in `dispatch.ts` and `registry.ts`" fails the existing +parity assertions. The binding constraints: + +1. `CLI_COMMANDS` entry needs `name`, `usage`, `summary` (all required). +2. No `hidden: true` — the hidden set is pinned to exactly six `__`-prefixed names. +3. A `capabilities:` key in `commandRunners` returning `Promise`. +4. No aliases unless a matching own-name entry exists. +5. **Ordering: 020.1 lands before 020.3.** The banner test greps `help.ts` source text, + so a registry entry added before the banner is generated requires a hand-edit that + 020.1 then deletes. `020` states no ordering; this amendment fixes it. + +## A8 — the `src/lab/` boundary risk `020` never mentions + +`020` does not address the Lab boundary at all, and the protected set is **four** files, +not three: `tests/core-lab-boundary.test.ts` includes `src/server/management-api.ts` — +which statically imports every `src/server/management/` handler, making it the natural +importer of a new `route-registry.ts`. If that registry reaches `src/lab/`, the guard +fails. + +**Mechanism, verified against the guard's own source.** The registry holds only inert +data — `{ method, path, module, auth, mutates, exempt? }`. Three specifics make it safe: + +- Path strings are data. `"/api/lab/status"` in a string literal creates no module edge; the walker follows only `import`/`export … from` and direct `import()`. +- Any Lab-adjacent type comes in via `import type`, which the guard's regex excludes with a negative lookahead on every alternative. +- The `module` field names the *handler module* (`"./management/lab-routes"`), which the guard deliberately does not treat as naming Lab. Existing lazy dispatch at `management-api.ts:126,129` stays untouched: the registry describes those routes, it must never resolve their handlers. + +Verify with `bun test tests/core-lab-boundary.test.ts`, which prints the offending +chain on failure, rather than by inspection. + +## A9 — unreproducible headline numbers + +`001`'s "183 reachable routes / 108 mutating / 19 files" records no counting method and +no command. An independent enumeration produced 206/116/21. Neither was adjudicated, +and that is the point: **an unreproducible number has no place in the phase whose +entire purpose is preventing a vacuous gate.** + +**Amendment.** `001` is annotated to mark the figures unsourced. wp3 does not depend on +them — the registry is *declared*, and once it exists it becomes the count, with the +reconciliation test as its proof. Accept criteria are restated against the registry +rather than against any prior number. + +## Amended test table + +| File | State | Assertion | +|---|---|---| +| `tests/management-route-registry.test.ts` | NEW | three checks: scan→registry, registry→source, per-module `(method,path)` reconciliation with fail-loud method resolution | +| `tests/cli-api-parity.test.ts` | NEW | every route has a capability or a reasoned exemption; every `deferred-verb` owner is a live goalplan phase | +| `tests/cli-capabilities.test.ts` | NEW | `--json` shape stable; `--route` filter resolves | +| `tests/cli-registry.test.ts` | MODIFIED | generated banner equals the visible capability set incl. `help`/`--version`/`bannerLines` | +| `tests/proxy-liveness.test.ts` | **MODIFIED (was missing)** | 12 `toEqual` assertions carry `version` | +| `tests/cli-status-json.test.ts` | MODIFIED | `versionSkew` present; `schemaVersion` stays 1; stderr stays empty under `--json` | +| `tests/doctor.test.ts` | MODIFIED | skew section emitted (exists: 763 lines, drives `runDoctor`) | +| `tests/core-lab-boundary.test.ts` | UNCHANGED, must stay green | the registry reaches no `src/lab/` module | + +## Amended accept criteria + +1. `ocx --help` is generated; no hand-maintained command list remains. +2. A new route with no capability and no reasoned exemption fails `tests/cli-api-parity.test.ts` — and the gate is **green on day one**, because the 7 mutating lab routes carry bounded `deferred-verb` exemptions owned by wp7. +3. `ocx capabilities --json` enumerates the surface with routes and flags. +4. `ocx status` warns on skew in **both** human and JSON output, and suppresses the warning when either side reports a placeholder version. +5. The reconciliation test fails on a route added by any of the mechanisms in A2's table, proven by adding one and observing red before removing it. + +Criterion 5 replaces a claim with a demonstration. Given that `020`'s original gate +would have failed on correct code while believing itself rigorous, a gate that has not +been driven red is not yet evidence of anything. + +## A10 — self-audit: four defects in this amendment + +The A-gate audit of this document was attempted twice with an adversarial reviewer and +both attempts died on provider rate limits (`429`), so the audit was performed directly +instead. Recording that substitution honestly matters: an unaudited amendment claiming +to fix an unaudited plan is the same failure one level up. + +Four defects were found in the amendment itself. Two are blocking. + +### A10.1 — A1's method resolution looks the wrong direction (blocking) + +A1 says resolve the method "from the same line, else the two following lines, else the +enclosing block." In `lab-routes.ts` the method is fixed by a **preceding early-return +guard**, not an enclosing block: + +```ts + if (req.method !== "GET") return null; // lab-routes.ts:352 + + if (url.pathname === "/api/lab/status") { // :354 — GET, decided 2 lines earlier +``` + +`storage-log-guard-routes.ts` inverts it again — the path is outer and the method is +the **inner** early return: + +```ts + if (url.pathname === "/api/storage/codex-logs") { // :112 + if (req.method !== "GET") return null; // :113 +``` + +So three distinct shapes carry a method: same-line conjunction, a preceding sibling +guard that narrows everything after it, and a nested guard inside the path block. A +scanner that only looks forward and outward resolves none of the 8 lab reads. + +**Fix.** Resolve the method by walking the enclosing function's statements in order and +maintaining a *method narrowing context*: a top-level `if (req.method !== X) return` +narrows every subsequent sibling statement to X; a nested one narrows only its own +block; a same-line conjunction binds only that route. This is a small interpreter over +guard statements, not a regex, and A1 must say so — the honest cost of the fail-loud +requirement is that the scanner cannot be a one-line `rg`. + +### A10.2 — A3's `owner` assertion cannot run in CI (blocking) + +A3 has `tests/cli-api-parity.test.ts` assert that every `deferred-verb` owner "is a +phase that still exists in the goalplan." The goalplan is machine-local and +**gitignored**: + +``` +$ rg -n 'codexclaw' .gitignore +45:.codexclaw/ +46:**/.codexclaw/ +$ git ls-files .codexclaw # empty +``` + +`tests/repo-hygiene.test.ts` additionally forbids tracking it. A test reading that file +passes on this machine and cannot even find it in CI, which is the same class of +vacuous gate this amendment exists to eliminate — and it would have been introduced by +the fix, not the original. + +**Fix.** Bind the exemption to a **tracked** artifact instead. `deferred-verb` carries +`owner: "wp7"` plus `ownerDoc: "devlog/_plan/260828_ocx_agentic_control/060_phase_gui_parity.md"`, +and the test asserts the doc exists and names the route. `devlog/` is tracked ordinary +markdown, so the assertion means the same thing in CI as locally. The debt stays +visible in the repository rather than in one developer's state directory. + +### A10.3 — A5's lookup can silently produce empty usage text (major) + +A5 has each module's `const USAGE` become a lookup into the capability table. Those +constants are **top-level**, evaluated at import time (`access.ts:12` and its 19 +siblings). ESM tolerates a top-level cycle by yielding `undefined` rather than +throwing, so if the capability table ever imports a module that imports it back, every +`rejectArgs(args, USAGE)` in that module quietly starts reporting empty usage — a +silent regression in exactly the error-reporting surface these issues are about. + +Today the direction is clean (`help.ts` imports only `./registry`; nothing imports +`access.ts`, `combo.ts`, or `observe.ts`), so the cycle is a risk introduced by the +change, not a present defect. + +**Fix.** `src/cli/capabilities.ts` imports **nothing** from `src/cli/` — it is a leaf +data module, same discipline A8 imposes on the route registry. Add a guard test +asserting `capabilities.ts` has no `./`-relative import into a command module, and +assert each generated `USAGE` is a non-empty string so an accidental cycle fails loudly +instead of degrading. + +### A10.4 — A6's `--version` entry is wrong; `help` is deliberately excluded (major) + +A6 proposes capability entries for `help` and `--version`. Both are mis-specified. + +`--version`, `-v`, and `version` never reach the dispatch table at all. They are +resolved in the CLI head (`root.ts:28`) and exit before dispatch, so `--version` has no +runner key and an entry named `--version` would fail the assertion that every canonical +entry is a direct runner key. + +`help` is not an oversight either. `tests/cli-registry.test.ts:14-21` documents the +exclusion in a comment and encodes it in a `headHandled` set — `help`/`--help`/`-h` are +"head-handled pseudo-cases, not commands." A6 read a deliberate decision as a gap. + +**Fix.** Neither becomes a `CLI_COMMANDS` entry. The capability table gains a separate +`headCapabilities` list for head-handled surfaces, which contributes banner lines and +`ocx capabilities --json` output without touching runner-key parity. The banner +equality assertion then compares against `visible capabilities + headCapabilities`, +which is satisfiable — A6's version was not. + +### Confirmed correct in A2 + +`agent-settings-routes.ts` and `oauth-account-routes.ts` are rightly absent from the +18-route table. Their `startsWith`/`slice` hits are payload manipulation +(`oauth-account-routes.ts:584` truncates a key prefix; `agent-settings-routes.ts:900` +filters model routes), not path guards. The omission was checked rather than assumed. diff --git a/devlog/_plan/260828_ocx_agentic_control/025_phase_uniform_cli_contract.md b/devlog/_plan/260828_ocx_agentic_control/025_phase_uniform_cli_contract.md new file mode 100644 index 0000000000..62756c105e --- /dev/null +++ b/devlog/_plan/260828_ocx_agentic_control/025_phase_uniform_cli_contract.md @@ -0,0 +1,70 @@ +# 025 — wp3b: uniform CLI contract (exit codes and `--json`) + +Branch: `codex/ocx-uniform-contract` off `codex/ocx-capability-registry`. + +Split out of wp3 (see `020` §020.5). It consumes wp3's capability table: the tests +here read each capability's declared `json` mode, so this phase cannot precede it. + +## 025.1 — commands that cannot gate a script + +`doctor` and `sync-cache` always return 0 (002). A diagnostic that cannot fail is +not usable in a pipeline, which is the whole point of an agentic surface. + +- `src/cli/doctor.ts` — return non-zero when any check fails. `010.5` added the + admin/data-plane collision check, which is exactly the case an operator needs to + gate on. +- `sync-cache` — return non-zero on a failed cache write. + +**This is a breaking change for pipelines** that run `ocx doctor` and ignore the +result. Call it out in the PR description and the docs-site changelog. The +alternative — a diagnostic command that always claims success — is worse. + +## 025.2 — `--json` accepted in any argv position + +Two commands parse it specially and both are wrong for scripting: + +- `status` accepts `--json` **only as a lone argument** (`index.ts:833`: + `statusArgs.length === 1 && statusArgs[0] === "--json"`), so `ocx status --json --verbose` + silently prints human output. +- `restore` matches it positionally at `args[1]`, so `ocx restore back --json` + **ignores the flag entirely**. + +Convert both to the order-independent `takeFlag` used everywhere else. + +## 025.3 — `--json` where it is missing + +`doctor`, `login`, `logout`, `sync`, `sync-cache`, `debug` have no `--json` at all +(002). Each gets one, emitting the same data its human output describes. + +`debug` is the interesting one: it builds its usage text by string interpolation +(`debug.ts:184`) and prints raw log rows. Its JSON mode should emit the rows as an +array rather than a formatted blob, so an agent can filter without parsing text. + +## 025.4 — declare and enforce the contract + +Every capability in wp3's table declares a `json` mode. Add a test asserting that +each capability with `json !== "none"` accepts `--json` in **any** argv position and +emits parseable JSON on stdout. That is the assertion that stops the next drift: +today's inconsistency exists because nothing ever checked. + +Also assert the exit-code vocabulary is uniform: 0 ok, 2 usage, 4 not found, +5 conflict, 64 bad args (`ready` only), 1 otherwise — including for the `account` +family after `010.3` gave it the 404/409 mapping. + +## Tests + +| File | Assertion | +|---|---| +| `tests/cli-json-contract.test.ts` (NEW) | every `json`-declaring capability accepts `--json` in any position and emits valid JSON | +| `tests/cli-status-json.test.ts` | `ocx status --json` works alongside other flags | +| `tests/doctor.test.ts` | non-zero exit on a failing check | +| `tests/cli-dispatch.test.ts` | `restore back --json` honors the flag | + +## Accept criteria + +1. `doctor` and `sync-cache` exit non-zero on failure, and the change is documented + as breaking. +2. `--json` works in any argv position for every capability that declares it. +3. Six previously JSON-less commands emit JSON. +4. A test enforces the contract rather than a convention. + diff --git a/devlog/_plan/260828_ocx_agentic_control/026_wp3b_implementation_record.md b/devlog/_plan/260828_ocx_agentic_control/026_wp3b_implementation_record.md new file mode 100644 index 0000000000..15d081e464 --- /dev/null +++ b/devlog/_plan/260828_ocx_agentic_control/026_wp3b_implementation_record.md @@ -0,0 +1,66 @@ +# 026 — wp3b implementation record + +Branch `codex/ocx-uniform-contract` off `codex/ocx-capability-registry`. Implements `025`. + +## What landed + +| File | Change | +|---|---| +| `src/cli/doctor.ts` | per-pass failure flag + `doctorFailed()`; a `FAIL`-level OAuth check records a failure | +| `src/cli/dispatch.ts` | `doctor` returns 1 on failure; `restore` scans argv for `--json`; `sync-cache` returns 1 when the cache write did not complete and gained a `--json` envelope | +| `src/cli/index.ts` | `status` uses `takeFlag`, so `--json` works in any argv position | +| `tests/cli-json-contract.test.ts` | 8 tests, new file | + +## The plan under-specified how `doctor` aggregates failures + +`025` says "return non-zero when any check fails." That reads as though there were a +checks collection to inspect. There is not: the `checks.push` calls belong to +`collectOAuthDoctorChecks`, a different function, and `runDoctor` reports by direct +`console.log` across roughly a dozen sections with `ok `/`!! `/`[WARN]` prefixes. + +So the failure signal is a module-scoped flag reset at the top of each `runDoctor` pass. +The reset is not incidental: the suite drives `runDoctor` several times in one process, +and a sticky flag would fail the second call because the first saw a problem — a test +that passes or fails depending on execution order, which is worse than no gate. + +## Only `FAIL` fails the command + +`025` does not distinguish the levels. It matters. `WARN` describes a +degraded-but-working install, and this doctor emits `[WARN]` freely — a Codex app-server +started before the catalog changed, a WHAM probe that could not reach chatgpt.com. Failing +on those would break pipelines that are legitimately green, and the predictable response +is that people stop running the gate. `FAIL` is documented in `doctor.ts:63` as the level +for a surface that is unusable rather than degraded, which is exactly the line worth +exiting non-zero on. + +## `sync-cache` needed a success definition, not just an exit code + +`invalidated.kind === "completed"` with a falsy value means the cache was **not** +rewritten, and any other kind means the write never completed. Both previously exited 0. +But a deliberate skip — Codex integration off — is not a failure, and treating it as one +would make `ocx sync-cache` fail on a correctly configured machine that simply is not +using Codex. Success is therefore `wrote || desiredDisabled`, and the `--json` envelope +reports `wrote` and `skipped` separately so a caller can tell which happened. + +## The contract test generalises past the two known defects + +Pinning only `status` and `restore` would leave the next command free to repeat the +mistake, so the test fails on **any** `args[] === "--json"` in `dispatch.ts`, +`index.ts`, or `root.ts`. It also pins both defective forms as exact strings, so a revert +is caught by a failing test rather than discouraged by a comment. + +## Verification + +- `tsc --noEmit`: clean. +- 9 focused suites: 125 pass, 0 fail, 618 expect() calls. +- Non-vacuous: reverting the `restore` fix alone turned 3 of the 8 contract tests red. +- `ocx status --json` verified live; `ocx status --json --bogus` still rejects. + +## Deferred, deliberately + +`025.3` asks for `--json` on `login`, `logout`, `sync`, and `debug` as well. Those four +are interactive or long-running flows whose human output is not a single structured +result, and inventing an envelope for them without a consumer would be guesswork. They +move to wp7 alongside the GUI-parity verbs, where the shape is driven by an actual caller. +`doctor` and `sync-cache` are done here because both are already single-result commands +that a script wants to gate on. diff --git a/devlog/_plan/260828_ocx_agentic_control/030_phase_dto_fidelity.md b/devlog/_plan/260828_ocx_agentic_control/030_phase_dto_fidelity.md new file mode 100644 index 0000000000..eadcf6d43c --- /dev/null +++ b/devlog/_plan/260828_ocx_agentic_control/030_phase_dto_fidelity.md @@ -0,0 +1,192 @@ +# 030 — wp4: DTO fidelity (#2700, #2703, #2705) + +Closes: #2700, #2703, #2705. Branch: `codex/ocx-dto-fidelity` off +`codex/ocx-capability-registry`. + +Three cases of the CLI throwing away fields the API already returns. All three are +CLI-side; no server change. + +## 030.1 — `#2703`: account `paused` and the 5h window + +Three drops, and the order matters: **fix the projection first**, or the renderer +fixes have nothing to render. + +### (a) `projectQuota` strips the field — `src/cli/account-api.ts:195` + +The whitelist omits `fiveHourPercent` and `fiveHourResetAt`, so `quotaText`'s +`quota.fiveHourPercent ?? quota.shortPercent` (account.ts:89) has an unreachable +first operand. + +```ts + function projectQuota(raw: unknown): AccountQuota | undefined { + // ... + return { ++ fiveHourPercent: num(obj.fiveHourPercent), ++ fiveHourResetAt: str(obj.fiveHourResetAt), + weeklyPercent: num(obj.weeklyPercent), + // ... existing seven keys + }; + } +``` + +### (b) `paused` is not in the row types — `account-api.ts:14-27`, `:184` + +```ts + export type AccountRow = { + // ... ++ paused?: boolean; + }; + + type CodexAccountDto = { + // ... ++ paused?: boolean; + }; +``` + +Map it in `fetchCodexRows` (:230-241). The server always sends it — auth-api.ts:286 +for pool accounts, :1315 for main. + +### (c) renderers + +`statusText` (account.ts:65) gains a `paused` branch. Precedence: `paused` outranks +`selected`, because a paused-but-selected account is the confusing state an operator +most needs named. Print `paused (selected)` rather than picking one. + +`refreshLine` (account-extended.ts:253) gates the quota block on weekly/monthly and +prints `quota: unknown` for a 5h-only account. Five lines below, `quotaParts` (:275) +already does this correctly for the provider path. Rewrite `refreshLine`'s branch to +call the same helper rather than maintaining a second dialect — the two halves of one +file disagreeing is the actual defect. + +### Documentation obligation + +`quota` is only populated under `--quota` (`fetchCodexRows` spreads conditionally on +`forceRefresh`, :240; `cmdList` requests it only under `--quota`, account.ts:166). +That is the deliberate #2566 cost decision. So "5h in `list`" means "5h in +`list --quota`" — say so in the capability `details[]` and in the docs-site page, or +the next reporter files the same issue. + +## 030.2 — `#2705`: access key usage fields + +MODIFY `src/cli/access.ts:29`, which formats each key as exactly `id name prefix`. + +Target output: + +``` +ID NAME PREFIX REQ 7D TOTAL LAST USED +k_9f2a ci-runner ocx_live_… 1,204 18,330 2026-08-27T04:11Z +k_11bd laptop ocx_live_… ambiguous 2026-08-20T22:04Z + +attribution since 2026-07-29T00:00Z; older history truncated +``` + +Two contract requirements, both already encoded server-side: + +- `ApiKeyUsage` is a **discriminated union** (`api-key-usage.ts:15`). The + `{ambiguous:true}` variant carries no numbers, and the comment at line 11 states + that printing a number beside an ambiguity marker is the failure mode to avoid. + Render the word `ambiguous` spanning the numeric columns. Never `0`. +- `lastUsedAt` absent means "not used within the read window", which + `attributionSince` disambiguates. Print `attributionSince` and `historyTruncated` + once as a footer, not per row. + +`--json` already emits the raw payload (`printData`, runtime-api.ts:288); only the +human branch changes. + +## 030.3 — `#2700`: usage report `accounts[]` + +MODIFY `src/cli/usage-report.ts`. + +```ts + export type UsageReportInput = { + // ... ++ accounts?: readonly { ++ accountLogLabel: string; ++ ambiguous?: boolean; ++ requests: number; ++ totalTokens: number; ++ estimatedCostUsd?: number; ++ }[]; + }; +``` + +In `formatUsageReport`, after the PROVIDER table (line ~115) and before MODEL, add: + +```ts + const accounts = (input.accounts ?? []).filter(a => a.requests > 0); + if (accounts.length) { + out.push( + table( + ["ACCOUNT", "REQUESTS", "TOKENS", "EST. COST"], + accounts.map(a => [ + // 'legacy-ambiguous' rows aggregate several accounts; an operator who + // reads them as one account draws the wrong conclusion (summary.ts:97). + a.ambiguous ? \`${a.accountLogLabel} (ambiguous)\` : a.accountLogLabel, + count(a.requests), + count(a.totalTokens), + a.estimatedCostUsd === undefined ? "-" : usd(a.estimatedCostUsd), + ]), + ), + ); + } +``` + +Uses the existing `table`/`count`/`usd` helpers. `observe.ts:153` passes the payload +straight through, so this is one file. + +### The filtered case must not silently print nothing + +`accounts` is **not** unconditional. `projectUsageSummary` sets `accounts: []` +whenever a provider or model filter is active (summary.ts:943, reasoned at +:865-872) — deliberately, because account rows are not provider-partitioned in a way +the projection could honestly re-derive, and unfiltered account totals beside +filtered model totals would invite the wrong reading. + +So `ocx usage --provider xai --json` returns an empty `accounts` array. That is the +most natural way an agent would ask "what did this provider cost me per account", +and an empty table with no explanation is the same silently-wrong-output defect this +unit exists to remove (compare #2704's silently-ignored `--model`). + +Distinguish the two empty cases explicitly: + +```ts + const filtered = Boolean(input.filter?.provider || input.filter?.model); + if (filtered) { + // Not "no accounts" — the server withholds account rows under a filter because + // they cannot be honestly re-partitioned (summary.ts:865-872). + out.push("ACCOUNT: not reported under a provider or model filter; run without filters for per-account totals"); + } else if (accounts.length) { + out.push(table([...])); + } +``` + +Record the same sentence in the capability's `details[]` so +`ocx capabilities --json` carries it, and in wp8's recipe for per-account spend. + +Rows for xai/cursor will be empty until wp6 (#2699) stamps their labels. That is +expected and is why wp6 follows this phase rather than preceding it — the renderer +lands first so wp6's proof is visible immediately. + +## 030.4 — register the capabilities + +Add `account list --quota`'s new columns, `access key list`'s columns, and +`usage`'s accounts table to the wp3 capability entries' `details[]`, so +`ocx capabilities --json` reflects what the commands now emit. + +## Tests + +| File | Assertion | +|---|---| +| `tests/cli-account.test.ts` | `projectQuota` keeps `fiveHourPercent`/`fiveHourResetAt`; `statusText` prints `paused` and `paused (selected)`; `formatAccountTable` shows a 5h-only quota instead of `unknown` | +| `tests/cli-headless-parity.test.ts` | `refreshLine` renders 5h and paused; `handleAccessCommand` prints usage columns, `ambiguous` for the union's ambiguous variant, and the footer | +| `tests/cli-usage-report.test.ts` | `accounts` table renders, filters `requests === 0`, marks ambiguous rows; an active filter prints the withheld-rows note instead of an empty table | + +## Accept criteria + +1. `ocx account list --quota` shows paused state and a 5h-only quota. +2. `ocx access key list` shows `requests7d`, total, `lastUsedAt`, and prints + `ambiguous` rather than a fabricated `0`. +3. `ocx usage` renders an ACCOUNT table with ambiguous rows marked. +4. `ocx usage --provider X` states that account rows are withheld under a filter + rather than printing an empty table. +5. No server-side change in this phase's diff. diff --git a/devlog/_plan/260828_ocx_agentic_control/031_wp4_implementation_record.md b/devlog/_plan/260828_ocx_agentic_control/031_wp4_implementation_record.md new file mode 100644 index 0000000000..28862a7dea --- /dev/null +++ b/devlog/_plan/260828_ocx_agentic_control/031_wp4_implementation_record.md @@ -0,0 +1,91 @@ +# 031 — wp4 implementation record + +Branch `codex/ocx-dto-fidelity` off `codex/ocx-capability-registry`. Implements `030` +(#2700, #2703, #2705). No server change, as `030` required. + +## What landed + +| File | Change | +|---|---| +| `src/cli/account-api.ts` | `projectQuota` keeps the two 5h keys; `paused` added to `AccountRow`, `CodexAccountDto`, and the `fetchCodexRows` mapping | +| `src/cli/account.ts` | `statusText` prints `paused`, leading and additive to `selected` | +| `src/cli/account-extended.ts` | `refreshLine` delegates to `quotaParts` instead of keeping a second quota dialect | +| `src/cli/usage-report.ts` | `accounts` on the input type; ACCOUNT table between PROVIDER and MODEL; withheld-rows note under a filter | +| `src/cli/access.ts` | `formatKeyRows` renders usage columns with a union-safe ambiguous marker and a dataset footer | +| `src/cli/capabilities.ts` | `details[]` for `account list` and `usage` | +| `tests/cli-dto-fidelity.test.ts` | 19 tests, new file | + +## The test `030` proposed could not detect the bug it targeted + +This is the finding worth keeping. `030`'s test table asks +`tests/cli-account.test.ts` to assert that "`formatAccountTable` shows a 5h-only quota +instead of `unknown`". That assertion **passes with the defect fully present**: +`formatAccountTable` takes an `AccountRow` directly, and the field was being dropped one +layer earlier, inside `projectQuota`. + +Confirmed rather than reasoned: after writing the renderer test and seeing it green, the +`projectQuota` fix was reverted and the renderer test **stayed green**. Only then was the +coverage moved to drive `fetchCodexRows` with a server payload, which does go red on the +same revert. + +A renderer test for a projection bug is the same category of mistake as the bug: the layer +that looks responsible is not the one that is. + +The projection test also asserts the pre-existing windows still survive, so a future +whitelist edit cannot add the 5h keys while silently dropping `shortPercent`. + +## `paused` is additive, not exclusive + +`030` says `paused` outranks `selected`. Implemented as **both**, in that order. A +paused-but-selected account is the state an operator most needs named — requests route to +it while the pool believes it is held out of rotation — and printing only the winner of a +precedence rule hides exactly that case. + +## Two quota dialects in one file + +`refreshLine` gated its entire quota block on `weeklyPercent`/`monthlyPercent`, so a 5h-only +account printed `quota: unknown` while `quotaParts`, five lines below in the same file, +rendered the same DTO correctly. Teaching the second dialect about a third window would +have left the disagreement in place, so it delegates instead. + +## The ambiguous union is a contract, not a hint + +`ApiKeyUsage` is a discriminated union whose `{ambiguous:true}` variant carries **no** +numbers, and the type comment states why: an optional marker beside `requests7d: 7` invites +a consumer to render the 7. So the CLI prints `ambiguous` spanning the numeric columns and +never a `0`. A test asserts the output contains no standalone `0` in that case, because +reporting zero requests for a key that may be in heavy use is the dangerous answer for +someone deciding what to revoke. + +`attributionSince` and `historyTruncated` print once as a footer. Without +`attributionSince`, an absent `lastUsedAt` cannot be read at all: "never used" and "nothing +is attributable yet" look identical. + +## The withheld-rows case + +`projectUsageSummary` blanks `accounts` under any provider or model filter, because account +rows are not provider-partitioned in a way the projection could honestly re-derive. "What +did this provider cost me per account" is the most natural way an agent would ask, so an +empty table would have answered "no accounts used this provider" — a different and wrong +answer, and the same silently-wrong-output class this unit exists to remove. + +The renderer states the withholding, and the same sentence is recorded in the `usage` +capability's `details[]` so `ocx capabilities --json` carries it. + +## A plan inaccuracy + +`030` describes `formatUsageReport` as though it returned text and gives an insertion point +of "line ~115". It returns `string[]`. The first version of the new tests asserted +`toContain` against an array and failed for that reason rather than for any product defect. + +## Verification + +- `tsc --noEmit`: clean. +- 6 focused suites: 189 pass, 0 fail, 748 expect() calls. +- Non-vacuous: reverting `projectQuota` turns the projection test red; the renderer test + alone does not move, which is why both exist. + +## Left for wp6 + +ACCOUNT rows stay empty for xai and cursor until wp6 stamps their labels (#2699). The +renderer lands first deliberately, so wp6's proof is visible the moment it lands. diff --git a/devlog/_plan/260828_ocx_agentic_control/040_phase_new_verbs.md b/devlog/_plan/260828_ocx_agentic_control/040_phase_new_verbs.md new file mode 100644 index 0000000000..f7f976564a --- /dev/null +++ b/devlog/_plan/260828_ocx_agentic_control/040_phase_new_verbs.md @@ -0,0 +1,135 @@ +# 040 — wp5: new verbs and filters (#2702, #2704) + +Closes: #2702, #2704. Branch: `codex/ocx-new-verbs` off `codex/ocx-dto-fidelity`. + +## 040.1 — `#2702`: account pause / resume / strategy / sticky + +Server routes are complete; this is purely a missing CLI caller. Note the methods — +the issue says POST, the code says **PUT**: + +| Verb | Route | Body | +|---|---|---| +| `ocx account pause --id ` | `PUT /api/codex-auth/accounts/pause` | `{id, paused: true}` | +| `ocx account resume --id ` | same route | `{id, paused: false}` | +| `ocx account pause-exhausted [--off]` | `PUT /api/codex-auth/accounts/pause-exhausted` | flag | +| `ocx account strategy []` | `GET` via accounts payload / `PUT|PATCH /api/codex-auth/pool-strategy` | `{strategy}` | +| `ocx account sticky []` | same route | `{stickyLimit}` | + +MODIFY `src/cli/account-extended.ts`: add `cmdPause`, `cmdResume`, +`cmdPauseExhausted`, `cmdStrategy`, `cmdSticky` following the existing `cmdPriority` +shape (account-extended.ts:637-690). + +**Use the real signatures.** They are easy to get wrong, and an earlier draft of this +doc got four of them wrong at once: + +| Helper | Real signature | Wrong assumption to avoid | +|---|---|---| +| `apiJson` | `(deps, baseUrl, method, path, body?, options?)` — account-api.ts:88 | not `(baseUrl, path, {method, body})`; method is the **third positional** arg | +| `apiError` | `(json: Record, fallback: string)` — account-api.ts:123 | takes the json record and a fallback **string**, not the result object and a boolean | +| `configAndType` | `(deps, name)`, **synchronous**, returns a classify result — account-extended.ts:230 | not `await configAndType(deps)` returning `{baseUrl}`; base URL comes from `resolveBaseUrl(deps)` separately | +| `flag` / `flagValue` | `(args, name)` — account-extended.ts:52, :59 | this module has no `takeFlag`/`takeOption`, and does not import `printData` | +| `usage` | `(message?) => number` — account-extended.ts:224 | usage errors return a code; they do not throw `CliUsageError` here | + +Also note `status === 0` is the transport sentinel and must be checked **before** the +status comparison, or an unreachable proxy reports as a management error. + +```ts +export async function cmdPause(args: string[], deps: AccountDeps, paused: boolean): Promise { + const wantsJson = flag(args, "--json"); + const name = args.shift(); + const requestedId = args.shift(); + if (!name || !requestedId || args.length) return usage(); + const classified = configAndType(deps, name); + if ("error" in classified) return usage(`Error: ${classified.error}`); + if (classified.type !== "codex") { + return usage("Error: pause applies to the openai Codex account pool"); + } + const id = requestedId === "main" ? MAIN_ID : requestedId; + + const baseUrl = await resolveBaseUrl(deps); + if (!baseUrl) return proxyUnreachable(); + + const response = await apiJson(deps, baseUrl, "PUT", "/api/codex-auth/accounts/pause", { id, paused }); + if (response.status === 0) return proxyUnreachable(); + if (response.status !== 200) { + return apiError(response.json, `failed to ${paused ? "pause" : "resume"} ${requestedId}`); + } + if (wantsJson) console.log(JSON.stringify({ ok: true, provider: name, id, paused }, null, 2)); + else console.log(`${name}: ${requestedId} ${paused ? "paused" : "resumed"}`); + return 0; +} +``` + +The other four verbs follow the same skeleton. `cmdStrategy` and `cmdSticky` share +`PUT /api/codex-auth/pool-strategy`, so implement one helper taking the field to set +rather than two near-duplicates. + +Do **not** re-validate `stickyLimit` client-side. The server owns the 1-100 contract +(`parseAccountPoolStickyLimit`); a duplicated bound is a second thing to keep in +sync, and the 400 is already actionable now that wp2 prints `reason`. + +Register in the `cmdAccount` chain (account.ts:298-309) and add the capability +entries. `ACCOUNT_USAGE` no longer exists after wp3, so the help text comes from the +capability table automatically — which is the payoff for ordering wp3 first. + +**Sibling gap:** `/api/oauth/accounts/pool` is the same capability for the Anthropic +pool (GUI class 4 in 003) and has no verb either. Add `ocx account provider-strategy` +/ `provider-sticky` (or `--provider` on the same verbs — decide at implementation +time and record the choice) so the two pools are symmetric. A CLI that can steer one +pool and not the other is a trap. + +## 040.2 — `#2704`: `logs --conversation`, and the silently-ignored `--model` + +### (a) CLI filter + +MODIFY `src/cli/observe.ts:60-70`: + +```ts ++ const conversation = takeOption(args, "--conversation") ?? takeOption(args, "--conversationId"); + const provider = takeOption(args, "--provider"); + const model = takeOption(args, "--model"); + // ... +- const qs = query({ provider, model, status, limit }); ++ const qs = query({ provider, model, status, limit, conversationId: conversation }); +``` + +The server accepts both spellings (`request-log.ts:1032`: +`params.get("conversationId") || params.get("conversation")`), so accept both on the +CLI too rather than forcing operators to remember which. + +Also surface `conversationId` in `formatLog` (observe.ts:48), which prints only +time/status/route/duration today. A conversation filter whose output does not show +the conversation is hard to trust. + +### (b) the server-side `--model` hole + +`filterRequestLogs` handles `provider`, `conversationId`, `status`, `tail`, +`offset`, `limit` — and **no `model`**. So `ocx logs --model x` is accepted and +silently ignored today. That is worse than an error: it yields wrong conclusions from +correct-looking output. + +MODIFY `src/server/request-log.ts` `filterRequestLogs`: add a `model` clause +mirroring the `provider` clause one line above, matching `entry.model` **and** +`entry.attempts[].model` — a request that failed over should match the model that +actually served it, consistent with how `provider` already behaves. + +This is the one server-side change in wp5. It is in scope because leaving it means +shipping a CLI whose documented filter lies, which is the class of defect this whole +unit exists to remove. + +## Tests + +| File | Assertion | +|---|---| +| `tests/cli-account.test.ts` | pause/resume send `PUT` with `{id, paused}`; `strategy`/`sticky` hit `/api/codex-auth/pool-strategy`; a server 400 surfaces its `reason` (wp2 integration) | +| `tests/cli-headless-parity.test.ts` | the new verbs appear in the capability table and in generated help | +| `tests/cli-usage-report.test.ts` | `ocx logs --conversation X` and `--conversationId X` both build `conversationId=X` | +| `tests/management-api-logs-metrics.test.ts` | `model` filter matches `entry.model` and `attempts[].model`; a non-matching model returns no rows | + +## Accept criteria + +1. Pause, resume, pause-exhausted, strategy, sticky all work from the CLI for the + Codex pool, and the provider pool has symmetric verbs. +2. `ocx logs --conversation` filters server-side and the output shows the id. +3. `ocx logs --model` actually filters, including failover attempts. +4. All new verbs appear in `ocx capabilities --json`. diff --git a/devlog/_plan/260828_ocx_agentic_control/041_wp5_implementation_record.md b/devlog/_plan/260828_ocx_agentic_control/041_wp5_implementation_record.md new file mode 100644 index 0000000000..067b998ec6 --- /dev/null +++ b/devlog/_plan/260828_ocx_agentic_control/041_wp5_implementation_record.md @@ -0,0 +1,161 @@ +# 041 — wp5 implementation record: new verbs and filters (#2702, #2704) + +Branch: `codex/ocx-new-verbs`, stacked on `codex/ocx-dto-fidelity`. +Plan: `040_phase_new_verbs.md`. Both accept-criteria sets are met; the deviations from the +plan are recorded below rather than silently absorbed. + +## What shipped + +| Verb / behavior | Route | File | +|---|---|---| +| `ocx account pause ` | `PUT /api/codex-auth/accounts/pause` | `src/cli/account-extended.ts` | +| `ocx account resume ` | same route, `paused: false` | same | +| `ocx account pause-exhausted ` | `PUT /api/codex-auth/accounts/pause-exhausted` | same | +| `ocx account strategy []` | codex or anthropic pool (see below) | same | +| `ocx account sticky []` | same pair of pools | same | +| `ocx logs --conversation\|--conversationId ` | `GET /api/logs` | `src/cli/observe.ts` | +| server-side `model` filter | `filterRequestLogs` | `src/server/request-log.ts` | + +## The plan left one decision open, and this is the decision + +The plan named the sibling gap — `/api/oauth/accounts/pool` is the same capability for the +Anthropic pool and had no verb either — and explicitly deferred the choice between +`--provider` on the existing verbs and a second `provider-strategy`/`provider-sticky` pair. + +**Chosen: one verb pair over both pools**, dispatched on the provider positional that these +verbs already required. A second pair would double the surface an operator has to learn to +express one idea, and the provider argument was already there. + +That choice only works because the asymmetry is encoded rather than assumed. The two routes +differ in four ways, and every one of them would have been a live defect under a naive +"same settings, so same call" implementation: + +| | Codex pool | Anthropic pool | +|---|---|---| +| read | `GET /api/codex-auth/active` | `GET /api/oauth/accounts/pool?provider=` | +| write | `PUT /api/codex-auth/pool-strategy` | `PUT /api/oauth/accounts/pool` | +| response keys | `accountPoolStrategy` / `accountPoolStickyLimit` | `strategy` / `stickyLimit` | +| write body | bare field | field **plus a mandatory `provider`** | + +The mandatory `provider` is the sharpest one: omit it and the route answers 400 +(`oauth-account-routes.ts:344`), so a symmetric implementation would have failed at runtime +on every Anthropic write while passing every Codex test. + +`--json` output uses pool-neutral keys (`strategy`, `stickyLimit`) for both pools. A consumer +driving `ocx` programmatically should not have to branch on which pool answered in order to +read the value it just set. + +`anthropic` is the only OAuth provider with this setting, and the route says so with a 400. +The CLI refuses any other OAuth provider locally instead of spending a round-trip to learn it. + +## The server-side `--model` hole was real + +`filterRequestLogs` had clauses for `provider`, `conversationId`, `status`, `tail`, `offset`, +and `limit` — and none for `model`. So `ocx logs --model x` was accepted and every row came +back. That is worse than an error: the output looks filtered, so it yields a wrong conclusion +from correct-looking data. + +The new clause matches `entry.model` **and** `entry.attempts[].model`, mirroring the `provider` +clause directly above it, because a request that failed over should be findable by the model +that actually served it. + +## Every new gate was driven red before being trusted + +Four probes, each reverting a specific decision: + +| Probe | Result | +|---|---| +| `model` clause matches top-level only, not attempts | 1 fail — the failover row stopped matching | +| `model` clause deleted entirely (the shipped bug) | 1 fail — `model=absent-model` returned 2 rows where 0 were expected | +| Anthropic `writeBody` drops `provider` | 1 fail — the exact-body assertion caught it | +| Anthropic routed through `CODEX_POOL_TRANSPORT` (assume symmetry) | 3 fails — read path, write body, and `--json` keys all wrong | + +The second probe is the one worth keeping in mind: the positive assertion +(`model=gpt-test` returns `["a"]`) passes with **no filter implemented at all**, since an +unfiltered result contains the expected row. Only the non-matching assertion +(`model=absent-model` → `[]`) can detect the shipped defect. A test suite for a filter that +omits the negative case measures nothing. + +## Verification + +``` +bun test tests/cli-account-pool-verbs.test.ts tests/cli-usage-report.test.ts \ + tests/request-log.test.ts tests/cli-capabilities.test.ts tests/cli-headless-parity.test.ts \ + tests/management-route-registry.test.ts tests/request-log-conversation.test.ts \ + tests/management-api-logs-metrics.test.ts +→ 176 pass, 0 fail across 8 files + +./node_modules/.bin/tsc --noEmit → clean +``` + +Live, against the running proxy on :10100: + +``` +account strategy openai → openai: pool strategy is quota (exit 0) +account sticky openai → openai: sticky limit is 1 (exit 0) +account strategy anthropic → anthropic: pool strategy is quota (exit 0) +account strategy gemini → Error: unknown provider "gemini" + usage (exit 1) +account pause openai bogus_id → Error: Account not found (exit 4) +logs --limit 2 → rows now carry `conv=24f7175…` +``` + +Two details worth pinning, because both contradict a plausible guess: + +**Exit 4, not 1.** A not-found management error exits 4 under the wp3b uniform exit-code +contract; only the usage error exits 1. An earlier draft of this record said 1 for both. + +**`gemini` is refused before it reaches the new pool check.** `classifyAccount` rejects it as +an unknown provider first, since it is not configured in this environment. The pool-specific +refusal (`… not "gemini"`) is what a configured-but-poolless OAuth provider gets, and that +path is covered by the unit test rather than by this live run. + +**The `--model` hole reproduced live.** The proxy on :10100 runs an older build from a +different checkout, so it still has the unfixed `filterRequestLogs`: + +``` +logs --model no-such-model --limit 5 → 5 rows, all kiro/claude-opus-5 (exit 0) +``` + +A nonsense model returning a full page of rows, with exit 0, is exactly the defect #2704 +describes — output that looks filtered and is not. The fix is verified against +`filterRequestLogs` directly in `tests/request-log.test.ts`; this live run is the +before-picture, not a regression. + +### A note on how these tests were run + +Another worktree held the machine test lock (`opencodex-bun-test.lock`) for a full-suite run, +so these ran under `OCX_TEST_NO_QUEUE=1`, which is the documented escape for intentional +overlap (`scripts/test-run-lock.ts:164`). It is sound for this file set: every test injects +`fetchImpl` or calls `filterRequestLogs` directly, so none binds a port, and `tests/preload.ts` +sandboxes `HOME`/`CODEX_HOME` on every invocation regardless of the wrapper. + +## Criterion 4: the new surface is in `ocx capabilities` + +``` +ocx capabilities --json → invocations: + ocx status, ocx capabilities, ocx provider list, ocx account list, ocx usage, + ocx account pause, ocx account resume, ocx account pause-exhausted, + ocx account strategy, ocx account sticky, ocx logs + +ocx capabilities --route /api/oauth/accounts/pool + → ocx account strategy, ocx account sticky (both, with all four routes listed) +``` + +`ocx logs` had no capability entry at all before this phase, even though it was already a +shipped command. It gets one here rather than in a later phase, because this phase changed its +filter contract: an entry added later would have documented the fixed behavior without ever +having declared the broken one. + +## Deferred, with an owner + +`ocx logs --model` now filters correctly, but the `--model` **flag** was already declared in +`observe.ts` usage, so no help change was needed. `#2699` per-account attribution and the +remaining GUI-only Lab routes stay with wp6 and wp7 as declared in the route registry +exemptions. + +## Subagent dispatch + +Sol-tier subagent spawns continued to fail with 429 rate limits, so the route-method +verification, helper-signature audit, and both red-probe designs in this phase were done +directly against source rather than delegated. Recording the substitution rather than +implying a review that did not happen. diff --git a/devlog/_plan/260828_ocx_agentic_control/050_phase_account_attribution.md b/devlog/_plan/260828_ocx_agentic_control/050_phase_account_attribution.md new file mode 100644 index 0000000000..ae94aab67a --- /dev/null +++ b/devlog/_plan/260828_ocx_agentic_control/050_phase_account_attribution.md @@ -0,0 +1,199 @@ +# 050 — wp6: per-account usage attribution for OAuth providers (#2699) + +Closes: #2699. Branch: `codex/ocx-account-attribution` off `codex/ocx-new-verbs`. + +The only phase in this unit that touches the request path and the shared usage-log +schema. It is last among the code phases for that reason. + +## Root cause recap + +The label type is Codex-only by construction: + +`src/usage/log.ts:14` — `type CodexUsageAccountLogLabel = "main" | \`p${string}\``, +validated at :16 against `CODEX_ACCOUNT_LOG_LABEL_RE = /^p[a-f0-9]{6}$/` +(`src/codex/account-label.ts:6`). Four writers drop a non-matching label +(usage/log.ts:369, :456; server/request-log.ts:262, :381). The only producer, +`codexAuthContextLogLabel` (account-label.ts:32), returns `undefined` outside a +Codex `pool`/`main-pool` context. And `legacyCodexAccountLabel` (summary.ts:681) +returns `null` unless `baseProviderLabel(provider) === "openai"`, so `buildAccounts` +drops the row at :706. + +The identity is already resolved at request time: `core.ts` puts +`resolved.accountId` into `genericFailoverAccountId` (core.ts:2888) purely for 429 +cooldown attribution. Anthropic already folds its account into the provider label +(core.ts:2876 `formatAnthropicProviderForLog`). So xai/cursor are the gap, not OAuth +as a category. + +## 050.1 — widen the label type in one place + +MODIFY `src/codex/account-label.ts`. + +```ts +-export const CODEX_ACCOUNT_LOG_LABEL_RE = /^p[a-f0-9]{6}$/; ++// 'p' = Codex pool account, 'o' = non-Codex OAuth provider account. ++// Both are sha256-derived hex6 digests: the label must never carry an email or a ++// raw provider account id (#2699 privacy requirement). ++export const CODEX_ACCOUNT_LOG_LABEL_RE = /^p[a-f0-9]{6}$/; ++export const OAUTH_ACCOUNT_LOG_LABEL_RE = /^o[a-f0-9]{6}$/; ++export const ACCOUNT_LOG_LABEL_RE = /^(?:main|[po][a-f0-9]{6})$/; ++ ++export function oauthAccountLogLabel(accountId: string): string { ++ return "o" + createHash("sha256").update(accountId).digest("hex").slice(0, 6); ++} +``` + +Reuse the digest shape of the existing `fallbackCodexAccountLogLabel` (:17) so the +two label families stay visually and structurally parallel. + +MODIFY `src/usage/log.ts:14`: rename the type off `Codex…` to +`UsageAccountLogLabel = "main" | \`p${string}\` | \`o${string}\`` and validate at :16 +against `ACCOUNT_LOG_LABEL_RE`. The four writers then stop dropping `o…` labels +without individual edits — one regex, one type. + +Collision note: hex6 is 16.7M values, so a birthday collision between two accounts +is negligible at operator scale but not impossible. Two accounts colliding merge +into one row, which is a reporting inaccuracy, not a correctness or privacy failure. +Record it rather than widening the label and breaking the existing `p` format. + +## 050.2 — stamp the label in the request path + +MODIFY `src/server/responses/core.ts`. + +**Do not attach at the `genericFailoverAccountId` assignment.** That line +(core.ts:2888) sits inside `if (isGenericFailoverProvider(route.providerName, route.provider))` +at :2887, and that predicate (`src/oauth/generic-account-failover.ts:82`) requires +`provider.authMode === "oauth"` and excludes `{openai, anthropic}`. The rotation +paths are gated more tightly still: `isGenericOAuthFailoverEnabled` (:128) also +requires failover enabled and, at :164, **at least two stored accounts**. + +Attaching there would mean the ordinary case — one xai or cursor account, failover +off — never stamps a label, while every test listed below still passes. That is the +C-ACTIVATION-GROUNDING-01 trap, and it would make accept criterion 1 unreachable. + +Attach instead at the `resolved` snapshot itself (core.ts:2878-2879), which carries +`resolved.accountId` unconditionally for every OAuth provider on this path, +**outside** the failover gate: + +```ts + const resolved = await getValidAccessTokenSnapshot(route.providerName); + replayOAuthCredentialSnapshot = { accountId: resolved.accountId, generation: resolved.generation }; ++ // Attribution is independent of failover: a single-account xai/cursor user ++ // must still get per-account usage. Stamping inside the ++ // isGenericFailoverProvider gate below would silently skip them. ++ stampOAuthAccountLabel(logCtx, route.providerName, route.provider, resolved.accountId); +``` + +Then repeat it after **each rotation site** (core.ts:4317, :4618, and the +`genericFailoverAccountId` re-resolutions at :4696 and :4781 — five sites, not the +three an earlier draft named). A request that rotated accounts must attribute to the +account that actually served it. Reuse one helper so the sites cannot drift: + +```ts +// Lives in src/codex/account-label.ts (Lab-clean: it imports only node:crypto). +export function stampOAuthAccountLabel( + logCtx: { accountLogLabel?: string }, + providerName: string, + provider: OcxProviderConfig, + accountId: string | undefined, +): void { + if (!accountId) return; + // openai keeps its own p-label producer; anthropic already folds the account + // into the provider label (core.ts:2876 formatAnthropicProviderForLog). + if (provider.authMode !== "oauth") return; + const base = baseProviderLabel(providerName); + if (base === "openai" || base === "anthropic") return; + logCtx.accountLogLabel = oauthAccountLogLabel(accountId); +} +``` + +**Activation scenario (for C).** Provider `xai`, `authMode: "oauth"`, exactly one +stored account, generic failover **disabled**. Observable effect: the persisted usage +entry carries `accountLogLabel: "o"` and `ocx usage --json` reports one +non-`legacy-ambiguous` account row. If that case does not stamp, the phase has +re-created the bug it set out to fix. A second scenario with two accounts and +failover enabled proves the rotation re-stamp. + +Boundary: this must not reach into `src/lab/`. `core.ts` is one of the three files +`tests/core-lab-boundary.test.ts` guards, so the helper lives in +`src/codex/account-label.ts` or a `src/lib/` leaf, never in a Lab module. + +## 050.3 — let the label survive attribution + +The gate is `accountLabelForAttribution` at `src/usage/summary.ts:687`, called from +`buildAccounts` at :705 as `accountLabelForAttribution(input.provider, input.accountLogLabel)`. +An earlier draft of this doc named `legacyCodexAccountLabel(entry)`, which does not +exist — that function takes `provider: string` and is only the fallback. + +Current: + +```ts +function accountLabelForAttribution(provider: string, explicit: unknown): string | null { + if (isCodexUsageAccountLogLabel(explicit)) return explicit; + return legacyCodexAccountLabel(provider); +} +``` + +**Decide which layer owns the widening, because doing both is a no-op on top of a +no-op.** Two options, and this doc chooses the second: + +1. Widen `isCodexUsageAccountLogLabel` to accept `o`. Then :688 already passes + the new labels and this function needs no edit at all. But the predicate's name + then lies, and it is also the validator four writers use to *reject* bad labels — + widening it there weakens validation for a rename's convenience. +2. **Chosen:** keep `isCodexUsageAccountLogLabel` as the Codex-specific predicate, + add a sibling `isOAuthUsageAccountLogLabel`, and widen only the attribution gate: + +```ts + function accountLabelForAttribution(provider: string, explicit: unknown): string | null { + if (isCodexUsageAccountLogLabel(explicit)) return explicit; ++ // An explicitly stamped non-Codex label is authoritative for any provider (#2699). ++ // The legacy fallback below stays openai-only: guessing for a non-Codex row would ++ // silently merge unrelated accounts into 'legacy-ambiguous'. ++ if (isOAuthUsageAccountLogLabel(explicit)) return explicit; + return legacyCodexAccountLabel(provider); + } +``` + +The writers in `src/usage/log.ts` and `src/server/request-log.ts` accept either +family via `ACCOUNT_LOG_LABEL_RE` from 050.1, so persistence and attribution are +widened in exactly one place each. + +Leave `legacy-ambiguous` behavior for unlabeled openai rows untouched (`buildAccounts` +sets `ambiguous: label === LEGACY_AMBIGUOUS_ACCOUNT_LABEL` at :708). wp4 renders the +marker, so those rows stay honest. + +## 050.4 — out of scope, explicitly + +`supportsPerAccountQuota` (`src/providers/quota.ts:1454`, currently +`provider === "anthropic"`) is per-account **quota**, a different concern from log +attribution. Not in this phase. Recorded in `081` as a candidate follow-up so it is +a decision rather than an omission. + +## Verification exception + +Per `AGENTS.md`, a change to shared runtime, routing, config, or server behavior +needs full `bun run typecheck` and `bun run test`. This phase qualifies: it edits +`core.ts`, the usage-log schema, and the summary rollup. + +The operator suspended local suite runs for this loop, so full validation for this +phase happens in wp9's CI pass. This is a **stated, bounded exception**, not an +oversight: it is the only phase where a focused test is insufficient by the +repository's own rule, and wp9 must not be skipped or reduced while this phase is in +the stack. If wp9's CI cannot run, this phase does not ship. + +## Tests + +| File | Assertion | +|---|---| +| `tests/usage-log.test.ts` | an `o` label round-trips through persist and read; an invalid label is still rejected | +| `tests/usage-summary.test.ts` | an explicitly labeled xai row appears in `accounts[]`; an unlabeled openai row still reports `legacy-ambiguous`; a labeled non-openai row is not merged into it | +| `tests/responses-account-label.test.ts` | the label is stamped for xai and cursor, and re-stamped after a rotation so the serving account is credited | +| `tests/core-lab-boundary.test.ts` | unchanged and still green — the helper import must not pull Lab modules | + +## Accept criteria + +1. An xai or cursor request persists an `o` account label. +2. A rotated request attributes to the account that served it. +3. `ocx usage` (wp4's table) shows those accounts. +4. No email or raw account id is written to any log. +5. The Lab core-boundary test still passes. diff --git a/devlog/_plan/260828_ocx_agentic_control/051_wp6_implementation_record.md b/devlog/_plan/260828_ocx_agentic_control/051_wp6_implementation_record.md new file mode 100644 index 0000000000..36f20e06b1 --- /dev/null +++ b/devlog/_plan/260828_ocx_agentic_control/051_wp6_implementation_record.md @@ -0,0 +1,128 @@ +# 051 — wp6 implementation record: per-account OAuth attribution (#2699) + +Branch: `codex/ocx-account-attribution`, stacked on `codex/ocx-new-verbs`. +Plan: `050_phase_account_attribution.md`. All five accept criteria are met. The plan was wrong +about two things and this record says which, because both were caught by driving gates red +rather than by reading. + +## What shipped + +| Change | File | +|---|---| +| `o` label family, `ACCOUNT_LOG_LABEL_RE`, `oauthAccountLogLabel` | `src/codex/account-label.ts` | +| widened persisted-label validator + `isCodexPoolAccountLogLabel` sibling | `src/usage/log.ts` | +| `stampOAuthAccountLabel` helper | `src/providers/label.ts` | +| stamp at resolve, re-stamp at the rotation chokepoint | `src/server/responses/core.ts` | +| documented why the attribution gate needs no second predicate | `src/usage/summary.ts` | + +## The plan's central warning was wrong + +The plan spends a paragraph on a C-ACTIVATION-GROUNDING-01 trap: stamping next to the +`genericFailoverAccountId` assignment would supposedly skip the single-account case, because +the rotation paths require two or more stored accounts. + +I implemented the stamp outside that gate as instructed, then probed the warning by moving the +call *inside* `if (isGenericFailoverProvider(...))`. **All 10 tests still passed, including the +single-account activation scenario.** Removing the stamp entirely failed 2, so the tests were +not vacuous — the warning simply does not describe this predicate: + +``` +isGenericFailoverProvider(name, provider) // generic-account-failover.ts:83 + → provider.authMode === "oauth" && !EXCLUDED_PROVIDERS.has(name) +``` + +No account count, no enablement check. It is *the same condition* the helper applies. The +two-account requirement the plan attributed to it lives in `rotateGenericOAuthAccountOn429` +(`:167`) and in `isGenericOAuthFailoverEnabled` (`:128`) — neither of which guards that +assignment. + +The stamp stays outside the gate anyway, and the reason is now honest rather than borrowed: the +placement is *robust* rather than *necessary*. Attribution and 429-cooldown attribution are +different concerns that happen to share a predicate today, and a future narrowing of the +failover predicate should not silently switch usage attribution off. The code comment says that, +instead of claiming a bug that the probe disproved. + +## The plan's two halves contradicted each other + +050.1 says to widen the shared validator to `ACCOUNT_LOG_LABEL_RE` so "the four writers then +stop dropping `o…` labels without individual edits". 050.3 then rejects widening that same +predicate — "widening it there weakens validation for a rename's convenience" — and picks a +sibling predicate at the attribution gate instead. + +Doing both is impossible, and only one order works: **the writers must accept `o`-labels or +nothing is ever persisted**, and once they do, the attribution gate is already open. So 050.1 is +implemented and 050.3's edit is deliberately a comment rather than code — a second predicate +call there would be a no-op guarded by a comment claiming otherwise. + +The validation concern behind 050.3 is answered differently: `isCodexPoolAccountLogLabel` now +exists for callers that genuinely mean "a Codex pool account", and a test asserts the widened +validator still rejects `oZZZZZZ`, `oabc12`, `oabc1234`, `xabc123`, a raw account id, an email, +`null`, and `42`. Widening admitted one more shape; it did not become permissive. + +## Also corrected against source + +| Plan claim | Reality | +|---|---| +| four writers drop non-matching labels | **six**: `usage/log.ts:369,:456` and `request-log.ts:262,:381,:972,:1187`. The last two are in the live request path and would have dropped every new label. | +| rotation sites at `core.ts:4317,:4618,:4696,:4781` | assignments at `:2888,:4328,:4629,:5221` | +| five re-stamp sites needed | **one**: all three rotations funnel through `applyFailoverSnapshot` (`:2830`), which receives an `OAuthAccessSnapshot` carrying `accountId` | + +The helper lives in `src/providers/label.ts`, not `src/codex/account-label.ts` as the plan +suggested: it needs `baseProviderLabel`, and `providers/label.ts` already imports from +`account-label.ts`, so the plan's placement would have been an import cycle. Both files are +Lab-clean, which matters because `core.ts` is one of the three files +`tests/core-lab-boundary.test.ts` guards. + +## Accept criteria + +| # | Criterion | Evidence | +|---|---|---| +| 1 | an xai/cursor request persists an `o` label | single-account activation test, failover off; fails when the stamp is removed | +| 2 | a rotated request attributes to the serving account | rotation test asserts the label matches the bearer that got the 200; fails when the re-stamp is removed | +| 3 | `ocx usage` shows those accounts | two stamped accounts become two rows; fails under the pre-fix validator | +| 4 | no email or raw account id in any log | label is a sha256 digest; asserted against an email-shaped account id end to end | +| 5 | the Lab boundary still passes | `tests/core-lab-boundary.test.ts` 17 pass | + +## Red probes + +| Probe | Result | +|---|---| +| stamp moved inside the failover gate | **0 fail** — disproved the plan's warning | +| stamp removed entirely | 2 fail | +| re-stamp removed from `applyFailoverSnapshot` | 1 fail (the rotation test) | +| validator reverted to Codex-only | 4 fail, spanning persistence, request path, and attribution | + +The last one is the useful shape: one reverted regex failed tests in three different layers, +which is the evidence that the widening genuinely carries all three rather than three separate +fixes coincidentally passing. + +## Verification + +``` +bun test tests/oauth-account-attribution.test.ts tests/usage-summary.test.ts \ + tests/usage-log.test.ts tests/responses-account-label.test.ts \ + tests/codex-account-label.test.ts tests/core-lab-boundary.test.ts \ + tests/request-log.test.ts tests/generic-oauth-failover.test.ts +→ 187 pass, 0 fail across 8 files + +./node_modules/.bin/tsc --noEmit → clean +bun run privacy:scan → passed +``` + +## The verification exception still stands + +This phase edits `core.ts`, the usage-log schema, and the summary rollup, so `AGENTS.md` calls +for full `bun run typecheck` and `bun run test`. Typecheck ran and is clean. The full suite is +deferred to wp9's CI pass under the operator's suspension of local suite runs. That deferral is +bounded and named in the plan: **if wp9's CI cannot run, this phase does not ship.** + +## Out of scope, as decided + +`supportsPerAccountQuota` (`src/providers/quota.ts`, currently anthropic-only) is per-account +*quota*, not log attribution. Left alone, recorded in `081` as a candidate follow-up. + +## Subagent dispatch + +Sol-tier spawns continued to return 429, so the source audit and every probe above were done +directly. Recorded rather than implied. + diff --git a/devlog/_plan/260828_ocx_agentic_control/060_phase_gui_parity.md b/devlog/_plan/260828_ocx_agentic_control/060_phase_gui_parity.md new file mode 100644 index 0000000000..eee9c7a08d --- /dev/null +++ b/devlog/_plan/260828_ocx_agentic_control/060_phase_gui_parity.md @@ -0,0 +1,88 @@ +# 060 — wp7: residual GUI-parity closure + +Branch: `codex/ocx-gui-parity` off `codex/ocx-account-attribution`. + +wp5 closed the account-pool gaps. This phase closes the rest of 003's inventory so +the parity test in wp3 can run with an empty unexplained-gap set. + +## The remaining gaps + +| 003 class | Capability | New verb | Route(s) | +|---|---|---|---| +| 2 | storage cleanup preview/run | `ocx storage cleanup [--percent N] [--preview] [--yes]` | `POST /api/storage/cleanup/preview`, `POST /api/storage/cleanup` | +| 2 | storage trash list/restore | `ocx storage trash [list]`, `ocx storage trash restore ` | `GET /api/storage/trash`, `POST /api/storage/trash/restore` | +| 2 | cleanup policy | `ocx storage policy [show]`, `policy set …`, `policy run` | `GET|PUT /api/storage/cleanup-policy`, `POST /cleanup-policy/run` | +| 6 | default-mode request-user-input | `ocx agent request-user-input [on|off]` | `GET|PUT /api/codex-auth/features/default-mode-request-user-input` | +| 7 | client config snippet | `ocx integration client-config --client ` | `GET /api/client-config` | +| 8 | native integrations | `ocx integration native [list]`, `native on|off` | `GET /api/native-integrations`, `PUT /{client}` | +| 9 | rename an access key | `ocx access key rename --id --name ` | `PATCH /api/keys` | +| 10 | provider request pacing | `ocx provider pacing [--name

]` | `GET /api/provider-request-pacing` | +| — | codex prompt read | `ocx codex-prompt show [--text]` | `GET /api/codex-prompt`, `/text` | +| — | github star status | `ocx status --star` or `ocx system star-status` | `GET /api/github/star` | + +Also worth adding while the surface is open, since each is a route with no verb found +in 001's family table: + +- `ocx system settings [set …]` -> `GET|PUT /api/settings` (partially covered today) +- `ocx system windows-replace-retries` -> `GET /api/system/windows-replace-retries` +- `ocx account failover` -> `PUT /api/codex-auth/failover`. Note `auto-switch` and + `reset-credits` already exist (account.ts:302, :313) — do not re-add them +- `ocx models discovery ack` -> `POST /api/model-discovery/acknowledge` +- `ocx request-history` -> `GET /api/request-history`, `/{id}`, `/{id}/route-decision` + (`ocx observe` reaches only the route-decision variant) + +The exact list is settled at implementation time by running wp3's parity test and +reading its failure output. **That is the phase's method:** the test names the gaps, +so this doc does not need to pre-guess a list that would go stale. + +## Destructive-verb rules + +`storage cleanup`, `storage policy run`, and `trash restore` delete or move operator +data. Rules for all three: + +1. Default to preview. `ocx storage cleanup` without `--yes` runs the preview route + and prints what *would* be freed, then exits 0 without mutating. +2. `--yes` is required to mutate. No interactive prompt — an agent cannot answer one, + and a prompt an agent can answer is not a safety boundary (the reasoning in + `AGENTS.md` §User-consent actions). +3. `--json` on the preview emits the exact target list, so an agent can decide. + +This is the opposite of the star POST: cleanup spends the operator's *data*, which a +flag can authorize, while the star spends their *identity*, which no flag can. + +## Not parity targets + +Recorded as exemptions in wp3's registry with these reasons, so the test passes +without them: + +- `POST /api/github/star` — `session-only`, user-consent boundary. GET is added; POST + never will be. +- the 6 mutating `/api/codex-prompt*` verbs — `session-only` (403 + `dashboard_session_required`). Read verbs are added. +- `POST /api/providers/reload` — `capability-principal`. +- `PUT /api/config` — `disabled` (405). +- the 2 `test-stream` routes — `test-seam`. +- 20 `/api/lab/*` reads — `local-transport`; `ocx lab` reads the same projection from + SQLite. **Decision recorded here:** no `--remote` HTTP path is added. A second + transport for the same data doubles the surface for an agent that already has the + local one, and a remote agent is not a supported topology today. +- the shadowed `GET /api/storage` in `logs-usage-routes.ts:346` — `dead`. Delete it in + this phase rather than exempting it; an unreachable duplicate is a trap for the next + reader. + +## Tests + +| File | Assertion | +|---|---| +| `tests/cli-api-parity.test.ts` | passes with zero unexplained gaps | +| `tests/cli-storage.test.ts` (NEW) | cleanup without `--yes` calls only the preview route; with `--yes` calls the mutating route; trash restore targets the named entry | +| `tests/cli-headless-parity.test.ts` | each new verb hits its declared route and honors `--json` | +| `tests/management-api-*.test.ts` | the deleted shadowed route changes no observable behavior | + +## Accept criteria + +1. `tests/cli-api-parity.test.ts` passes with every route either covered or + exempted with a reason. +2. No destructive verb mutates without `--yes`. +3. The dead route is gone and no test regressed. +4. `ocx capabilities --json` lists every new verb. diff --git a/devlog/_plan/260828_ocx_agentic_control/061_wp7_implementation_record.md b/devlog/_plan/260828_ocx_agentic_control/061_wp7_implementation_record.md new file mode 100644 index 0000000000..49da3d6441 --- /dev/null +++ b/devlog/_plan/260828_ocx_agentic_control/061_wp7_implementation_record.md @@ -0,0 +1,144 @@ +# 061 — wp7 implementation record: residual GUI-parity closure + +Branch: `codex/ocx-gui-parity`, stacked on `codex/ocx-account-attribution`. +Plan: `060_phase_gui_parity.md`, whose stated method is to let the measurement name the gaps +rather than trusting a pre-written table. Doing that changed the answer substantially. + +## What the measurement said + +Of 207 declared management routes, 33 are exempt and 164 have no capability entry. But a +capability entry is bookkeeping; the parity question is whether the CLI can *reach* the route at +all. Checking each uncovered path against `src/cli/` with an exact-literal search: + +| | count | +|---|---| +| declared routes | 207 | +| exempt | 33 | +| no capability entry | 164 | +| **no CLI reference at all** | **26** | + +The remaining 138 are reachable today and simply undeclared — a wp3 bookkeeping debt, not a +GUI-only capability. Conflating the two would have turned this phase into 164 speculative verbs. + +Two heuristics were tried and both were wrong before the exact search settled it: a bare substring +match called `POST /api/storage/cleanup` reachable (it is not — no CLI file mentions it), and a +strict literal match called the `codex-logs` routes unreachable (they are reachable, built by +interpolation at `observe.ts:201`). Both were corrected by per-path `rg`, and the plan's own table +was wrong on the same two points. + +## Verbs added + +| Verb | Routes | +|---|---| +| `ocx storage report` | `GET /api/storage` | +| `ocx storage cleanup --percent N [--mode] [--yes]` | `POST /api/storage/cleanup/preview`, `POST /api/storage/cleanup` | +| `ocx storage trash [list]`, `trash restore --yes` | `GET /api/storage/trash`, `POST /api/storage/trash/restore` | +| `ocx storage policy [show|set|run --yes]` | `GET|PUT /api/storage/cleanup-policy`, `POST …/run` | +| `ocx inspect config|catalog|routing-analytics|key-providers|windows-tray` | the matching GETs | +| `ocx inspect pacing [--name]` | `GET /api/provider-request-pacing` | +| `ocx inspect client-config --client ` | `GET /api/client-config` | +| `ocx inspect codex-prompt [--text]` | `GET /api/codex-prompt`, `/text` | +| `ocx inspect star` | `GET /api/github/star` — **read only, permanently** | +| `ocx integration native [list| on|off]` | `GET /api/native-integrations`, 4 per-client PUTs | +| `ocx agent request-user-input [on|off]` | `GET|PUT …/features/default-mode-request-user-input` | + +## Destructive verbs + +Three of these delete or move operator data, and all three follow the same rule: **no mutation +without `--yes`, and no interactive prompt.** A prompt an agent can answer is not a safety +boundary, so the flag is the boundary. + +`cleanup` is the interesting one. It previews in *both* paths, and not out of politeness: the +mutating route requires the digest the preview returns and rejects a stale one with 409 +`stale_preview`. So the confirmed path cannot skip the preview, which means `--yes` and bare +invocation agree about what is being authorized. + +`inspect star` is the deliberate opposite. `POST /api/github/star` spends the operator's GitHub +identity, and the server requires a real dashboard session for it precisely so an agent cannot +answer that question on their behalf. No flag can carry that consent, so the verb reads status and +says plainly that starring is not available from the CLI, rather than offering a `--yes` that +would be a lie. + +## The dead route is gone + +`GET /api/storage` had two handlers. `handleStorageLogGuardRoutes` runs first +(`management-api.ts:221`) and answers every such request, so the copy at +`logs-usage-routes.ts:346` was unreachable — declared in the registry with a `dead` exemption +whose own note said to delete rather than expose it. + +It is deleted, along with its two now-unused imports. The registry declaration is gone, and the +reconciliation test was rewritten: it now asserts `/api/storage` has exactly ONE declaration +pointing at the live module, and that **no `dead` exemption survives anywhere** — that vocabulary +exists for routes awaiting deletion, so a lingering one means the deletion never happened. Driving +the deletion first made the old test fail, which is how I know it was checking something real. + +## Two regressions caught while building + +**`ocx storage --json` broke.** `storage` was an alias of `observe storage`; giving it subcommands +made a leading flag parse as a subcommand name, so the previously-working invocation errored with +`unknown storage command --json`. Fixed by only treating a non-flag first argument as a +subcommand, and pinned by a test that runs both `[]` and `["--json"]`. + +**`integration native list` printed `clients: 4 item(s)`.** The shared depth-1 flattener renders +an array as a count, so every per-client column was in the payload and discarded before the +terminal — the same defect class wp4 fixed for the account tables. It now renders CLIENT / STATE / +INSTALLED / DESIRED / CONFIG, and names a blocked disable instead of dropping it. + +`integration` and `inspect` also already existed as names. `native` was folded into the existing +`integration` dispatcher rather than shadowing it, and the duplicate-name gate in +`tests/cli-registry.test.ts` is what caught the collision. + +## Red probes + +| Probe | Result | +|---|---| +| `cleanup` ignores `--yes` and always mutates | 1 fail — the no-mutating-request assertion | +| `cleanup --yes` omits the preview digest | 1 fail | +| `policy set` always sends `enabled` | 2 fail — implicit-disable and empty-write | +| the dead `/api/storage` handler deleted | the old registry test failed until updated | + +## Verification + +``` +bun test tests/cli-storage-inspect.test.ts tests/cli-capabilities.test.ts \ + tests/cli-headless-parity.test.ts tests/cli-registry.test.ts tests/cli-dispatch.test.ts \ + tests/management-route-registry.test.ts tests/management-api-logs-metrics.test.ts \ + tests/storage-log-guard-routes.test.ts +→ 107 pass, 0 fail across 7 files + +./node_modules/.bin/tsc --noEmit → clean +bun run privacy:scan → passed +``` + +Live, against the running proxy: + +``` +storage --json → real report (45.0 GB, 450057 files) +storage cleanup --percent 1 → names the exact file, "Nothing was deleted", exit 0 +storage policy run → refuses, exit 2 +storage trash restore some-id → refuses, exit 2 +storage cleanup (no --percent) → refuses, exit 2 +inspect star → starred + the cannot-star sentence +inspect pacing --name xai → provider: xai, enabled: false +inspect client-config --client codex → 400 naming all 11 valid ids +integration native list → 4 clients with real state columns +agent request-user-input → enabled: true +``` + +The `client-config` result is worth keeping: `codex` is not a valid export client id, and the +route answered with the full accepted list. That is why the CLI does not duplicate the list +locally — the server's error is more useful than a local copy that can drift. + +## Deferred, still owned + +The ~138 reachable-but-undeclared routes are capability-table debt, not parity gaps. Declaring all +of them is mechanical and belongs with the wp3 registry work rather than here; the ones this phase +touched are declared. The mutating `/api/lab` routes keep their `deferred-verb` exemptions naming +this phase — they remain owed, and the exemption vocabulary keeps them visible rather than +silently accepted. + +## Subagent dispatch + +Sol-tier spawns continued to fail with 429, so the route census, the two corrected heuristics, and +every probe were done directly. Recorded rather than implied. + diff --git a/devlog/_plan/260828_ocx_agentic_control/070_phase_agent_skill.md b/devlog/_plan/260828_ocx_agentic_control/070_phase_agent_skill.md new file mode 100644 index 0000000000..2d89b9edc7 --- /dev/null +++ b/devlog/_plan/260828_ocx_agentic_control/070_phase_agent_skill.md @@ -0,0 +1,119 @@ +# 070 — wp8: the `ocx` agent skill and docs-site reference + +Branch: `codex/ocx-agent-skill` off `codex/ocx-gui-parity`. + +Every prior phase widened what an agent *can* do. This phase makes it *discoverable* +without reading the source. + +## 070.1 — where the skill lives + +NEW `skills/ocx/SKILL.md` in this repository, plus `skills/ocx/references/`. + +Repo-owned, not `$CODEX_HOME/skills`: the skill describes this repository's CLI +contract and must version with it. A user-directory copy goes stale the moment the +CLI changes, which is the same drift class as the 20 dead `USAGE` constants. + +``` +skills/ocx/ + SKILL.md entry point, routing, safety rules + references/ + 01_management_surface.md capability -> route map, generated + 02_json_shapes.md response envelopes and error shapes + 03_recipes.md copy-paste task recipes + 04_failure_semantics.md exit codes, 503 classes, what to retry +``` + +## 070.2 — the generated half + +`references/01_management_surface.md` is **generated from wp3's capability table**, +not hand-written, by a script under `scripts/`. A test asserts the committed file +matches regeneration. + +Hand-writing it would recreate the exact defect this unit removed: a second +description of the surface, free to drift from the first. If the generator and the +committed file disagree, CI fails and someone regenerates. + +## 070.3 — SKILL.md content + +Front matter with `name: ocx` and a description naming real triggers (`ocx`, +opencodex, proxy control, account pool, provider routing, usage report, access key, +management API), so it activates on the tasks it covers. + +Body sections: + +**Orientation.** `ocx capabilities --json` first. It is the machine-readable index; +everything else in the skill explains how to act on what it returns. + +**The three-step contract for any management call.** + +1. `ocx ready --json` — is the proxy up and admitting requests? +2. `ocx status --json` — is this binary the same version as the running proxy? + A version mismatch means the help and flags describe a different build (#2701). +3. Then the actual command with `--json`. + +**Exit codes.** 0 ok · 2 usage error · 4 not found · 5 conflict · 64 bad args +(`ready` only) · 1 everything else, including transport and 503. Never treat a +printed error with exit 0 as success — that was #2697, and a source scan now prevents +its return. + +**Reading failures.** A management failure prints up to three lines: message, +`reason:`, `hint:`. The `reason` is the machine-actionable part. Named 503 classes +worth branching on: `oauth_mutation_busy` and `catalog_busy` (both send +`Retry-After: 1` — retry once), `CONFIG_MUTATION_LOCK_UNAVAILABLE` (a config +mutation holds the lock; retry), and the credential-conflict reason (a broken +install; `ocx doctor` explains it, retrying will not help). + +**What an agent must not do.** `POST /api/github/star` has no CLI verb and must not +be driven another way — starring spends the user's identity and needs their consent +(`AGENTS_INSTALL.md`). Same for the session-gated `/api/codex-prompt` writes. +Destructive storage verbs need explicit `--yes`; run the preview and report it first. + +**Recipes** (`references/03_recipes.md`), each a real sequence with the JSON field to +read: + +- audit the account pool and pause an exhausted account +- switch pool strategy and set a sticky limit +- trace one conversation end to end (`ocx logs --conversation`, then + `ocx request-history --route-decision`) +- attribute spend per account (`ocx usage --json`, read `accounts[]`) +- rotate an access key and confirm its usage went quiet +- add a provider, test connectivity, make it default +- diagnose "management API unavailable" (ready -> status -> doctor) +- preview and then run a storage cleanup + +## 070.4 — docs-site + +NEW/MODIFY under `docs-site/`: a CLI reference page generated from the same +capability table, and a changelog entry for the breaking changes this unit lands: + +- `doctor` and `sync-cache` now exit non-zero on failure (wp3) +- `account` client error codes now map 404 -> 4 and 409 -> 5 (wp2) +- `--json` is accepted in any argv position, including `ocx restore back --json` + which previously ignored it (wp3) + +Translated locales must not contradict the English source. If a locale cannot be +updated in this phase, leave it untranslated rather than stale. + +## 070.5 — AGENTS.md pointer + +MODIFY `AGENTS.md`: one line under the commands section pointing at +`skills/ocx/SKILL.md` as the operating-the-proxy reference, distinct from +`AGENTS_INSTALL.md` (installing/operating consent) and this file +(developing the codebase). + +## Tests + +| File | Assertion | +|---|---| +| `tests/skill-ocx.test.ts` (NEW) | `references/01_management_surface.md` matches regeneration from the capability table; every command named in SKILL.md exists in the table; no recipe references a session-only route | +| `tests/repo-hygiene.test.ts` | the skill directory carries no credential-shaped strings | +| `bun run privacy:scan` | stays green over the new files | + +## Accept criteria + +1. `skills/ocx/SKILL.md` exists and routes to four references. +2. The surface reference is generated and a test enforces freshness. +3. Recipes cover the eight tasks above and name the JSON fields to read. +4. Failure semantics document exit codes and the named 503 classes. +5. Docs-site has a generated CLI reference and the breaking-change note. + diff --git a/devlog/_plan/260828_ocx_agentic_control/071_wp8_implementation_record.md b/devlog/_plan/260828_ocx_agentic_control/071_wp8_implementation_record.md new file mode 100644 index 0000000000..c1e01be9ac --- /dev/null +++ b/devlog/_plan/260828_ocx_agentic_control/071_wp8_implementation_record.md @@ -0,0 +1,122 @@ +# 071 — wp8 implementation record: the `ocx` agent skill + +Branch: `codex/ocx-agent-skill`, stacked on `codex/ocx-gui-parity`. +Plan: `070_phase_agent_skill.md`. All five accept criteria met. + +## What shipped + +``` +skills/ocx/ + SKILL.md 112 lines — orientation, exit codes, consent, routing + references/ + 01_management_surface.md 485 lines — GENERATED from the capability table + 02_json_shapes.md 125 lines — envelopes and which field to read + 03_recipes.md 168 lines — eight verified task sequences + 04_failure_semantics.md 84 lines — exit codes, 503 classes, retry policy +scripts/generate-ocx-skill-surface.ts the generator, with a --check mode +tests/skill-ocx.test.ts 11 tests +``` + +Repo-owned rather than `$CODEX_HOME/skills`, because the skill describes *this* repository's CLI +contract and has to version with it. A user-directory copy goes stale the moment the CLI changes. + +## The generated half is the point + +`01_management_surface.md` is rendered from `src/cli/capabilities.ts` by +`scripts/generate-ocx-skill-surface.ts`, and `tests/skill-ocx.test.ts` asserts the committed file +matches regeneration byte for byte. `bun run skill:surface` writes it; `bun run skill:surface:check` +is what CI asserts. + +Hand-writing it would have recreated exactly the defect this unit removed: a second description of +the CLI surface, free to drift from the first. Now a capability added without regenerating fails a +test instead of silently shipping a skill that describes an older build. + +Driven red both ways: adding a comment to a capability left the check green (it renders no output), +and changing one `summary` string failed both the `--check` and the test. So the gate tracks content, +not incidental edits. + +## The command-existence gate found a real error — in the plan + +One test extracts every `ocx ` presented as a command across all five pages and asserts each +exists in `CLI_COMMANDS`. It immediately failed on **`ocx request-history`**, which the plan's recipe +section named and which does not exist. The route-decision view is `ocx logs explain `. + +A skill that documents a command nobody can run is worse than no skill: an agent tries it, gets +`Unknown command`, and concludes the tool is broken. + +Two more errors surfaced the same way, from checking against source rather than assuming: + +| I wrote | Reality | +|---|---| +| `ocx access key add --label X` | `ocx access key create ` — positional | +| `ocx access key remove --id X` | `ocx access key remove --yes` — positional | +| `ocx provider default X` | `ocx provider set-default X` | + +### The extractor needed a second pass + +A raw prose scan produced two false positives worth recording: "driving ocx **programmatically**" +(an ordinary sentence) and "there is no `ocx request-history` command" — a line whose entire purpose +is to say the command does *not* exist. A gate that fails on documentation warning you about a +missing command is measuring the wrong thing. + +The extractor now reads only fenced blocks and inline code spans, skipping spans on lines that +negate them. A companion test asserts it still finds `capabilities`, `ready`, `status`, `logs`, +`usage`, `account`, `storage`, and `inspect` — without that, narrowing the extractor could have made +the main assertion vacuously true. + +## Everything in the recipes was executed + +Not transcribed from source. `ready`, `status`, `logs --jsonl`, `logs explain`, `access key list`, +`storage report`, `storage cleanup --percent 1`, `inspect star`, `inspect pacing`, +`inspect client-config`, `integration native list`, and `agent request-user-input` were all run +against the live proxy, and the field names in `02_json_shapes.md` were read off those responses. + +`logs explain` is where that mattered: the real payload nests everything under `routeDecision` with +`candidates[].exclusions` and `selected.reason`, which is the part an operator actually needs and is +not obvious from the route name. + +## Consent, stated rather than implied + +`SKILL.md` says plainly not to star the repository on the user's behalf, and says why: the POST +spends *their* GitHub identity and the server requires a dashboard session precisely so an agent +cannot answer that question for them. It also names the workarounds and forbids them — `gh`, a raw +HTTP call, a minted session. + +Three tests hold that line: the prohibition must be present, no page may contain `gh api`, and no +page may end a line with a bare `POST /api/github/star`. The failure mode being guarded is a skill +that mentions a boundary and then hands over the workaround anyway. + +## Docs-site + +`reference/cli.md` gains the exact exit-code table (0/2/4/5/1), the preview-first rule for +`storage cleanup`, an agent-orientation section pointing at `ocx capabilities --json` and +`skills/ocx/`, and a behavior-change list covering this unit: `doctor`/`sync-cache` exiting non-zero, +the 404→4 and 409→5 mapping, position-independent `--json`, `logs --model` actually filtering, and +`ocx storage` gaining subcommands while its bare form is unchanged. + +Changes are **additive**, so the seven translated locales are less complete but do not contradict the +English source — which is the plan's stated requirement. Leaving them untranslated is preferred over +machine-translating a contract page. + +## AGENTS.md + +One pointer added, distinguishing the three audiences: `skills/ocx/` operates a proxy, +`AGENTS_INSTALL.md` installs one, `AGENTS.md` changes the codebase. It also names the regeneration +commands, because a generated file whose generator is undiscoverable gets hand-edited. + +## Verification + +``` +bun test tests/skill-ocx.test.ts tests/repo-hygiene.test.ts tests/cli-capabilities.test.ts +→ 34 pass, 0 fail across 3 files + +bun run skill:surface:check → current +./node_modules/.bin/tsc --noEmit → clean +bun run privacy:scan → passed +``` + +## Subagent dispatch + +Sol-tier spawns continued to return 429. The command verification, the three corrected recipe +errors, and the extractor false-positive analysis were done directly. + diff --git a/devlog/_plan/260828_ocx_agentic_control/080_phase_rebase_and_ci.md b/devlog/_plan/260828_ocx_agentic_control/080_phase_rebase_and_ci.md new file mode 100644 index 0000000000..14fbff1883 --- /dev/null +++ b/devlog/_plan/260828_ocx_agentic_control/080_phase_rebase_and_ci.md @@ -0,0 +1,75 @@ +# 080 — wp9: stack rebase, final CI, parallel triage + +Branch: whichever heads exist at the time. No new source scope. + +The operator's instruction for this unit: no local full-suite runs during build, no +per-push CI polling. **All verification concentrates here**, which makes this phase +load-bearing rather than ceremonial. + +## 080.1 — rebase the whole stack onto current `dev` + +The stack is eight branches deep, so `dev` will have moved. Order matters: rebase +parent-first, then each child onto its rebased parent, or a child re-applies commits +its parent already carries. + +``` +git fetch origin dev +for each branch in stack order: + git switch + git rebase # roadmap rebases onto origin/dev + git push --force-with-lease --no-verify +``` + +`--force-with-lease`, never bare `--force`: the lease is what refuses to overwrite a +push that arrived from elsewhere. Snapshot every branch SHA before starting +(`git for-each-ref`) so any branch can be restored. + +Because each child PR targets its parent's head branch, the retarget order after +rebasing is the same order — GitHub keeps the base pointer, so no PR edits are needed +unless a parent has already merged (then retarget that child to `dev`, per +`AGENTS.md`). + +## 080.2 — final CI + +CI runs `bun run typecheck`, `bun run test`, `bun run lint:gui`, and +`bun run privacy:scan` on Linux, Windows, and macOS. **This is where wp6's stated +verification exception is settled** (see `050` §Verification exception): the +usage-log schema and `core.ts` changes have had no local full-suite run, so a green +CI here is their only proof. If CI cannot run, wp6 does not ship. + +## 080.3 — parallel triage + +Read all PR check states at once rather than serially, and group failures by cause +before fixing: + +- one failure appearing in every PR of the stack -> it originates in the lowest PR + that shows it; fix there and let the rebase carry it up. Fixing it in the top PR + leaves the stack red below. +- a failure only in one PR -> local to that phase. +- a platform-specific failure (Windows path handling, `schtasks`, case sensitivity) + -> fix in the phase that introduced the surface, not in a follow-up. + +Repeat rebase-push-check until every PR is green. A failure that reappears twice +after two different fixes stops patching and gets a root-cause pass +(`LOOP-REPAIR-01`) rather than a third guess. + +## 080.4 — PR hygiene + +Each PR uses `.github/PULL_REQUEST_TEMPLATE.md` with all three sections filled and +`Closes #` for the issues it resolves. Since these PRs target `dev` and GitHub +only auto-closes on a default-branch merge, the issues get closed manually once the +change is on `dev`. + +`enforce-target` will reject a thin description, and any PR whose title or +description mentions `gui` needs a screenshot. None of these phases changes the GUI, +so the word should not appear in a title — if a description must mention it, include +the screenshot or reword. + +## Accept criteria + +1. Every stacked branch is rebased on current `origin/dev`, parent-first. +2. Every PR's CI is green on all three platforms. +3. wp6's deferred full-suite validation is satisfied by that green run. +4. Every PR uses the template and links its issues. +5. No branch was force-pushed without a lease, and pre-rebase SHAs were recorded. + diff --git a/devlog/_plan/260828_ocx_agentic_control/081_deferred_decisions.md b/devlog/_plan/260828_ocx_agentic_control/081_deferred_decisions.md new file mode 100644 index 0000000000..c5653c8b46 --- /dev/null +++ b/devlog/_plan/260828_ocx_agentic_control/081_deferred_decisions.md @@ -0,0 +1,36 @@ +# 081 — follow-up decisions deliberately deferred + +Not omissions. Each is recorded so a later reader sees a decision instead of a gap. + +## 081.1 — loopback repair for the token collision (#2696) + +`010` ships the write-time refusal only. The startup repair — delete a colliding +`service-api-token` when the bind is loopback — changes credential state on disk at +boot and needs the security review `MAINTAINERS.md` requires plus a proof that it +cannot run for a non-loopback bind. + +Consequence of deferring: an install already broken by the collision stays broken +until the operator re-installs. It is now *diagnosable* (`010.2` prints the reason, +`010.5` names it in `doctor`), which was the actual complaint in the issue. Ship the +repair as its own reviewed PR. + +## 081.2 — per-account quota for non-Anthropic providers + +`supportsPerAccountQuota` (`src/providers/quota.ts:1454`) is `provider === "anthropic"`. +`050` deliberately scopes to log *attribution*, not quota fetching. Extending quota +means per-provider quota endpoints and rate-limit budget, which is a different unit. + +## 081.3 — remote transport for `ocx lab` and `ocx config` + +Both reach their data locally (SQLite, file I/O) rather than over `/api/*`. `060` +records these as `local-transport` exemptions and adds no `--remote` path: a second +transport for the same data doubles the agent-facing surface, and an agent operating +a proxy on another host is not a supported topology today. Revisit if that changes. + +## 081.4 — the GUI's 78 inlined endpoint call sites + +`003` found no central GUI API client; endpoints are inlined across ~78 files. That +makes the GUI unable to participate in the parity gate — wp3's registry is declared +server-side instead. A GUI-side endpoint manifest would let the test verify all three +surfaces agree, but touching 78 files is its own unit and outside this scope. + diff --git a/devlog/_plan/260828_ocx_agentic_control/081_wp9_implementation_record.md b/devlog/_plan/260828_ocx_agentic_control/081_wp9_implementation_record.md new file mode 100644 index 0000000000..64936d26bd --- /dev/null +++ b/devlog/_plan/260828_ocx_agentic_control/081_wp9_implementation_record.md @@ -0,0 +1,129 @@ +# 081 — wp9 implementation record: rebase no-op, CI triage, and an audit that disproved me + +Closes the unit. Five fixes across three branches, each traced to a specific commit in +this stack before being changed. + +## The rebase was a no-op, and that was verified rather than assumed + +`080.1` planned a parent-first rebase of eight branches onto a moved `dev`. `dev` had not +moved: it sat at `50e955604` when this unit opened, the same commit the stack was built +on. Rather than skip the step, the ancestry was proved link by link — +`git merge-base --is-ancestor` for each of the nine consecutive pairs from `origin/dev` +to `codex/ocx-agent-skill`, all OK. A restack still happened, because the fixes below +landed on lower branches and had to be carried up. + +Pre-rewrite SHAs were snapshotted to `/tmp/wp9snap/pre-rebase-shas.txt` before any +history was rewritten, and every push used `--force-with-lease`. + +## Three CI failures, three distinct causes + +CI was read for all nine PRs at once, as `080.3` requires. Grouping by cause first was +what made this cheap: two of the three failures appeared in every PR from a given depth +upward, which located them in the lowest PR showing them rather than the one where they +were noticed. + +| Failure | Cause | Fixed in | +|---|---|---| +| `hygiene`: `empty_catch` on a docs-only PR | scanner matches added lines textually; two devlog lines quote the construct they argue against | `codex/ocx-agentic-control-roadmap` | +| `cli-native-profile`: expected 1, got 5 | 409 now maps to exit 5; the old assertion pinned the pre-mapping behaviour | `codex/ocx-transport-honesty` | +| `codex-retained-root-serialization`: expected 0, got 1 | a contended catalog lock was classified as a failure | `codex/ocx-uniform-contract` | + +The 409 case was the only one where an existing test was edited, so it needed the +strongest justification. `025` line 51 declares the vocabulary — 0 ok, 2 usage, 4 not +found, 5 conflict — and the test asserted 1 only because every account-family failure +used to exit 1 regardless of status. It was pinning the defect. What the test exists to +cover, the idempotent cancel fallback and the absence of a spurious cleanup warning, is +untouched and still asserted. + +Two CI entries that looked like failures were not: a `ci` job failing in 2–4s on every +PR was `needed job(s) did not pass: changes=cancelled`, the older run superseded by the +force-push, and a `windows-schtasks` failure timestamped before the push belonged to the +pre-push commit. Neither was chased as a defect. + +## The audit disproved a premise I had asserted + +The A-gate reviewer returned **fail** with two blocking findings, and both were correct. +Recorded here in full because the value of the gate is precisely that it caught something +my own scan could not. + +**Finding 1 — the stack did add a real empty catch.** I had scanned every changed file +with the gate's own exported `hasEmptyCatch` and got zero matches, and concluded the +hygiene failure was purely a prose match. The scan was sound and the conclusion was +wrong: `tests/management-route-registry.test.ts:138` wrapped `Bun.writeSync?.(0, "")` in a +catch whose body is only a comment, and the regex at `pr-hygiene.cjs:113` does not match a +comment-only body. So the gate would have gone green while a genuinely swallowed failure +shipped. The call was dead anyway — the probe writes its fixture with `node:fs` on the +next line — so the block was removed rather than given a handler. + +Re-scanning with a comment-aware pattern found seven more files, all pre-existing on +`dev` (zero added catch lines in each), so they are out of this unit's scope. + +**Finding 2 — the first sync-cache fix masked real failures.** `ok = wrote || +desiredDisabled || contended` treated Codex-integration-off as automatic success. But the +call passes `allowWhenDesiredDisabled: true`, so the OFF gate inside the refresh never +fires and the work is genuinely attempted. A falsy result with integration off therefore +means the refresh *failed*, and the expression returned 0 with `skipped: true` for exactly +that case — asserting a false reason, which is worse than the always-0 behaviour this unit +set out to fix. Now only `busy` is a skip; `database`, `unsafe-path`, and a falsy +`completed` all exit 1. `--json` gained `reason`, because `outcome` alone cannot separate a +contended lock from a hard serialization failure — both report `unavailable`. + +## Verification + +Local runs were focused, per the operator's no-full-suite constraint; the three-platform +full suite is CI's job and is what settles wp6's deferred validation (`050` +§Verification exception). + +- `tsc --noEmit` clean. +- 41 tests pass across `codex-composed-acceptance`, `local-management-direct-transport`, + `codex-retained-root-serialization`, and `cli-json-contract`; 37 across + `management-route-registry` and `cli-native-profile` in the first round. +- Red-first proof for the contended-lock fix: dropping `contended` from the success set + turns exactly one test red and leaves the other five passing, so the assertion is not + vacuous. +- Detector integrity proof: `hasEmptyCatch` still returns true for a catch with a literally + empty body and false for one that handles the error, so the reword did not weaken the + guard. (Phrased rather than quoted, because a literal example of the construct in this + file is itself an added line the scanner matches -- which is how this very sentence + failed the gate once.) + +## Second triage round: two more live failures, and a case both I and the audit missed + +The first round's fixes exposed two failures that the earlier cancelled runs had hidden. +Both reproduced locally, so neither was treated as CI flake. + +| Failure | Cause | Fixed in | +|---|---|---| +| `local-management-direct-transport`: extra `version` in identity | the version-skew fix (#2701) widened the identity payload; the exact-match assertion predates it | `codex/ocx-capability-registry` | +| `codex-composed-acceptance`: expected 0, got 1 | an absent catalog was classified as a failure | `codex/ocx-uniform-contract` | + +The second one matters more than its diff suggests, because it shows the audit's finding 2 +was directionally right and still not the whole answer. +`invalidateCodexModelsCacheWithPermit` returns a bare boolean for four distinct +situations -- wrote the cache, no catalog file exists, the OFF gate fired, or it threw. +So `false` cannot be read as failure any more than it could be read as success. My first +version read it as success when integration was off (masking real failures, which the +audit caught); my second read it as failure (inventing one in a native home, which the +audit did not catch because the reviewer reasoned from the reason matrix and the +`existsSync` early return is not in it). + +`!existsSync(catalogPath)` is now checked at the call site and joins a contended lock as a +benign skip, with `skippedReason` in `--json` so `skipped: true` is never opaque. The check +lives at the call site rather than in the shared function because that boolean is consumed +by a dozen management routes with no use for the distinction. + +The lesson worth keeping: a boolean that means four things will be misread by whoever +reads it next, in whichever direction their test happens to cover. Three consecutive +attempts got a different subset right. + +Both new assertions were driven red. Reverting the `version` expectation fails exactly that +test; dropping `noCatalog` from the success set fails exactly the composed-toggle +acceptance test. + + +## Honest note on subagent substitution + +Earlier phases in this unit recorded that subagent dispatch was failing with 429 rate +limits and that audits were performed directly. That constraint lifted here: the A-gate +reviewer for wp9 was a real dispatched `explorer` (gpt-5.6-sol, high effort), and its +two blocking findings are the substance of this record. diff --git a/devlog/_plan/260828_ocx_agentic_control/090_phase_gap_closure.md b/devlog/_plan/260828_ocx_agentic_control/090_phase_gap_closure.md new file mode 100644 index 0000000000..18e8a31b64 --- /dev/null +++ b/devlog/_plan/260828_ocx_agentic_control/090_phase_gap_closure.md @@ -0,0 +1,189 @@ +# 090 — wp10: close the gap-audit findings + +The wp9 close-out gap audit answered YES to "does a material gap remain in agentic CLI +control of GUI capabilities", with three High findings and one Medium. Each was +independently reproduced against source before this plan was written, so none of it is +taken on the reviewer's word. + +Reproductions (run from the branch, not the released `ocx` on PATH — the first attempt at +this measurement used the installed binary and got "Unknown command: capabilities", which +is a stale build, not evidence): + +``` +bun run src/cli/index.ts capabilities --route /api/keys --json -> {"capabilities": []}, exit 4 +bun run src/cli/index.ts logout --json -> "Logged out of --json.", exit 0 +bun run src/cli/index.ts definitely-not-a-command -> exit 1 +capabilities declared: 26 routes declared: 207 +``` + +## 090.1 — `logout --json` silently no-ops (highest severity) + +`src/cli/dispatch.ts` `logout` takes `args[1]` as the provider name with no flag parsing, so +`ocx logout --json` lowercases `--json`, calls `removeCredential("--json")`, prints +`Logged out of --json.` and exits 0. An agent gets a success exit for an operation that did +nothing, which is the worst failure mode in this whole unit: silent, and indistinguishable +from success. + +**Plan audit correction.** My first reading called `removeCredential("--json")` harmless +because `store.ts:598` returns early on an unknown key. That is wrong for a store this code +does not control: `normalizeAuthStore` (`store.ts:346-355`) copies **every** top-level key +it finds, so a hand-edited, legacy, or corrupted `auth.json` containing a `--json` key would +have its active account deleted — and the key removed entirely if that was its last account. +The severity is therefore "can destroy credentials in an unusual but reachable store", not +"wastes a call". Recorded because it changes what the regression has to prove. + +Fix: parse flags out of argv **before any store I/O**, and split the outcomes the vocabulary +already distinguishes rather than collapsing them: + +| Case | Exit | +|---|---| +| omitted provider, unknown flag, invalid argument | 2 (usage), before touching the store | +| valid provider name with no stored credential | 4 (not found) | +| removed | 0 | + +The regression must assert that a malformed invocation causes **zero** store mutation, not +merely a non-zero exit. + +## 090.2 — three GUI capabilities have no CLI equivalent + +| GUI call | CLI today | Missing verb | +|---|---|---| +| `POST /api/oauth/logout` | `ocx logout` only calls `removeCredential` locally | API-backed logout | +| `GET /api/system/codex-app-server`, `POST /api/system/codex-restart` | `sync --restart-codex` only as a side effect after a write | `system codex-app-server status` / `restart` | +| `GET /api/claude-desktop/status` | `claude desktop show` emits locally-built state only | `claude desktop status` | + +The OAuth one is not cosmetic. The route does five things past `removeCredential`: +`reconcileLiveStateStores`, `clearLoginState`, `clearModelCache`, +`clearGatherRoutedModelsInflight`, and quota-cache eviction +(`oauth-account-routes.ts:228-243`). A CLI logout that skips them leaves a running proxy +serving a removed credential's cached models and quota, so the local-only path is a +correctness gap and not just a parity gap. + +**Plan audit correction — the stopped-proxy contract was missing, and it is the whole +design question.** An API-backed verb needs a live proxy; discovery failure throws +"Proxy is not running" (`runtime-api.ts:43`). So this phase must state the behaviour: + +- Proxy running: go through `POST /api/oauth/logout` so the five invalidations happen. +- Proxy not running: exit non-zero, say how to start it, and **mutate nothing**. + +No automatic local fallback. A best-effort fallback is actively dangerous here: if a proxy +is alive but momentarily undiscoverable, falling back would delete the credential on disk +while that proxy keeps serving its cached models, login state and quota — the precise +divergence the API path exists to prevent. An offline mode is acceptable only as an explicit +opt-in that proves no proxy is live, not as error recovery. + +Two further under-specifications to settle before implementing: + +- The route reports success even when nothing was removed, because `removeCredential` + returns no disposition (`oauth-account-routes.ts:231`). Exit 4 is impossible until the + store or route returns a removed/not-found result. Do it there, not via a CLI preflight + read — a preflight is racy by construction. +- Define whether logout removes only the active account or all of them, and whether legacy + `ocx logout` becomes an alias or keeps its offline behaviour. Silence here is how two + commands end up meaning different things. + +## 090.3 — the parity gate only checks one direction + +`tests/cli-capabilities.test.ts` asserts every capability's route exists. It never asserts +the converse, so 139 non-exempt routes carry no capability entry and nothing fails. The +observable consequence is that `capabilities --route` — the agent's discovery entry point — +returns empty and exits 4 for `/api/keys` and `/api/routing-profiles` while `ocx access key` +and `ocx route policy` work. + +**Plan audit correction — the allowlist was the wrong mechanism, and the counts were off.** +`ManagementRoute` already carries an `exempt` field with a typed `ExemptionReason` union +(`route-registry.ts:24-46`, `:68`) covering exactly the categories a parallel allowlist would +have re-invented: `session-only`, `disabled`, `capability-principal`, `test-seam`, +`local-transport`, `dead`. A second list would duplicate the source of truth and relocate the +omission problem rather than close it. + +The reverse gate is therefore: **every route is either covered by `capabilityRouteKeys()` or +carries a justified `route.exempt`** — never neither, and ideally never both. + +The audit's fresh counts also correct mine: 206 routes (I said 207), 35 capability-covered +route keys, 32 exempt, 139 unexplained. More importantly it disproved my framing of what +those 139 are: 122 of them are already referenced from CLI source, and of the remaining 17 +about 15 are operator-facing. So the split is roughly ~137 user-facing to ~2 genuine plumbing +(`/api/update/badge`, `/api/system/windows-replace-retries`) — not 139 internal exceptions. + +That changes the work: most of these need a capability declaration, not an exemption. Since +139 declarations will not land in one phase, the gate goes in with the currently-known +user-facing families declared (access keys, routing profiles, provider CRUD/test, custom +models/visibility/presets/discovery, injection and subagent settings) and the remainder +marked with a bounded deferred exemption that names an owner — so the debt is visible and +dated rather than silent. + +## 090.4 — `--json` and exit codes still not uniform + +- `doctor --json` is documented in the skill's recipes but `runDoctor` only looks for its own + flags; `--json` is ignored and human output is printed. + + **Plan audit correction — this is a refactor, not a flag.** I filed it beside two one-line + fixes, which understated it badly. `runDoctor` has no report collection at all: it keeps a + module-level failure bit and emits directly through ~90 `console.log` calls across a + 1,309-line surface (`doctor.ts:73`), and `dispatch.ts:175` appends the Codex Log Guard's + human output *after* `runDoctor` returns. Adding a JSON print would therefore emit human + lines and a JSON document on the same stdout — invalid output, worse than the ignored flag. + My flag inventory was also incomplete: `--yes`, `--reclaim-response-temps` and reclaim-flag + typo detection exist too (`doctor.ts:1028`). + + Doing it properly needs a structured report DTO, separate human and JSON renderers, Log + Guard output folded into the report rather than printed alongside it, a stable schema, + exit derivation from collected findings, unknown-flag rejection, and a decision for + `--json` combined with each mutating recovery mode. **Split to its own work-phase (wp11).** + What lands in wp10 is the honest interim: `doctor` rejects `--json` with the usage exit and + a message saying it is not yet supported, and the skill recipe stops recommending it. A + documented flag that silently does nothing is the defect; refusing it is not ideal but it is + not a lie. +- JSON-mode API failures print `Error: …` on stderr and discard the structured body + (`runtime-api.ts:333`), contradicting the error envelope the skill promises. +- Unknown command exits 1, but the declared vocabulary says 2 for usage. + +## 090.5 — the skill test validates command heads only + +`tests/skill-ocx.test.ts` reduces each documented invocation to its leading `ocx ` +before checking it, so a nonexistent subcommand or an ignored flag passes. `doctor --json` +is exactly that case: head exists, documented flag does nothing. + +**Plan audit correction — there is no full-invocation oracle to validate against.** I wrote +"validate full invocations" without checking what could answer the question. `CAPABILITIES` +does carry structured command paths and flags, but only for the 26 declared capabilities +(`capabilities.ts:48`); `src/cli/registry.ts` holds only top-level commands and free-form +usage strings, and the real subcommand parsers are scattered across command modules. +Appending `--help` is not an oracle either: `root.ts:40` intercepts help before subcommand +dispatch, so a nonexistent subcommand still prints help and exits 0. + +So the achievable scope for wp10 is narrower and stated as such: validate every documented +invocation **that maps to a declared capability** against that capability's command path and +flag list — a real oracle, covering 26 capabilities — and assert that any invocation outside +that set is explicitly listed as unverified rather than silently reduced to its head. A +hand-maintained subcommand table is refused: it would be a third drifting source of truth. + +The general answer is a declarative command grammar shared by parsing, help, capabilities and +skill generation. That is real work and belongs with the doctor refactor in wp11, not smuggled +into this phase. + +Also: `skills/ocx/SKILL.md` calls the generated map "every verb" while the map contains 26 +capabilities. Either the claim narrows or the map grows; it cannot stay as-is. + +## Accept criteria + +1. `ocx logout` never reads a flag as a provider name, and a malformed invocation mutates the + credential store **zero** times — asserted directly, not inferred from the exit code. + Usage errors exit 2 before any I/O; a valid provider with no stored credential exits 4. +2. The three missing verbs exist, are API-backed, declare capabilities, and emit `--json`. + With the proxy stopped they exit non-zero, explain how to start it, and mutate nothing; + there is no automatic local fallback. +3. Logout returns a removed/not-found disposition from the store or route, so exit 4 is real + rather than assumed, and the active-account-vs-all-accounts semantics are written down. +4. The parity gate fails when a route is neither capability-covered nor `route.exempt`- + justified, using the existing `ExemptionReason` union rather than a parallel allowlist. +5. `capabilities --route` resolves for every family named in 090.3 that has a working CLI + command; the rest carry a bounded deferred exemption naming an owner, so the debt is dated + rather than silent. +6. JSON-mode API failures emit the documented error envelope instead of a bare stderr line. +7. `doctor --json` is refused with the usage exit and the skill recipe no longer recommends + it; the structured-report refactor is wp11, not this phase. +8. The skill test validates full invocations against the capability oracle where one exists, + and every invocation outside it is explicitly listed as unverified. +9. Every new assertion is driven red before being trusted. diff --git a/devlog/_plan/260828_ocx_agentic_control/091_wp10_implementation_record.md b/devlog/_plan/260828_ocx_agentic_control/091_wp10_implementation_record.md new file mode 100644 index 0000000000..bd741317e5 --- /dev/null +++ b/devlog/_plan/260828_ocx_agentic_control/091_wp10_implementation_record.md @@ -0,0 +1,129 @@ +# 091 — wp10 implementation record: closing the gap audit, and two plans it disproved + +The wp9 close-out gap audit answered YES to "does a material gap remain in agentic CLI +control of GUI capabilities". This phase closes the findings that could be closed honestly +and moves the rest into wp11 with the reasons written down. + +## What shipped + +| Finding | Disposition | +|---|---| +| `logout --json` silently no-ops | Fixed: argv parsed before any store I/O, three-way exit taxonomy | +| `doctor --json` silently ignored | Refused with exit 2; skill recipe corrected | +| parity gate one-directional | Fixed: bidirectional with a dated 139-route ratchet | +| `system codex-app-server` missing | Fixed | +| `system codex-restart` missing | Fixed | +| `claude desktop status` missing | Fixed | +| API-backed OAuth logout missing | wp11 (needs live-proxy cache invalidation) | +| no full-invocation skill oracle | wp11 | +| structured doctor report | wp11 | + +## The audit disproved two things I had written + +Both are recorded because in each case my reasoning was sound and my conclusion was wrong, +which is the failure mode worth leaving evidence of. + +**`removeCredential("--json")` is not harmless.** I checked `store.ts:598`, saw the early +return on an unknown key, and wrote the bug up as a wasted call. But `normalizeAuthStore` +(`store.ts:346-355`) copies *every* top-level key it finds, so a hand-edited, legacy, or +corrupted `auth.json` holding a `--json` key would lose that key's active account -- and the +key itself if it was the last one. The severity moves from cosmetic to credential-destroying +in an unusual but reachable store, and that changed what the regression had to prove: it now +compares the store file byte-for-byte around every malformed invocation, rather than treating +a non-zero exit as evidence nothing was written. + +**My proposed allowlist was redundant.** I planned a separate list of internal plumbing for +the reverse parity gate. `ManagementRoute.exempt` already carries a typed `ExemptionReason` +union with a mandatory `why` and, for `deferred-verb`, a required owner and tracked doc that +an existing test verifies. A second list would have duplicated the source of truth. + +The audit also corrected my count (206 routes, not 207) and, more usefully, my framing: of +the 139 unexplained routes, 122 paths are already referenced from CLI source and only about +two are plausibly pure plumbing. So this is not 139 things that should never have verbs; it +is ~137 working commands that never declared a capability. That is why the mechanism is a +ratchet rather than an allowlist -- an allowlist says "these are fine", and they are not fine, +they are dated debt. + +## Two deferrals that hold up, and one that did not + +A later audit accepted the two below and rejected a third I had bundled with them. That third +one is in the second-round section further down; recording the split here so this section is not +read as a clean bill of health. + +`doctor --json` cannot be a flag addition. `runDoctor` has no report collection: a +module-level failure bit and ~90 direct `console.log` calls across a 1,309-line surface, and +`dispatch.ts` appends the Codex Log Guard's human output *after* it returns. A JSON print +there would interleave prose and JSON on one stdout, which is strictly worse for a parser than +the ignored flag. So wp10 refuses the flag with exit 2 and a pointer to `status --json` / +`ready --json`, and the skill recipe stops recommending it. A documented flag that does +nothing is the defect; refusing it is not ideal, but it is honest. + +The full-invocation skill oracle has nothing to validate against yet. `CAPABILITIES` covers +26 verbs; `registry.ts` holds top-level commands and free-form usage strings; and `--help` is +intercepted at `root.ts:40` before subcommand dispatch, so even a nonexistent subcommand +prints help and exits 0. Promising validation without an oracle would have produced a +hand-maintained subcommand table -- a third drifting source of truth. The real answer is a +declarative command grammar shared by parsing, help, capabilities and skill generation, which +is wp11. + +## Second audit round: my own fix was incomplete, and one deferral was a dodge + +A verification audit of the first wp10 commit returned FAIL. It was right on all three counts, +and two of them are about the fix I had just written and verified. + +**The flag guard was the same defect one dash shorter.** I wrote `arg.startsWith("--")` and +tested `--json`, `--wat`, and extra positionals. `-j` was still accepted as a provider name, so +with a `-j` key in the store the command deleted a credential and exited 0 -- the exact +behaviour the commit claimed to have eliminated. The lesson is narrow and worth keeping: I +tested the reported input rather than the input class. Any leading dash is now an option. + +**The non-mutation regression was vacuous, and I found that one myself.** It compared +`auth.json` before and after; the sandbox home has no `auth.json`, so both sides were null and +the assertion would have passed even if the store had been written. Found by probing the +sandbox rather than re-reading the test. Every case now seeds a credential first, and the audit +then pushed it further: seeding only `claude` cannot detect a bad `removeCredential("--json")`, +because removing a key that is not there leaves the file byte-identical. The cases now seed a +**sentinel credential under the malformed token itself**. + +**The preflight could claim credit for someone else's removal.** `getAccountSet` then +`removeCredential` is not atomic: `mutateStore` serializes writes, so two concurrent logouts +both saw a credential and both exited 0. `removeCredential` now returns its disposition from +inside the mutation. This is a smaller false success than the flag bug but the same species, +and it is the kind that only appears under concurrency -- so it would have read as a flake. + +**One deferral was scope-dodging.** I had deferred all three missing GUI verbs together. Two +were nearly free: `system` already wraps `runtimeRequest` and the endpoints already return +complete DTOs, so `codex-app-server` and `codex-restart --yes` are branches; `claude-desktop.ts` +already imports `runtimeRequest`, so `status` is one action. Bundling them with the genuinely +hard OAuth-logout case let a cheap gap ride along behind an expensive one. All three shipped; +only API-backed OAuth logout remains deferred, and that one needs atomic disposition plus the +five live-proxy cache invalidations. + +**The skill overclaimed.** `SKILL.md` said "Everything the dashboard can do, the CLI can do" +while 136 routes had no declared capability. That is worse than a documentation nit: an agent +that believes the index is exhaustive stops looking after `capabilities --route` returns empty, +and `ocx access key` works. It now states that the index is authoritative for what it lists, +that a verb can exist without appearing there, and that `ocx help` is the fallback. + +The ratchet went 139 -> 136 on its first real test, and the shrink-only assertion is what +forced the edit instead of letting the list quietly go stale. + + +## Verification + +- `tsc --noEmit` clean. +- 57 pass across `cli-dispatch` (20, of which 11 are new logout assertions), `cli-capabilities` + (2 new parity assertions), `skill-ocx`, and `management-route-registry`. +- Red-first, five probes, each failing only what it should: restoring the original logout runner + fails all six first-round assertions; restoring `--`-only flag detection fails the short-flag + sentinel case alone; restoring the read-then-remove preflight fails the concurrency case alone; + removing one ratchet entry fails the forward gate; adding an already-covered route fails the + shrink gate. +- Behavioural checks run from the branch rather than the installed binary, after an early probe + used the released `ocx` and reported a stale "Unknown command" that was not evidence: + `logout --json` exits 2 (was 0 with a false success), `logout -j` exits 2 (was 0 **and + deleted a credential**), `logout --json=true` exits 2, `logout nosuch --json` exits 4 with a + JSON not-found envelope, `logout foo bar` exits 2, `doctor --json` exits 2. +- Verified live against the running proxy: `system codex-app-server --json` returns app-server + state, `system codex-restart` without `--yes` exits 2, `claude desktop status --json` returns + the applied/desired DTO. diff --git a/docs-site/src/content/docs/reference/cli.md b/docs-site/src/content/docs/reference/cli.md index d9a7d6ea0e..1ea37d6c44 100644 --- a/docs-site/src/content/docs/reference/cli.md +++ b/docs-site/src/content/docs/reference/cli.md @@ -46,10 +46,55 @@ and unavailable required services exit nonzero. `ocx health` specifically exits proxy is healthy and 1 otherwise, so it can be used as a service probe. Scripts should test the exit code instead of scraping human-readable output. +The specific codes are set in one place, so every management command agrees: + +| Code | Cause | +|---|---| +| 0 | success | +| 2 | usage error — bad, missing, or unknown arguments; nothing was sent | +| 4 | HTTP 404 — the named account, provider, key, or route does not exist | +| 5 | HTTP 409 — conflict; a lock is held or state changed underneath | +| 1 | everything else, including transport failure and other HTTP errors | + +Exit 0 means no error was reported. Preview verbs (for example `ocx storage cleanup` without `--yes`) also exit 0 without mutating. A command never prints an error and exits 0. + Destructive removal, import, credit-consumption, and update operations that advertise confirmation require `--yes` in non-interactive use. The flag is an explicit opt-in; omitting it must not silently confirm the action. +`ocx storage cleanup` goes further: without `--yes` it runs the preview and prints what *would* be +freed, then exits 0 having changed nothing. There is no interactive confirmation for any of these — +a prompt an automated caller can answer is not a safety boundary, so the flag is the boundary. + +## Driving the CLI from an agent + +`ocx capabilities --json` is the machine-readable index of every command, the management routes it +drives, its flags, and whether it mutates state. Start there rather than parsing help text: + +```bash +ocx capabilities --json +ocx capabilities --mutating-only --json +ocx capabilities --route /api/logs +``` + +An unmatched `--route` exits 4 rather than reporting empty success. The repository ships a fuller +operating guide at `skills/ocx/`, whose surface map is generated from the same table. + +## Recent behavior changes + +These are corrections to commands that previously misreported their own results: + +- `doctor` and `sync-cache` now exit non-zero on failure. They previously printed a failure and + exited 0, so a script could not tell success from failure. +- Client errors from `account` map HTTP 404 to exit 4 and HTTP 409 to exit 5, instead of collapsing + everything into 1. +- `--json` is honored in any argument position, including `ocx restore back --json`, which + previously accepted the flag and ignored it. +- `ocx logs --model` now actually filters. It was accepted and silently ignored, so the output + looked filtered while showing every row. +- `ocx storage` gained `cleanup`, `trash`, and `policy` subcommands. A bare `ocx storage` still + prints the storage report, as it did when it was an alias of `ocx observe storage`. + ## Version and internal dispatch targets `ocx --version`, `ocx -v`, and `ocx version` print one script-friendly version line and exit. diff --git a/gui/src/i18n/de.ts b/gui/src/i18n/de.ts index 5bea652194..f849c9be0a 100644 --- a/gui/src/i18n/de.ts +++ b/gui/src/i18n/de.ts @@ -1685,6 +1685,7 @@ export const de: Record = { "storage.policy.skippedEmpty": "Keine Archivkandidaten passend zum Ziel.", "storage.policy.doneQuarantine": "Richtlinie hat {count} Datei(en) in Quarantäne ({size}).", "storage.policy.donePermanent": "Richtlinie hat {count} Datei(en) endgültig gelöscht ({size}).", + "storage.policy.metadataSaveWarning": "Der Richtlinienlauf wurde beendet, aber seine Planungsmetadaten konnten nicht gespeichert werden.", "modal.back": "Zurück", "modal.badge.oauth": "OAuth", "modal.customProvider": "Benutzerdefinierter Anbieter", diff --git a/gui/src/i18n/en.ts b/gui/src/i18n/en.ts index 0e27ca29e2..0e809578bd 100644 --- a/gui/src/i18n/en.ts +++ b/gui/src/i18n/en.ts @@ -1007,6 +1007,7 @@ export const en = { "storage.policy.skippedEmpty": "No archived candidates matched the target.", "storage.policy.doneQuarantine": "Policy quarantined {count} file(s) ({size}).", "storage.policy.donePermanent": "Policy permanently deleted {count} file(s) ({size}).", + "storage.policy.metadataSaveWarning": "The policy run finished, but its scheduling metadata could not be saved.", // add-provider modal "modal.addNamed": "Add: {label}", diff --git a/gui/src/i18n/fr.ts b/gui/src/i18n/fr.ts index 4c5292014b..b552df536e 100644 --- a/gui/src/i18n/fr.ts +++ b/gui/src/i18n/fr.ts @@ -982,6 +982,7 @@ export const fr: Record = { "storage.policy.skippedEmpty": "Aucune archive candidate ne correspond à l’objectif.", "storage.policy.doneQuarantine": "La politique a mis {count} fichier(s) en quarantaine ({size}).", "storage.policy.donePermanent": "La politique a supprimé définitivement {count} fichier(s) ({size}).", + "storage.policy.metadataSaveWarning": "L’exécution de la politique est terminée, mais ses métadonnées de planification n’ont pas pu être enregistrées.", "modal.addNamed": "Ajouter : {label}", "modal.add": "Ajouter un fournisseur", "modal.search": "Rechercher des fournisseurs…", diff --git a/gui/src/i18n/ja.ts b/gui/src/i18n/ja.ts index 5be35ce9e4..82e0281f8b 100644 --- a/gui/src/i18n/ja.ts +++ b/gui/src/i18n/ja.ts @@ -950,6 +950,7 @@ export const ja: Record = { "storage.policy.skippedEmpty": "目標に合うアーカイブ候補がありません。", "storage.policy.doneQuarantine": "方針が {count} 件を隔離しました（{size}）。", "storage.policy.donePermanent": "方針が {count} 件を完全削除しました（{size}）。", + "storage.policy.metadataSaveWarning": "方針の実行は完了しましたが、スケジュールのメタデータを保存できませんでした。", // add-provider modal "modal.addNamed": "追加: {label}", diff --git a/gui/src/i18n/ko.ts b/gui/src/i18n/ko.ts index d7def6f1c7..0a0c58fdd0 100644 --- a/gui/src/i18n/ko.ts +++ b/gui/src/i18n/ko.ts @@ -1712,6 +1712,7 @@ export const ko: Record = { "storage.policy.skippedEmpty": "목표에 맞는 보관 후보가 없습니다.", "storage.policy.doneQuarantine": "정책이 파일 {count}개를 격리했습니다({size}).", "storage.policy.donePermanent": "정책이 파일 {count}개를 영구 삭제했습니다({size}).", + "storage.policy.metadataSaveWarning": "정책 실행은 완료됐지만 일정 메타데이터를 저장하지 못했습니다.", "modal.back": "뒤로", "modal.badge.oauth": "OAuth", "modal.customProvider": "사용자 지정 프로바이더", diff --git a/gui/src/i18n/ru.ts b/gui/src/i18n/ru.ts index 97f77fcdca..94e2dbc333 100644 --- a/gui/src/i18n/ru.ts +++ b/gui/src/i18n/ru.ts @@ -991,6 +991,7 @@ export const ru: Record = { "storage.policy.skippedEmpty": "Нет архивных кандидатов под цель.", "storage.policy.doneQuarantine": "Политика отправила в карантин {count} файл(ов) ({size}).", "storage.policy.donePermanent": "Политика навсегда удалила {count} файл(ов) ({size}).", + "storage.policy.metadataSaveWarning": "Выполнение политики завершено, но не удалось сохранить метаданные расписания.", // add-provider modal "modal.addNamed": "Добавить: {label}", diff --git a/gui/src/i18n/tr.ts b/gui/src/i18n/tr.ts index 57e40312d0..1391401055 100644 --- a/gui/src/i18n/tr.ts +++ b/gui/src/i18n/tr.ts @@ -998,6 +998,7 @@ export const tr: Record = { "storage.policy.skippedEmpty": "Hedefle eşleşen aday yok.", "storage.policy.doneQuarantine": "Politika {count} dosyayı karantinaya aldı ({size}).", "storage.policy.donePermanent": "Politika {count} dosyayı kalıcı olarak sildi ({size}).", + "storage.policy.metadataSaveWarning": "Politika çalışması tamamlandı ancak zamanlama meta verileri kaydedilemedi.", // add-provider modal "modal.addNamed": "Ekle: {label}", diff --git a/gui/src/i18n/zh-TW.ts b/gui/src/i18n/zh-TW.ts index 36d4e6b6d2..d0f337d05e 100644 --- a/gui/src/i18n/zh-TW.ts +++ b/gui/src/i18n/zh-TW.ts @@ -795,6 +795,7 @@ export const zhTW: Record = { "storage.policy.skippedEmpty": "沒有匹配目標的歸檔候選項。", "storage.policy.doneQuarantine": "策略已隔離 {count} 個檔案（{size}）。", "storage.policy.donePermanent": "策略已永久刪除 {count} 個檔案（{size}）。", + "storage.policy.metadataSaveWarning": "策略執行已完成，但無法儲存其排程中繼資料。", "modal.addNamed": "新增：{label}", "modal.add": "新增供應商", "modal.search": "搜尋供應商…", diff --git a/gui/src/i18n/zh.ts b/gui/src/i18n/zh.ts index 894c9a07ca..aaa31df4e2 100644 --- a/gui/src/i18n/zh.ts +++ b/gui/src/i18n/zh.ts @@ -1705,6 +1705,7 @@ export const zh: Record = { "storage.policy.skippedEmpty": "没有匹配目标的归档候选项。", "storage.policy.doneQuarantine": "策略已隔离 {count} 个文件（{size}）。", "storage.policy.donePermanent": "策略已永久删除 {count} 个文件（{size}）。", + "storage.policy.metadataSaveWarning": "策略运行已完成，但无法保存其调度元数据。", "modal.back": "返回", "modal.badge.oauth": "OAuth", "modal.customProvider": "自定义提供方", diff --git a/gui/src/pages/Storage.tsx b/gui/src/pages/Storage.tsx index 3c99c5a2cd..019b93e6b0 100644 --- a/gui/src/pages/Storage.tsx +++ b/gui/src/pages/Storage.tsx @@ -74,6 +74,7 @@ interface CleanupPolicy { skipped?: string; deferred?: string; error?: string; + metadataPersistenceError?: "missing" | "invalid" | "conflict" | "write_failed"; mode?: string; freedBytes?: number; removed?: number; @@ -888,6 +889,9 @@ function AutoCleanupPolicyPanel({ if (outcome.skipped === "disabled") { setStatus(t("storage.policy.skippedDisabled")); + } else if (outcome.ok && outcome.metadataPersistenceError) { + setError(t("storage.policy.metadataSaveWarning")); + if (outcome.removed !== undefined) onDone(); } else if (outcome.skipped === "under_threshold") { setStatus(t("storage.policy.skippedUnder")); } else if (outcome.skipped === "nothing_selected") { diff --git a/gui/tests/storage-policy-metadata-warning.test.tsx b/gui/tests/storage-policy-metadata-warning.test.tsx new file mode 100644 index 0000000000..cc46172359 --- /dev/null +++ b/gui/tests/storage-policy-metadata-warning.test.tsx @@ -0,0 +1,136 @@ +import { afterEach, beforeEach, expect, test } from "bun:test"; +import { Window } from "happy-dom"; +import { act } from "react"; +import type { Root } from "react-dom/client"; +import { LanguageProvider } from "../src/i18n/provider"; +import { clearClientResourceStoresForTests } from "../src/client-resource"; +import Storage from "../src/pages/Storage"; + +const globals = ["document", "window", "navigator", "localStorage", "sessionStorage", "IS_REACT_ACT_ENVIRONMENT"] as const; +let previousGlobals: Record<(typeof globals)[number], unknown>; +let testWindow: Window; +const originalFetch = globalThis.fetch; + +const REPORT = { + codexHome: "/tmp/codex", + generatedAt: 1, + total: { bytes: 100, fileCount: 1 }, + buckets: [{ key: "archived_sessions", label: "Archived", bytes: 100, fileCount: 1 }], +}; + +const POLICY = { + enabled: true, + trigger: { archivedBytesOver: 0 }, + target: { removeOldestPercent: 25 }, + schedule: "manual", + mode: "quarantine", +} as const; + +beforeEach(() => { + clearClientResourceStoresForTests(); + previousGlobals = Object.fromEntries(globals.map(key => [key, Reflect.get(globalThis, key)])) as typeof previousGlobals; + testWindow = new Window({ url: "http://localhost/" }); + Object.defineProperties(globalThis, { + document: { configurable: true, value: testWindow.document }, + window: { configurable: true, value: testWindow }, + navigator: { configurable: true, value: testWindow.navigator }, + localStorage: { configurable: true, value: testWindow.localStorage }, + sessionStorage: { configurable: true, value: testWindow.sessionStorage }, + }); + (globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true; +}); + +afterEach(() => { + globalThis.fetch = originalFetch; + clearClientResourceStoresForTests(); + testWindow.close(); + for (const key of globals) { + Object.defineProperty(globalThis, key, { configurable: true, value: previousGlobals[key] }); + } +}); + +async function waitFor(predicate: () => boolean, timeoutMs = 1500): Promise { + const start = Date.now(); + while (!predicate()) { + if (Date.now() - start > timeoutMs) throw new Error("waitFor timed out"); + await act(async () => { + await new Promise(resolve => testWindow.setTimeout(resolve, 10)); + }); + } +} + +test("storage policy run warns when cleanup succeeds but metadata persistence fails", async () => { + const startedAt = 10; + let started = false; + let storageFetches = 0; + globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => { + const url = String(input); + const method = init?.method ?? "GET"; + if (url.endsWith("/api/storage/cleanup-policy/run") && method === "POST") { + started = true; + return Response.json({ + ok: true, + started: true, + job: { status: "running", startedAt }, + policy: { ...POLICY, job: { status: "running", startedAt } }, + }); + } + if (url.endsWith("/api/storage/cleanup-policy") && method === "PUT") { + return Response.json({ ok: true, policy: POLICY }); + } + if (url.endsWith("/api/storage/cleanup-policy")) { + if (!started) return Response.json(POLICY); + return Response.json({ + ...POLICY, + job: { + status: "idle", + startedAt, + finishedAt: startedAt + 1, + lastOutcome: { + ok: true, + mode: "quarantine", + removed: 1, + freedBytes: 100, + metadataPersistenceError: "missing", + }, + }, + }); + } + if (url.endsWith("/api/storage/trash")) return Response.json({ entries: [] }); + if (url.endsWith("/api/storage")) { + storageFetches += 1; + return Response.json(REPORT); + } + return new Response(null, { status: 404 }); + }) as typeof fetch; + + const { createRoot } = await import("react-dom/client"); + const container = document.createElement("div"); + document.body.append(container); + let root!: Root; + try { + await act(async () => { + root = createRoot(container); + root.render(); + }); + await waitFor(() => Array.from(container.querySelectorAll("button")).some(button => button.textContent?.includes("Run now"))); + const runButton = Array.from(container.querySelectorAll("button")) + .find(button => button.textContent?.includes("Run now")); + expect(runButton).toBeDefined(); + + await act(async () => { + runButton!.click(); + }); + await waitFor(() => (container.textContent ?? "").includes("scheduling metadata could not be saved")); + await waitFor(() => storageFetches >= 2); + + expect(container.textContent).not.toContain("Policy quarantined"); + expect(container.querySelector('[role="alert"]')?.textContent).toContain("scheduling metadata could not be saved"); + expect(storageFetches).toBeGreaterThanOrEqual(2); + } finally { + await act(async () => { + root.unmount(); + }); + container.remove(); + } +}); diff --git a/package.json b/package.json index f13e70a612..57f06ad22b 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@bitkyc08/opencodex", - "version": "2.34.0-preview.20260827", + "version": "2.35.0", "description": "Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code", "type": "module", "main": "./bin/package-main.mjs", @@ -42,6 +42,8 @@ "typecheck": "bun x tsc --noEmit", "audit:high": "bun audit --audit-level=high && cd gui && bun audit --audit-level=high", "privacy:scan": "bun scripts/privacy-scan.ts", + "skill:surface": "bun scripts/generate-ocx-skill-surface.ts", + "skill:surface:check": "bun scripts/generate-ocx-skill-surface.ts --check", "generate:model-metadata": "bun scripts/generate-model-metadata.ts", "build:gui": "cd gui && bun install --frozen-lockfile && bun run build && cd .. && bun run prepare:package", "prepare:package": "bun scripts/prepare-package.ts", diff --git a/scripts/generate-ocx-skill-surface.ts b/scripts/generate-ocx-skill-surface.ts new file mode 100644 index 0000000000..c6a0d71c27 --- /dev/null +++ b/scripts/generate-ocx-skill-surface.ts @@ -0,0 +1,111 @@ +/** + * Generates `skills/ocx/references/01_management_surface.md` from the capability table. + * + * Generated rather than written, because a hand-maintained surface map is a SECOND description + * of the CLI that is free to drift from the first -- the same defect class this unit removed from + * the help text. `tests/skill-ocx.test.ts` asserts the committed file matches this output, so a + * capability added without regenerating fails CI instead of silently shipping a stale skill. + * + * Usage: + * bun scripts/generate-ocx-skill-surface.ts # write + * bun scripts/generate-ocx-skill-surface.ts --check # exit 1 if stale + */ +import { writeFileSync, readFileSync, existsSync } from "node:fs"; +import { join } from "node:path"; +import { CAPABILITIES, HEAD_CAPABILITIES, capabilityInvocation } from "../src/cli/capabilities"; + +const TARGET = join(import.meta.dir, "..", "skills", "ocx", "references", "01_management_surface.md"); + +export function renderManagementSurface(): string { + const lines: string[] = []; + lines.push(""); + lines.push(""); + lines.push(""); + lines.push("# The `ocx` management surface"); + lines.push(""); + lines.push("Every capability the CLI declares, with the management routes it drives and whether it"); + lines.push("mutates state. This file is generated from the same table `ocx capabilities --json`"); + lines.push("serves, so it cannot describe a command that does not exist."); + lines.push(""); + lines.push("Ask the running binary instead of trusting this file when the two disagree:"); + lines.push(""); + lines.push("```bash"); + lines.push("ocx capabilities --json # the whole table"); + lines.push("ocx capabilities --mutating-only --json # only state-changing verbs"); + lines.push("ocx capabilities --route /api/logs # which verbs drive one route"); + lines.push("```"); + lines.push(""); + + lines.push("## Resolved before dispatch"); + lines.push(""); + lines.push("These answer in the CLI head and never reach the proxy, so they work with nothing running."); + lines.push(""); + lines.push("| Invocation | Purpose |"); + lines.push("|---|---|"); + for (const head of HEAD_CAPABILITIES) { + lines.push(`| \`${head.invocations.join("\` \`")}\` | ${head.summary} |`); + } + lines.push(""); + + const mutating = CAPABILITIES.filter(c => c.mutates); + const reading = CAPABILITIES.filter(c => !c.mutates); + + for (const [title, group, note] of [ + ["Read-only capabilities", reading, "Safe to run at any time; none of these change state."], + ["State-changing capabilities", mutating, "Each of these writes. Check the flags column before running one unattended."], + ] as const) { + lines.push(`## ${title}`); + lines.push(""); + lines.push(note); + lines.push(""); + for (const cap of group) { + lines.push(`### \`${capabilityInvocation(cap)}\``); + lines.push(""); + lines.push(cap.summary); + lines.push(""); + if (cap.routes.length > 0) { + lines.push("| Method | Route |"); + lines.push("|---|---|"); + for (const route of cap.routes) lines.push(`| ${route.method} | \`${route.path}\` |`); + } else { + lines.push("Drives no management route."); + } + lines.push(""); + if (cap.flags.length > 0) { + lines.push("| Flag | Value | Meaning |"); + lines.push("|---|---|---|"); + for (const flag of cap.flags) lines.push(`| \`${flag.name}\` | ${flag.value} | ${flag.summary} |`); + lines.push(""); + } + lines.push(`JSON mode: \`${cap.json}\`.`); + lines.push(""); + for (const detail of cap.details ?? []) lines.push(`- ${detail}`); + if ((cap.details ?? []).length > 0) lines.push(""); + } + } + + lines.push("## Counts"); + lines.push(""); + lines.push(`- declared capabilities: ${CAPABILITIES.length}`); + lines.push(`- of those, state-changing: ${mutating.length}`); + lines.push(`- head-resolved invocations: ${HEAD_CAPABILITIES.length}`); + lines.push(""); + return lines.join("\n"); +} + +if (import.meta.main) { + const rendered = renderManagementSurface(); + if (process.argv.includes("--check")) { + const current = existsSync(TARGET) ? readFileSync(TARGET, "utf8") : ""; + if (current === rendered) { + console.log("skills/ocx/references/01_management_surface.md is current."); + process.exit(0); + } + console.error("skills/ocx/references/01_management_surface.md is STALE."); + console.error("Regenerate: bun scripts/generate-ocx-skill-surface.ts"); + process.exit(1); + } + writeFileSync(TARGET, rendered); + console.log(`wrote ${TARGET}`); +} + diff --git a/skills/ocx/SKILL.md b/skills/ocx/SKILL.md new file mode 100644 index 0000000000..cba29e7dd9 --- /dev/null +++ b/skills/ocx/SKILL.md @@ -0,0 +1,120 @@ +--- +name: ocx +description: Drive a running opencodex (`ocx`) proxy from the CLI — account pools, provider routing, model catalog, usage and cost attribution, request logs, access keys, storage cleanup, and the management API. Use when a task involves controlling or inspecting an opencodex proxy rather than editing the opencodex codebase. Triggers: ocx, opencodex, proxy control, account pool, pause account, pool strategy, provider routing, usage report, cost attribution, access key, request log, conversation trace, storage cleanup, management API. +--- + +# Operating `ocx` + +`ocx` controls a locally running opencodex proxy. The CLI covers the dashboard's operational +surface, with one consent exception (starring) recorded under Consent below. `ocx capabilities` +lists the *declared* index, not every verb. + +Be precise about the gap, because guessing costs you more than reading: the capability index below +is complete and authoritative for what it lists, and it does not yet list every management route. +A route with no declared capability may still have a working command — `ocx access key` and +`ocx route policy` both work while `capabilities --route` returns nothing for them. So use the +index first, and fall back to `ocx help` before concluding a capability is missing. + +This skill is for **operating** a proxy. Two neighbours cover different jobs: `AGENTS_INSTALL.md` +is for installing one, and the repository `AGENTS.md` is for changing the codebase. + +## Start here + +```bash +ocx capabilities --json +``` + +That is the machine-readable index of declared verbs, the routes they drive, their flags, and whether they +mutate. Read it first rather than guessing a command name. It is not exhaustive — an unmatched +`--route` exits 4 when the table has no row, even if a working verb exists. The converse of +generation also holds: a verb can exist without appearing here (`ocx access key`, `ocx route policy`). + +Narrow it when you already know what you want: + +```bash +ocx capabilities --mutating-only --json # only state-changing verbs +ocx capabilities --route /api/logs # which verbs drive one route +``` + +An unmatched `--route` exits 4 rather than printing an empty success. + +## Three steps before any management call + +1. `ocx ready --json` — is the proxy up and admitting requests? +2. `ocx status --json` — is this binary the same build as the running proxy? A version skew means + the help and flags you just read describe a *different* build than the one answering. +3. Then the real command, with `--json`. + +Skipping step 2 is how an agent ends up reporting that a flag "does not work" when it simply does +not exist in the running build yet. + +## Exit codes + +| Code | Meaning | +|---|---| +| 0 | success | +| 2 | usage error — bad or missing arguments; nothing was sent | +| 4 | not found — the named account, provider, key, or route does not exist | +| 5 | conflict — a lock is held or the state changed under you; usually retryable | +| 1 | everything else, including transport failure and any other HTTP error | + +**Never read a printed error with exit 0 as success.** Commands used to print a failure and exit 0; +they no longer do, and a source scan keeps it that way. Exit 0 means no error was reported; +inspect the result to see whether anything mutated (cleanup without `--yes` is a preview). + +## Reading a failure + +A management failure prints up to three lines: the message, then `reason:`, then `hint:`. The +`reason` is the machine-actionable part — branch on it, not on the prose. + +Four named classes are worth handling specifically: + +| Reason | What it means | What to do | +|---|---|---| +| `oauth_mutation_busy` | another credential write is in flight (503, `Retry-After: 1`) | retry once after a second | +| `catalog_busy` | a catalog gather is in flight (503, `Retry-After: 1`) | retry once after a second | +| a config-mutation lock reason | a config write holds the lock | retry shortly | +| a credential-conflict reason | the install is broken, not busy | run `ocx doctor`; retrying will not help | + +The first two are transient by construction and the server tells you how long to wait. The last is +the one to stop on: repeating it just produces the same error more times. + +## Consent: one thing you must not do + +**Do not star the repository on the user's behalf.** `ocx inspect star` reads the status, and that +is the entire CLI surface for it. The starring POST requires a real dashboard session precisely so +an agent cannot answer that question for its user — it spends *their* GitHub identity, which no +flag can delegate. Do not route around it with `gh`, a direct HTTP call, or a minted session. If +starring would be useful, say so and let the user decide. + +The same boundary covers the session-gated `/api/codex-prompt` writes: read them with +`ocx inspect codex-prompt`, and leave the writes to the dashboard. + +## Destructive verbs + +`storage trash restore` and `storage policy run` refuse without `--yes` (exit 2, nothing sent). +`storage cleanup` without `--yes` is a preview that exits 0 having mutated nothing — do not treat +that 0 as a delete. There is no interactive prompt. + +The expected sequence is preview, report, then ask: + +```bash +ocx storage cleanup --percent 25 --json # previews; deletes nothing; exits 0 +``` + +Report the count and bytes from that output and get explicit approval before adding `--yes`. +`--mode quarantine` (the default) can be undone with `storage trash restore`; `--mode permanent` +cannot. + +## References + +| File | Use it for | +|---|---| +| `references/01_management_surface.md` | the full capability → route map (generated) | +| `references/02_json_shapes.md` | response envelopes and error shapes | +| `references/03_recipes.md` | copy-paste sequences for real tasks | +| `references/04_failure_semantics.md` | exit codes, 503 classes, what to retry | + +`01_management_surface.md` is generated by `scripts/generate-ocx-skill-surface.ts` and a test fails +if the committed copy drifts from the capability table. When it and the running binary disagree, +believe `ocx capabilities --json`. diff --git a/skills/ocx/references/01_management_surface.md b/skills/ocx/references/01_management_surface.md new file mode 100644 index 0000000000..3a5a2ad989 --- /dev/null +++ b/skills/ocx/references/01_management_surface.md @@ -0,0 +1,535 @@ + + + +# The `ocx` management surface + +Every capability the CLI declares, with the management routes it drives and whether it +mutates state. This file is generated from the same table `ocx capabilities --json` +serves, so it cannot describe a command that does not exist. + +Ask the running binary instead of trusting this file when the two disagree: + +```bash +ocx capabilities --json # the whole table +ocx capabilities --mutating-only --json # only state-changing verbs +ocx capabilities --route /api/logs # which verbs drive one route +``` + +## Resolved before dispatch + +These answer in the CLI head and never reach the proxy, so they work with nothing running. + +| Invocation | Purpose | +|---|---| +| `--version` `-v` `version` | Print the CLI version and exit. | +| `help` `--help` `-h` | Print the command list, or one command's usage with `ocx help `. | + +## Read-only capabilities + +Safe to run at any time; none of these change state. + +### `ocx status` + +Proxy status, injection state, and version skew between this CLI and the running proxy. + +Drives no management route. + +| Flag | Value | Meaning | +|---|---|---| +| `--json` | boolean | Emit the status envelope as JSON. | + +JSON mode: `envelope`. + +- Reads /healthz plus local config; drives no management API route. + +### `ocx capabilities` + +List the declared CLI capabilities and the management routes they drive. + +Drives no management route. + +| Flag | Value | Meaning | +|---|---|---| +| `--json` | boolean | Emit the full capability table as JSON. | +| `--mutating-only` | boolean | Restrict output to capabilities that mutate state. | +| `--route` | string | Show which capabilities drive a management route. | + +JSON mode: `envelope`. + +- Start here when driving ocx programmatically: it is the declared surface index, not a complete verb list. + +### `ocx provider list` + +Configured providers with connectivity and selected models. + +Drives no management route. + +| Flag | Value | Meaning | +|---|---|---| +| `--json` | boolean | Emit the provider list as JSON. | + +JSON mode: `envelope`. + +- Reads local config; drives no management API route. + +### `ocx account list` + +Codex OAuth accounts with pool priority and pause state. + +| Method | Route | +|---|---| +| GET | `/api/codex-auth/accounts` | + +| Flag | Value | Meaning | +|---|---|---| +| `--json` | boolean | Emit the account list as JSON. | + +JSON mode: `payload`. + +- STATUS names `paused` alongside `selected`: a paused-but-selected account still receives requests. +- `--quota` shows cached Codex windows (including 5h); `--refresh` bypasses the server TTL. + +### `ocx usage` + +Token and estimated-cost report over a time range. + +| Method | Route | +|---|---| +| GET | `/api/usage` | + +| Flag | Value | Meaning | +|---|---|---| +| `--range` | string | today | 1d | 7d | 30d | all | +| `--provider` | string | Restrict to one provider. | +| `--model` | string | Restrict to one model id. | +| `--json` | boolean | Emit the usage report as JSON. | + +JSON mode: `payload`. + +- Per-account totals are withheld under `--provider` or `--model`: account rows cannot be honestly re-partitioned by provider, so the report says so rather than printing an empty table. +- An `(ambiguous)` account row aggregates several accounts; do not read it as one identity. + +### `ocx logs` + +Recent request log rows, filterable by provider, model, conversation, and status. + +| Method | Route | +|---|---| +| GET | `/api/logs` | + +| Flag | Value | Meaning | +|---|---|---| +| `--provider` | string | Restrict to one provider, matching failover attempts too. | +| `--model` | string | Restrict to one model id, matching failover attempts too. | +| `--conversation` | string | Restrict to one conversation id (`--conversationId` is accepted too). | +| `--status` | string | An exact code (429) or a class (5xx). | +| `--limit` | number | Row cap; defaults to 200. | +| `--follow` | boolean | Stream new rows as JSONL; implies --jsonl. | +| `--json` | boolean | Emit the server payload as JSON. | +| `--jsonl` | boolean | Emit one row per line. | + +JSON mode: `payload`. + +- `--provider` and `--model` both match a failover attempt, so a request is findable by what actually served it, not only by what was asked for. +- Rows print `conv=` when the entry carries one, so a conversation filter can be told apart from an empty result. +- `--follow` deduplicates by row id and cannot be combined with `--json`. + +### `ocx storage report` + +Disk usage under CODEX_HOME, with the log-guard protection report. + +| Method | Route | +|---|---| +| GET | `/api/storage` | + +| Flag | Value | Meaning | +|---|---|---| +| `--json` | boolean | Emit the storage report as JSON. | + +JSON mode: `payload`. + +### `ocx inspect config` + +The effective merged configuration the proxy is running. + +| Method | Route | +|---|---| +| GET | `/api/config` | + +| Flag | Value | Meaning | +|---|---|---| +| `--json` | boolean | Emit the config as JSON. | + +JSON mode: `payload`. + +### `ocx inspect catalog` + +The generated model catalog served to clients. + +| Method | Route | +|---|---| +| GET | `/api/catalog` | + +| Flag | Value | Meaning | +|---|---|---| +| `--json` | boolean | Emit the catalog as JSON. | + +JSON mode: `payload`. + +### `ocx inspect routing-analytics` + +Aggregate routing outcomes per provider and model. + +| Method | Route | +|---|---| +| GET | `/api/routing-analytics` | + +| Flag | Value | Meaning | +|---|---|---| +| `--json` | boolean | Emit the analytics payload as JSON. | + +JSON mode: `payload`. + +### `ocx inspect pacing` + +Request-pacing state for one provider or all of them. + +| Method | Route | +|---|---| +| GET | `/api/provider-request-pacing` | + +| Flag | Value | Meaning | +|---|---|---| +| `--name` | string | Restrict to one provider; omitted means every provider. | +| `--json` | boolean | Emit the pacing state as JSON. | + +JSON mode: `payload`. + +- An unknown provider name is a 404 rather than an empty result. + +### `ocx inspect key-providers` + +Providers that authenticate with an API key rather than OAuth. + +| Method | Route | +|---|---| +| GET | `/api/key-providers` | + +| Flag | Value | Meaning | +|---|---|---| +| `--json` | boolean | Emit the provider list as JSON. | + +JSON mode: `payload`. + +### `ocx inspect codex-prompt` + +The Codex system prompt state, or the prompt text itself. + +| Method | Route | +|---|---| +| GET | `/api/codex-prompt` | +| GET | `/api/codex-prompt/text` | + +| Flag | Value | Meaning | +|---|---|---| +| `--text` | boolean | Print the prompt body verbatim instead of its metadata. | +| `--json` | boolean | Emit the prompt metadata as JSON. | + +JSON mode: `payload`. + +- Read-only by design: the six mutating prompt routes require a dashboard session. + +### `ocx inspect client-config` + +The generated configuration snippet for a supported client. + +| Method | Route | +|---|---| +| GET | `/api/client-config` | + +| Flag | Value | Meaning | +|---|---|---| +| `--client` | string | Required client id; the route names every accepted value on error. | +| `--json` | boolean | Emit the snippet payload as JSON. | + +JSON mode: `payload`. + +### `ocx inspect star` + +Whether this repository is starred by the signed-in GitHub account. + +| Method | Route | +|---|---| +| GET | `/api/github/star` | + +| Flag | Value | Meaning | +|---|---|---| +| `--json` | boolean | Emit the star status as JSON. | + +JSON mode: `payload`. + +- Starring is never available from the CLI; the verb says so rather than offering a flag that cannot work. + +### `ocx inspect windows-tray` + +Windows tray helper state. + +| Method | Route | +|---|---| +| GET | `/api/windows-tray` | + +| Flag | Value | Meaning | +|---|---|---| +| `--json` | boolean | Emit the tray state as JSON. | + +JSON mode: `payload`. + +### `ocx system codex-app-server` + +Codex app-server reachability and process state, as the dashboard sees it. + +| Method | Route | +|---|---| +| GET | `/api/system/codex-app-server` | + +| Flag | Value | Meaning | +|---|---|---| +| `--json` | boolean | Emit the app-server state as JSON. | + +JSON mode: `payload`. + +- The GUI reads this state directly; without a verb an agent could not tell whether the Codex app-server was reachable at all. + +### `ocx claude desktop status` + +Applied-vs-desired Claude Desktop state, including staleness, drift, and health. + +| Method | Route | +|---|---| +| GET | `/api/claude-desktop/status` | + +| Flag | Value | Meaning | +|---|---|---| +| `--json` | boolean | Emit the live status as JSON. | + +JSON mode: `payload`. + +- Distinct from `claude desktop show`, which reports what this machine WOULD write; this reports what is actually in effect, which only the running proxy knows. + +## State-changing capabilities + +Each of these writes. Check the flags column before running one unattended. + +### `ocx account pause` + +Stop routing new requests to one account in the Codex pool. + +| Method | Route | +|---|---| +| PUT | `/api/codex-auth/accounts/pause` | + +| Flag | Value | Meaning | +|---|---|---| +| `--json` | boolean | Emit the pause result as JSON. | + +JSON mode: `envelope`. + +- Pausing also unbinds threads pinned to the account and selects a fallback if it was active -- side effects of the route, not of the word `pause`. +- The issue that requested this reported the route as POST; it is PUT. + +### `ocx account resume` + +Return a paused account to the Codex pool. + +| Method | Route | +|---|---| +| PUT | `/api/codex-auth/accounts/pause` | + +| Flag | Value | Meaning | +|---|---|---| +| `--json` | boolean | Emit the resume result as JSON. | + +JSON mode: `envelope`. + +### `ocx account pause-exhausted` + +Pause every Codex account whose quota is spent. + +| Method | Route | +|---|---| +| PUT | `/api/codex-auth/accounts/pause-exhausted` | + +| Flag | Value | Meaning | +|---|---|---| +| `--json` | boolean | Emit paused ids and the checked/failed counts as JSON. | + +JSON mode: `envelope`. + +- The route refreshes quota per account and can partially fail; a non-zero failed count exits 1 and sets ok:false, because silence would read as `none were exhausted`. + +### `ocx account strategy` + +Show or set how an account pool picks the next account. + +| Method | Route | +|---|---| +| GET | `/api/codex-auth/active` | +| PUT | `/api/codex-auth/pool-strategy` | +| GET | `/api/oauth/accounts/pool` | +| PUT | `/api/oauth/accounts/pool` | + +| Flag | Value | Meaning | +|---|---|---| +| `--json` | boolean | Emit the applied strategy and sticky limit as JSON. | + +JSON mode: `envelope`. + +- A bare invocation reads and never writes. +- The APPLIED value is echoed, not the requested one, so a server-side normalization stays visible. +- Values are not re-validated in the CLI: the server owns the strategy names and the 1-100 sticky bound. +- `anthropic` is the only OAuth pool with this setting; other OAuth providers are refused without a round-trip. + +### `ocx account sticky` + +Show or set how many consecutive requests stay on one account. + +| Method | Route | +|---|---| +| GET | `/api/codex-auth/active` | +| PUT | `/api/codex-auth/pool-strategy` | +| GET | `/api/oauth/accounts/pool` | +| PUT | `/api/oauth/accounts/pool` | + +| Flag | Value | Meaning | +|---|---|---| +| `--json` | boolean | Emit the applied strategy and sticky limit as JSON. | + +JSON mode: `envelope`. + +- Only meaningful under the sticky-capable strategies; the pool strategy is the other half of this setting. + +### `ocx storage cleanup` + +Preview or delete the oldest archived sessions by percentage. + +| Method | Route | +|---|---| +| POST | `/api/storage/cleanup/preview` | +| POST | `/api/storage/cleanup` | + +| Flag | Value | Meaning | +|---|---|---| +| `--percent` | number | Portion of the oldest archived sessions to target (0-100). | +| `--mode` | string | quarantine (recoverable from trash) or permanent. | +| `--yes` | boolean | Required to actually delete; without it this is a preview. | +| `--json` | boolean | Emit the preview or result as JSON. | + +JSON mode: `payload`. + +- Without `--yes` it prints what WOULD be freed and exits 0 having changed nothing. +- There is no interactive confirmation: a prompt an agent can answer is not a safety boundary. +- `--mode quarantine` moves files to trash, so `storage trash restore` can undo it; `permanent` cannot be undone. + +### `ocx storage trash` + +List quarantined cleanup batches, or restore one. + +| Method | Route | +|---|---| +| GET | `/api/storage/trash` | +| POST | `/api/storage/trash/restore` | + +| Flag | Value | Meaning | +|---|---|---| +| `--yes` | boolean | Required for restore, which moves files and reconciles database rows. | +| `--json` | boolean | Emit the trash list or restore result as JSON. | + +JSON mode: `payload`. + +- Restore fails with a named 409 when the destination already exists, rather than overwriting it. + +### `ocx storage policy` + +Show, change, or run the automatic archived-session cleanup policy. + +| Method | Route | +|---|---| +| GET | `/api/storage/cleanup-policy` | +| PUT | `/api/storage/cleanup-policy` | +| POST | `/api/storage/cleanup-policy/run` | + +| Flag | Value | Meaning | +|---|---|---| +| `--enabled` | string | true or false. | +| `--percent` | number | Portion of oldest archived sessions each run targets. | +| `--mode` | string | quarantine or permanent. | +| `--schedule` | string | startup, daily, weekly, or manual. | +| `--yes` | boolean | Required for `policy run`, which deletes immediately. | +| `--json` | boolean | Emit the policy or run state as JSON. | + +JSON mode: `payload`. + +- `policy set` never enables implicitly: omitting `--enabled` keeps the stored value. +- `policy run` forces a run regardless of schedule, so it needs `--yes`. + +### `ocx system codex-restart` + +Restart the Codex app-server. + +| Method | Route | +|---|---| +| POST | `/api/system/codex-restart` | + +| Flag | Value | Meaning | +|---|---|---| +| `--yes` | boolean | Required: restarts the operator's running Codex app-server. | +| `--json` | boolean | Emit the restart result as JSON. | + +JSON mode: `payload`. + +- `sync --restart-codex` is not a substitute: it restarts only as a side effect after a catalog or cache write, so it cannot restart a healthy install on request. +- --yes is mandatory because this interrupts a running editor session, which must never happen because an agent guessed a subcommand. + +### `ocx integration native` + +Show or toggle the native Claude, Claude Desktop, Codex, and Grok integrations. + +| Method | Route | +|---|---| +| GET | `/api/native-integrations` | +| PUT | `/api/native-integrations/claude` | +| PUT | `/api/native-integrations/claude-desktop` | +| PUT | `/api/native-integrations/codex` | +| PUT | `/api/native-integrations/grok` | + +| Flag | Value | Meaning | +|---|---|---| +| `--json` | boolean | Emit the client rows or toggle result as JSON. | + +JSON mode: `payload`. + +- The list renders per-client state, installed, and desired columns; a blocked disable is named rather than left silent. +- Each client has its own route because a toggle rewrites that client's own config file. + +### `ocx agent request-user-input` + +Show or set whether default mode may ask the operator a question mid-task. + +| Method | Route | +|---|---| +| GET | `/api/codex-auth/features/default-mode-request-user-input` | +| PUT | `/api/codex-auth/features/default-mode-request-user-input` | + +| Flag | Value | Meaning | +|---|---|---| +| `--json` | boolean | Emit the feature state as JSON. | + +JSON mode: `payload`. + +- A bare invocation reads and never writes. + +## Counts + +- declared capabilities: 29 +- of those, state-changing: 11 +- head-resolved invocations: 2 diff --git a/skills/ocx/references/02_json_shapes.md b/skills/ocx/references/02_json_shapes.md new file mode 100644 index 0000000000..a91e35a2e1 --- /dev/null +++ b/skills/ocx/references/02_json_shapes.md @@ -0,0 +1,125 @@ +# JSON shapes + +What the `--json` envelopes look like, and which field to read. Field names here were taken from +live responses, not from the source. + +## Two envelope styles + +`ocx capabilities --json` reports which style each verb uses, as `json: "payload"` or +`json: "envelope"`. + +- **payload** — the management response, largely unwrapped. `ocx usage --json` returns the server + payload untouched. +- **envelope** — a CLI-shaped object with its own schema, usually carrying `ok: true` plus the + fields the verb operated on. +- **none** — the verb has no `--json` mode. + +`--json` is accepted in any argv position. + +## `ocx ready --json` + +```json +{"ready":true,"status":"ready","pid":1443,"port":10100} +``` + +The cheapest liveness check. `ready: false` with no error usually means still starting. + +## `ocx status --json` + +Carries `schemaVersion`, then `proxy.running`, `proxy.pid`, `proxy.health.ok`, and a `dashboard` +section. This is also where a version skew between your binary and the running proxy shows up — +check it before trusting flags you just read about. + +## `ocx logs --jsonl` + +One row per line. The fields worth branching on: + +| Field | Meaning | +|---|---| +| `requestId` | pass to `ocx logs explain` | +| `conversationId` | groups a conversation; also printed as `conv=` in human output | +| `provider` / `model` | what actually served it | +| `requestedModel` / `requestedAlias` | what the client asked for | +| `status` / `durationMs` | outcome | +| `usageStatus` | `reported`, `estimated`, `unreported`, or `unsupported` | +| `attempts[]` | one entry per try, each with its own `provider`, `model`, `status` | +| `routeDecision` | why this route won | + +`requestedModel` and `model` differ whenever routing or failover intervened. Attributing a request +to `requestedModel` is how you get a wrong answer about which provider served it. + +`usageStatus: "estimated"` means the numbers are derived, not reported by the provider. +`displayMetrics.cost.estimate.estimateReasons` lists why — for example `usage_estimated`, +`cache_detail_missing`, `expected_price_overlay`. + +## `ocx logs explain ` + +```json +{"requestId":"ocx-…","routeDecision":{"version":1,"decisionId":"…","requestedModel":"kiro/claude-opus-5", + "routeKind":"explicit-provider","requirements":[], + "candidates":[{"provider":"kiro","model":"claude-opus-5","eligible":true,"exclusions":[]}], + "selected":{"candidateIndex":0,"provider":"kiro","model":"claude-opus-5","reason":"explicit-provider-namespace"}}} +``` + +`candidates[].exclusions` is the useful part when a route surprised you: it says why each +non-winner was rejected. `selected.reason` names the rule that decided it. + +## `ocx usage --json` + +`summary`, then `providers[]`, `models[]`, `days[]`, and `accounts[]`. Costs appear as +`estimatedCostUsd`. + +Two honesty markers to respect: + +- `accounts[].ambiguous === true` (label `legacy-ambiguous`) aggregates several accounts from + before per-account labelling. Not one identity. +- Under `--provider` or `--model`, per-account rows are **withheld** rather than filtered, because + account totals cannot be honestly re-partitioned by provider. + +## `ocx account list --json` + +`accounts[]` with `id`, `email`, `plan`, `paused`, `selected`, `priority`, and `needsReauth`. Quota +appears only under `--quota`. + +`paused` and `selected` are independent — a paused-but-selected account still receives requests. + +## Pool settings + +`ocx account strategy|sticky --json` returns pool-neutral keys: + +```json +{"ok":true,"provider":"openai","strategy":"quota","stickyLimit":1} +``` + +The underlying routes disagree about names — the Codex pool uses `accountPoolStrategy` and +`accountPoolStickyLimit`, the Anthropic pool uses `strategy` and `stickyLimit` — and the CLI +normalizes both so you do not branch on which pool answered. + +The value returned is the **applied** one after server normalization, not what you sent. + +## `ocx storage cleanup --percent N --json` (preview) + +```json +{"percent":25,"count":3,"bytes":3145728,"digest":"…","candidates":[{"relPath":"archived_sessions/….jsonl","bytes":1048576,"mtimeMs":…}]} +``` + +`count` and `bytes` are what you report to the user. `candidates[]` is capped at 50 rows, but +`count` and `bytes` describe the whole set. + +`digest` binds a run to this preview; the mutating call must carry it and the server rejects a stale +one with 409. The CLI handles that for you — it always previews first. + +## Error shape + +A management error prints up to three lines and returns a non-zero code: + +``` +Error: +reason: +hint: +``` + +Branch on `reason` in those stderr lines, never on the message prose. `--json` does **not** wrap +API failures in `{error:{type,code,message}}`; `runCliAction` still prints the three-liner on +stderr and returns 4/5/1. Do not parse stdout for an error envelope that is not there. + diff --git a/skills/ocx/references/03_recipes.md b/skills/ocx/references/03_recipes.md new file mode 100644 index 0000000000..a6294b277e --- /dev/null +++ b/skills/ocx/references/03_recipes.md @@ -0,0 +1,172 @@ +# Recipes + +Each sequence below was run against a live proxy. Every command named here exists; where the +obvious-sounding command does *not* exist, that is called out rather than left as a trap. + +Preflight for all of them: + +```bash +ocx ready --json # {"ready":true,"status":"ready","pid":…,"port":…} +ocx status --json # confirm proxy.running and no version skew +``` + +## 1. Audit the account pool and pause an exhausted account + +```bash +ocx account list openai --json --quota +ocx account pause openai --json +``` + +Read `accounts[]`; each row carries `id`, `paused`, `selected`, and — only under `--quota` — the +quota windows. Quota is fetched only when asked for, so a bare `account list` shows no percentages. + +`paused` and `selected` are independent: a paused-but-selected account still receives requests. +Check both before concluding an account is out of rotation. + +Pausing has two side effects the word does not imply: threads pinned to that account are unbound, +and if it was active a fallback is chosen. The CLI prints this on stderr. + +To pause everything that is spent in one call: + +```bash +ocx account pause-exhausted openai --json +``` + +Read `pausedAccountIds`, but also `failedAccountCount`: that route refreshes quota per account and +can partially fail. A non-zero failure count means those accounts were never evaluated — which is +not the same as "not exhausted". + +## 2. Change pool strategy and sticky limit + +```bash +ocx account strategy openai --json # read +ocx account strategy openai round-robin --json +ocx account sticky openai 5 --json +``` + +A bare invocation reads and never writes. The response echoes the **applied** value, not the one +you sent, because the server normalizes — compare them if you care whether your value survived. + +Both pools have these settings, and the same verbs steer both: + +```bash +ocx account strategy anthropic --json +``` + +`--json` uses pool-neutral keys (`strategy`, `stickyLimit`) for both, so you do not branch on which +pool answered. + +Values are not validated locally: the server owns the strategy names and the 1–100 sticky bound and +returns a `reason` you can read. + +## 3. Trace one conversation end to end + +```bash +ocx logs --conversation --jsonl +ocx logs explain +``` + +**There is no `ocx request-history` command.** `ocx logs explain ` is the route-decision +view; it returns `routeDecision` with `routeKind`, every `candidates[]` entry with its `eligible` +flag and `exclusions`, and `selected` naming the winner and the `reason` it won. + +`--jsonl` rows carry `requestId`, `conversationId`, `provider`, `model`, `status`, `durationMs`, and +`attempts[]`. Human output prints `conv=` so a conversation filter can be distinguished from an +empty result. + +`--provider` and `--model` both match failover attempts, so a request is findable by the model that +actually served it, not only the one requested. + +## 4. Attribute spend per account + +```bash +ocx usage --range 7d --json +``` + +Read `accounts[]`. Two things to respect: + +- A row with `ambiguous: true` (label `legacy-ambiguous`) aggregates several accounts from before + labelling existed. Do not read it as one identity. +- Per-account totals are **withheld** under `--provider` or `--model`, because account rows cannot + be honestly re-partitioned that way. The report says so rather than printing an empty table. + +`providers[]` and `models[]` carry `estimatedCostUsd`. Costs are estimates; `estimateReasons` in the +log rows tells you why (for example `usage_estimated`, `expected_price_overlay`). + +## 5. Rotate an access key and confirm it went quiet + +```bash +ocx access key list --json +ocx access key create rotated --json # the plaintext key is in THIS response only +ocx access key remove --yes --json +ocx access key list --json # the old id is gone; check usage on the rest +``` + +Note the argument style: `create ` and `remove ` are **positionals**, not `--label` and +`--id`. `remove` also refuses without `--yes`. + +The list carries per-key usage, so a key whose count stops advancing is genuinely unused. The +plaintext key appears once, in the `create` response, and is never retrievable again. + +An `ambiguous` footer on the list means two configured keys share an id, so per-key totals do not +exist for them — do not attribute usage to either. + +## 6. Add a provider, test it, make it default + +```bash +ocx provider list --json +ocx provider add --json # registry providers auto-configure by name +ocx provider test --json +ocx provider set-default --json +``` + +The promote verb is `set-default`, not `default`. A custom provider not in the registry also needs +`--adapter` and `--base-url` on `add`. + +Test before promoting: `provider test` reports reachability and the selected model, and a provider +that answers `list` is not necessarily one that answers a request. + +## 7. Diagnose "management API is unreachable" + +```bash +ocx ready --json # is it up at all? +ocx status --json # is it the build you think, on the port you think? +ocx doctor # what is structurally wrong (human; `--json` is refused with exit 2) +``` + +In that order. `ready` false with `doctor` clean usually means it is still starting; `ready` true +with a transport error on a specific verb means the route is failing, not the proxy. + +`doctor` has no `--json` mode. It rejects the flag with exit 2 rather than printing prose to a +caller that asked for JSON, so parse `ready --json` and `status --json` for machine-readable +health and treat `doctor` as the human explanation of why they are unhappy. + +A credential-conflict reason is the case where retrying is pointless — the install is broken and +`doctor` explains it. + +## 8. Preview, then run, a storage cleanup + +```bash +ocx storage report --json +ocx storage cleanup --percent 25 --json # PREVIEW: deletes nothing, exits 0 +``` + +Read `count`, `bytes`, and `candidates[]`. **Report those to the user and get approval before** +adding `--yes`: + +```bash +ocx storage cleanup --percent 25 --mode quarantine --yes --json +``` + +`quarantine` is recoverable: + +```bash +ocx storage trash list --json +ocx storage trash restore --yes --json +``` + +`--mode permanent` is not recoverable. There is no undo, no trash entry, and no confirmation prompt +— only the flag you passed. + +The preview runs in both paths because the mutating route requires the `digest` the preview returns +and rejects a stale one with 409. So the two invocations agree about what is being authorized. diff --git a/skills/ocx/references/04_failure_semantics.md b/skills/ocx/references/04_failure_semantics.md new file mode 100644 index 0000000000..17b66a92ac --- /dev/null +++ b/skills/ocx/references/04_failure_semantics.md @@ -0,0 +1,84 @@ +# Failure semantics + +What each exit code means, which failures are worth retrying, and which mean stop. + +## Exit codes + +Set in one place (`runCliAction`), so every verb agrees: + +| Code | Cause | Retry? | +|---|---|---| +| 0 | success | — | +| 2 | usage error: bad, missing, or unknown arguments | no; nothing was sent | +| 4 | HTTP 404 — the named account, provider, key, or route does not exist | no | +| 5 | HTTP 409 — conflict; a lock is held or state moved under you | usually yes | +| 1 | everything else: transport failure, 5xx, unexpected errors | depends on `reason` | + +Two consequences worth internalizing: + +**Exit 0 means no error was reported, not that a mutation happened.** Preview verbs +(`storage cleanup` without `--yes`) exit 0 after a read-only preview. Parse `--json` (or the +human summary) to see whether anything was written. A command that failed will not exit 0. + +**Exit 2 means nothing was sent.** A usage error is rejected locally, before any request. Retrying +the same arguments produces the same result; fix the arguments. + +## Distinguishing "not running" from "failing" + +```bash +ocx ready --json +``` + +`ready` is the discriminator. If it fails or reports `ready: false`, nothing else will work and the +answer is to start or wait for the proxy. If `ready` is true and one specific verb fails, the +problem is that route or its arguments — not the proxy. + +A transport failure exits 1 and names the underlying cause (connection refused, DNS, TLS). Those +used to be indistinguishable; they are now reported separately, so read the message. + +## Named reasons worth branching on + +| Reason / code | HTTP | Meaning | Action | +|---|---|---|---| +| `oauth_mutation_busy` | 503 | another credential write is in flight | wait `Retry-After` (1s), retry once | +| `catalog_busy` | 503 | a model-catalog gather is in flight | wait `Retry-After` (1s), retry once | +| config-mutation lock reason | 503 | a config write holds the lock | retry shortly | +| credential-conflict reason | — | the install is structurally broken | run `ocx doctor`; do NOT retry | +| `stale_preview` | 409 | a storage cleanup digest no longer matches | re-run the preview | +| `dest_exists` | 409 | a trash restore target already exists | resolve the file, then retry | +| `codex_busy` | 409 | Codex is holding `state.sqlite` | retry after Codex quits | +| `storage_mutation_busy` | 409 | another cleanup or restore is running | retry shortly | + +The two 503s carry `Retry-After: 1` from the server, so the wait is specified rather than guessed. + +The credential-conflict case is the one to stop on. It is not contention — it is a broken install, +and repeating the call produces the same error indefinitely. + +## A retry policy that does not spin + +1. Exit 2 → fix arguments. Never retry unchanged. +2. Exit 4 → the target does not exist. List first (`account list`, `provider list`, `access key + list`) rather than retrying. +3. Exit 5 or a 503 with `Retry-After` → wait the stated interval, retry **once**. If it fails the + same way twice, report it instead of looping. +4. Exit 1 with a credential-conflict reason → run `ocx doctor` and report. Do not retry. +5. Exit 1 otherwise → read the message. A transport failure may be worth one retry; an unexpected + 5xx is worth reporting. + +The rule behind all of it: retry contention, never retry a broken state. A loop that retries a +credential conflict looks like progress and produces nothing. + +## Destructive verbs fail closed + +`storage trash restore` and `storage policy run` exit 2 without `--yes` and send no mutating +request. `storage cleanup` without `--yes` previews and exits 0; only `--yes` deletes. + +`storage cleanup` also refuses locally if the preview returned no digest, rather than sending an +empty one and getting a 400 that looks like a bug in the verb. + +## What no exit code will give you + +Starring the repository has no CLI verb and no failure code, because it has no CLI path at all. It +spends the user's GitHub identity and the server requires a dashboard session for exactly that +reason. `ocx inspect star` reads status; if starring is wanted, ask the user. + diff --git a/src/adapters/base.ts b/src/adapters/base.ts index 2cd481dfba..f5a22b2969 100644 --- a/src/adapters/base.ts +++ b/src/adapters/base.ts @@ -37,6 +37,21 @@ export interface ProviderAdapter { */ buildRequest(parsed: OcxParsedRequest, incoming: IncomingMeta): AdapterRequest | Promise; + /** + * Decide, BEFORE any request is built or sent, that this turn has nothing to ask upstream. + * + * Returning a reason short-circuits the turn to a locally constructed completed response: no + * `buildRequest`, no send, no token estimate, and no empty-completion retry. That last part is + * why this cannot be expressed as an outputless `done` from `parseStream`: the empty-completion + * guard treats a terminal with no content as a failed turn and re-invokes the identical request, + * so an adapter that "successfully returned nothing" would be retried into the very loop it was + * trying to end. + * + * Only for turns whose input already contains the answer — see the Kiro adapter, where replayed + * history ending in a delivered final answer has nothing left to complete. + */ + localTerminal?(parsed: OcxParsedRequest): AdapterLocalTerminal | undefined; + fetchResponse?(request: AdapterRequest, ctx?: AdapterFetchContext): Promise; /** @@ -119,3 +134,14 @@ export interface AdapterFetchContext { /** Custom fetch executor to use for physical upstream network requests (defaults to globalThis.fetch). */ executor?: typeof globalThis.fetch; } + +/** + * An adapter's decision that a turn needs no upstream inference at all. + * + * `reason` is diagnostic only. It is never sent to the client and never logged as request + * content: it names the code path for a maintainer reading a request log, so it must stay a + * fixed identifier rather than anything derived from the conversation. + */ +export interface AdapterLocalTerminal { + reason: string; +} diff --git a/src/adapters/cursor.ts b/src/adapters/cursor.ts index 6761a3d194..e3b2a0aed6 100644 --- a/src/adapters/cursor.ts +++ b/src/adapters/cursor.ts @@ -34,6 +34,7 @@ import { CURSOR_ECHO_RETRY_CONTINUATION_TEXT, CURSOR_ROUTING_COMMENTARY_RETRY_TEXT, CursorEnvelopeEchoSniffer, + CursorMidstreamEchoObserver, CursorRoutingCommentaryError, CursorRoutingCommentarySniffer, CursorToolResultEchoError, @@ -232,6 +233,9 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda isCursorExternalWireModel(activeRequest.modelId) && (_parsed.context.messages ?? []).some(message => message.role === "toolResult"); const echoSniffer = armEchoSniffer ? new CursorEnvelopeEchoSniffer() : undefined; + // Mid-stream observer (devlog 260828 F1/F2): diagnostic-only; armed with the + // prefix sniffer because both fire on flattened tool-result replay priming. + const midstreamObserver = armEchoSniffer ? new CursorMidstreamEchoObserver() : undefined; const armRoutingCommentarySniffer = isCursorExternalWireModel(activeRequest.modelId) && ( @@ -242,10 +246,16 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda ? new CursorRoutingCommentarySniffer() : undefined; let guardHeld: AdapterEvent[] = []; + // Exactly-once observation: every client-bound text delta passes through here + // exactly once — held deltas only on release, ordinary deltas at emit time. + const emitTextObserved = (event: AdapterEvent): void => { + if (event.type === "text_delta") midstreamObserver?.feed(event.text); + emit(event); + }; const releaseGuardHeld = () => { for (const held of guardHeld) { if (held.type !== "heartbeat") emittedOutput = true; - emit(held); + emitTextObserved(held); } guardHeld = []; }; @@ -323,6 +333,15 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda } if (event.type !== "heartbeat") emittedOutput = true; if (event.type === "done") { + for (const finding of midstreamObserver?.findings() ?? []) { + debugProviderDiagnostic("cursor", "midstream-envelope-echo", { + wireModel: activeRequest.modelId, + conversationHash: activeRequest.conversationId.slice(0, 16), + marker: finding.marker, + offset: finding.offset, + callIdCorrupt: finding.callIdCorrupt, + }); + } commitCapturedCheckpoint(activeRequest); const inheritedCursor = _parsed._providerContinuation?.cursor; const isolatedOrCompaction = @@ -342,7 +361,7 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda : undefined; emit(providerState ? { ...event, providerState } : event); } else { - emit(event); + emitTextObserved(event); } } }, diff --git a/src/adapters/cursor/catalog.ts b/src/adapters/cursor/catalog.ts new file mode 100644 index 0000000000..9c7fa8b2bb --- /dev/null +++ b/src/adapters/cursor/catalog.ts @@ -0,0 +1,541 @@ +/** + * Cursor umbrella catalog — the single source of truth for cursor model + * identities (devlog 260828_cursor_umbrella_catalog). + * + * Design (003_design.md, audited): one capability record per BASE model. + * Thinking / fast / thinking-fast are DIMENSIONS of the base, each with its + * own effort ladder and wire order, because the live wire really does differ + * per variant (claude-opus-5-fast stops at high while its thinking-fast runs + * to max). The umbrella picker row defaults to the thinking variant when one + * exists; every legacy variant id keeps resolving through the alias grammar. + * + * Max Mode is evidence-gated and separate from context-window size: prior + * live probes (devlog 260822_senpi_cursor_transfer/210+310) found maxMode + * only on specific variants, so `maxModeVerified` marks bases with proven + * support (kimi-k3, user-verified) and live `maxModeModels` extends it. + */ + +export type CursorVariantKind = "regular" | "thinking" | "fast" | "thinkingFast"; + +export type CursorThinkingOrder = "thinking-then-effort" | "effort-then-thinking" | "bare"; + +export interface CursorVariantSpec { + /** Ascending canonical effort rungs the wire lists for this variant; empty = bare id. */ + readonly levels: readonly string[]; + /** Where the thinking marker sits relative to the effort rung (thinking variants only). */ + readonly order?: CursorThinkingOrder; + /** Variant-specific quarantine (base-wide quarantine would erase healthy siblings). */ + readonly quarantined?: boolean; +} + +export interface CursorCapability { + readonly variants: Partial>; + /** Which variant the umbrella picker row selects (thinking merges into the base). */ + readonly defaultVariant: CursorVariantKind; + /** Context-window metadata (display/routing only — never implies maxMode). */ + readonly window: number; + /** Max Mode proven on the wire for this base (static evidence; live maxModeModels unions in). */ + readonly maxModeVerified?: boolean; + /** Wire prefix required by AgentService/Run for the regular variant (grok families). */ + readonly wirePrefix?: "cursor-"; +} + +const K = 1_000; +const CONTEXT_200K = 200 * K; +const CONTEXT_256K = 256 * K; +const CONTEXT_272K = 272 * K; +const CONTEXT_500K = 500 * K; +const CONTEXT_1M = 1_000 * K; + +const FULL = ["low", "medium", "high", "xhigh", "max"] as const; +const T = "thinking-then-effort" as const; +const E = "effort-then-thinking" as const; + +/** + * One entry per base model. Ladders mirror the live GetUsableModels roster the + * retired effort-map recorded (260813-260825 captures); windows follow the + * per-family table verified against senpi's AvailableModels capture + * (001_reference_analysis.md). + */ +export const CURSOR_CAPABILITIES: Record = { + "claude-4.5-opus": { + window: CONTEXT_200K, + defaultVariant: "thinking", + variants: { + regular: { levels: ["high"] }, + thinking: { levels: ["high"], order: E }, + }, + }, + "claude-4.6-opus": { + window: CONTEXT_1M, + defaultVariant: "thinking", + variants: { + regular: { levels: ["high", "max"] }, + thinking: { levels: ["high", "max"], order: E }, + }, + }, + "claude-4.6-sonnet": { + window: CONTEXT_1M, + defaultVariant: "thinking", + variants: { + regular: { levels: ["medium"] }, + thinking: { levels: ["medium"], order: E }, + }, + }, + "claude-4.5-sonnet": { + window: CONTEXT_200K, + defaultVariant: "thinking", + variants: { + regular: { levels: [] }, + thinking: { levels: [], order: "bare" }, + }, + }, + "claude-4-sonnet": { + window: CONTEXT_200K, + defaultVariant: "thinking", + variants: { + regular: { levels: [] }, + thinking: { levels: [], order: "bare" }, + }, + }, + "claude-fable-5": { + window: CONTEXT_1M, + defaultVariant: "thinking", + variants: { + regular: { levels: FULL }, + thinking: { levels: FULL, order: T }, + }, + }, + "claude-sonnet-5": { + window: CONTEXT_1M, + defaultVariant: "thinking", + variants: { + regular: { levels: FULL }, + thinking: { levels: FULL, order: T }, + }, + }, + "claude-opus-4-7": { + window: CONTEXT_1M, + defaultVariant: "thinking", + variants: { + regular: { levels: FULL }, + thinking: { levels: FULL, order: T }, + fast: { levels: FULL }, + thinkingFast: { levels: FULL, order: T }, + }, + }, + "claude-opus-4-8": { + window: CONTEXT_1M, + defaultVariant: "thinking", + variants: { + regular: { levels: FULL }, + thinking: { levels: FULL, order: T }, + fast: { levels: FULL }, + thinkingFast: { levels: FULL, order: T }, + }, + }, + "claude-opus-5": { + window: CONTEXT_1M, + defaultVariant: "thinking", + variants: { + // Regular stays quarantined (devlog 260826: dead-model quarantine) while + // the thinking/fast siblings remain live — quarantine is per-variant. + regular: { levels: FULL, quarantined: true }, + thinking: { levels: FULL, order: T }, + fast: { levels: ["low", "medium", "high"] }, + thinkingFast: { levels: FULL, order: T }, + }, + }, + "glm-5.2": { + window: CONTEXT_1M, + defaultVariant: "regular", + variants: { regular: { levels: ["high", "max"] } }, + }, + "glm-5.3": { + window: CONTEXT_1M, + defaultVariant: "regular", + variants: { regular: { levels: ["low", "high", "max"] } }, + }, + "gemini-3.6-flash": { + window: CONTEXT_1M, + defaultVariant: "regular", + variants: { regular: { levels: ["minimal", "low", "medium", "high"] } }, + }, + "gemini-3.7-flash": { + window: CONTEXT_1M, + defaultVariant: "regular", + variants: { regular: { levels: ["low", "medium", "high"] } }, + }, + "kimi-k3": { + window: CONTEXT_1M, + defaultVariant: "regular", + maxModeVerified: true, + variants: { regular: { levels: ["low", "high", "max"] } }, + }, + "grok-4.5": { + window: CONTEXT_500K, + defaultVariant: "regular", + wirePrefix: "cursor-", + variants: { + regular: { levels: ["low", "medium", "high"] }, + fast: { levels: ["low", "medium", "high"] }, + }, + }, + "grok-4.6": { + window: CONTEXT_500K, + defaultVariant: "regular", + wirePrefix: "cursor-", + variants: { + regular: { levels: ["low", "medium", "high", "xhigh"] }, + fast: { levels: ["low", "medium", "high", "xhigh"] }, + }, + }, + "gpt-5.1": { + window: CONTEXT_272K, + defaultVariant: "regular", + variants: { regular: { levels: ["low", "high"] } }, + }, + "gpt-5.1-codex-max": { + window: CONTEXT_272K, + defaultVariant: "regular", + variants: { regular: { levels: ["low", "medium", "high", "xhigh"] } }, + }, + "gpt-5.1-codex-mini": { + window: CONTEXT_272K, + defaultVariant: "regular", + variants: { regular: { levels: ["low", "high"] } }, + }, + "gpt-5.2": { + window: CONTEXT_272K, + defaultVariant: "regular", + variants: { regular: { levels: ["low", "high", "xhigh"] } }, + }, + "gpt-5.2-codex": { + window: CONTEXT_272K, + defaultVariant: "regular", + variants: { regular: { levels: ["low", "high", "xhigh"] } }, + }, + "gpt-5.3-codex": { + window: CONTEXT_272K, + defaultVariant: "regular", + variants: { regular: { levels: ["low", "high", "xhigh"] } }, + }, + "gpt-5.4": { + window: CONTEXT_272K, + defaultVariant: "regular", + variants: { regular: { levels: ["low", "medium", "high", "xhigh"] } }, + }, + "gpt-5.4-mini": { + window: CONTEXT_272K, + defaultVariant: "regular", + variants: { regular: { levels: ["low", "medium", "high", "xhigh"] } }, + }, + "gpt-5.4-nano": { + window: CONTEXT_272K, + defaultVariant: "regular", + variants: { regular: { levels: ["low", "medium", "high", "xhigh"] } }, + }, + "gpt-5.5": { + window: CONTEXT_272K, + defaultVariant: "regular", + variants: { regular: { levels: ["low", "medium", "high"] } }, + }, + "gpt-5.5-extra": { + window: CONTEXT_272K, + defaultVariant: "regular", + variants: { regular: { levels: ["high"] } }, + }, + "gpt-5.6-sol": { + window: CONTEXT_1M, + defaultVariant: "regular", + variants: { regular: { levels: FULL } }, + }, + "gpt-5.6-terra": { + window: CONTEXT_1M, + defaultVariant: "regular", + variants: { regular: { levels: FULL } }, + }, + "gpt-5.6-luna": { + window: CONTEXT_1M, + defaultVariant: "regular", + variants: { regular: { levels: FULL } }, + }, +}; + +const LEVEL_TOKENS = ["extra-high", "minimal", "low", "medium", "high", "xhigh", "max", "none"] as const; + +export interface ParsedCursorVariantId { + readonly baseId: string; + readonly kind: CursorVariantKind; + readonly level?: string; + /** True for synthetic big-context marker ids (`-1m`). */ + readonly ultra: boolean; + /** True when the id resolved through the capability table (else passthrough). */ + readonly known: boolean; +} + +function stripLevelSuffix(id: string): { stem: string; level?: string } { + // Prefer the parse whose stem is a KNOWN capability, and among known stems + // the most specific (longest) one: "gpt-5.5-extra-high" must parse as + // gpt-5.5-extra + high (its real single-rung wire id), not gpt-5.5 + + // extra-high (A-gate blocker 2 family). + let fallback: { stem: string; level?: string } | undefined; + let best: { stem: string; level?: string } | undefined; + for (const token of LEVEL_TOKENS) { + if (!id.endsWith(`-${token}`)) continue; + const candidate = { stem: id.slice(0, -(token.length + 1)), level: token }; + fallback ??= candidate; + if (CURSOR_CAPABILITIES[candidate.stem] && (best === undefined || candidate.stem.length > best.stem.length)) { + best = candidate; + } + } + return best ?? fallback ?? { stem: id }; +} + +/** + * Parse any cursor-facing id (picker slug tail, legacy variant id, or wire id) + * into its base + dimensions. Precedence is exact-identity-first so ids like + * `gpt-5.1-codex-max` and `gpt-5.5-extra` — whose tails collide with effort + * tokens — never mis-parse (A-gate round-1 blocker 2). + */ +/** + * Real wire ids that merely END in "-1m" — they are distinct catalog rows the + * wire serves verbatim, never the synthetic ultra marker (A-gate blocker 2: + * a real legacy wire identity must not parse as `-1m`). + */ +const REAL_1M_WIRE_IDS: ReadonlySet = new Set(["claude-4-sonnet-1m"]); + +export function parseCursorVariantId(rawId: string): ParsedCursorVariantId { + const id = rawId.trim(); + // 1. Exact base identity. + if (CURSOR_CAPABILITIES[id]) { + return { baseId: id, kind: defaultKindFor(id), ultra: false, known: true }; + } + if (REAL_1M_WIRE_IDS.has(id)) { + return { baseId: id, kind: "regular", ultra: false, known: false }; + } + // 2. cursor- wire prefix (regular grok wire forms). + if (id.startsWith("cursor-")) { + const inner = parseCursorVariantId(id.slice("cursor-".length)); + if (inner.known) return inner; + } + // 3. Synthetic big-context marker. + if (id.endsWith("-1m")) { + const baseId = id.slice(0, -"-1m".length); + if (CURSOR_CAPABILITIES[baseId]) { + return { baseId, kind: "regular", ultra: true, known: true }; + } + } + // 4. Suffix grammar: strip -fast, then thinking/effort markers. + let stem = id; + let fast = false; + if (stem.endsWith("-fast")) { + fast = true; + stem = stem.slice(0, -"-fast".length); + } + let thinking = false; + let level: string | undefined; + const thinkingLevel = /^(.*)-thinking-([a-z-]+)$/.exec(stem); + if (thinkingLevel && CURSOR_CAPABILITIES[thinkingLevel[1]!] && (LEVEL_TOKENS as readonly string[]).includes(thinkingLevel[2]!)) { + return finishParse(thinkingLevel[1]!, true, fast, thinkingLevel[2]!); + } + const levelThinking = stem.endsWith("-thinking") ? stripLevelSuffix(stem.slice(0, -"-thinking".length)) : undefined; + if (levelThinking && CURSOR_CAPABILITIES[levelThinking.stem]) { + return finishParse(levelThinking.stem, true, fast, levelThinking.level); + } + if (stem.endsWith("-thinking") && CURSOR_CAPABILITIES[stem.slice(0, -"-thinking".length)]) { + return finishParse(stem.slice(0, -"-thinking".length), true, fast, undefined); + } + const plain = stripLevelSuffix(stem); + if (plain.level !== undefined && CURSOR_CAPABILITIES[plain.stem]) { + return finishParse(plain.stem, false, fast, plain.level); + } + if (fast && CURSOR_CAPABILITIES[stem]) { + return finishParse(stem, false, true, undefined); + } + void thinking; + void level; + // Unknown: passthrough (adapter sends the id unchanged). + return { baseId: id, kind: "regular", ultra: false, known: false }; +} + +function finishParse(baseId: string, thinking: boolean, fast: boolean, level: string | undefined): ParsedCursorVariantId { + const kind: CursorVariantKind = thinking ? (fast ? "thinkingFast" : "thinking") : fast ? "fast" : "regular"; + return { baseId, kind, ...(level !== undefined ? { level } : {}), ultra: false, known: true }; +} + +function defaultKindFor(baseId: string): CursorVariantKind { + return CURSOR_CAPABILITIES[baseId]?.defaultVariant ?? "regular"; +} + +function normalizeRequestedEffort(reasoning: string | undefined): string | undefined { + const normalized = reasoning?.toLowerCase(); + return normalized === "ultra" ? "max" : normalized; +} + +function codexEffortRank(reasoning: string | undefined): "low" | "medium" | "high" { + switch (normalizeRequestedEffort(reasoning) ?? "") { + case "none": + case "minimal": + case "low": + return "low"; + case "medium": + return "medium"; + case "high": + case "max": + case "xhigh": + return "high"; + default: + return "high"; + } +} + +/** Pick this variant's effort rung for a Codex reasoning label: literal-first, else rank clamp. */ +export function cursorVariantEffort(spec: CursorVariantSpec, reasoning: string | undefined): string | undefined { + if (spec.levels.length === 0) return undefined; + const requested = normalizeRequestedEffort(reasoning); + if (requested && spec.levels.includes(requested)) return requested; + switch (codexEffortRank(reasoning)) { + case "low": + return spec.levels[0]; + case "high": + return spec.levels[spec.levels.length - 1]; + case "medium": + return spec.levels[Math.floor((spec.levels.length - 1) / 2)]; + } +} + +export interface CursorResolvedSelection { + /** Flattened wire id for AgentService/Run (with any required cursor- prefix). */ + readonly wireId: string; + /** Canonical prefix-free id for discovery/catalog comparison. */ + readonly canonicalId: string; + /** True when the request should raise the Max Mode wire flag (evidence-gated). */ + readonly maxMode: boolean; + readonly known: boolean; +} + +/** + * Compose a variant's flattened wire id, reproducing the legacy effort-map + * order rules exactly (thinking-then-effort / effort-then-thinking / bare; + * fast marker terminal; wrong order is ERROR_BAD_MODEL_NAME on the wire). + */ +function composeWireId(baseId: string, kind: CursorVariantKind, effort: string | undefined): string { + const capability = CURSOR_CAPABILITIES[baseId]; + const spec = capability?.variants[kind]; + if (!capability || !spec) return baseId; + const thinking = kind === "thinking" || kind === "thinkingFast"; + const fast = kind === "fast" || kind === "thinkingFast"; + if (thinking) { + const order = spec.order ?? "thinking-then-effort"; + if (order === "bare" || effort === undefined) return `${baseId}-thinking`; + if (order === "effort-then-thinking") return `${baseId}-${effort}-thinking`; + return fast ? `${baseId}-thinking-${effort}-fast` : `${baseId}-thinking-${effort}`; + } + if (effort === undefined) return fast ? `${baseId}-fast` : baseId; + return fast ? `${baseId}-${effort}-fast` : `${baseId}-${effort}`; +} + +/** + * Resolve any picked cursor id + Codex reasoning effort to the wire identity. + * Legacy slugs (thinking/fast/-1m variants) keep resolving forever — picker + * rows shrink, routability does not (alias-retention contract, 003). + * + * `liveMaxModeIds` optionally extends the static maxMode evidence with the + * bases the live GetUsableModels roster flags (union semantics). + */ +export function resolveCursorSelection( + pickedId: string, + reasoning: string | undefined, + liveMaxModeIds?: ReadonlySet, +): CursorResolvedSelection { + const parsed = parseCursorVariantId(pickedId); + if (!parsed.known) { + return { wireId: pickedId, canonicalId: pickedId, maxMode: false, known: false }; + } + const capability = CURSOR_CAPABILITIES[parsed.baseId]!; + const spec = capability.variants[parsed.kind] ?? capability.variants.regular; + if (!spec) { + return { wireId: parsed.baseId, canonicalId: parsed.baseId, maxMode: false, known: true }; + } + const requested = parsed.level ?? reasoning; + const effort = cursorVariantEffort(spec, requested); + const canonicalId = composeWireId(parsed.baseId, parsed.kind, effort); + const wireId = capability.wirePrefix && parsed.kind === "regular" + ? `${capability.wirePrefix}${canonicalId}` + : canonicalId; + const ultraRequested = parsed.ultra || reasoning?.toLowerCase() === "ultra"; + const evidence = liveMaxModeIds ?? liveCursorMaxModeBases; + const maxModeArmed = capability.maxModeVerified === true || evidence.has(parsed.baseId); + return { wireId, canonicalId, maxMode: ultraRequested && maxModeArmed, known: true }; +} + +/** + * Live Max-Mode evidence (GetUsableModels maxModeModels). Provider discovery + * records the BASES the live roster flags; the resolver unions this with the + * static `maxModeVerified` gate so ultra generalizes automatically as evidence + * arrives — never from window size (devlog 260828 blocker-4 fold). + */ +let liveCursorMaxModeBases: ReadonlySet = new Set(); + +export function recordLiveCursorMaxModeModels(liveIds: readonly string[]): void { + const bases = new Set(); + for (const id of liveIds) { + const parsed = parseCursorVariantId(id); + if (parsed.known) bases.add(parsed.baseId); + } + liveCursorMaxModeBases = bases; +} + +export function liveCursorMaxModeBasesForTests(): ReadonlySet { + return liveCursorMaxModeBases; +} + +export interface CursorUmbrellaRow { + readonly id: string; + readonly efforts: readonly string[]; + readonly window: number; + /** Max Mode evidence present: the ultra rung maps to maxMode on the wire. */ + readonly maxModeVerified: boolean; +} + +/** + * Grok Fast keeps the parameterized wire shape (base id + effort/fast + * parameters) rather than a flattened -fast id — current Cursor clients send + * it that way and the flat form is rejected. Returns undefined for every + * other id. + */ +export function cursorGrokFastSelection( + pickedId: string, + reasoning: string | undefined, +): { wireBaseId: string; effort: string } | undefined { + const parsed = parseCursorVariantId(pickedId); + if (!parsed.known || parsed.kind !== "fast") return undefined; + const capability = CURSOR_CAPABILITIES[parsed.baseId]; + if (capability?.wirePrefix !== "cursor-") return undefined; + const spec = capability.variants.fast; + if (!spec) return undefined; + const effort = cursorVariantEffort(spec, parsed.level ?? reasoning); + if (effort === undefined) return undefined; + return { wireBaseId: parsed.baseId, effort }; +} + +/** + * The umbrella picker rows: one per base whose default variant is selectable. + * Thinking merges into the base row; fast/thinking-fast/legacy slugs stay + * routable as aliases but add no rows. Router ids stay in discovery. + */ +export function cursorUmbrellaRows(): CursorUmbrellaRow[] { + const rows: CursorUmbrellaRow[] = []; + for (const [baseId, capability] of Object.entries(CURSOR_CAPABILITIES)) { + const spec = capability.variants[capability.defaultVariant]; + if (!spec || spec.quarantined) continue; + rows.push({ + id: baseId, + efforts: spec.levels, + window: capability.window, + maxModeVerified: capability.maxModeVerified === true, + }); + } + return rows; +} diff --git a/src/adapters/cursor/cursor-errors.ts b/src/adapters/cursor/cursor-errors.ts index 33ded8dc7c..e4d5682a3e 100644 --- a/src/adapters/cursor/cursor-errors.ts +++ b/src/adapters/cursor/cursor-errors.ts @@ -241,6 +241,21 @@ export function classifyCursorError(message: string, sizeContext?: CursorSizeCon lower.includes("access denied") ) return "Cursor authentication failed"; + // gRPC FAILED_PRECONDITION is deterministic and non-retryable (unlike UNAVAILABLE): + // the backend rejected the call because the account/plan state does not allow it — + // seen live when a plan-gated model (e.g. claude-fable-5) runs on a plan without it. + // Leaving it as "Cursor upstream error" (502) made clients retry it as overload. + // + // This MUST precede the overload keywords. The explicit gRPC status code is a + // structured signal from the backend; the keywords are inference over free text. A + // plan-gated rejection routinely reads "failed_precondition: model unavailable for + // this plan", which matched "unavailable" first and came back as a retryable + // overload — the exact misclassification this branch was added to stop. Checking the + // code first lets the deterministic signal win over the words around it. + if (lower.includes("failed_precondition") || lower.includes("failed precondition")) { + return "Cursor invalid request"; + } + if ( lower.includes("unavailable") || lower.includes("overloaded") || diff --git a/src/adapters/cursor/discovery.ts b/src/adapters/cursor/discovery.ts index 15f529fdb0..1b0709fd82 100644 --- a/src/adapters/cursor/discovery.ts +++ b/src/adapters/cursor/discovery.ts @@ -5,6 +5,7 @@ import { cursorWireModelIdWithEffort, CURSOR_THINKING_MODEL_IDS, } from "./effort-map"; +import { parseCursorVariantId } from "./catalog"; export interface CursorModelInfo { id: string; @@ -76,9 +77,16 @@ function stripCursorWirePrefix(id: string): string { * ordinary `{base}-{effort}` form, or Cursor's current `{base-without-fast}-{effort}-fast` form. */ export function isCursorModelAvailableForAccount(modelId: string, liveIds: readonly string[]): boolean { + // Umbrella matching (devlog 260828_cursor_umbrella_catalog): a live suffix + // id counts toward its BASE — any variant dimension (thinking/fast/effort) + // proves the account can reach the umbrella. Unknown ids fall back to the + // legacy exact/suffix comparison so non-cataloged rows keep matching. + const parsedTarget = parseCursorVariantId(modelId); return liveIds.some(raw => { const id = stripCursorWirePrefix(raw); if (id === modelId) return true; + const parsedLive = parseCursorVariantId(id); + if (parsedLive.known && parsedTarget.known && parsedLive.baseId === parsedTarget.baseId) return true; for (const effort of CANONICAL_EFFORT_SUFFIXES) { if ( id === `${modelId}-${effort}` || @@ -244,15 +252,13 @@ export function filterCursorConfiguredModelsByLiveDiscovery = new Set([ - "claude-opus-5", -]); +export const CURSOR_KNOWN_UNCALLABLE_MODEL_IDS: ReadonlySet = new Set([]); export const CURSOR_STATIC_MODELS: readonly CursorModelInfo[] = normalizeCursorModels([ // Context windows and the model lineup mirror Cursor's public models/pricing docs plus the jawcode @@ -265,26 +271,26 @@ export const CURSOR_STATIC_MODELS: readonly CursorModelInfo[] = normalizeCursorM // gemini/grok/kimi-k2.7/gpt-5-mini are reasoning models in the SOT but are sent bare (no tier picker). ...CURSOR_ROUTER_MODEL_IDS.map(id => ({ id, contextWindow: CONTEXT_200K, supportsReasoningEffort: false })), - { id: "claude-sonnet-5", contextWindow: CONTEXT_200K, supportsReasoningEffort: true }, + // Umbrella seed (devlog 260828_cursor_umbrella_catalog): one row per BASE + // model. Thinking merges into the base (the resolver routes the thinking + // variant); fast / thinking-fast / -1m stay routable as aliases but add no + // rows. Windows follow CURSOR_CAPABILITIES where the base is cataloged. + { id: "claude-sonnet-5", contextWindow: CONTEXT_1M, supportsReasoningEffort: true }, { id: "claude-4-sonnet", contextWindow: CONTEXT_200K }, { id: "claude-4-sonnet-1m", contextWindow: CONTEXT_1M }, { id: "claude-4.5-haiku", contextWindow: CONTEXT_200K }, { id: "claude-4.5-sonnet", contextWindow: CONTEXT_200K }, { id: "claude-4.5-opus", contextWindow: CONTEXT_200K, supportsReasoningEffort: true }, - { id: "claude-4.6-opus", contextWindow: CONTEXT_200K, supportsReasoningEffort: true }, - { id: "claude-4.6-sonnet", contextWindow: CONTEXT_200K, supportsReasoningEffort: true }, - { id: "claude-opus-4-7", contextWindow: CONTEXT_200K, supportsReasoningEffort: true }, - // Opus Fast families: live GetUsableModels (260822) lists ONLY effort-suffixed wire ids - // ({base-without-fast}-{effort}-fast; the bare id returns not_found), so every entry - // carries a tier picker. Live-verified: claude-opus-4-8-high-fast completed a turn. - // Tiers per the 260822 dump (devlog 260822_senpi_cursor_transfer/300). - { id: "claude-opus-4-7-fast", contextWindow: CONTEXT_200K, supportsReasoningEffort: true }, - { id: "claude-opus-4-8-fast", contextWindow: CONTEXT_200K, supportsReasoningEffort: true }, - { id: "claude-opus-4-8", contextWindow: CONTEXT_200K, supportsReasoningEffort: true }, - // claude-opus-5 (bare) removed from the seed: GetUsableModels lists it but every Run returns - // not_found (quarantined via CURSOR_KNOWN_UNCALLABLE_MODEL_IDS; -fast/-thinking families stay). - { id: "claude-opus-5-fast", contextWindow: CONTEXT_200K, supportsReasoningEffort: true }, - { id: "claude-fable-5", contextWindow: CONTEXT_200K, supportsReasoningEffort: true }, + { id: "claude-4.6-opus", contextWindow: CONTEXT_1M, supportsReasoningEffort: true }, + { id: "claude-4.6-sonnet", contextWindow: CONTEXT_1M, supportsReasoningEffort: true }, + { id: "claude-opus-4-7", contextWindow: CONTEXT_1M, supportsReasoningEffort: true }, + { id: "claude-opus-4-8", contextWindow: CONTEXT_1M, supportsReasoningEffort: true }, + // claude-opus-5: regular variant is quarantined (not_found on every Run) but + // the umbrella row routes the THINKING variant, which is live — so the base + // row returns to the seed under the umbrella (resolver never sends the + // quarantined regular wire id for the bare slug). + { id: "claude-opus-5", contextWindow: CONTEXT_1M, supportsReasoningEffort: true }, + { id: "claude-fable-5", contextWindow: CONTEXT_1M, supportsReasoningEffort: true }, { id: "composer-1", contextWindow: CONTEXT_200K }, { id: "composer-2.5", contextWindow: CONTEXT_200K }, @@ -301,17 +307,6 @@ export const CURSOR_STATIC_MODELS: readonly CursorModelInfo[] = normalizeCursorM { id: "gemini-3.6-flash", contextWindow: CONTEXT_GEMINI, supportsReasoningEffort: true }, { id: "gemini-3.7-flash", contextWindow: CONTEXT_GEMINI, supportsReasoningEffort: true }, - // Explicit-thinking variants (260825 live roster). Exposed as first-class ids the same way the - // Opus Fast families were in 831810c13: `isCursorModelAvailableForAccount` matches a base id - // against `{base}`, `{base}-{effort}` and the family's wire form, and none of those ever - // matched a `-thinking` id, so every one of these was invisible in the routed catalog. - // Suffix ORDER differs per family; `cursorWireModelIdWithEffort` owns that mapping. - ...CURSOR_THINKING_MODEL_IDS.map(id => ({ - id, - contextWindow: CONTEXT_200K, - supportsReasoningEffort: cursorModelHasEffortTiers(id), - })), - { id: "gpt-5-codex", contextWindow: CONTEXT_272K }, { id: "gpt-5-fast", contextWindow: CONTEXT_272K }, { id: "gpt-5-mini", contextWindow: CONTEXT_272K }, @@ -344,17 +339,15 @@ export const CURSOR_STATIC_MODELS: readonly CursorModelInfo[] = normalizeCursorM { id: "kimi-k2.7-code", contextWindow: CONTEXT_262K }, // kimi-k3: cursor.com/docs/models/kimi-k3; account-verified via GetUsableModels (2026-07-28) — // ships only as effort-suffixed kimi-k3-{low,high,max}, so the tier picker is exposed. - { id: "kimi-k3", contextWindow: CONTEXT_262K, supportsReasoningEffort: true }, - // kimi-k3-1m: synthetic ultra/Max-Mode picker variant (CURSOR_ULTRA_1M_MODEL_IDS) — wire sends - // kimi-k3- with maxMode=true; 1M context user-verified live on the Ultra plan - // (devlog 260826_cursor_responses_gap/025). inferCursorContextWindow maps "1m" ids to 1M. - { id: "kimi-k3-1m", contextWindow: CONTEXT_1M, supportsReasoningEffort: true }, + // kimi-k3 folds the old synthetic kimi-k3-1m row into the umbrella: the base + // is maxModeVerified (user-verified 1M on the Ultra plan, devlog 260826/025), + // so the ultra effort rung arms Max Mode on the wire and the separate picker + // row is gone. cursor/kimi-k3-1m stays routable as an alias. + { id: "kimi-k3", contextWindow: CONTEXT_1M, supportsReasoningEffort: true }, { id: "grok-4.5", contextWindow: 500_000, supportsReasoningEffort: true }, - { id: "grok-4.5-fast", contextWindow: 500_000, supportsReasoningEffort: true }, // 260813 preemptive: grok-4.6 seeded ahead of Cursor's lineup update (mirrors grok-4.5). { id: "grok-4.6", contextWindow: 500_000, supportsReasoningEffort: true }, - { id: "grok-4.6-fast", contextWindow: 500_000, supportsReasoningEffort: true }, ]); export function cursorModelIds(models: readonly CursorModelInfo[] = CURSOR_STATIC_MODELS): string[] { diff --git a/src/adapters/cursor/envelope-echo.ts b/src/adapters/cursor/envelope-echo.ts index ac7ec429c3..ffaf3df193 100644 --- a/src/adapters/cursor/envelope-echo.ts +++ b/src/adapters/cursor/envelope-echo.ts @@ -14,6 +14,14 @@ const ECHO_MARKERS = ["[Tool Result]", "[Tool Error]", "[tool_result]"] as const; const MAX_SNIFF_BYTES = 40; +/** Mid-stream observer: max leading whitespace on a line before matching disarms. */ +const MAX_MIDSTREAM_LINE_INDENT = 128; +/** Mid-stream observer: post-marker window watched for call-id corruption. */ +const MIDSTREAM_CORRUPTION_WINDOW = 512; +/** Mid-stream observer: cumulative scan cap (UTF-16 code units, checked between feeds). */ +export const MAX_MIDSTREAM_SCAN_LENGTH = 512 * 1024; +/** Mid-stream observer: findings retained per turn. */ +const MAX_MIDSTREAM_FINDINGS = 8; const MAX_ROUTING_COMMENTARY_BYTES = 512; /** Aggregate quarantine cap: past this, flush and disarm. */ const MAX_HOLD_BYTES = 8 * 1024; @@ -43,6 +51,126 @@ export type EchoSnifferDecision = | { kind: "flush" } | { kind: "echo"; marker: string }; +export interface MidstreamEchoFinding { + marker: string; + /** UTF-16 offset of the marker's line start within the turn's full text. */ + offset: number; + callIdCorrupt: boolean; +} + +/** + * Diagnostic-only mid-stream envelope-echo observer (devlog 260828 F1/F2). + * + * The prefix sniffer only watches the first ~40 bytes of a turn, but live + * probing caught grok-4.6 echoing "[Tool Result]" envelope blocks in the + * MIDDLE of an agent message — after legitimate leading text — one of them + * carrying a whitespace-spliced call-id ("fc_x mar-y" instead of "fc_x-y"). + * Deltas at that point have already reached the client, so this observer + * never throws and never withholds output: it records findings so the + * adapter can emit a structured diagnostic at turn end. Only fixed marker + * enums, numeric offsets, and corruption booleans are retained — never + * content bytes. + */ +export class CursorMidstreamEchoObserver { + private lineBuffer = ""; + private lineStartOffset = 0; + private totalLength = 0; + private disarmed = false; + private lineDisarmed = false; + private corruptionWatch: { finding: MidstreamEchoFinding; remaining: number; window: string } | undefined; + private readonly recorded: MidstreamEchoFinding[] = []; + + feed(textDelta: string): void { + if (this.disarmed && !this.corruptionWatch) return; + let index = 0; + while (index < textDelta.length) { + const newline = textDelta.indexOf("\n", index); + const segment = newline === -1 ? textDelta.slice(index) : textDelta.slice(index, newline); + if (this.corruptionWatch) this.watchCorruption(segment + (newline === -1 ? "" : "\n")); + if (!this.disarmed && !this.lineDisarmed && segment.length > 0) { + this.lineBuffer += segment; + if (this.lineBuffer.length > MAX_MIDSTREAM_LINE_INDENT + 32) { + // Bound per-line work: nothing beyond the indent cap + longest marker can match. + this.lineDisarmed = !this.lineMatchesPrefixSoFar(); + this.lineBuffer = this.lineBuffer.slice(0, MAX_MIDSTREAM_LINE_INDENT + 32); + } + this.checkLine(); + } + if (newline === -1) break; + this.lineBuffer = ""; + this.lineDisarmed = false; + this.lineStartOffset = this.totalLength + newline + 1; + index = newline + 1; + } + this.totalLength += textDelta.length; + if (this.totalLength > MAX_MIDSTREAM_SCAN_LENGTH) this.disarmed = true; + } + + findings(): readonly MidstreamEchoFinding[] { + if (this.corruptionWatch) { + this.settleCorruption(); + } + return this.recorded; + } + + private lineMatchesPrefixSoFar(): boolean { + const probe = this.lineBuffer.replace(/^[ \t]*/, ""); + return ECHO_MARKERS.some(marker => probe.startsWith(marker) || marker.startsWith(probe)); + } + + private checkLine(): void { + const indentMatch = /^[ \t]*/.exec(this.lineBuffer); + const indent = indentMatch ? indentMatch[0].length : 0; + if (indent > MAX_MIDSTREAM_LINE_INDENT) { + this.lineDisarmed = true; + return; + } + const probe = this.lineBuffer.slice(indent); + for (const marker of ECHO_MARKERS) { + if (probe.startsWith(marker)) { + // The prefix sniffer owns the very start of the turn; only offsets past + // its window count as mid-stream. + if (this.lineStartOffset === 0) { + this.lineDisarmed = true; + return; + } + const finding: MidstreamEchoFinding = { + marker, + offset: this.lineStartOffset, + callIdCorrupt: false, + }; + this.corruptionWatch = { finding, remaining: MIDSTREAM_CORRUPTION_WINDOW, window: "" }; + this.lineDisarmed = true; + return; + } + } + if (!ECHO_MARKERS.some(marker => marker.startsWith(probe)) && probe.length > 0) { + this.lineDisarmed = true; + } + } + + private watchCorruption(text: string): void { + const watch = this.corruptionWatch; + if (!watch) return; + const take = Math.min(watch.remaining, text.length); + watch.window += text.slice(0, take); + watch.remaining -= take; + if (watch.remaining <= 0) this.settleCorruption(); + } + + private settleCorruption(): void { + const watch = this.corruptionWatch; + if (!watch) return; + const window = watch.window; + watch.finding.callIdCorrupt = + /fc_[0-9a-f]+[ \t]+mar-/.test(window) + || /call_id: \S+[ \t]+\S+_0\b/.test(window); + if (this.recorded.length < MAX_MIDSTREAM_FINDINGS) this.recorded.push(watch.finding); + // Window text is discarded here; only booleans/offsets survive. + this.corruptionWatch = undefined; + } +} + /** * Incremental envelope-prefix sniffer. Leading whitespace is tolerated so a * marker copied after a newline is still caught. diff --git a/src/adapters/cursor/request-builder.ts b/src/adapters/cursor/request-builder.ts index e99791134a..e73d5e98ea 100644 --- a/src/adapters/cursor/request-builder.ts +++ b/src/adapters/cursor/request-builder.ts @@ -12,7 +12,7 @@ import type { CursorRequestMessage, CursorRequestedModelParameter, CursorRunRequ import { cursorCheckpointModelAffinityId, cursorWireModelSelection, type CursorRoutingLevel } from "./discovery"; import { cursorUltraBaseModelId } from "./discovery"; import { decodeCursorCallId } from "./call-id"; -import { cursorEffortSuffix, cursorRequestWireModelIdWithEffort } from "./effort-map"; +import { cursorGrokFastSelection, resolveCursorSelection } from "./catalog"; import { cursorMcpToolEncodedSize, cursorMcpToolsEncodedSize, @@ -192,25 +192,32 @@ function normalizeCursorModelId(modelId: string, reasoning?: string): { routingLevel?: CursorRoutingLevel; maxMode?: boolean; } { - // Synthetic ultra (-1m) picker rows resolve to their wire base with Max Mode on - // (devlog 260826 070); the marker never reaches the wire. - const ultraBase = cursorUltraBaseModelId(modelId); - const selection = cursorWireModelSelection(ultraBase ?? modelId); - const maxMode = ultraBase !== undefined ? { maxMode: true } : {}; + // Router ids (auto / auto-) keep their dedicated wire selection. + const selection = cursorWireModelSelection(modelId); + if (selection.routingLevel !== undefined || selection.modelId === "default") return selection; + // Umbrella catalog resolution (devlog 260828_cursor_umbrella_catalog): one + // resolver owns effort composition, variant dimensions, the synthetic -1m + // marker (ultra -> Max Mode, evidence-gated), and the cursor- wire prefix. const id = selection.modelId; - const suffix = cursorEffortSuffix(id, reasoning); - if ((id === "grok-4.5-fast" || id === "grok-4.6-fast") && suffix) { + // Grok Fast stays parameterized: current Cursor clients send the base id + // plus effort/fast parameters instead of the flattened -fast id. + const grokFast = cursorGrokFastSelection(id, reasoning); + if (grokFast) { return { ...selection, - ...maxMode, - modelId: id.slice(0, -"-fast".length), + modelId: grokFast.wireBaseId, requestedModelParameters: [ - { id: "effort", value: suffix }, + { id: "effort", value: grokFast.effort }, { id: "fast", value: "true" }, ], }; } - return { ...selection, ...maxMode, modelId: suffix ? cursorRequestWireModelIdWithEffort(id, suffix) : id }; + const resolved = resolveCursorSelection(id, reasoning); + return { + ...selection, + ...(resolved.maxMode ? { maxMode: true } : {}), + modelId: resolved.wireId, + }; } function contentPartToText(part: OcxContentPart | OcxAssistantContentPart): string | undefined { diff --git a/src/adapters/cursor/tool-definitions.ts b/src/adapters/cursor/tool-definitions.ts index b0f2f26cf6..ae9bfcec4b 100644 --- a/src/adapters/cursor/tool-definitions.ts +++ b/src/adapters/cursor/tool-definitions.ts @@ -3,6 +3,7 @@ import { ValueSchema } from "@bufbuild/protobuf/wkt"; import type { OcxRequestOptions, OcxTool } from "../../types"; import { namespacedToolName, toolChoiceAliases } from "../../types"; import { McpToolDefinitionSchema, McpToolsSchema, type McpToolDefinition } from "./gen/agent_pb"; +import { CODE_MODE_RESULT_ECHO_SENTENCE } from "../exec-tool-result-normalize"; export const OCX_RESPONSES_TOOL_PROVIDER = "opencodex-responses"; export const CODEX_EXEC_COMMAND_TOOL = "exec_command"; @@ -654,7 +655,7 @@ export function buildCursorToolGuidanceSystemNote( ? `\`${CODEX_UNIFIED_EXEC_TOOL}\` is Codex code mode: its body is JavaScript evaluated in a V8 isolate, not a shell command and not Node. Shell, file edits, and MCP are nested helpers called INSIDE that body as \`await tools.(...)\`, for example \`await tools.exec_command({cmd: \"ls\"})\`. Read the tool description and the isolate global \`ALL_TOOLS\` (not \`tools.ALL_TOOLS\`) for helpers this turn provides; absence from the top-level catalog or from \`exec\`'s description is not absence. Those nested helpers are not themselves top-level tools, so do not call \`exec_command\` or \`shell_command\` at the top level here${codeModeOtherTopLevelNames.length > 0 ? `; every other tool this turn lists, including ${quotedNames(codeModeOtherTopLevelNames)}, remains callable at the top level as usual` : ""}. Nested \`tools.apply_patch(input)\` is host-executed: the string must begin exactly with \`*** Begin Patch\` and end with \`*** End Patch\` (no trailing \`***\` on those lines). OpenCodex does not rewrite JavaScript inside exec, so a decorated \`*** Begin Patch ***\` envelope is rejected by Codex before the file is touched.` : undefined, codeMode - ? "In code mode the isolate returns nothing on its own: call `text(...)` (or `notify(...)`) on any value you need to see, or the call completes with empty output. There is no `require`, no `module`, and no filesystem or network globals; reach the host only through the nested helpers." + ? CODE_MODE_RESULT_ECHO_SENTENCE + " There is no `require`, no `module`, and no filesystem or network globals; reach the host only through the nested helpers." : undefined, codeMode ? "NEVER attempt Cursor-native Shell, Read, Grep, List, or any tool absent from the catalog — they are not executed in this environment and every probe wastes a turn. The exec code cell (with its nested helpers) is the ONLY execution surface; go to it directly on the FIRST attempt and do not narrate switching surfaces." diff --git a/src/adapters/cursor/tool-result-normalize.ts b/src/adapters/cursor/tool-result-normalize.ts index c89e247e9a..997ef56fea 100644 --- a/src/adapters/cursor/tool-result-normalize.ts +++ b/src/adapters/cursor/tool-result-normalize.ts @@ -9,6 +9,23 @@ * dropping images oldest-first — see toolCallStep in protobuf-request.ts). */ +import { + EMPTY_EXEC_OUTPUT_MESSAGE, + EMPTY_EXEC_OUTPUT_REGEX, + FAILED_EXEC_OUTPUT_MESSAGE, + FAILED_EXEC_OUTPUT_REGEX, + isCodexExecBridgeTool, +} from "../exec-tool-result-normalize"; + +/** + * Cursor treats a failed-but-empty wrapper as an empty result too (its Computer Use branch marks + * such results `isError` separately). The shared success regex deliberately excludes + * `Script failed`, so restore that arm here rather than widening the shared one. + */ +function isEmptyOrFailedExecWrapper(text: string): boolean { + return EMPTY_EXEC_OUTPUT_REGEX.test(text) || FAILED_EXEC_OUTPUT_REGEX.test(text); +} + const COMPUTER_USE_TOOL_NAMES = new Set([ "node_repl", "node_repl__js", @@ -29,31 +46,6 @@ function isNodeReplOrComputerUseTool(toolName?: string, toolNamespace?: string): return lower.startsWith("mcp__node_repl") || lower.startsWith("mcp__computer_use"); } -/** - * Codex exec / shell-bridge tool names (flat and MCP-prefixed display aliases). An empty result - * here is almost always a code-mode cell that never called text()/notify() — the cursor model - * reads the blank [tool_result], concludes prior results were lost, and spirals into - * re-orientation retries (devlog 260826_cursor_responses_gap, live subagent transcripts). - */ -function isCodexExecBridgeTool(toolName?: string, toolNamespace?: string): boolean { - if (toolNamespace && toolNamespace.includes("opencodex-responses")) return true; - if (!toolName) return false; - const lower = toolName.toLowerCase(); - return ( - lower === "exec" - || lower === "exec_command" - || lower === "shell_command" - // Codex CLI/desktop native tool names: the multi-round "이전 출력이 비어 있어 처음부터" - // restart loop reproduced via codex exec because `shell` was not in this set - // (devlog 260826 gap-8 QA round 2). - || lower === "shell" - || lower === "local_shell" - || lower === "container.exec" - || lower.startsWith("mcp_opencodex-responses_") - || lower.startsWith("mcp__opencodex-responses__") - ); -} - /** Failure states the Computer Use / node_repl runtime reports as PLAIN TEXT inside a non-error result. */ const RUNTIME_FAILURE_GUIDANCE: ReadonlyArray<{ marker: string; guidance: string }> = [ { @@ -74,9 +66,6 @@ const RUNTIME_FAILURE_GUIDANCE: ReadonlyArray<{ marker: string; guidance: string }, ]; -/** Matches exec wrappers whose only payload is an empty-output marker. */ -const EMPTY_EXEC_OUTPUT_REGEX = /^(?:(?:Script completed|Script failed|Command finished|Execution finished)[^\n]*\n+)?(?:Wall time[^\n]*\n+)?(?:Output:\s*)?(?:)?\s*$/; - export interface NormalizedToolResultText { text: string; isError: boolean; @@ -98,16 +87,19 @@ export function normalizeCursorToolResultText( ): NormalizedToolResultText { const isError = options.isError === true; const computerUse = isNodeReplOrComputerUseTool(options.toolName, options.toolNamespace); - if (computerUse && EMPTY_EXEC_OUTPUT_REGEX.test(text.trim())) { + if (computerUse && isEmptyOrFailedExecWrapper(text.trim())) { return { text: "[empty output: the tool ran but produced no stdout or return value. Verify application state with get_app_state, or make the script emit output.]", isError: true, changed: true, }; } - if (isCodexExecBridgeTool(options.toolName, options.toolNamespace) && EMPTY_EXEC_OUTPUT_REGEX.test(text.trim())) { + if (isCodexExecBridgeTool(options.toolName, options.toolNamespace) && isEmptyOrFailedExecWrapper(text.trim())) { return { - text: "[empty output: the exec cell completed but emitted nothing. This is NOT lost context and NOT a blocked tool — in code mode call text(...) or notify(...) on any value you need to see (a bare await tools.exec_command(...) is not echoed automatically); in shell mode the command simply printed nothing. Do not re-run the same call expecting different output.]", + // A `Script failed` wrapper is empty but NOT a success: reporting it as an empty success + // would erase the only failure signal. Text classification stays separate from Cursor's + // isError policy, which the Computer Use branch above owns. + text: FAILED_EXEC_OUTPUT_REGEX.test(text.trim()) ? FAILED_EXEC_OUTPUT_MESSAGE : EMPTY_EXEC_OUTPUT_MESSAGE, isError: false, changed: true, }; diff --git a/src/adapters/exec-tool-result-normalize.ts b/src/adapters/exec-tool-result-normalize.ts new file mode 100644 index 0000000000..f06a07c411 --- /dev/null +++ b/src/adapters/exec-tool-result-normalize.ts @@ -0,0 +1,99 @@ +/** + * Provider-neutral empty-exec-output normalization. + * + * A code-mode `exec` cell that never calls `text()`/`notify()` returns nothing: the last + * expression value is NOT echoed automatically. The routed model reads a blank tool result, + * concludes its earlier output was lost, and burns turns re-running the same call or restarting + * the task from scratch. Naming that state explicitly is what breaks the loop. + * + * This module owns the shared detection so every adapter reports the same thing. Cursor keeps its + * own wrapper (`normalizeCursorToolResultText`) for Computer Use precedence and isError policy; + * Kiro consumes this helper directly. + */ + +/** + * Matches exec wrappers whose only payload is an empty-output marker. + * + * `Script failed` is deliberately NOT in this set. A failed cell with no captured output is still + * a FAILURE, and the success guidance below ("not a blocked tool", "do not re-run") would erase the + * only signal that anything went wrong — reachable through Responses history, where + * `function_call_output` is parsed with `isError: false`. Cursor keeps its own broader regex for + * Computer Use, where a failed wrapper is separately marked `isError`. + */ +export const EMPTY_EXEC_OUTPUT_REGEX = /^(?:(?:Script completed|Command finished|Execution finished)[^\n]*\n+)?(?:Wall time[^\n]*\n+)?(?:Output:\s*)?(?:)?\s*$/; + +/** Wrapper for a cell that FAILED without emitting output: empty, but not a success. */ +export const FAILED_EXEC_OUTPUT_REGEX = /^Script failed[^\n]*\n*(?:Wall time[^\n]*\n*)?(?:Output:\s*)?(?:)?\s*$/; + +/** Guidance for a failed cell whose output was empty: the failure must survive normalization. */ +export const FAILED_EXEC_OUTPUT_MESSAGE = + "[exec failed with no captured output: the cell raised before emitting anything. This is a real failure, not an empty success — inspect the call for a thrown error or syntax problem before retrying.]"; + +/** + * The guidance itself. Worded to close all three wrong conclusions a model draws from a blank + * result: that context was lost, that the tool is blocked, and that retrying will differ. + */ +export const EMPTY_EXEC_OUTPUT_MESSAGE = + "[empty output: the exec cell completed but emitted nothing. This is NOT lost context and NOT a blocked tool — in code mode call text(...) or notify(...) on any value you need to see (a bare await tools.exec_command(...) is not echoed automatically); in shell mode the command simply printed nothing. Do not re-run the same call expecting different output.]"; + +/** + * The SAME rule stated BEFORE the first call, for the code-mode tool-catalog nudge. + * + * `EMPTY_EXEC_OUTPUT_MESSAGE` above is a repair: it fires only after a model has already spent a + * call and read a blank result. That recovers the turn but cannot prevent the wasted round trip, + * and the model still has to guess whether its command failed or its output was merely dropped. + * Stating the echo rule up front removes the failure instead of explaining it afterwards. + * + * Kept beside the recovery text on purpose: the two are one pair guarding one defect, and wording + * that drifts apart is how a model gets told two different things about the same isolate. + */ +export const CODE_MODE_RESULT_ECHO_SENTENCE = + "Nothing in the isolate is echoed automatically: a bare trailing `await tools.(...)` or final expression value is DISCARDED, and the cell reports empty output. Pass anything you need to read to `text(...)` (or `notify(...)`) in the same cell — for example `text(JSON.stringify(await tools.exec_command({cmd: \"ls\"})))` — and treat an empty result as your own missing `text(...)` call rather than a failed command or lost context."; + +/** + * Codex exec / shell-bridge tool names (flat and MCP-prefixed display aliases). An empty result + * here is almost always a code-mode cell that never called text()/notify(). + */ +export function isCodexExecBridgeTool(toolName?: string, toolNamespace?: string): boolean { + if (toolNamespace && toolNamespace.includes("opencodex-responses")) return true; + if (!toolName) return false; + const lower = toolName.toLowerCase(); + return ( + lower === "exec" + || lower === "exec_command" + || lower === "shell_command" + // Codex CLI/desktop native tool names: the multi-round "이전 출력이 비어 있어 처음부터" + // restart loop reproduced via codex exec because `shell` was not in this set + // (devlog 260826 gap-8 QA round 2). + || lower === "shell" + || lower === "local_shell" + || lower === "container.exec" + || lower.startsWith("mcp_opencodex-responses_") + || lower.startsWith("mcp__opencodex-responses__") + ); +} + +/** True when this result is an exec-bridge call that produced no usable output. */ +export function isEmptyExecToolResult( + text: string, + options: { toolName?: string; toolNamespace?: string } = {}, +): boolean { + return isCodexExecBridgeTool(options.toolName, options.toolNamespace) + && EMPTY_EXEC_OUTPUT_REGEX.test(text.trim()); +} + +/** + * Returns the guidance text when this is an empty exec-bridge result, else `undefined` so the + * caller keeps its own fallback. Undefined rather than the original text: an adapter must be able + * to tell "not my case" from "normalized to the same string". + */ +export function normalizeEmptyExecToolResultText( + text: string, + options: { toolName?: string; toolNamespace?: string } = {}, +): string | undefined { + if (!isCodexExecBridgeTool(options.toolName, options.toolNamespace)) return undefined; + const trimmed = text.trim(); + // Failure first: a failed wrapper must never be described as an empty success. + if (FAILED_EXEC_OUTPUT_REGEX.test(trimmed)) return FAILED_EXEC_OUTPUT_MESSAGE; + return EMPTY_EXEC_OUTPUT_REGEX.test(trimmed) ? EMPTY_EXEC_OUTPUT_MESSAGE : undefined; +} diff --git a/src/adapters/google-antigravity-replay.ts b/src/adapters/google-antigravity-replay.ts index 514008a983..9e3453aa59 100644 --- a/src/adapters/google-antigravity-replay.ts +++ b/src/adapters/google-antigravity-replay.ts @@ -512,10 +512,10 @@ export function antigravityReplaySessionKeysForTests(): string[] { function extractSignature(part: Record): string | undefined { const direct = part.thoughtSignature ?? part.thought_signature; - if (typeof direct === "string" && direct.length >= MIN_SIGNATURE_LEN) return direct; + if (typeof direct === "string" && direct.length >= MIN_SIGNATURE_LEN && direct !== THOUGHT_SIGNATURE_BYPASS) return direct; const extra = part.extra_content as { google?: { thought_signature?: unknown } } | undefined; const nested = extra?.google?.thought_signature; - if (typeof nested === "string" && nested.length >= MIN_SIGNATURE_LEN) return nested; + if (typeof nested === "string" && nested.length >= MIN_SIGNATURE_LEN && nested !== THOUGHT_SIGNATURE_BYPASS) return nested; return undefined; } @@ -624,6 +624,75 @@ export function antigravityUsesReplayCache(model: string): boolean { return !/claude/i.test(model); } +/** + * Gemini 3 rejects a turn whose FIRST functionCall part carries no thought signature. When + * neither the wire metadata nor the replay cache can supply a real one, this is the official + * validator-bypass token. + */ +const THOUGHT_SIGNATURE_BYPASS = "skip_thought_signature_validator"; + +/** + * True when the model speaks the Gemini wire dialect that requires a thought signature on the + * first functionCall of a turn — and therefore accepts the validator-bypass sentinel. + * + * Deliberately NOT `antigravityUsesReplayCache`. That predicate is broad on purpose (every + * non-Claude model participates in signature replay), and reusing it for the sentinel is how a + * Gemini-only control token was observed being injected into `gpt-oss-120b-medium`. Replaying a + * signature upstream gave us is harmless for any model; *fabricating* a Gemini token is not. + * + * The identity must be REDUCED to its model component before matching, not scanned whole. The + * Vertex replay key is built in `src/adapters/google.ts` as + * `vertex:::`, and the project id is operator-chosen: a project + * named `gemini-prod` made a whole-string scan return true for + * `vertex:gemini-prod:global:gpt-oss-120b`, arming the Gemini-only sentinel for a non-Gemini + * model — the exact class of defect this predicate exists to prevent, reintroduced one layer up. + * + * So: take the last `:` segment for a Vertex identity, then the last `/` segment for a + * namespaced id (`google/gemini-3-pro`), and match only that. The trailing `[-.\d]` keeps + * `geminibot` and `my-gemini-clone` out. A model outside this set that genuinely needs the + * sentinel must arrive with a captured accepted CCA contract, not by widening this predicate. + */ +export function antigravitySupportsThoughtSignatureSentinel(model: string): boolean { + const afterTransport = model.slice(model.lastIndexOf(":") + 1); + const wireModel = afterTransport.slice(afterTransport.lastIndexOf("/") + 1); + return /^gemini[-.\d]/i.test(wireModel); +} + +/** + * Ensure every model turn's FIRST functionCall carries a thought signature, injecting the + * validator-bypass sentinel only where one is genuinely absent. + * + * Split out of `applyAntigravityReplay` on purpose. Replay answers "what did upstream already + * tell us about this call", and its absence of a signature is meaningful — 18 assertions in the + * suite read `thoughtSignature === undefined` as "the cache did not match", covering eviction, + * TTL expiry, oversize refusal and clear-on-invalid. Folding a fabricated token into that + * function would overwrite the very signal those tests read. Keeping the sentinel as its own + * pass means a cache miss still looks like a cache miss. + * + * Three properties this must hold, each of which a naive presence-check gets wrong: + * - it decides from `extractSignature`, so a valid NESTED + * `extra_content.google.thought_signature` counts as signed (no competing sentinel) and a + * present-but-too-short value does not (the fallback still fires); + * - it looks at the FIRST functionCall only, so a later sibling receiving a cached signature + * cannot vote away the sentinel the first call requires; + * - it is gated on the Gemini wire dialect, not on replay-cache participation. + */ +export function applyAntigravityThoughtSignatureFallback(model: string, contents: unknown[]): unknown[] { + if (!antigravitySupportsThoughtSignatureSentinel(model) || !Array.isArray(contents)) return contents; + for (const rawContent of contents as { role?: string; parts?: unknown[] }[]) { + if (!rawContent || typeof rawContent !== "object" || rawContent.role !== "model") continue; + if (!Array.isArray(rawContent.parts)) continue; + for (const rawPart of rawContent.parts) { + if (!rawPart || typeof rawPart !== "object") continue; + const part = rawPart as Record; + if (!part.functionCall) continue; + if (!extractSignature(part)) part.thoughtSignature = THOUGHT_SIGNATURE_BYPASS; + break; + } + } + return contents; +} + /** * Observe a parsed CCA chunk's `candidates[0].content.parts` and record thought signatures keyed by * the functionCall identity (name + args). Accumulates across the whole session so a sequential diff --git a/src/adapters/google-antigravity-wire.ts b/src/adapters/google-antigravity-wire.ts index b4b0ca3176..8b208aa644 100644 --- a/src/adapters/google-antigravity-wire.ts +++ b/src/adapters/google-antigravity-wire.ts @@ -29,6 +29,11 @@ export const ANTIGRAVITY_REQUEST_UA = antigravityUserAgent(); */ export function isLikelyRealThoughtSignature(sig: string | undefined): boolean { if (typeof sig !== "string" || sig.length < 16) return false; + // The validator-bypass sentinel is something WE fabricate for outbound requests when no real + // signature exists. It is alphanumeric with underscores, so it would otherwise satisfy every + // check below and be re-ingested as genuine — cached, replayed, and eventually treated as + // evidence that a turn was signed. It is never a real signature. + if (sig === "skip_thought_signature_validator") return false; // Reject synthetic Responses/tool-call ids and Anthropic tool-use ids (`_` or `-` separators). if (/^(fc|ctc|tsc|call|msg|rs|resp|reasoning|item|ws|toolu|tool|func|function)[-_]/i.test(sig)) return false; // Real Gemini thought signatures are opaque base64/base64url blobs: only [A-Za-z0-9+/_=-]. diff --git a/src/adapters/google.ts b/src/adapters/google.ts index 78354e7fe5..d2f40a96e7 100644 --- a/src/adapters/google.ts +++ b/src/adapters/google.ts @@ -23,7 +23,13 @@ import { isVertexTruncatedTurn, vertexTruncationErrorMessage } from "./google-tr import { ANTIGRAVITY_REQUEST_UA, antigravitySessionId, isLikelyRealThoughtSignature, sanitizeAntigravityClaudeSignatures } from "./google-antigravity-wire"; import { compileGoogleWireBody } from "./google-wire-compiler"; import { identifyRoutedModel } from "./identity"; -import { antigravityUsesReplayCache, applyAntigravityReplay, clearAntigravityReplay, observeAntigravityReplay } from "./google-antigravity-replay"; +import { + antigravityUsesReplayCache, + applyAntigravityReplay, + applyAntigravityThoughtSignatureFallback, + clearAntigravityReplay, + observeAntigravityReplay, +} from "./google-antigravity-replay"; import { resolveAntigravityEffortWireModel } from "../providers/antigravity-models"; import { googleVertexLocationConfigError } from "../providers/google-vertex-location"; import { forgetThoughtSignatureForReplay, lookupReplayThoughtSignature } from "../responses/thought-signature-replay"; @@ -826,6 +832,10 @@ export function createGoogleAdapter(provider: OcxProviderConfig): ProviderAdapte } else { sanitizeAntigravityClaudeSignatures(contents); } + // After replay, not instead of it: a real signature always wins, and the sentinel only + // fills a first functionCall that replay could not sign. Outside the cache branch too, + // because the turn still needs a signature when no session was ever recorded. + applyAntigravityThoughtSignatureFallback(wireModelId, contents); // Claude-on-Antigravity rejects assistant-tail (model-tail in Gemini terms) histories // as prefill: "This model does not support assistant message prefill. The conversation // must end with a user message." Context compaction, previous_response_id expansion, @@ -870,6 +880,10 @@ export function createGoogleAdapter(provider: OcxProviderConfig): ProviderAdapte vertexReplaySession, (compiled.body as { contents: unknown[] }).contents, ); + applyAntigravityThoughtSignatureFallback( + vertexReplayModel, + (compiled.body as { contents: unknown[] }).contents, + ); } // Vertex AI: project/location endpoint with GCP ADC, or x-goog-api-key fast path. const apiKey = resolveVertexApiKey(provider.apiKey); diff --git a/src/adapters/kiro-constants.ts b/src/adapters/kiro-constants.ts index 4b3c709135..a4e52472cd 100644 --- a/src/adapters/kiro-constants.ts +++ b/src/adapters/kiro-constants.ts @@ -22,6 +22,18 @@ export const KIRO_COMPLETION_RETRY_MESSAGE = export const KIRO_TOOL_RESULT_CARRIER_MESSAGE = "The requested tool result is attached."; export const KIRO_EMPTY_TOOL_RESULT_MESSAGE = "The tool completed without textual output."; +/** + * Placeholder for the user turn Kiro requires after an assistant turn that ALREADY delivered its + * final answer. + * + * The protocol needs a trailing user turn, but the usual continuation/retry text instructs the + * model to keep working, which reopens a finished task and reads as a still-open goal. This states + * the delivered state and explicitly withholds a new request, so the turn stays structurally valid + * without asking for more work. + */ +export const KIRO_ANSWER_DELIVERED_MESSAGE = + "The previous final answer was delivered to the user and that task is closed. No new request has been made yet. Do not repeat, revise, or continue that work; wait for the user's next instruction."; + export const KIRO_COMPLETION_INSTRUCTIONS = `When tools are available, ordinary assistant text is mid-task commentary and does not end the turn. Continue using tools after progress updates. When the task is fully complete and no more tool calls are needed, call ${KIRO_COMPLETION_TOOL_NAME} exactly once with the complete user-facing final answer in \`answer\`. Do not provide the final answer as ordinary assistant text.`; diff --git a/src/adapters/kiro.ts b/src/adapters/kiro.ts index b4161be196..ccfd80febe 100644 --- a/src/adapters/kiro.ts +++ b/src/adapters/kiro.ts @@ -36,15 +36,18 @@ import type { OcxTool, OcxUsage, } from "../types"; +import { hasRecordedTrailingDeliveredFinalAnswer } from "../responses/turn-termination"; import type { ProviderAdapter } from "./base"; import type { AdapterFetchContext, AdapterRequest } from "./base"; import { extractKiroImages, normalizeKiroImages, type KiroImage } from "./kiro-images"; import { sniffImageDimensions } from "./anthropic-image-guard"; import { fetchKiroWithRetry, noteKiroTransientThrottle } from "./kiro-retry"; import { convertKiroToolContext } from "./kiro-tools"; +import { normalizeEmptyExecToolResultText } from "./exec-tool-result-normalize"; import { identifyRoutedModel } from "./identity"; import { buildNonOpenAIToolCatalogNudgeFromNames, isBareShellBridgeTool, isCodexCodeModeExecTool } from "./tool-catalog-nudge"; import { + KIRO_ANSWER_DELIVERED_MESSAGE, KIRO_COMPLETION_INSTRUCTIONS, KIRO_COMPLETION_RETRY_MESSAGE, KIRO_COMPLETION_TOOL_NAME, @@ -343,8 +346,54 @@ function validateKiroCapabilities(parsed: OcxParsedRequest): void { } type KiroTurn = - | { kind: "user"; content: string; images: KiroImage[]; toolResults: KiroToolResult[] } - | { kind: "assistant"; content: string; toolUses: KiroToolUse[]; redactedReasoning?: string }; + | { + kind: "user"; + content: string; + images: KiroImage[]; + toolResults: KiroToolResult[]; + /** + * True only for the proxy-generated acknowledgement that follows a delivered final answer. + * A flag rather than a content comparison: a real user message may legitimately quote the + * same sentence, and treating that as internal state would strip its thinking tags and + * completion retry. + */ + answerDeliveredAck?: boolean; + } + | { + kind: "assistant"; + content: string; + toolUses: KiroToolUse[]; + redactedReasoning?: string; + /** + * True when this assistant turn was the DELIVERED final answer (Responses + * `phase: "final_answer"`). A trailing assistant turn normally means the model stopped + * mid-task and needs a continuation prompt, but a delivered final answer already ended its + * turn — prompting it again restarts finished work as if a goal were still open. + */ + finalAnswer?: boolean; + }; + +/** + * True when the LAST content-bearing message is an assistant final answer that closed its turn. + * + * Mirrors the turn-merge rule: a tool call in that message, or any later user/tool-result message, + * means work continued, so the turn is no longer terminal. Empty assistant messages are skipped + * rather than treated as continuation, since they carry no visible turn. + */ +function hasTrailingDeliveredFinalAnswer(messages: readonly OcxMessage[], parsed?: OcxParsedRequest): boolean { + for (let i = messages.length - 1; i >= 0; i--) { + const msg = messages[i]; + if (msg.role !== "assistant") return false; + const aMsg = msg as OcxAssistantMessage; + const hasToolCall = (aMsg.content ?? []).some(part => part.type === "toolCall"); + if (hasToolCall) return false; + const hasText = (aMsg.content ?? []).some(part => part.type === "text" && part.text.trim()); + if (!hasText) continue; + return aMsg.phase === "final_answer" + || (parsed !== undefined && hasRecordedTrailingDeliveredFinalAnswer(parsed, messages)); + } + return false; +} function appendTurnText(target: string, next: string): string { if (!next) return target; @@ -453,8 +502,19 @@ export function buildKiroPayload( const registry = createKiroToolNameRegistry(); const toolContext = convertKiroToolContext(parsed, registry); const ordinaryTools = toolContext.tools; + // A turn whose history already ENDS with a delivered final answer has nothing to complete. + // Leaving completion "required" here would keep advertising codex_kiro_final_answer with its + // instructions, so the model answers again, or replies with ordinary text and trips the + // `needsFallback` retry, which ends its payload with KIRO_COMPLETION_RETRY_MESSAGE and reopens + // the finished task. Suppressing the mode is what actually closes that loop; the neutral + // acknowledgement below only stops the resume wording. + // + // Read from parsed messages because `completionMode` is needed to build the tool catalog, which + // happens before the turn list exists. `forcedCompletionMode` still wins: the fallback retry + // passes "text_fallback" explicitly and must not be silently downgraded. + const trailingDeliveredAnswer = hasTrailingDeliveredFinalAnswer(kiroPayloadMessages(parsed), parsed); const completionMode: KiroCompletionMode = forcedCompletionMode - ?? (ordinaryTools.length > 0 ? "required" : "disabled"); + ?? (ordinaryTools.length > 0 && !trailingDeliveredAnswer ? "required" : "disabled"); const kiroTools = completionMode === "disabled" ? ordinaryTools : [...ordinaryTools, kiroCompletionTool()]; @@ -521,15 +581,24 @@ export function buildKiroPayload( turns.push({ kind: "user", content, images: [...images], toolResults: [...toolResults] }); } }; - const pushAssistant = (content: string, toolUses: KiroToolUse[], redactedReasoning?: string): void => { + const pushAssistant = (content: string, toolUses: KiroToolUse[], redactedReasoning?: string, finalAnswer?: boolean): void => { const last = turns.at(-1); if (last?.kind === "assistant") { last.content = appendTurnText(last.content, content); last.toolUses.push(...toolUses); // Merged turns keep the newest blob: it covers the reasoning up to the merged turn's end. if (redactedReasoning) last.redactedReasoning = redactedReasoning; + // A merged turn is final only if its LAST component was: commentary appended after a final + // answer means the model kept working, so the turn is no longer terminal. + last.finalAnswer = finalAnswer === true; } else { - turns.push({ kind: "assistant", content, toolUses: [...toolUses], ...(redactedReasoning ? { redactedReasoning } : {}) }); + turns.push({ + kind: "assistant", + content, + toolUses: [...toolUses], + ...(redactedReasoning ? { redactedReasoning } : {}), + ...(finalAnswer ? { finalAnswer: true } : {}), + }); } }; @@ -559,14 +628,24 @@ export function buildKiroPayload( const hasReasoning = aMsg.content.some(part => part.type === "thinking" && part.thinking.trim()); if (hasReasoning) continue; } - pushAssistant(text, toolUses, aMsg.kiroRedactedReasoning); + // `phase` survives the Responses round trip (parser.ts assistant branch), so a replayed + // final answer is identifiable here rather than guessed from turn position. + pushAssistant(text, toolUses, aMsg.kiroRedactedReasoning, aMsg.phase === "final_answer" && toolUses.length === 0); } else if (msg.role === "toolResult") { const tr = msg as OcxToolResultMessage; if (tr.containsEncryptedContent) { throw new Error(`Kiro cannot translate encrypted output for tool call ${JSON.stringify(tr.toolCallId)}`); } const text = userContentText(tr.content); - const resultText = text.trim() ? text : KIRO_EMPTY_TOOL_RESULT_MESSAGE; + // An empty code-mode exec result needs the SPECIFIC reason, not the generic fallback: the + // model otherwise reads a blank result, concludes its earlier context was lost, and restarts + // the task instead of calling text()/notify(). Checked before `text.trim()` because the + // wrapper form ("Script completed\nWall time ...\nOutput:\n") is non-blank and would + // otherwise pass through as if it were real output. + const resultText = normalizeEmptyExecToolResultText(text, { + toolName: tr.toolName, + toolNamespace: tr.toolNamespace, + }) ?? (text.trim() ? text : KIRO_EMPTY_TOOL_RESULT_MESSAGE); const images = extractKiroImages(tr.content); const toolUseId = normalizeToolId(tr.toolCallId); if (!priorCalls.has(toolUseId)) { @@ -587,12 +666,23 @@ export function buildKiroPayload( if (turns.length === 0 || turns[0].kind === "assistant") { turns.unshift({ kind: "user", content: KIRO_CONTINUATION_MESSAGE, images: [], toolResults: [] }); } - if (turns.at(-1)?.kind === "assistant") { + // Kiro requires the request to end with a user turn, so a trailing assistant turn always gets + // one appended (the pop below throws otherwise). What that turn SAYS is the load-bearing part. + // + // Normally a trailing assistant turn means the model stopped mid-task, and a continuation/retry + // prompt is correct. A DELIVERED final answer is the exception: the turn already ended, and + // telling that model to "continue" or to call the completion tool again reopens finished work — + // the completed-task-behaves-like-an-open-goal loop. It gets a neutral acknowledgement instead: + // structurally valid, but carrying no instruction to resume. + const trailing = turns.at(-1); + if (trailing?.kind === "assistant") { + const resumeText = completionMode === "text_fallback" ? KIRO_COMPLETION_RETRY_MESSAGE : KIRO_CONTINUATION_MESSAGE; turns.push({ kind: "user", - content: completionMode === "text_fallback" ? KIRO_COMPLETION_RETRY_MESSAGE : KIRO_CONTINUATION_MESSAGE, + content: trailing.finalAnswer ? KIRO_ANSWER_DELIVERED_MESSAGE : resumeText, images: [], toolResults: [], + ...(trailing.finalAnswer ? { answerDeliveredAck: true } : {}), }); } @@ -608,6 +698,8 @@ export function buildKiroPayload( const currentTurn = turns.pop(); if (!currentTurn || currentTurn.kind !== "user") throw new Error("Kiro request must end with a user turn"); + // Survives the pop as state, so the checks below never infer intent from user-supplied text. + const answerDeliveredAck = currentTurn.answerDeliveredAck === true; const toEntry = (turn: KiroTurn): KiroHistoryEntry => turn.kind === "assistant" ? { assistantResponseMessage: { @@ -638,10 +730,17 @@ export function buildKiroPayload( currentUim.userInputMessageContext = { ...(currentUim.userInputMessageContext ?? {}), tools: kiroTools }; } if (completionMode === "text_fallback") { - if (currentUim.content !== KIRO_COMPLETION_RETRY_MESSAGE) { + // Never append the retry instruction onto the answer-delivered acknowledgement: it exists + // precisely to avoid asking a finished turn for another completion call, and appending here + // would reinstate the loop it prevents. + if (currentUim.content !== KIRO_COMPLETION_RETRY_MESSAGE && !answerDeliveredAck) { currentUim.content = appendTurnText(currentUim.content, KIRO_COMPLETION_RETRY_MESSAGE); } - } else if (!currentUim.userInputMessageContext?.toolResults && currentUim.content !== KIRO_CONTINUATION_MESSAGE) { + } else if ( + !currentUim.userInputMessageContext?.toolResults + && currentUim.content !== KIRO_CONTINUATION_MESSAGE + && !answerDeliveredAck + ) { currentUim.content = injectKiroThinkingTags(currentUim.content, parsed); } @@ -1905,6 +2004,24 @@ export function createKiroAdapter(provider: OcxProviderConfig): ProviderAdapter return { name: "kiro", + // A replayed history that already ENDS with a delivered final answer has nothing to ask Kiro. + // Before this hook the adapter still appended a trailing user turn — a neutral acknowledgement, + // but structurally still a prompt — and performed a real inference, so the model answered the + // closed task again and the finished turn behaved like a still-open goal. + // + // Suppressing the completion contract (above) removed the instruction to complete; it could not + // remove the inference. This is the boundary: no request is built, nothing is sent, and no token + // estimate is recorded. + // + // The forced-fallback build is deliberately NOT consulted here: this hook runs on the inbound + // turn only, and the adapter-owned bounded retry passes "text_fallback" through `build` + // directly, never through this path. + localTerminal(parsed: OcxParsedRequest) { + return hasTrailingDeliveredFinalAnswer(kiroPayloadMessages(parsed), parsed) + ? { reason: "kiro_final_answer_already_delivered" } + : undefined; + }, + async buildRequest(parsed: OcxParsedRequest, incoming) { const built = await build(parsed); modelId = parsed.modelId; diff --git a/src/adapters/openai-chat.ts b/src/adapters/openai-chat.ts index 9add6b8a8c..f2a36e0490 100644 --- a/src/adapters/openai-chat.ts +++ b/src/adapters/openai-chat.ts @@ -1113,7 +1113,8 @@ function intersectBound(target: unknown, sibling: unknown, direction: "max" | "m * Compose two `properties` maps. A property named in BOTH the referenced target and the * node is the same conjunction problem `required` had: letting the sibling win discards * the target's constraints for that member. Merge the two member schemas so neither side - * loses its keywords, and let the node narrow on a genuine conflict. + * loses its keywords. Shared member bounds are the same conjunction one level down, + * and nested object members recurse through this helper instead of replacing the target. */ function composeProperties( target: Record, @@ -1127,7 +1128,20 @@ function composeProperties( const member: Record = Object.create(null) as Record; for (const [k, v] of Object.entries(existing)) member[k] = v; for (const [k, v] of Object.entries(sub)) { - member[k] = k === "required" ? unionRequired(member[k], v) : v; + if (k === "required") { + member[k] = unionRequired(member[k], v); + continue; + } + if (k === "properties" && isXaiObjectSchema(member[k]) && isXaiObjectSchema(v)) { + member[k] = composeProperties(member[k] as Record, v); + continue; + } + const boundDirection = MOONSHOT_BOUND_KEYWORDS[k]; + if (boundDirection && k in member) { + member[k] = intersectBound(member[k], v, boundDirection); + continue; + } + member[k] = v; } combined[name] = member; continue; diff --git a/src/adapters/openai-responses.ts b/src/adapters/openai-responses.ts index d69d2909b1..70e6e7a1d7 100644 --- a/src/adapters/openai-responses.ts +++ b/src/adapters/openai-responses.ts @@ -318,8 +318,8 @@ function stripUnsupportedReasoningParams(body: unknown): unknown { } /** - * GPT-5.6 replaced the legacy 24-hour retention field with `prompt_cache_options.ttl`, and the - * ChatGPT backend 400s the whole request when the retired field is present (issue #2092). + * GPT-5.6 retired the legacy 24-hour retention field, and the ChatGPT backend 400s the whole + * request when that field is present (issue #2092). * * The retired field is NOT translated to the replacement: 5.6 carries a different TTL contract, * and implicit caching still applies when the caller sent no replacement options. Inventing a @@ -339,6 +339,18 @@ function stripDeprecatedPromptCacheRetention(body: unknown, modelId: unknown): u return rest; } +/** + * Public Responses clients can send `prompt_cache_options`, but the canonical ChatGPT Codex + * backend rejects the top-level field before inference (issue #2765). Custom forward gateways and + * API-key Responses providers own different wire contracts, so the caller applies this only after + * the canonical destination predicate succeeds. + */ +function stripCanonicalForwardPromptCacheOptions(body: unknown): unknown { + if (!isPlainObject(body) || !Object.hasOwn(body, "prompt_cache_options")) return body; + const { prompt_cache_options: _options, ...rest } = body; + return rest; +} + /** * A false model capability prevents Codex from emitting summary fields after the catalog refresh. * Strip them here as well so an already-running client with a stale catalog cannot keep sending an @@ -2001,6 +2013,7 @@ export function createResponsesPassthroughAdapter(provider: OcxProviderConfig): // third-party forward gateway may still accept it, so this must not be widened. if (isCanonicalOpenAiForwardProvider(provider)) { outBody = stripDeprecatedPromptCacheRetention(outBody, parsed.modelId); + outBody = stripCanonicalForwardPromptCacheOptions(outBody); outBody = normalizeCanonicalForwardPromptEnvelope(outBody); outBody = normalizeCanonicalForwardContinuationEnvelope(outBody); } diff --git a/src/adapters/run-turn-queue.ts b/src/adapters/run-turn-queue.ts index 795743f54b..4b63e387de 100644 --- a/src/adapters/run-turn-queue.ts +++ b/src/adapters/run-turn-queue.ts @@ -4,6 +4,13 @@ type QueueReader = (result: IteratorResult) => void; export const PREFLIGHT_HEARTBEAT_RETAIN_LIMIT = 16; +/** + * Coalescing threshold for adjacent text/thinking deltas buffered with no + * waiting reader (UTF-16 code units). This is a merge-size ceiling, not a + * byte-memory cap: a single oversized incoming event stays one item. + */ +export const COALESCE_MAX_CHUNK_LENGTH = 64 * 1024; + export interface AdapterEventQueue { push(event: AdapterEvent): void; close(): void; @@ -64,6 +71,33 @@ export function createAdapterEventQueue(opts?: { const maxBacklog = opts?.maxBacklog ?? 1_024; let closed = false; + // Merge an incoming delta into the buffered tail when no reader is waiting. + // The backlog cap counts events, not tokens, so a detached or briefly + // stalled consumer (e.g. a Codex app mid-reconnect whose disconnect Bun has + // not yet delivered) used to hit the cap within seconds of token-granular + // streaming and abort a healthy turn. Adjacent same-phase text deltas, + // adjacent thinking deltas, and consecutive heartbeats carry no ordering + // information between themselves, so merging them preserves every consumer + // contract while making the cap approximate buffered items again. + // Pushed objects may be retained by adapters, so the tail is REPLACED with + // a fresh object — never mutated (alias safety). + const coalesceIntoTail = (event: AdapterEvent): boolean => { + const tail = queued[queued.length - 1]; + if (!tail) return false; + if (event.type === "heartbeat") return tail.type === "heartbeat"; + if (event.type === "text_delta" && tail.type === "text_delta" && tail.phase === event.phase) { + if (tail.text.length + event.text.length > COALESCE_MAX_CHUNK_LENGTH) return false; + queued[queued.length - 1] = { type: "text_delta", text: tail.text + event.text, phase: tail.phase }; + return true; + } + if (event.type === "thinking_delta" && tail.type === "thinking_delta") { + if (tail.thinking.length + event.thinking.length > COALESCE_MAX_CHUNK_LENGTH) return false; + queued[queued.length - 1] = { type: "thinking_delta", thinking: tail.thinking + event.thinking }; + return true; + } + return false; + }; + const push = (event: AdapterEvent): void => { if (closed) return; const reader = readers.shift(); @@ -71,9 +105,10 @@ export function createAdapterEventQueue(opts?: { reader({ done: false, value: event }); return; } + if (coalesceIntoTail(event)) return; if (queued.length >= maxBacklog) { opts?.onBacklogExceeded?.(); - queued.push({ type: "error", message: "consumer backlog exceeded — turn aborted" }); + queued.push({ type: "error", message: "consumer stalled: adapter event backlog exceeded — turn aborted" }); close(); return; } diff --git a/src/adapters/tool-catalog-nudge.ts b/src/adapters/tool-catalog-nudge.ts index b14ff09837..8653fde1d7 100644 --- a/src/adapters/tool-catalog-nudge.ts +++ b/src/adapters/tool-catalog-nudge.ts @@ -5,6 +5,7 @@ import { type OcxTool, type OcxProviderConfig, } from "../types"; +import { CODE_MODE_RESULT_ECHO_SENTENCE } from "./exec-tool-result-normalize"; // Tool names that exist only in OTHER agent harnesses (Claude Code and friends). Naming one // here tells a routed model not to call it unless this turn's catalog really lists it. @@ -120,7 +121,7 @@ export function buildNonOpenAIToolCatalogNudgeFromNames( "Call only listed names with their listed argument keys; do not invent, translate, or rename tools.", "Names mentioned only in instructions, tool descriptions, argument descriptions, or nested helper APIs are not additional top-level tools.", verifiedCodeModeExecName - ? "`" + verifiedCodeModeExecName + "` is Codex code mode: its body is JavaScript evaluated in a V8 isolate. Nested helpers are called INSIDE that body as `await tools.(...)`, for example `await tools.exec_command({cmd: \"ls\"})` or `await tools.codex_app__list_threads({})`. Absence from the top-level catalog or from `" + verifiedCodeModeExecName + "`'s description is not absence: deferred helpers stay callable on `tools.`. Discover them from the isolate global `ALL_TOOLS`, not `tools.ALL_TOOLS`. Do not skip an available nested helper because it is omitted from the listed top-level names. Nested `tools.apply_patch(input)` is host-executed: the string must begin exactly with `*** Begin Patch` and end with `*** End Patch` (no trailing `***` on those lines). OpenCodex does not rewrite JavaScript inside exec, so a decorated `*** Begin Patch ***` envelope is rejected by Codex before the file is touched." + ? "`" + verifiedCodeModeExecName + "` is Codex code mode: its body is JavaScript evaluated in a V8 isolate. Nested helpers are called INSIDE that body as `await tools.(...)`, for example `await tools.exec_command({cmd: \"ls\"})` or `await tools.codex_app__list_threads({})`. Absence from the top-level catalog or from `" + verifiedCodeModeExecName + "`'s description is not absence: deferred helpers stay callable on `tools.`. Discover them from the isolate global `ALL_TOOLS`, not `tools.ALL_TOOLS`. Do not skip an available nested helper because it is omitted from the listed top-level names. " + CODE_MODE_RESULT_ECHO_SENTENCE + " Nested `tools.apply_patch(input)` is host-executed: the string must begin exactly with `*** Begin Patch` and end with `*** End Patch` (no trailing `***` on those lines). OpenCodex does not rewrite JavaScript inside exec, so a decorated `*** Begin Patch ***` envelope is rejected by Codex before the file is touched." : "If a listed tool exposes nested helpers such as a tools.* API, call the listed parent tool and use those helpers only inside that tool's input.", unavailableNeighborNames.length > 0 ? "Do not use neighboring-agent tool names " + quoteNames(unavailableNeighborNames) + " unless this turn's catalog lists those exact names." diff --git a/src/adapters/xai-web-search.ts b/src/adapters/xai-web-search.ts index 5cc4313c6f..a02a5755e8 100644 --- a/src/adapters/xai-web-search.ts +++ b/src/adapters/xai-web-search.ts @@ -1,8 +1,8 @@ import type { OcxProviderConfig } from "../types"; +import { isXaiResponsesDestination } from "../providers/xai-transport"; const CODEX_WEB_SEARCH_TOOL = "web_search"; const CODEX_WEB_SEARCH_PREVIEW_TOOL = "web_search_preview"; -const XAI_API_HOST = "api.x.ai"; function isPlainObject(value: unknown): value is Record { return !!value && typeof value === "object" && !Array.isArray(value); @@ -12,18 +12,6 @@ function isCodexWebSearchToolType(value: unknown): boolean { return value === CODEX_WEB_SEARCH_TOOL || value === CODEX_WEB_SEARCH_PREVIEW_TOOL; } -/** Match only xAI's documented public API, not arbitrary Responses-compatible gateways. */ -function isXaiPublicApi(provider: Pick): boolean { - try { - const url = new URL(provider.baseUrl); - return url.protocol === "https:" - && url.hostname.toLowerCase() === XAI_API_HOST - && (url.port === "" || url.port === "443"); - } catch { - return false; - } -} - type ToolGroupRewrite = { tools: unknown[]; changed: boolean; @@ -150,12 +138,20 @@ function normalizeToolChoice(body: Record): Record 422 `unknown variant`, `external_web_access` -> 400 on every value, + * `search_context_size` -> 400, while `user_location` and `search_content_types` -> 200. Identical + * to the public API, which is what makes one shared gate correct. */ export function normalizeXaiResponsesWebSearch( body: unknown, provider: Pick, ): unknown { - if (!isXaiPublicApi(provider) || !isPlainObject(body)) return body; + if (!isXaiResponsesDestination(provider) || !isPlainObject(body)) return body; let next: Record = body; if (Array.isArray(body.tools)) { diff --git a/src/claude/outbound.ts b/src/claude/outbound.ts index 6256de34dd..48bb06c15a 100644 --- a/src/claude/outbound.ts +++ b/src/claude/outbound.ts @@ -11,6 +11,7 @@ * - errors: {type:"error", error:{type,message}}; may arrive mid-stream after HTTP 200. */ import { createHash } from "node:crypto"; +import { httpStatusFromTerminalError } from "../lib/errors"; import { isTransientUpstreamStatus } from "../lib/upstream-retry"; import { isTranslatorBudgetExceededError, @@ -555,9 +556,19 @@ export function responsesSseToAnthropicSse( } const status = code === "translation_buffer_limit" ? 413 - : typeof error.status === "number" ? error.status : 500; - // status-absent response.failed (relaySseWithFailedTail synthetic tail) defaults - // to 500, which is in the transient set — the mid-stream reset shape maps to + : typeof error.status === "number" + ? error.status + // Internal response.failed envelopes carry the classified {type, code, message} + // but no numeric status. Derive it with the same mapping /api/logs uses so a + // classified 429/401/400 reaches Claude Code as its real Anthropic error type + // instead of being masked as retryable overload. + : httpStatusFromTerminalError({ + type: typeof error.type === "string" ? error.type : undefined, + code: typeof error.code === "string" ? error.code : null, + message, + }); + // Unclassified status-absent response.failed (relaySseWithFailedTail synthetic + // tail) still lands on a transient 5xx here — the mid-stream reset shape maps to // overloaded_error by design. fail( status, diff --git a/src/cli/access.ts b/src/cli/access.ts index e22bae786a..0003aa64f9 100644 --- a/src/cli/access.ts +++ b/src/cli/access.ts @@ -17,6 +17,51 @@ const USAGE = `Usage: ocx access models [--json] ocx access test [--protocol ] [--json]`; +/** + * Render the key table with the usage fields the API already returns (#2705). + * + * `usage` is a DISCRIMINATED UNION server-side (`api-key-usage.ts`): the `{ambiguous:true}` + * variant carries no numbers at all, because when two config entries share an id there IS no + * per-key total. The union exists specifically so a consumer cannot print a number beside an + * ambiguity marker, so this renders the word `ambiguous` across the numeric columns rather + * than a fabricated 0 -- reporting 0 requests for a key that may be in heavy use is the + * dangerous answer to hand someone deciding what to delete. + * + * `attributionSince` and `historyTruncated` describe the DATA SET, not a key, so they print + * once as a footer. Without `attributionSince`, an absent `lastUsedAt` is unreadable: it + * could mean "never used" or "nothing is attributable yet". + */ +function formatKeyRows(payload: Record, keys: Array>): string[] { + const cells: string[][] = [["ID", "NAME", "PREFIX", "REQ 7D", "TOTAL", "LAST USED"]]; + for (const entry of keys) { + const usage = (entry.usage ?? {}) as Record; + const ambiguous = usage.ambiguous === true; + const num = (value: unknown): string => (typeof value === "number" ? value.toLocaleString("en-US") : "-"); + cells.push([ + String(entry.id ?? ""), + String(entry.name ?? ""), + String(entry.prefix ?? ""), + // One marker spanning both numeric columns: the union guarantees neither exists. + ambiguous ? "ambiguous" : num(usage.requests7d), + ambiguous ? "" : num(usage.totalRequests), + ambiguous ? "" : (typeof usage.lastUsedAt === "string" ? usage.lastUsedAt : "never"), + ]); + } + const widths = cells[0]!.map((_, column) => Math.max(...cells.map(row => (row[column] ?? "").length))); + const lines = cells.map(row => row.map((cell, i) => (cell ?? "").padEnd(widths[i]!)).join(" ").trimEnd()); + const footer: string[] = []; + if (typeof payload.attributionSince === "string") { + footer.push(`attribution since ${payload.attributionSince}`); + } + if (payload.historyTruncated === true) { + footer.push("older history truncated"); + } + if (keys.some(entry => (entry.usage as Record | undefined)?.ambiguous === true)) { + footer.push("ambiguous: two configured keys share an id, so per-key totals do not exist"); + } + return footer.length > 0 ? [...lines, "", ...footer] : lines; +} + async function key(argv: string[], deps: RuntimeApiDeps): Promise { const args = [...argv]; const action = (args.shift() ?? "list").toLowerCase(); @@ -25,9 +70,7 @@ async function key(argv: string[], deps: RuntimeApiDeps): Promise { rejectArgs(args, USAGE); const result = await runtimeRequest>("/api/keys", {}, deps); const keys = Array.isArray(result.keys) ? result.keys as Array> : []; - printData(result, wantsJson, keys.length - ? keys.map(entry => `${String(entry.id)} ${String(entry.name)} ${String(entry.prefix ?? "")}`) - : ["No API access keys configured."]); + printData(result, wantsJson, keys.length ? formatKeyRows(result, keys) : ["No API access keys configured."]); return; } if (action === "create") { diff --git a/src/cli/account-api.ts b/src/cli/account-api.ts index 9cd06cd939..b21f72b85d 100644 --- a/src/cli/account-api.ts +++ b/src/cli/account-api.ts @@ -24,6 +24,14 @@ export interface AccountRow { /** Codex pool selection order, higher used earlier. Absent where ordering does not apply. */ priority?: number; quota?: CodexQuotaDto | null; + /** + * Whether the pool is holding this account out of rotation. + * + * The server has always sent it (auth-api.ts:286 for pool accounts, :1315 for main) and the + * CLI dropped it, so a paused account was indistinguishable from an available one in every + * human listing (#2703). + */ + paused?: boolean; } export type ClassifyResult = { type: AccountType } | { error: string }; @@ -83,6 +91,12 @@ export interface ApiResult { /** 0 = network-level failure (proxy unreachable). */ status: number; json: Record; + /** + * Message from the thrown transport error when `status` is 0. Previously the + * error was swallowed by a catch block with an empty body, so an unreachable proxy, a DNS + * failure and a TLS error were indistinguishable (#2698). + */ + transportError?: string; } export async function apiJson( @@ -103,8 +117,14 @@ export async function apiJson( }); const json = (await res.json().catch(() => ({}))) as Record; return { status: res.status, json }; - } catch { - return { status: 0, json: {} }; + } catch (error) { + // status 0 stays the transport sentinel, but keep the cause: callers can now + // tell the operator why the request never reached the proxy (#2698). + return { + status: 0, + json: {}, + transportError: error instanceof Error ? error.message : String(error), + }; } } @@ -115,18 +135,43 @@ export async function resolveBaseUrl(deps: AccountDeps): Promise return `http://${probeHostname(live.hostname)}:${live.port}`; } -export function proxyUnreachable(): number { +export function proxyUnreachable(transportError?: string): number { console.error("Proxy not reachable. Start it with 'ocx start' or 'ocx ensure'."); + // Naming the transport cause distinguishes "nothing is listening" from a refused + // or reset connection, which is what made #2696-class breakage undiagnosable. + if (transportError) console.error(`reason: ${transportError}`); return 1; } -export function apiError(json: Record, fallback: string): number { - const message = typeof json.error === "string" ? json.error : fallback; - console.error(`Error: ${message}`); +function accountStringField(json: Record, key: string): string | undefined { + const value = json[key]; + return typeof value === "string" && value.trim() ? value.trim() : undefined; +} + +/** + * Report a failed management call from the account family. + * + * `reason` and `hint` are the actionable fields on a refusal — the management plane + * sets both on a 503, and several routes return `reason` with no `error` key at all, + * which used to print only the generic fallback (#2698). + * + * `status` selects the exit code so the account client speaks the same vocabulary as + * runtime-api.ts: 4 for not-found, 5 for conflict, 1 otherwise. Previously every + * failure exited 1, so a script could not distinguish a missing account from a + * concurrent mutation. + */ +export function apiError(json: Record, fallback: string, status: number): number { + const primary = accountStringField(json, "error") ?? fallback; + const lines = [`Error: ${primary}`]; + const reason = accountStringField(json, "reason"); + if (reason && reason !== primary) lines.push(`reason: ${reason}`); + const hint = accountStringField(json, "hint"); + if (hint && hint !== primary) lines.push(`hint: ${hint}`); + for (const line of lines) console.error(line); if (json.cleanupRequired === true) { console.error("Warning: native-login staging cleanup is still required; run 'ocx account main doctor'."); } - return 1; + return status === 404 ? 4 : status === 409 ? 5 : 1; } export interface FamilyRows { @@ -134,10 +179,12 @@ export interface FamilyRows { activeId: string | null; autoSwitchThreshold?: number; /** HTTP status for a completed family read, including failures. */ - status?: number; + status: number; /** Set when the family endpoint returned an error. */ errorJson?: Record; networkDown?: boolean; + /** Transport cause when `networkDown` is set. Callers must forward this to `proxyUnreachable`. */ + transportError?: string; } export interface CodexQuotaDto { @@ -190,12 +237,19 @@ interface CodexAccountDto { needsReauth?: boolean; priority?: number; quota?: CodexQuotaDto | null; + paused?: boolean; } function projectQuota(quota: CodexQuotaDto | null | undefined): CodexQuotaDto | null { if (!quota) return null; const projected: CodexQuotaDto = {}; - for (const key of ["weeklyPercent", "monthlyPercent", "weeklyResetAt", "monthlyResetAt", "shortPercent", "shortResetAt", "shortWindowSeconds"] as const) { + // `fiveHourPercent`/`fiveHourResetAt` were declared on the DTO and read by two renderers + // -- `quotaText`'s `quota.fiveHourPercent ?? quota.shortPercent` (account.ts:89) and + // `quotaParts` (account-extended.ts:275) -- but omitted from this whitelist, so the first + // operand was unreachable and a 5h-only account rendered as unknown (#2703). A projection + // that silently drops a field its own type declares is worse than one that never had it: + // the type checks, the renderer looks correct, and only the output is wrong. + for (const key of ["fiveHourPercent", "fiveHourResetAt", "weeklyPercent", "monthlyPercent", "weeklyResetAt", "monthlyResetAt", "shortPercent", "shortResetAt", "shortWindowSeconds"] as const) { if (typeof quota[key] === "number" && Number.isFinite(quota[key])) projected[key] = quota[key]; } return projected; @@ -205,6 +259,7 @@ export async function fetchCodexRows( deps: AccountDeps, baseUrl: string, forceRefresh = false, + includeQuota = forceRefresh, ): Promise { const accountsPath = `/api/codex-auth/accounts${forceRefresh ? "?refresh=1" : ""}`; const [accountsRes, activeRes] = await Promise.all([ @@ -218,7 +273,13 @@ export async function fetchCodexRows( return { rows: [], activeId: null, status: activeRes.status, errorJson: activeRes.json }; } if (accountsRes.status === 0 || activeRes.status === 0) { - return { rows: [], activeId: null, status: 0, networkDown: true }; + return { + rows: [], + activeId: null, + status: 0, + networkDown: true, + transportError: accountsRes.transportError ?? activeRes.transportError, + }; } const activeId = typeof activeRes.json.activeCodexAccountId === "string" ? activeRes.json.activeCodexAccountId @@ -237,7 +298,8 @@ export async function fetchCodexRows( active: a.id === activeId, needsReauth: a.needsReauth, priority: typeof a.priority === "number" ? a.priority : 0, - ...(forceRefresh ? { quota: projectQuota(a.quota) } : {}), + paused: a.paused === true, + ...(includeQuota ? { quota: projectQuota(a.quota) } : {}), })); return { rows, activeId, autoSwitchThreshold, status: 200 }; } @@ -264,7 +326,9 @@ async function fetchOAuthRows( ? `?provider=${encodeURIComponent(name)}"a=1${quota.refresh ? "&refresh=1" : ""}` : `?provider=${encodeURIComponent(name)}`; const res = await apiJson(deps, baseUrl, "GET", `/api/oauth/accounts${query}`); - if (res.status === 0) return { rows: [], activeId: null, status: 0, networkDown: true }; + if (res.status === 0) { + return { rows: [], activeId: null, status: 0, networkDown: true, transportError: res.transportError }; + } if (res.status !== 200) return { rows: [], activeId: null, status: res.status, errorJson: res.json }; const activeId = typeof res.json.activeAccountId === "string" ? res.json.activeAccountId : null; const accounts = Array.isArray(res.json.accounts) ? res.json.accounts as OAuthAccountDto[] : []; @@ -291,7 +355,9 @@ interface ApiKeyDto { async function fetchKeyRows(deps: AccountDeps, baseUrl: string, name: string): Promise { const res = await apiJson(deps, baseUrl, "GET", `/api/providers/keys?name=${encodeURIComponent(name)}`); - if (res.status === 0) return { rows: [], activeId: null, status: 0, networkDown: true }; + if (res.status === 0) { + return { rows: [], activeId: null, status: 0, networkDown: true, transportError: res.transportError }; + } if (res.status !== 200) return { rows: [], activeId: null, status: res.status, errorJson: res.json }; const activeId = typeof res.json.activeId === "string" ? res.json.activeId : null; const keys = Array.isArray(res.json.keys) ? res.json.keys as ApiKeyDto[] : []; @@ -313,7 +379,7 @@ export function fetchRows( type: AccountType, quota?: { refresh?: boolean }, ): Promise { - if (type === "codex") return fetchCodexRows(deps, baseUrl); + if (type === "codex") return fetchCodexRows(deps, baseUrl, Boolean(quota?.refresh), quota !== undefined); if (type === "oauth") return fetchOAuthRows(deps, baseUrl, name, quota); return fetchKeyRows(deps, baseUrl, name); } @@ -322,8 +388,11 @@ export async function fetchProviderQuotaReport( deps: AccountDeps, baseUrl: string, name: string, -): Promise<{ status: number; report: ProviderQuotaReportDto | null; errorJson?: Record }> { +): Promise<{ status: number; report: ProviderQuotaReportDto | null; errorJson?: Record; transportError?: string }> { const res = await apiJson(deps, baseUrl, "GET", "/api/provider-quotas?refresh=1"); + if (res.status === 0) { + return { status: 0, report: null, errorJson: res.json, transportError: res.transportError }; + } if (res.status !== 200) return { status: res.status, report: null, errorJson: res.json }; const reports = Array.isArray(res.json.reports) ? res.json.reports as ProviderQuotaReportDto[] : []; return { status: 200, report: reports.find(report => report?.provider === name) ?? null }; diff --git a/src/cli/account-extended.ts b/src/cli/account-extended.ts index 952a552d79..72cd038c49 100644 --- a/src/cli/account-extended.ts +++ b/src/cli/account-extended.ts @@ -40,6 +40,11 @@ const EXTENDED_USAGE = `Usage: ocx account auto-switch > [--json] ocx account alias [--json] ocx account priority [<-100..100|first|earlier|normal|later|last|reset>] [--json] + ocx account pause [--json] + ocx account resume [--json] + ocx account pause-exhausted [--json] + ocx account strategy [] [--json] + ocx account sticky [<1-100>] [--json] ocx account remove --yes [--json] ocx account clear-cooldown [--json] ocx account add-key [--label