Skip to content

Commit 1e7c45b

Browse files
authored
feat(cli): ocx agent sidecar --list shares the server candidate sets (#2188 L5) (#2211)
* feat(cli): ocx agent sidecar --list prints the server's candidate sets (#2188) --list GETs /api/sidecar-settings and prints webSearchModels or visionModels — the exact filtered lists the GUI picker consumes, so the CLI cannot drift from the server policy. Writes already flow through the gated PUT. Parsed before rejectArgs; read-only by construction. Docs describe the surface and the shared gate. * docs+test(cli): state the per-sidecar gate honestly and pin --list request shape * docs(devlog): record live probe results for all five web-search protocol lanes * docs(devlog): roadmap for three new web-search backends (xai/gemini/exa) Grok built-in tool research (003, Luna swarm + live OAuth captures) and audited decade docs 060-090: inert union widening, executor layers with core.ts dispatch wiring, pinned CCA destination, exa key redaction, and probe-resolved xAI wire shapes. Seven audit findings folded in; docs consolidated to single executable contracts. * fix(cli): preserve sidecar backend provenance * fix(cli): preserve explicit sidecar backend clear
1 parent 60f60b6 commit 1e7c45b

9 files changed

Lines changed: 394 additions & 1 deletion

File tree

‎devlog/_plan/260820_sidecar_selection_unification/002_protocol_research.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,3 +40,29 @@ Luna swarm (5 lanes) + primary-source verification. All findings below were sour
4040
2. Anthropic executor (anthropic-executor.ts) currently pins web_search_20250305 — fine (not deprecated, ZDR-eligible, direct default). Upgrading to 20260209 would REQUIRE allowed_callers:["direct"] — record as follow-up, not this unit.
4141
3. encrypted_content replay + srvtoolu_ pairing are existing executor obligations — verify tests cover replay-unchanged before touching anthropic paths in L3.
4242

43+
44+
## LIVE PROBE RESULTS (2026-08-21, this machine, ocx credentials)
45+
46+
All five lanes verified live. Raw scripts in .tmp/probes/ (gitignored scratch).
47+
48+
### OpenAI (ChatGPT forward) — PASS, shipped executor
49+
runWebSearch via main-account token against chatgpt.com/backend-api/codex/responses, model gpt-5.6-luna: 287 text chars, 2 sources with url+title. Executor path proven end to end.
50+
51+
### Anthropic (stored OAuth) — PASS, shipped executor
52+
runAnthropicWebSearch via anthropic OAuth, model claude-haiku-4-5, web_search_20250305: 150 result chars, outcome keys {text, sources}. Executor path proven end to end.
53+
54+
### xAI Responses (Grok OAuth, api.x.ai/v1/responses, grok-4.6) — PASS with two contract findings
55+
- web_search: HTTP 200. SSE events response.web_search_call.in_progress|searching|completed (6 each), item types reasoning/web_search_call/message, id prefixes rs_/ws_/msg_. Matches the OpenAI-shaped contract 002 predicted; the undocumented SSE names are now probe-confirmed.
56+
- x_search: HTTP 200 BUT the server emits it as custom_tool_call items (ctc_ prefix) with response.custom_tool_call_input.delta/done events — NOT x_search_call as docs.x.ai implies for Responses. allowed_x_handles accepted (200). Consequence for #2190: the OAuth transport's wire item is custom_tool_call; #2173's ctc_ prefix handling already covers the id family, but a dedicated x_search_call extractor would see nothing on this transport. Re-probe with an api.x.ai API key before assuming parity.
57+
58+
### Gemini (Antigravity CCA OAuth) — PASS
59+
v1internal:generateContent envelope (project from stored credential, ANTIGRAVITY_REQUEST_UA, wireModelId gemini-3.7-flash-tiered) with tools [{google_search:{}}]: HTTP 200, grounded answer, groundingMetadata {webSearchQueries:2, groundingChunks:2, groundingSupports:1, searchEntryPoint present}. Plain "antigravity" UA gets 404 (fingerprint gate) — any future executor must reuse the adapter's UA + envelope builder.
60+
NOTE: this proves the CCA transport grounds; AI-Studio-key transport (x-goog-api-key) remains unprobed (no key on this machine).
61+
62+
### Exa /search — PASS (new account, key stored at ~/.opencodex/.exa-probe-key, 0600)
63+
POST api.exa.ai/search x-api-key: HTTP 200, {requestId(32-hex), resolvedSearchType, results[3]{id,title,url,publishedDate,text,image,favicon}, searchTime, costDollars{total:0.007}}. result.id === result.url confirmed. resolvedSearchType still present despite docs marking it deprecated. Non-LLM JSON lane shape confirmed for a future SidecarOutcome mapping.
64+
65+
### Registry consequences
66+
- xAI + Gemini(CCA) + Exa all clear the "live probe" half of the WEB_SEARCH_BACKENDS activation bar. Still missing: executors + wire mapping (extractor/relay) per backend — activation stays blocked on the executor half, as designed.
67+
- The x_search custom_tool_call finding narrows #2190 step 1: OAuth-transport probes are done, API-key transport still required.
68+
Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# 003 — Grok built-in tool deep research (2026-08-21, Luna swarm 2 + live OAuth probes)
2+
3+
## Full built-in tool inventory (docs.x.ai, primary)
4+
| Tool | tools[].type | Output item | Price |
5+
|---|---|---|---|
6+
| Web search | web_search | web_search_call | $5/1k |
7+
| X search | x_search | x_search_call (docs) / custom_tool_call (observed) | $5/1k |
8+
| Code execution | code_interpreter | code_interpreter_call | $5/1k |
9+
| Collections/RAG | file_search | file_search_call | $2.50/1k |
10+
| Remote MCP | mcp | mcp_call | tokens only |
11+
| Image generation | image_generation | image_generation_call | Imagine rates |
12+
Internal server-side sub-tools (not request types): search_images, view_image, view_x_video, attachment_search ($10/1k when files attached).
13+
14+
## Live OAuth-transport captures (this machine, grok-4.6)
15+
- web_search + include ["web_search_call.action.sources"]: ws_ item carries action {type:"search", query, sources:[{type:"url",url}...]}. VERIFIED live.
16+
- Annotation SSE envelope (VERIFIED live): response.output_text.annotation.added { annotation: {type:"url_citation", url, start_index, end_index, title}, item_id: msg_..., annotation_index, content_index, output_index }.
17+
- x_search: server emits custom_tool_call items — names observed live: x_user_search; community capture (Vercel ai#10607, API-KEY transport): x_semantic_search. id prefix ctc_, call_id prefix xs_call-. NOT x_search_call on either transport in practice → parse annotations for sources, tolerate both discriminators.
18+
- Inline citation text format: [[N]](url); disable via include ["no_inline_citations"].
19+
- response.citations array documented as always-returned post-tool-execution (docs) — not asserted in our stream capture; treat as secondary channel.
20+
21+
## Params (validated limits)
22+
- web_search: filters.allowed_domains XOR excluded_domains, ≤5 each; enable_image_search, enable_image_understanding.
23+
- x_search: allowed_x_handles XOR excluded_x_handles, ≤20 each; from_date/to_date ISO-8601 inclusive; enable_image_understanding, enable_video_understanding (video is X-only).
24+
- max_turns bounds agentic turns; multiple tool calls can run parallel within a turn; multiple output indexes per response (SDK changelog fix) → reducer-style parsing, never assume 1 tool item.
25+
- tool_choice forced form documented only for functions — do NOT assume forced built-ins.
26+
- action may be ABSENT on response.output_item.added (skeleton-first; fills at .searching) → optional field.
27+
28+
## Transport verdict
29+
OAuth (Grok CLI creds via auth.x.ai) hits the same api.x.ai/v1/responses with Bearer; hosted-tool JSON identical; entitlement 403 is the failure mode distinct from wire errors. API key is the documented default. Our executor uses the stored xai OAuth (present on this machine), fail-closed on 401/403.
30+
31+
## Executor consequences (070)
32+
1. Sources = union of (a) message annotations url_citation urls, (b) ws action.sources urls when include requested. Dedupe by url.
33+
2. Accept both x_search_call and custom_tool_call (name x_*) as x-search activity markers; never fail parse on unknown item types.
34+
3. Buffer text from response.output_text.delta on msg items; strip [[N]](url) markers optional — keep text as-is (they're valid markdown), collect annotations as sources.
35+
4. Bound raw SSE bytes like parseSidecarSSE does; timeout via settings.timeoutMs.
36+
Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# 060 — Layer 6: backend union widening, INERT (wp2) [rev 2, post-audit]
2+
3+
Branch: codex/sidecar-backend-union (base: codex/sidecar-cli).
4+
5+
## Principle (audit F1): union ≠ activation. This layer is INERT for new ids.
6+
- src/types/config.ts backend union: "openai" | "anthropic" | "xai" | "gemini" | "exa". Comment: unset ALWAYS openai; new ids explicit-only AND inactive until their executor layer lands.
7+
- src/web-search/index.ts:
8+
- export type WebSearchBackendId = union above.
9+
- resolveSidecarBackend stays PURE: known id → itself, else/undefined → "openai".
10+
- planWebSearch: for "xai"|"gemini"|"exa" return undefined UNCONDITIONALLY in this layer (fail-closed inert — no plan means the normal routed path, identical to today's unknown-backend behavior). Each executor layer replaces its arm with the real credential-gated plan. This keeps L6 standalone-CI-green with zero dispatch risk (audit F1).
11+
- shouldResolveOpenAiWebSearchSidecar: verify unchanged semantics (backend !== openai → false) for new ids — add test.
12+
- config-routes.ts + agent-settings-routes.ts backend validation strings widened (webSearch only; claude-code override webSearchSidecar.backend union widened in the SAME commit — audit F3 partial: binary types in claude-code section body).
13+
- gui claude-code-types.ts / dashboard-shared.ts SidecarBackend type: NOT widened here (GUI backend selector redesign is explicitly deferred to a follow-up issue — new backends are config/CLI-explicit only; document in docs-site later layer). Audit F3 resolution: GUI cannot select new backends in this program; the write gate + options stay model-centric for openai/anthropic; for xai/gemini the model field is honored, for exa ignored. File a follow-up issue for the GUI backend selector at program end.
14+
- exaApiKey config field: added here as OcxWebSearchSidecarConfig.exaApiKey?: string with: PUT accepts string (empty clears), GET NEVER echoes it (assert), redact.ts gains "exaApiKey" in its key list (audit F4) + structured redaction test.
15+
- structure/04_transports-and-sidecars.md + 05_gui-and-management-api.md: update the two-backend claims (audit F7).
16+
17+
## Tests: tests/web-search-backend-union.test.ts
18+
- resolveSidecarBackend(undefined)==="openai" pin; ("xai")==="xai".
19+
- planWebSearch xai/gemini/exa → undefined (inert pin, will be flipped per layer).
20+
- shouldResolveOpenAiWebSearchSidecar false for new ids.
21+
- PUT backend "xai" ok / "zen" 400; exaApiKey set/clear; GET omits exaApiKey; redactSecrets strips exaApiKey.
22+
23+
## Verify (audit F7): bun x tsc --noEmit && bun run test (FULL) per layer from now on.
24+
Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# 070 — Layer 7: xAI executor + x_search opt-in (wp3) [rev 2, consolidated]
2+
3+
Branch: codex/sidecar-xai-executor (base: codex/sidecar-backend-union).
4+
5+
## New file: src/web-search/xai-executor.ts (research: 003; wire probes 2026-08-21 all HTTP 200)
6+
```ts
7+
export interface XaiSearchOptions { xSearch?: boolean; allowedXHandles?: string[]; excludedXHandles?: string[]; fromDate?: string; toDate?: string; }
8+
export function validateXaiSearchOptions(o): string | undefined // 20-handle cap, allow XOR exclude, ISO date shape
9+
export async function runXaiWebSearch(query, providerName, provider, settings, options, abortSignal?): Promise<SidecarOutcome>
10+
```
11+
- Token: getValidAccessToken(providerName) (stored xai OAuth). 401/403 → error outcome with entitlement-distinct message. Never throws.
12+
- POST https://api.x.ai/v1/responses (canonical; provider.baseUrl consulted only if it matches the api.x.ai origin, else pinned) with redirect: "manual".
13+
- Body: { model: settings.model (default "grok-4.6"), input: [{role:"user", content: query}], tools: [{type:"web_search"}, ...(options.xSearch ? [{type:"x_search", allowed_x_handles?/excluded_x_handles?/from_date?/to_date?}] : [])], include: ["web_search_call.action.sources"], reasoning: { effort: settings.reasoning }, stream: true }. All shapes probe-verified (reasoning+tools 200; both tools in one request 200; handles+dates 200) — no contingency paths.
14+
- SSE reducer (003 rules): text ← response.output_text.delta on message items; sources ← url_citation annotations ∪ web_search_call action.sources, deduped by url; tolerate BOTH custom_tool_call and x_search_call items; action optional on output_item.added (skeleton-first); bound raw bytes like parse.ts; reasoning deltas ignored.
15+
16+
## Config
17+
- OcxWebSearchSidecarConfig gains xSearch?: { enabled?: boolean; allowedXHandles?: string[]; excludedXHandles?: string[]; fromDate?: string; toDate?: string }.
18+
- PUT /api/sidecar-settings validates (400 on >20 handles, allow+exclude both set, malformed date); executor re-validates (defense in depth). GET echoes xSearch (no secrets involved).
19+
20+
## Dispatch wiring (the audited path)
21+
- SidecarPlan gains xaiSidecar?: { providerName: string; provider: OcxProviderConfig }.
22+
- planWebSearch "xai" arm becomes REAL (flips 060's inert undefined): enabled provider named/oauthId "xai" + getAccountSet active !needsReauth → plan with xaiSidecar; else undefined (fail-closed).
23+
- src/server/responses/core.ts (~:3583, where SidecarPlan unpacks into WebSearchLoopDeps): pass backend + xaiSidecar through.
24+
- loop.ts: WebSearchLoopDeps gains xaiSidecar; dispatch switch gains "xai" arm → runXaiWebSearch with cfg.xSearch options.
25+
- backends.ts registry: { backend:"xai", isActive: stored xai OAuth usable, eligibleModel: candidate.provider === "xai" }.
26+
27+
## Tests: tests/xai-web-search.test.ts + loop integration
28+
- validateXaiSearchOptions: 21 handles error; allow+exclude error; bad date error.
29+
- SSE fixtures from live capture shapes: text assembly, source dedupe (annotations ∪ action.sources), custom_tool_call tolerated, absent action tolerated.
30+
- 401 fixture → error outcome, no throw. PUT xSearch validation 400s.
31+
- Loop-level integration: backend "xai" dispatches the xai executor (mocked), not runWebSearch.
32+
33+
## Verify (per-layer full gate): bun x tsc --noEmit && bun run test && live probe via the actual executor (attest evidence).
34+
Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# 080 — Layer 8: Gemini CCA executor (wp4) [rev 2, consolidated]
2+
3+
Branch: codex/sidecar-gemini-executor (base: codex/sidecar-xai-executor).
4+
5+
## New file: src/web-search/gemini-executor.ts (probe: 002 LIVE PROBE)
6+
```ts
7+
export async function runGeminiWebSearch(query, providerName, provider, settings, abortSignal?): Promise<SidecarOutcome>
8+
```
9+
- Credential: getValidAccessTokenSnapshot(providerName) + projectId from the active stored credential. Missing projectId → error outcome naming re-login. Never throws.
10+
- Destination PINNED to the registry canonical CCA endpoint exactly as src/server/images.ts:211 does — provider.baseUrl is NOT trusted for the OAuth-bearing request (mutable-URL credential leak). redirect: "manual".
11+
- POST {pinned}/v1internal:generateContent (non-stream; grounded answers are short) with envelope: { model: wireModelId, userAgent: "antigravity", requestType: "agent", project, requestId: "agent-"+uuid, request: { contents: [user query], tools: [{google_search:{}}], sessionId: uuid, generationConfig?: { thinkingConfig: { thinkingLevel } } } }.
12+
- Reasoning: settings.reasoning maps through resolveAntigravityEffortWireModel(settings.model default "gemini-3.7-flash", effort, pinnedBase) → { wireModelId, thinkingLevel }; thinkingLevel set when returned, NOT discarded.
13+
- Headers: User-Agent: ANTIGRAVITY_REQUEST_UA (002: plain UA gets 404), Authorization Bearer.
14+
- Mapping: candidates[0].content.parts[].text joined → text; groundingMetadata.groundingChunks[].web {uri,title} → sources; absent metadata → sources [].
15+
- Imports: ONLY google-antigravity-wire (UA) + providers/antigravity-models (wire model) — auditor-verified lean, no google.ts drag, no cycle.
16+
17+
## Dispatch wiring (mirrors 070)
18+
- SidecarPlan.geminiSidecar; planWebSearch "gemini" arm real (google-antigravity provider enabled + OAuth + projectId → plan; else undefined); core.ts handoff; loop.ts arm; registry { backend:"gemini", isActive: OAuth usable + projectId present, eligibleModel: candidate.provider === "google-antigravity" }.
19+
20+
## Tests: tests/gemini-web-search.test.ts + loop integration
21+
- Fixture (002 capture) → text + sources; absent groundingMetadata → []; missing projectId → error; envelope assertion incl. thinkingConfig when effort maps; destination-pinning assertion (baseUrl override ignored).
22+
23+
## Verify (per-layer full gate): bun x tsc --noEmit && bun run test && live probe via executor.
24+
Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# 090 — Layer 9: Exa executor + top validation (wp5) [rev 2, consolidated]
2+
3+
Branch: codex/sidecar-exa-executor (base: codex/sidecar-gemini-executor).
4+
5+
## New file: src/web-search/exa-executor.ts (probe: 002 — non-LLM lane)
6+
```ts
7+
export async function runExaWebSearch(query, apiKey, settings, abortSignal?): Promise<SidecarOutcome>
8+
```
9+
- POST https://api.exa.ai/search, headers x-api-key, redirect: "manual" (Bun forwards custom headers across redirects). Body { query, numResults: 5, contents: { text: { maxCharacters: 1000 } } }.
10+
- Mapping: results[] → sources [{url, title}]; text = per-result "Title — snippet (url)" digest (Exa returns no prose; the routed model synthesizes). resolvedSearchType/costDollars ignored.
11+
- ALL upstream error strings pass redactSecretString; a canary-key test asserts the key never reaches the outcome.
12+
13+
## Key handoff (audited path)
14+
- core.ts reads config.webSearchSidecar.exaApiKey at plan-unpack; WebSearchLoopDeps.exaApiKey?: string; SidecarPlan carries only exaConfigured: true. loop.ts "exa" arm → runExaWebSearch(query, deps.exaApiKey, ...).
15+
- redact.ts "exaApiKey" entry + GET-never-echo landed in 060; this layer adds the runtime canary test.
16+
17+
## GUI stance (fixed in 060)
18+
- No GUI backend selector this program; exa is config/CLI-explicit. exa has no model candidates (eligibleModel: () => false); webSearchModels for openai/anthropic backends unchanged. Follow-up GUI-selector issue filed at program end.
19+
20+
## Docs
21+
- docs-site guides/sidecars.md + reference/configuration/server.md: new-backends section (explicit-only, credentials, x_search opt-in, exa key). English only.
22+
23+
## Final verification (top of stack)
24+
- bun run typecheck && bun run test (FULL) && bun run privacy:scan && bun run lint:gui.
25+
- Live executor probes for all three backends as attest evidence; gh pr list chain → goalplan c6.
26+
27+
## Tests: tests/exa-web-search.test.ts — fixture mapping, error non-throw, canary-key redaction.
28+

‎docs-site/src/content/docs/reference/cli/agents.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,22 @@ surface modes, delegation, effort, and fallback behavior fit together.
1717
ocx agent subagents set ark/model-a,openai/gpt-5.5
1818
```
1919

20+
`ocx agent sidecar web --list` and `ocx agent sidecar vision --list` print the models the
21+
server currently offers for each sidecar — the exact filtered set the dashboard picker shows
22+
(picker-visible rows plus the login-entitled Luna/Haiku auth slots, intersected with executor
23+
availability for web search, minus provably text-only models for vision). Human-readable lists
24+
show each model's backend in brackets. A web-search `--model` write resolves that server-offered
25+
row and persists its backend and model together, so switching to an Anthropic option cannot keep
26+
an OpenAI backend (or vice versa). Writes go to the same management route as the GUI and are
27+
subject to the same per-sidecar gate: web search refuses a backend/model pair outside the listed
28+
set (closed membership), while vision refuses only a model provably unable to see (unknown ids
29+
stay writable).
30+
31+
```bash
32+
ocx agent sidecar web --list
33+
ocx agent sidecar web --model gpt-5.6-luna
34+
```
35+
2036
### `ocx v2 <status|on|off|mode <v1|default|v2>|keep-native-v1 <on|off>|threads <n>|mode-hint <text|--clear>>`
2137

2238
Manage the Codex `multi_agent_v2` feature flag and the three-state multi-agent surface mode.

0 commit comments

Comments
 (0)