Skip to content

Commit 8a8a548

Browse files
NathanFlurryNathanFlurry
committed
feat: add configuration for model, mode, and thought level
1 parent c3a95c3 commit 8a8a548

File tree

11 files changed

+1090
-20
lines changed

11 files changed

+1090
-20
lines changed

‎CLAUDE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,7 @@
8686
- Regenerate `docs/openapi.json` when HTTP contracts change.
8787
- Keep `docs/inspector.mdx` and `docs/sdks/typescript.mdx` aligned with implementation.
8888
- Append blockers/decisions to `research/acp/friction.md` during ACP work.
89+
- `docs/agent-capabilities.mdx` lists models/modes/thought levels per agent. Update it when adding a new agent or changing `fallback_config_options`. If its "Last updated" date is >2 weeks old, re-run `cd scripts/agent-configs && npx tsx dump.ts` and update the doc to match. Source data: `scripts/agent-configs/resources/*.json` and hardcoded entries in `server/packages/sandbox-agent/src/router/support.rs` (`fallback_config_options`).
8990
- TypeScript SDK tests should run against a real running server/runtime over real `/v1` HTTP APIs, typically using the real `mock` agent for deterministic behavior.
9091
- Do not use Vitest fetch/transport mocks to simulate server functionality in TypeScript SDK tests.
9192

