Skip to content

Commit 377f229

Browse files
authored
feat(sidecar): shared auth module with login-shaped flags and auth slots (#2188 L1) (#2203)
* docs(devlog): roadmap unit for sidecar selection unification (#2188) Cleanup record (wp0), current-state research, verified hosted web-search protocol research (OpenAI/Anthropic/xAI/Gemini/vendors), and five audited decade docs mapping 1:1 onto the stacked PR layers. Audited by grok-4.6 (two FAIL rounds folded back in; final PASS). * feat(sidecar): shared auth module with login-shaped flags and auth slots (#2188) isCodexAuth requires a live stored ChatGPT credential (main token or a usable selectable pool account), not mere forward-provider presence. isAnthropicAuth extracts the predicate previously duplicated in findAnthropicSidecarProvider and findAnthropicVisionProvider; both now delegate. sidecarAuthSlots emits the fixed Luna/Haiku candidates that survive picker hiding. * refactor(sidecar): source the codex slot provider id from openai-tiers * docs(devlog): recast the wp0 cleanup plan as an executed historical record Maintainer review blocker on #2203: the tracked doc was written as an executable deletion plan with contradictory KEEP/REMOVE rows, no per-batch preflight, an incomplete protected set, an unpreserved detached commit, and codex/merge-loop-closeout listed as both KEEP and remote-delete. Rewritten as a non-executable EXECUTED RECORD: KEEP rows moved out of removal sections, the b2ac250 preservation branch ordering made explicit, the 37-row remote list corrected to the 36 actually deleted (merge-loop-closeout excluded), and a mandatory 5-step protected-set preflight template appended for any future batch. Live-state post-check: 0 deleted remote refs resurrected, kept worktrees intact. * docs(devlog): preflight step 1 detects dirty worktrees via per-path status C-gate blocker: git worktree list --porcelain reports metadata, not cleanliness; the template now enumerates each path and runs git -C <path> status --porcelain, protecting dirty paths and their attached branches. * docs(devlog): preflight step 3 protects dirty worktree paths, not only branches
1 parent 826a1b7 commit 377f229

14 files changed

Lines changed: 643 additions & 18 deletions
Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# 260820 — Sidecar selection unification (#2188)
2+
3+
Roadmap for implementing issue #2188 as a stacked PR chain onto dev.
4+
Session 01a01f4b; goalplan implement-github-issue-2188-feat-sidecar-unify-w.
5+
6+
## Docs
7+
- 000 (this file) — unit overview + stack map.
8+
- 000_wp0 — branch/worktree cleanup record (executed, closed).
9+
- 001 — research: current selection state at dev f2ebd3067.
10+
- 010 — Layer 1: src/sidecar/auth.ts shared auth + slots (branch codex/sidecar-auth-slots → dev).
11+
- 020 — Layer 2: src/sidecar/candidates.ts picker set + vision filter (codex/sidecar-picker-candidates → L1).
12+
- 030 — Layer 3: web-search backend registry + candidate ∩ (no default-backend change) (codex/sidecar-websearch-slots → L2).
13+
- 031 — future-backend research table + probe contracts (doc-only, inside L3 PR).
14+
- 040 — Layer 4: write gates + GUI lists (codex/sidecar-write-gates → L3).
15+
- 050 — Layer 5: ocx agent sidecar --list + docs-site + full validation (codex/sidecar-cli → L4).
16+
17+
## Stack invariants (DEV-STACK)
18+
Bottom targets dev; each child targets the branch below. Merge bottom-up; retarget children after parent lands. Each layer: own tests green + typecheck before PR; full suite at top layer. Every A/C gate: xai/grok-4.6 read-only reviewer, verdict binding.
19+
20+
## Out of scope (issue-fixed)
21+
Gemini/Grok/Zen/Exa executors, #2190 x_search, #398, types.ts-split rebases.
22+
23+
24+
## AMENDMENT 1 (post-audit, auditor Hegel VERDICT: fail — all four blockers accepted)
25+
26+
### B1 — isCodexAuth must mean LOGIN, not provider presence (fixes 010)
27+
```ts
28+
// src/sidecar/auth.ts
29+
isCodexAuth = listOpenAiForwardSidecarCandidates(config).length > 0
30+
&& ( isCodexAccountUsable(config, MAIN_CODEX_ACCOUNT_ID) // live ~/.codex auth.json token
31+
|| (config.codexAccounts ?? []).some(a => isSelectableCodexPoolAccount(a)
32+
&& isCodexAccountUsable(config, a.id)) ) // any usable pool credential
33+
```
34+
Symmetric with the Anthropic predicate (stored OAuth + !needsReauth). Uses src/codex/account-usability.ts:17 isCodexAccountUsable; no header/request context needed. Test: forward provider present but no live token & no pool creds → isCodexAuth false → Luna slot absent.
35+
36+
### B2 — extend ocx agent sidecar, do NOT add ocx sidecar (fixes 001 + 050)
37+
001 correction: src/cli/agent.ts:23 already ships `ocx agent sidecar <status|web|vision>` → PUT /api/sidecar-settings. Layer 5 extends it:
38+
- `ocx agent sidecar web --list` / `vision --list` print the exact candidate sets via a new GET consumer (same functions as GUI).
39+
- Writes already flow through the PUT gate added in L4 (server-side gate covers CLI automatically — the "CLI cannot bypass" property comes from gating the shared route, not from a parallel client check).
40+
- No new top-level command. 050's src/cli/sidecar.ts is WITHDRAWN.
41+
42+
### B3 — claude-code webSearch write gate is REQUIRED in L4 (fixes 040)
43+
- src/server/management/agent-settings-routes.ts:1064 writes webSearchSidecar.model ungated → same membership gate as /api/sidecar-settings (shared helper in src/server/management/web-search-sidecar-options.ts, mirroring vision-sidecar-options.ts placement; extraction happens IN L4, so L5 never restacks routes — also resolves the L5 write-gate.ts smell).
44+
- `ocx claude config set --web-model` rides the same route → covered.
45+
- Out of scope (explicit): `ocx config set webSearchSidecar.model` raw JSON writes bypass management gates by design (operator escape hatch, same as vision today).
46+
- GUI contract: GET must send webSearchModels: [] when empty, never omit (dashboard-shared.ts:273 omission fallback would show the full union). Persisted-but-now-illegal model: display-grandfather into options (same as vision GET :115) but reject NEW writes.
47+
48+
### B4 — default-backend decision split & pinned (fixes 030)
49+
- resolveSidecarBackend(explicit) keeps today's contract: unset → openai, no auth argument (web-search-anthropic.test.ts:58 assertion unchanged).
50+
- resolveVisionBackend keeps today's contract: unset → anthropic when OAuth credential exists.
51+
- The "전역 플래그로 맞춘다" issue sentence is satisfied by both resolvers CONSUMING resolveSidecarAuth for credential presence (shared auth state), NOT by unifying their default preference. Changing dual-auth default preference is a user-facing behavior change #2188 never ordered → OUT OF SCOPE, recorded for a follow-up issue.
52+
- L3 no longer touches src/vision/index.ts at all (removes the cross-surface smell).
53+
54+
### Corrections
55+
- 001: isCodexAuthContextUsable is auth-context.ts:612.
56+
Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# WP0 cleanup — EXECUTED RECORD (session 01a01f4b, performed 2026-08-20)
2+
3+
STATUS: HISTORICAL. Every deletion below was executed during wp0 and verified against
4+
live state afterwards (post-check 2026-08-21: 33 local branches remain, 0 deleted
5+
remote refs resurrected, 9 worktrees). Nothing in this file is a pending command.
6+
Anyone repeating a cleanup of this shape MUST run the preflight template at the end
7+
against CURRENT state first; this snapshot is not reusable as a target list.
8+
9+
## Protected set (mechanical, applied before every batch)
10+
11+
The protected set was computed mechanically, not by eye, and deletion aborted on any
12+
intersection: `dev`, `main`, `preview`, every open-PR head (31 at snapshot time),
13+
every branch checked out in any worktree, and every dirty worktree. KEEP entries
14+
below are the rows the protected set excluded from their surrounding batch.
15+
16+
## Worktrees removed (were all clean; content preserved in dev or a surviving ref)
17+
18+
- /private/tmp/ocx-m2148.LzD2/wt (absorb-baseurl-override, merged)
19+
- tmp.bxVhqaJyPc/sweeper (tmp-reclaim-1-sweeper, merged)
20+
- tmp.bzZ2ssU8WM/wp1b (split-wp1b-type-clusters, merged)
21+
- tmp.gLNBuhAyoP (detached d0cd99672, merge of two dev ancestors, nothing unique)
22+
- tmp.LfX0NlBXvp/r1876 (ingw/fix-windows-v2-catalog-blocking-1852, merged)
23+
- tmp.Mb171xHMCb/r2031 (ingw/fix-mimo-vision-1927, merged)
24+
- tmp.pQMnjf3VMg/wp1 (split-wp1-types, merged)
25+
- tmp.vSBe0MZ0LP/w2080 (pr2080, PR merged)
26+
- tmp.xfjQ3jxADE/w1934 (pr1934, PR merged)
27+
- tmp.2IOChwQmxR/wp1b + tmp.t3YTdy1JDC/wp1b (detached b2ac2500c) — removed ONLY
28+
after preservation branch wip/wp1b-superseded-b2ac2500c was created at b2ac2500c
29+
and verified (unique cherry patches; superseded by a0f8c0135 in dev).
30+
- ~/.codex/worktrees/3a35 (devlog-release-2280, merged)
31+
- ~/.codex/worktrees/3b3b (cursor-call-release-note-2, merged, upstream gone)
32+
- ~/.codex/worktrees/83d5 (tmp-reclaim-2-doctor, merged)
33+
- ~/.codex/worktrees/c6d8 (zcode-client, merged)
34+
- ~/.codex/worktrees/fe69 (detached 63bfd149d, clean, reachable from many branches)
35+
- ~/.codex/worktrees/land-1842 (clean, PR #1842 CLOSED, 0 unique patches)
36+
- .tmp/pr-2045-review (b92bb611c; PR2045 merged into dev as 0161a66d9)
37+
- .tmp/pr1903-review-8c38989f4 (PR1903 merged; commit kept by remotes/review/pr1903)
38+
39+
## Worktrees kept (dirty or otherwise protected — never in a removal batch)
40+
41+
- /private/tmp/opencodex-pr2068.uXcKNC (detached 5a4068bbd, kept by branch
42+
pr2068-check; PR 2068 OPEN)
43+
- tmp.UFYNSQT3qw/land1920 (DIRTY, 2 changes + 3 unique commits)
44+
- ~/.codex/worktrees/648b (DIRTY, 1 change)
45+
- ~/.codex/worktrees/71a2 (DIRTY, 1 change; split-wp2a-config-names stays checked out)
46+
47+
## Local branches deleted
48+
49+
- Merged into origin/dev (git branch --merged proof at snapshot): all 46 merged
50+
branches except dev and split-wp2a-config-names (checked out in a kept worktree).
51+
- Unmerged but 0 unique patches vs dev (git cherry all '-'):
52+
absorb-account-entitlement-stacked, absorb-capability-evidence,
53+
absorb-k12-short-window, absorb-xai-oauth-streaming,
54+
consolidate-prompt-cache-retention, fix-bearer-admission-2132, land-1842
55+
(PR closed), land-1876, ocx/integration, ocx/verify-2167.
56+
57+
## Local branches kept (unique commits or open PR)
58+
59+
combo-quota-badges (PR1704 OPEN), compat-multiagent-v2-catalog (4u), devlog-merge-log
60+
(1u), devlog-three-issues (PR2181 OPEN), external-vision (1u),
61+
issue-quality-provider-defect-bug-label (1u), land-1920 (3u+dirty wt),
62+
cursor-call-prerebase-260818 (2u), ocx-dev-verify (1u), ocx/rebuild-2178 (1u), wip/*
63+
(unique, incl. wip/wp1b-superseded-b2ac2500c), pr2053-check (2u), pr2056-check (1u),
64+
pr2068-check (PR OPEN), pr2072-check (PR OPEN), pr2101-probe (5u), pr2105tmp (3u),
65+
codex/merge-loop-closeout (2 unique local commits), main, preview, dev.
66+
67+
## Remote branches deleted (origin)
68+
69+
- 36 merged-into-origin/dev refs, none an open-PR head. The original 37-row list
70+
mistakenly included codex/merge-loop-closeout; the executed batch EXCLUDED it (it
71+
is a local-only KEEP with 2 unique commits and had no remote ref to delete):
72+
codex/absorb-agentrouter-language-framing, codex/absorb-antigravity-thought-signatures,
73+
codex/absorb-baseurl-override, codex/absorb-claude-shell-hook-gate,
74+
codex/absorb-fastwire-native-chat, codex/absorb-oauth-superseded-commit,
75+
codex/absorb-openai-chat-padding-repeats, codex/absorb-opencode-free-static-headers,
76+
codex/absorb-opencode-go-quota-siblings, codex/absorb-responses-id-backfill,
77+
codex/absorb-shadow-helper-attribution, codex/absorb-tool-search-passthrough,
78+
codex/audit-closeout, codex/audit-record, codex/audit-shadow-marker-leak,
79+
codex/audit-tool-search-id, codex/devlog-audit, codex/devlog-release-2280,
80+
codex/fix-admission-bearer-transport, codex/fix-audit-record-scan,
81+
codex/fix-privacy-scan-devlog, codex/fix-subagent-roster-truncation,
82+
codex/fix-windows-ci-shards, codex/harden-core-lab-guard,
83+
codex/logs-intercepted-helper-attribution, codex/merge-loop-outcome,
84+
codex/openai-chat-tool-call-heartbeat, codex/promote-2.28.0, codex/split-wp1-types,
85+
codex/split-wp1b-type-clusters, codex/split-wp2a-config-names,
86+
codex/sync-preview-2.28.0, codex/windows-shard-truncation-and-budgets,
87+
ingw/docs-tool-search-troubleshooting-1872, ingw/fix-mimo-vision-1927,
88+
ingw/fix-windows-v2-catalog-blocking-1852
89+
- Unmerged, 0 unique, PR closed/merged: codex/absorb-account-entitlement-stacked,
90+
codex/absorb-capability-evidence, codex/absorb-k12-short-window,
91+
codex/absorb-xai-oauth-streaming, codex/consolidate-prompt-cache-retention,
92+
codex/fix-bearer-admission-2132, codex/land-1842, codex/land-1876
93+
94+
## Preflight template (mandatory for any future cleanup batch)
95+
96+
Run immediately before EACH delete batch; abort the batch on any intersection:
97+
98+
1. `git worktree list --porcelain` — collect worktree paths and checked-out branches
99+
(this reports metadata only, NOT status). Then for EACH listed path run
100+
`git -C <path> status --porcelain`; any output marks that worktree dirty.
101+
Protect both the dirty path and its attached branch (detached dirty worktrees
102+
protect the path itself).
103+
2. `gh pr list --state open --json headRefName` — collect every open-PR head.
104+
3. Protected = {dev, main, preview} ∪ open-PR heads ∪ checked-out branches ∪
105+
dirty-worktree branches ∪ dirty-worktree PATHS (a detached dirty worktree has
106+
no branch — its path itself is the protected row). `comm -12` the sorted
107+
candidate list against sorted Protected; any overlap aborts the whole batch,
108+
not just the row.
109+
4. For unmerged candidates, re-prove 0 unique patches with `git cherry dev <ref>`
110+
at execution time; a snapshot proof is stale the moment the tree moves.
111+
5. Detached commits require a durable preservation ref (branch or tag) verified with
112+
`git rev-parse` BEFORE the containing worktree is removed.
Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# 001 — Research: current sidecar selection state (#2188)
2+
3+
Verified against dev @ f2ebd3067 (2026-08-20).
4+
5+
## Auth pieces (scattered today)
6+
- Codex/ChatGPT: `listOpenAiForwardSidecarCandidates` (src/providers/openai-sidecar.ts:56) — canonical forward provider, pinned baseUrl; `isCodexAuthContextUsable` (src/codex/auth-context.ts:613) — per-context account usability.
7+
- Anthropic: `findAnthropicSidecarProvider` (src/web-search/index.ts:87) and `findAnthropicVisionProvider` (src/vision/index.ts:219) — DUPLICATED predicate: enabled + adapter==="anthropic" + authMode==="oauth" + active account needsReauth!==true.
8+
9+
## Backend resolution asymmetry (issue-confirmed)
10+
- Web-search `resolveSidecarBackend` (src/web-search/index.ts:104-108): explicit anthropic else openai. types/config.ts:787-796 comment claims "unset prefers anthropic" — WRONG vs code.
11+
- Vision `resolveVisionBackend` (src/vision/index.ts:231-236): unset prefers anthropic when credential exists. Opposite default.
12+
13+
## Picker sets
14+
- `visibleNativeSlugs` (src/codex/catalog/metadata.ts:331): nativeOpenAiSlugs − disabled − alias-shadowed.
15+
- `listManagementModelRows` (src/server/management/model-rows.ts:50): native rows (incl. disabled, flagged) + account-bound + routed catalog rows.
16+
- `visionCandidateRows` (src/server/management/vision-sidecar-options.ts:45): rows.filter(disabled !== true) — close to picker policy but no auth-slot concept.
17+
18+
## Vision candidate expansion defect
19+
- `visionEligibleModelOptions` (src/vision/eligibility.ts:201): iterates ALL passed candidates + baselines. Candidates from visionCandidateRows = full catalog (all providers' rows), not picker-limited native set; anthropic side gated only by provider name match.
20+
21+
## Write gates
22+
- Vision: PUT /api/sidecar-settings (config-routes.ts:584) rejects via `visionDescriberIsProvablyBlind`. Claude-code override shares module.
23+
- Web-search: config-routes.ts:604-606 persists webSearch.model verbatim. NO GATE.
24+
25+
## GUI
26+
- gui/src/pages/dashboard-overview-sections.tsx + use-dashboard-data.ts render webSearch/vision sidecar settings; GET /api/sidecar-settings returns visionModels options but NO webSearchModels options list.
27+
28+
## CLI
29+
- No ocx sidecar command exists (src/cli/ has no sidecar.ts; only GUI/PUT paths).
30+
31+
## Tests nearby
32+
tests/vision-eligibility.test.ts, tests/sidecar-settings-vision-filter.test.ts, tests/web-search.test.ts, tests/sidecar-settings-vision-controls.test.ts, tests/claude-sidecar-override.test.ts.
33+
34+
## Executors that exist today (probe-relevant)
35+
- openai: src/web-search/executor.ts (ChatGPT forward /responses hosted web_search).
36+
- anthropic: src/web-search/anthropic-executor.ts (web_search_20250305 via OAuth Messages).
37+
- NO gemini/grok/zen/exa executor → per #2188 filter rule 2, only openai+anthropic can be active web-search backends in this unit.
38+
39+
40+
## CORRECTION (post-audit)
41+
- isCodexAuthContextUsable is src/codex/auth-context.ts:612 (not 613).
42+
- CLI: `ocx agent sidecar <status|web|vision>` ALREADY EXISTS (src/cli/agent.ts:23) writing PUT /api/sidecar-settings. The gap is only: no --list surface, and the PUT it calls has no web-search membership gate. "No ocx sidecar command exists" above is WRONG.
43+
- Additional ungated write path: PUT /api/claude-code writes webSearchSidecar.model verbatim (src/server/management/agent-settings-routes.ts:1064); `ocx claude config set --web-model` rides it.
44+
- GUI contract: dashboard-shared.ts:273 — an OMITTED visionModels key falls back to the full openai+anthropic union; [] means none. Any new webSearchModels key must always be present.
45+
- GET /api/sidecar-settings grandfathers the persisted vision model into options (config-routes.ts:115).
46+

0 commit comments

Comments
 (0)