Skip to content

Commit d4c35fd

Browse files
committed
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.
1 parent 60f60b6 commit d4c35fd

3 files changed

Lines changed: 88 additions & 1 deletion

File tree

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

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,18 @@ 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). Writes through
24+
`--model` go to the same management route as the GUI and are subject to the same gate, so a
25+
model outside the listed set is refused rather than persisted.
26+
27+
```bash
28+
ocx agent sidecar web --list
29+
ocx agent sidecar web --model gpt-5.6-luna
30+
```
31+
2032
### `ocx v2 <status|on|off|mode <v1|default|v2>|keep-native-v1 <on|off>|threads <n>|mode-hint <text|--clear>>`
2133

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

‎src/cli/agent.ts‎

Lines changed: 24 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ const USAGE = `Usage:
2020
ocx agent effort <status|set> [--main <level|->] [--subagent <level|->] [--json]
2121
ocx agent subagents <status|set|clear> [model,model...] [--json]
2222
ocx agent fallback <status|set|clear> [model,model...] [--poll-ms <5000-600000>] [--json]
23-
ocx agent sidecar <status|web|vision> [--model <id|->] [--backend <openai|anthropic|->]
23+
ocx agent sidecar <status|web|vision> [--list] [--model <id|->] [--backend <openai|anthropic|->]
2424
[--reasoning <level>] [--max-descriptions <n>] [--json]`;
2525

2626
function clearable(value: string | undefined): string | null | undefined {
@@ -152,6 +152,29 @@ async function sidecar(argv: string[], deps: RuntimeApiDeps): Promise<void> {
152152
return;
153153
}
154154
if (section !== "web" && section !== "vision") throw new CliUsageError("sidecar must be web, vision, or status", USAGE);
155+
// --list must be consumed BEFORE rejectArgs sees it. It prints the server's
156+
// candidate set — the exact list the GUI picker shows (#2188): the server
157+
// computes it once and every surface consumes it, so the CLI cannot drift.
158+
const wantsList = takeFlag(args, "--list");
159+
if (wantsList) {
160+
rejectArgs(args, USAGE);
161+
const settings = await runtimeRequest("/api/sidecar-settings", {}, deps) as {
162+
webSearchModels?: Array<{ value: string; authSlot?: boolean }>;
163+
visionModels?: Array<{ value: string; backend?: string; baseline?: boolean }>;
164+
};
165+
if (section === "web") {
166+
const options = settings.webSearchModels ?? [];
167+
printData(options, wantsJson, options.length === 0
168+
? ["no runnable web-search sidecar models (log in to ChatGPT or Anthropic)"]
169+
: options.map(option => `${option.value}${option.authSlot ? " (auth slot)" : ""}`));
170+
} else {
171+
const options = settings.visionModels ?? [];
172+
printData(options, wantsJson, options.length === 0
173+
? ["no eligible vision describers"]
174+
: options.map(option => `${option.value}${option.backend ? ` [${option.backend}]` : ""}${option.baseline ? " (baseline)" : ""}`));
175+
}
176+
return;
177+
}
155178
const model = takeOption(args, "--model");
156179
const backend = takeOption(args, "--backend");
157180
const reasoning = takeOption(args, "--reasoning");

‎tests/cli-headless-parity.test.ts‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,58 @@ import { handleProviderRuntimeCommand } from "../src/cli/provider-runtime";
1313
type Recorded = { path: string; method: string; body: unknown };
1414
const servers: Array<ReturnType<typeof Bun.serve>> = [];
1515

16+
describe("ocx agent sidecar --list (#2188)", () => {
17+
test("web --list prints the server's webSearchModels — the GUI's exact list", async () => {
18+
const { requests, deps } = fakeRuntime(req => {
19+
const url = new URL(req.url);
20+
if (url.pathname === "/api/sidecar-settings" && req.method === "GET") {
21+
return {
22+
webSearchModels: [
23+
{ value: "gpt-5.6-luna", label: "gpt-5.6-luna", authSlot: true },
24+
{ value: "gpt-5.6-terra", label: "gpt-5.6-terra" },
25+
],
26+
visionModels: [],
27+
};
28+
}
29+
return undefined;
30+
});
31+
const logSpy = spyOn(console, "log").mockImplementation(() => {});
32+
try {
33+
const code = await handleAgentCommand(["sidecar", "web", "--list"], deps);
34+
expect(code).toBe(0);
35+
// Read-only: --list must GET, never PUT.
36+
expect(requests.every(r => r.method === "GET")).toBe(true);
37+
const out = logSpy.mock.calls.map(call => String(call[0])).join("\n");
38+
expect(out).toContain("gpt-5.6-luna (auth slot)");
39+
expect(out).toContain("gpt-5.6-terra");
40+
} finally {
41+
logSpy.mockRestore();
42+
}
43+
});
44+
45+
test("vision --list prints visionModels with backend tags; empty set names the reason", async () => {
46+
const { deps } = fakeRuntime(req => {
47+
const url = new URL(req.url);
48+
if (url.pathname === "/api/sidecar-settings" && req.method === "GET") {
49+
return { webSearchModels: [], visionModels: [{ value: "claude-haiku-4-5", label: "claude-haiku-4-5", backend: "anthropic", baseline: true }] };
50+
}
51+
return undefined;
52+
});
53+
const logSpy = spyOn(console, "log").mockImplementation(() => {});
54+
try {
55+
expect(await handleAgentCommand(["sidecar", "vision", "--list"], deps)).toBe(0);
56+
const visionOut = logSpy.mock.calls.map(call => String(call[0])).join("\n");
57+
expect(visionOut).toContain("claude-haiku-4-5 [anthropic] (baseline)");
58+
logSpy.mockClear();
59+
expect(await handleAgentCommand(["sidecar", "web", "--list"], deps)).toBe(0);
60+
const webOut = logSpy.mock.calls.map(call => String(call[0])).join("\n");
61+
expect(webOut).toContain("no runnable web-search sidecar models");
62+
} finally {
63+
logSpy.mockRestore();
64+
}
65+
});
66+
});
67+
1668
afterEach(() => {
1769
for (const server of servers.splice(0)) server.stop(true);
1870
process.exitCode = 0;

0 commit comments

Comments
 (0)