‎docs/agent-capabilities.mdx‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
---
2+
title: "Agent Capabilities"
3+
description: "Models, modes, and thought levels supported by each agent."
4+
---
5+
6+
See [Agent Sessions](/agent-sessions) for full session configuration API details.
7+
8+
9+
<Info>
10+
_Last updated: March 3rd, 2026. See [Generating a live report](#generating-a-live-report) for up-to-date reference._
11+
</Info>
12+
13+
## Claude
14+
15+
| Category | Values |
16+
|----------|--------|
17+
| **Models** | `default`, `opus`, `sonnet`, `haiku` |
18+
| **Modes** | - |
19+
| **Thought levels** | - |
20+
21+
## Codex
22+
23+
| Category | Values |
24+
|----------|--------|
25+
| **Models** | `gpt-5.1-codex-max`, `gpt-5.1-codex-mini`, `gpt-5.2`, `gpt-5.2-codex`, `gpt-5.3-codex` (default) |
26+
| **Modes** | - |
27+
| **Thought levels** | - |
28+
29+
## OpenCode
30+
31+
| Category | Values |
32+
|----------|--------|
33+
| **Models** | See below |
34+
| **Modes** | `build` (default), `plan` |
35+
| **Thought levels** | - |
36+
37+
<Accordion title="See all models">
38+
39+
| Provider | Models |
40+
|----------|--------|
41+
| **Anthropic** | `anthropic/claude-3-5-haiku-20241022`, `anthropic/claude-3-5-haiku-latest`, `anthropic/claude-3-5-sonnet-20240620`, `anthropic/claude-3-5-sonnet-20241022`, `anthropic/claude-3-7-sonnet-20250219`, `anthropic/claude-3-7-sonnet-latest`, `anthropic/claude-3-haiku-20240307`, `anthropic/claude-3-opus-20240229`, `anthropic/claude-3-sonnet-20240229`, `anthropic/claude-haiku-4-5`, `anthropic/claude-haiku-4-5-20251001`, `anthropic/claude-opus-4-0`, `anthropic/claude-opus-4-1`, `anthropic/claude-opus-4-1-20250805`, `anthropic/claude-opus-4-20250514`, `anthropic/claude-opus-4-5`, `anthropic/claude-opus-4-5-20251101`, `anthropic/claude-opus-4-6`, `anthropic/claude-sonnet-4-0`, `anthropic/claude-sonnet-4-20250514`, `anthropic/claude-sonnet-4-5`, `anthropic/claude-sonnet-4-5-20250929` |
42+
| **OpenAI** | `openai/gpt-5.1-codex`, `openai/gpt-5.1-codex-max`, `openai/gpt-5.1-codex-mini`, `openai/gpt-5.2`, `openai/gpt-5.2-codex`, `openai/gpt-5.3-codex` |
43+
| **Cerebras** | `cerebras/gpt-oss-120b`, `cerebras/qwen-3-235b-a22b-instruct-2507`, `cerebras/zai-glm-4.7` |
44+
| **OpenCode Zen** | `opencode/big-pickle`, `opencode/claude-3-5-haiku`, `opencode/claude-haiku-4-5`, `opencode/claude-opus-4-1`, `opencode/claude-opus-4-5`, `opencode/claude-opus-4-6`, `opencode/claude-sonnet-4`, `opencode/claude-sonnet-4-5`, `opencode/gemini-3-flash`, `opencode/gemini-3-pro` (default), `opencode/glm-4.6`, `opencode/glm-4.7`, `opencode/gpt-5`, `opencode/gpt-5-codex`, `opencode/gpt-5-nano`, `opencode/gpt-5.1`, `opencode/gpt-5.1-codex`, `opencode/gpt-5.1-codex-max`, `opencode/gpt-5.1-codex-mini`, `opencode/gpt-5.2`, `opencode/gpt-5.2-codex`, `opencode/kimi-k2`, `opencode/kimi-k2-thinking`, `opencode/kimi-k2.5`, `opencode/kimi-k2.5-free`, `opencode/minimax-m2.1`, `opencode/minimax-m2.1-free`, `opencode/trinity-large-preview-free` |
45+
46+
</Accordion>
47+
48+
## Cursor
49+
50+
| Category | Values |
51+
|----------|--------|
52+
| **Models** | See below |
53+
| **Modes** | - |
54+
| **Thought levels** | - |
55+
56+
<Accordion title="See all models">
57+
58+
| Group | Models |
59+
|-------|--------|
60+
| **Auto** | `auto` |
61+
| **Composer** | `composer-1.5`, `composer-1` |
62+
| **GPT-5.3 Codex** | `gpt-5.3-codex`, `gpt-5.3-codex-low`, `gpt-5.3-codex-high`, `gpt-5.3-codex-xhigh`, `gpt-5.3-codex-fast`, `gpt-5.3-codex-low-fast`, `gpt-5.3-codex-high-fast`, `gpt-5.3-codex-xhigh-fast` |
63+
| **GPT-5.2** | `gpt-5.2`, `gpt-5.2-high`, `gpt-5.2-codex`, `gpt-5.2-codex-low`, `gpt-5.2-codex-high`, `gpt-5.2-codex-xhigh`, `gpt-5.2-codex-fast`, `gpt-5.2-codex-low-fast`, `gpt-5.2-codex-high-fast`, `gpt-5.2-codex-xhigh-fast` |
64+
| **GPT-5.1** | `gpt-5.1-high`, `gpt-5.1-codex-max`, `gpt-5.1-codex-max-high` |
65+
| **Claude** | `opus-4.6-thinking` (default), `opus-4.6`, `opus-4.5`, `opus-4.5-thinking`, `sonnet-4.5`, `sonnet-4.5-thinking` |
66+
| **Other** | `gemini-3-pro`, `gemini-3-flash`, `grok` |
67+
68+
</Accordion>
69+
70+
## Amp
71+
72+
| Category | Values |
73+
|----------|--------|
74+
| **Models** | `amp-default` |
75+
| **Modes** | `smart` (default), `deep`, `free`, `rush` |
76+
| **Thought levels** | - |
77+
78+
## Pi
79+
80+
| Category | Values |
81+
|----------|--------|
82+
| **Models** | `default` |
83+
| **Modes** | - |
84+
| **Thought levels** | - |
85+
86+
## Generating a live report
87+
88+
Requires a running Sandbox Agent server. `--endpoint` defaults to `http://127.0.0.1:2468`.
89+
90+
```bash
91+
sandbox-agent api agents report
92+
```
93+

‎docs/agent-sessions.mdx‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -82,6 +82,49 @@ if (sessions.items.length > 0) {
8282
}
8383
```
8484

85+
## Configure model, mode, and thought level
86+
87+
Set the model, mode, or thought level on a session at creation time or after:
88+
89+
```ts
90+
// At creation time
91+
const session = await sdk.createSession({
92+
agent: "codex",
93+
model: "gpt-5.3-codex",
94+
mode: "plan",
95+
thoughtLevel: "high",
96+
});
97+
```
98+
99+
```ts
100+
// After creation
101+
await session.setModel("gpt-5.2-codex");
102+
await session.setMode("build");
103+
await session.setThoughtLevel("medium");
104+
```
105+
106+
Query available modes:
107+
108+
```ts
109+
const modes = await session.getModes();
110+
console.log(modes?.currentModeId, modes?.availableModes);
111+
```
112+
113+
### Advanced config options
114+
115+
For config options beyond model, mode, and thought level, use `getConfigOptions` to discover what the agent supports and `setConfigOption` to set any option by ID:
116+
117+
```ts
118+
const options = await session.getConfigOptions();
119+
for (const opt of options) {
120+
console.log(opt.id, opt.category, opt.type);
121+
}
122+
```
123+
124+
```ts
125+
await session.setConfigOption("some-agent-option", "value");
126+
```
127+
85128
## Destroy a session
86129

87130
```ts

‎docs/cli.mdx‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -167,6 +167,56 @@ Shared option:
167167

168168
```bash
169169
sandbox-agent api agents list [--endpoint <URL>]
170+
sandbox-agent api agents report [--endpoint <URL>]
170171
sandbox-agent api agents install <AGENT> [--reinstall] [--endpoint <URL>]
171172
```
172173

174+
#### api agents list
175+
176+
List all agents and their install status.
177+
178+
```bash
179+
sandbox-agent api agents list
180+
```
181+
182+
#### api agents report
183+
184+
Emit a JSON report of available models, modes, and thought levels for every agent. Calls `GET /v1/agents?config=true` and groups each agent's config options by category.
185+
186+
```bash
187+
sandbox-agent api agents report --endpoint http://127.0.0.1:2468 | jq .
188+
```
189+
190+
Example output:
191+
192+
```json
193+
{
194+
"generatedAtMs": 1740000000000,
195+
"endpoint": "http://127.0.0.1:2468",
196+
"agents": [
197+
{
198+
"id": "claude",
199+
"installed": true,
200+
"models": {
201+
"currentValue": "default",
202+
"values": [
203+
{ "value": "default", "name": "Default (recommended)" },
204+
{ "value": "opus", "name": "Opus" },
205+
{ "value": "sonnet", "name": "Sonnet" },
206+
{ "value": "haiku", "name": "Haiku" }
207+
]
208+
},
209+
"modes": { "values": [] },
210+
"thoughtLevels": { "values": [] }
211+
}
212+
]
213+
}
214+
```
215+
216+
See [Agent Capabilities](/agent-capabilities) for a full reference of supported models, modes, and thought levels per agent.
217+
218+
#### api agents install
219+
220+
```bash
221+
sandbox-agent api agents install codex --reinstall
222+
```

‎docs/docs.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -94,6 +94,7 @@
9494
{
9595
"group": "Reference",
9696
"pages": [
97+
"agent-capabilities",
9798
"cli",
9899
"inspector",
99100
"opencode-compatibility",

‎docs/sdk-overview.mdx‎

Lines changed: 19 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -100,6 +100,25 @@ await restored.prompt([{ type: "text", text: "Continue from previous context." }
100100
await sdk.destroySession(restored.id);
101101
```
102102

103+
## Session configuration
104+
105+
Set model, mode, or thought level at creation or on an existing session:
106+
107+
```ts
108+
const session = await sdk.createSession({
109+
agent: "codex",
110+
model: "gpt-5.3-codex",
111+
});
112+
113+
await session.setModel("gpt-5.2-codex");
114+
await session.setMode("plan");
115+
116+
const options = await session.getConfigOptions();
117+
const modes = await session.getModes();
118+
```
119+
120+
See [Agent Sessions](/agent-sessions) for full details on config options and error handling.
121+
103122
## Events
104123

105124
Subscribe to live events:
@@ -171,13 +190,3 @@ Parameters:
171190
- `headers` (optional): Additional request headers
172191
- `fetch` (optional): Custom fetch implementation used by SDK HTTP and ACP calls
173192

174-
## Types
175-
176-
```ts
177-
import type {
178-
AgentInfo,
179-
HealthResponse,
180-
SessionEvent,
181-
SessionRecord,
182-
} from "sandbox-agent";
183-
```

0 commit comments

Comments
 (0)