Skip to content

Commit c70f412

Browse files
authored
Merge pull request #2773 from lidge-jun/codex/ocx-agentic-control-roadmap
docs(devlog): plan the ocx agentic control surface roadmap
2 parents 80e251a + d083f32 commit c70f412

16 files changed

Lines changed: 2177 additions & 0 deletions
Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
# 000 — ocx as a complete agentic control surface
2+
3+
## Objective
4+
5+
Make the `ocx` CLI a complete, scriptable control surface for every capability the
6+
web dashboard exposes, so an AI agent can operate opencodex end to end from a
7+
terminal with machine-readable output and honest exit codes. Close the ten
8+
operator-facing CLI issues (#2696-#2705) at their root causes rather than at their
9+
symptoms, give help a single source of truth that a test can hold to the API
10+
surface, and ship a repo-owned agent skill that documents the resulting surface.
11+
12+
## Why this unit exists
13+
14+
The dashboard is the complete surface today and the CLI is a partial mirror of it.
15+
Three separate failure classes make the CLI unusable for unattended agent control:
16+
17+
1. **Transport dishonesty.** `ocx models live` and `ocx provider quota` print an
18+
error and exit 0 (#2697); a 503 arrives with a `reason` and `hint` the CLI
19+
never renders (#2698); a launchd install can fence the entire management plane
20+
closed and the CLI cannot say why (#2696); the PATH binary can be older than
21+
the running proxy while its help claims otherwise (#2701).
22+
2. **DTO loss.** The API already returns fields the CLI throws away: usage
23+
`accounts[]` (#2700), account `paused` and the 5h quota window (#2703), access
24+
key `usage.requests7d`/`lastUsedAt` (#2705). One of these is worse than filed:
25+
`projectQuota` strips `fiveHourPercent` before any renderer runs.
26+
3. **Missing verbs.** Pause/resume, pool strategy, sticky limit (#2702) and
27+
`logs --conversationId` (#2704) exist as routes with no CLI caller, plus 13
28+
further GUI-only capability classes found by inventory.
29+
30+
Underneath all three sits the real defect: **there is no source of truth binding
31+
the CLI surface to the API surface.** Help lives in a hand-written 69-line banner
32+
plus 37 module-level usage blocks — 20 of them exported constants with zero
33+
consumers outside their own files — all free to drift. Nothing fails when a route
34+
lands with no verb.
35+
36+
## Constraints
37+
38+
- Bun-native TypeScript. No compile step, no Node-only APIs.
39+
- `src/lab/` must stay off the core request path; `tests/core-lab-boundary.test.ts`
40+
and the `startServer` synchronous-window scan are hard gates.
41+
- Management auth is applied before dispatch for every `/api/` path. Three routes
42+
require a browser session and MUST NOT get a CLI verb: `POST /api/github/star`
43+
(user-consent boundary, `AGENTS_INSTALL.md`), the non-GET `/api/codex-prompt*`
44+
verbs, and `POST /api/providers/reload` (capability principal, not a session).
45+
- `PUT /api/config` is a deliberate 405. Not a parity target.
46+
- No security triage in `devlog/`. Scratch space only.
47+
- Per the operator's instruction for this unit: no local full-suite runs during
48+
build, no per-push CI polling, `--no-verify` pushes, and a single final
49+
rebase-onto-`dev` plus parallel CI triage at the end.
50+
51+
## Measured surface (see 001, 002, 003)
52+
53+
| Surface | Count | Source |
54+
|---|---|---|
55+
| Reachable management routes | 183 (108 mutating) | 001 |
56+
| Dead/shadowed routes | 1 (`GET /api/storage` in logs-usage-routes) | 001 |
57+
| Session-only routes (never CLI) | 3 | 001 |
58+
| CLI dispatch runner keys | 57; registry 58 entries, 52 visible | 002 |
59+
| Disconnected help sources | 37 usage blocks (20 dead module exports) + 1 banner | 002 |
60+
| GUI-only capability classes | 13 declared, 8 real gaps after exemptions | 003 |
61+
| Reviewer blockers folded at the A gate | 7 blockers + 4 medium + 2 low | 005 |
62+
63+
## Work-phase map (dependency-ordered, PHASE-SPLIT-01)
64+
65+
Each phase consumes the verified output of the previous one. Ordering is by build
66+
structure — contract first, then the machinery that depends on the contract, then
67+
the capabilities that machinery exposes, then documentation of the finished
68+
surface — not by effort or payoff.
69+
70+
| Phase | Doc | Deliverable | Depends on |
71+
|---|---|---|---|
72+
| wp2 | `010` | Transport honesty: exit codes, error rendering, token-collision refusal (#2697 #2698 #2696) | — |
73+
| wp3 | `020` | Capability registry as help SoT + API/CLI parity test + version skew (#2701) | wp2 |
74+
| wp3b | `025` | Uniform CLI contract: exit codes and `--json` order-independence | wp3 |
75+
| wp4 | `030` | DTO fidelity (#2700 #2703 #2705) | wp3b |
76+
| wp5 | `040` | New verbs and filters (#2702 #2704) | wp3 |
77+
| wp6 | `050` | Per-account OAuth usage attribution (#2699) | wp4 |
78+
| wp7 | `060` | Residual GUI-parity closure (13 capability classes) | wp3 wp5 |
79+
| wp8 | `070` | `ocx` agent skill + docs-site CLI reference | wp7 |
80+
| wp9 | `080` | Stack rebase onto `dev`, final parallel CI triage | all |
81+
82+
wp2 comes first because every later phase is verified through CLI output: a phase
83+
that lands while `ocx` still exits 0 on failure cannot be proven. wp3 comes second
84+
because the registry it introduces is the thing every later phase registers into —
85+
adding verbs before the registry means writing them twice.
86+
87+
wp3b exists because the uniform exit-code and `--json` contract *consumes* wp3's
88+
capability table (its tests read each capability's declared `json` mode), so it is a
89+
successor phase rather than a slice carved off to balance effort. PHASE-SPLIT-01
90+
forbids effort buckets, not dependency-ordered successors.
91+
92+
wp6 follows wp4 rather than preceding it so that the `accounts` renderer already
93+
exists when the labels start being stamped — the phase's proof is then visible in
94+
`ocx usage` immediately instead of requiring a later phase to demonstrate it.
95+
96+
## Delivery shape
97+
98+
A stacked pull-request chain (DEV-STACK-01), one PR per work-phase, each child
99+
targeting its parent's head branch. Base of the stack is `origin/dev`.
100+
101+
```
102+
dev
103+
└── codex/ocx-agentic-control-roadmap wp1 (this unit's docs, PR #2773)
104+
└── codex/ocx-transport-honesty wp2
105+
└── codex/ocx-capability-registry wp3
106+
└── codex/ocx-uniform-contract wp3b
107+
└── codex/ocx-dto-fidelity wp4
108+
└── codex/ocx-new-verbs wp5
109+
└── codex/ocx-account-attribution wp6
110+
└── codex/ocx-gui-parity wp7
111+
└── codex/ocx-agent-skill wp8
112+
```
113+
114+
## Accept criteria for the unit
115+
116+
1. Every non-session, non-405 management capability has a CLI verb with `--json`.
117+
2. A parity test fails when a route lands with no verb and no recorded exemption.
118+
3. Help is generated from the registry; no hand-maintained command list survives.
119+
4. Every management failure path exits non-zero and prints `reason` and `hint`.
120+
5. A repo-owned skill documents the surface with copy-paste recipes.
121+
6. The whole stack is rebased on current `dev` with CI green.
122+
123+
## Terminal-outcome definitions
124+
125+
`DONE` requires all six above proven against the tree, not remembered.
126+
`BLOCKED` is a platform or credential refusal. `UNSAFE` is any fix that would
127+
weaken the admin-token or session boundary — stop and ask instead.
128+
`NEEDS_HUMAN` is a CLI-grammar choice the operator must make.
Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
# 001 — Management API route inventory
2+
3+
Source: read of `src/server/management-api.ts`, `src/server/management/*`,
4+
`src/codex/auth-api.ts`, `src/codex/native-profile-api.ts` at `50e955604`.
5+
6+
## How dispatch works
7+
8+
There is no route table and no framework. Every route is a hand-written
9+
`if (url.pathname === … && req.method === …)` inside one of 17 handler functions,
10+
chained with `??` in `src/server/management-api.ts` around line 220. First handler
11+
returning non-`null` wins; a handler returning `null` falls through. **Dispatch is
12+
order-sensitive.**
13+
14+
Auth is applied *before* dispatch, in `src/server/index.ts` near line 1010: every
15+
`/api/` path passes `requireManagementAuth`. No management route is unauthenticated.
16+
Individual routes then re-check the principal for consent.
17+
18+
`pathInManagementNamespace` (management-api.ts:102) matches exact-or-child only, so
19+
`/api/labfoo` deliberately does not match `/api/lab`.
20+
21+
## Totals
22+
23+
- **183 reachable routes** across 19 files; **108 mutating**.
24+
- **1 dead route**: `GET /api/storage` at `logs-usage-routes.ts:346` is shadowed by
25+
the identical claim at `storage-log-guard-routes.ts:150`, which runs earlier in the
26+
chain and always returns. The live payload is the guard version (scan plus
27+
`codexLogs`/`codexLogsError`). Audit parity against the guard version.
28+
- `/api/codex-auth/*` is gated by a `startsWith("/api/codex-auth/")` check with a
29+
trailing slash, so a bare `/api/codex-auth` 404s.
30+
31+
## Auth classes
32+
33+
| Class | Meaning | Routes |
34+
|---|---|---|
35+
| admin | admin token or GUI session (default gate) | ~177 |
36+
| session | minted GUI session required; admin token gets 403 | `POST /api/github/star`, the 6 non-GET `/api/codex-prompt*` verbs |
37+
| cap | process-scoped HMAC capability principal | `POST /api/providers/reload`; read-cap for `/api/codex-auth/accounts` and `/api/system/memory` |
38+
39+
The capability principals are narrow and replay-protected: local reads are limited
40+
to exactly those two paths with `url.search` required empty
41+
(`src/lib/local-management-capability.ts:10`).
42+
43+
## Registration mechanisms a naive `rg '/api/'` misses
44+
45+
| Mechanism | Where | What is missed |
46+
|---|---|---|
47+
| 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 |
48+
| 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/` |
49+
| 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` |
50+
| Prefix-decoded wildcard | integration-routes.ts:129 | `GET|PUT /api/client-integrations/{clientId}` |
51+
| Regex params | model-routes, lab-routes, lab-automation-routes | 7 routes |
52+
| Suffix matching | request-history-routes.ts:131 | `/route-decision` found via `endsWith` |
53+
| Namespace guards that swallow siblings | codex-prompt:278, request-history:47, lab:285 | unmatched children 404 from index.ts rather than falling through |
54+
55+
**This table is the parity test's hard requirement.** A parity test that greps for
56+
`'/api/…'` string literals would miss 40+ routes and pass vacuously. The test must
57+
enumerate from a declared registry, not from source text.
58+
59+
## Route families (grouped for CLI parity)
60+
61+
| Family | Routes | Existing CLI reach |
62+
|---|---|---|
63+
| 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` |
64+
| startup/tray | `/api/startup-health`, `/api/startup-action`, `/api/windows-tray` GET+POST | `ocx system` partial |
65+
| update | `/api/update/check`, `/run`, `/status`, `/badge` | `ocx system`, `ocx update` |
66+
| sidecar/shadow | `/api/sidecar-settings` GET+PUT, `/api/shadow-call-settings` GET+PUT | `ocx agent`, `ocx models` |
67+
| 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*` |
68+
| 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` |
69+
| request history | `/api/request-history`, `/{id}`, `/{id}/route-decision` | `ocx observe` partial |
70+
| routing | `/api/routing-profiles` GET+PUT+DELETE, `/dry-run`, `/api/routing-analytics` | `ocx route policy` |
71+
| 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 |
72+
| 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 |
73+
| combos | `/api/combos` GET+PUT+DELETE | `ocx combo` |
74+
| 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 |
75+
| 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 |
76+
| access keys | `/api/keys` GET+POST+PATCH+DELETE | `ocx access key` list/create/remove; PATCH rename has no verb |
77+
| 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 |
78+
| 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 |
79+
| native main profiles | 10 routes under `/api/native-main-profiles` | `ocx account main` |
80+
| system | `/api/system/memory`, `/windows-replace-retries`, `/restart`, `/codex-app-server`, `/codex-restart`, `/api/stop` | `ocx restart`, `ocx stop`, `ocx observe memory` |
81+
| lab | 20 read routes + `/public/*` 4 + automation 5 | `ocx lab` reads local SQLite, never the HTTP routes |
82+
| sidebar | `/api/github/star` GET+POST(session) | GET has no verb; POST must never get one |
83+
84+
## Cross-cutting error envelopes
85+
86+
From management-api.ts:237 — a CLI client should encode these once:
87+
88+
- `413 request body too large` (2 MB cap)
89+
- `403 cross-origin request blocked`
90+
- `503 oauth_mutation_busy`, `503 catalog_busy` (both with `Retry-After: 1`)
91+
- `503 CONFIG_MUTATION_LOCK_UNAVAILABLE` for the codex-auth family
92+
- `503` with `reason` + `hint` from `src/server/management-auth.ts:455`
93+
94+
The last one is #2698: the fields exist and the CLI does not print them.

0 commit comments

Comments
 (0)