fix(docs): correct lane start action API and sandbox/approval enum values
This commit is contained in:
+30
-9
@@ -219,6 +219,34 @@ attempts returns `409 EWORKTREEDIRCOLLISION`. A failed provision keeps its
|
||||
managed lane row with the git diagnostic in `notes`; use `DELETE /api/lanes/:id`
|
||||
to forget that row because no worktree exists to remove.
|
||||
|
||||
#### Start a lane's run
|
||||
|
||||
```http
|
||||
POST /api/lanes/:id/start
|
||||
```
|
||||
|
||||
Starts a new run in the lane's working directory, or attaches an existing idle tmux session. Returns the updated lane. The request body carries:
|
||||
|
||||
```json
|
||||
{
|
||||
"prompt": "Write a test for the user endpoint",
|
||||
"model": "claude-opus-5",
|
||||
"permissionMode": "plan",
|
||||
"effort": "medium",
|
||||
"resumeSessionId": "session-xyz",
|
||||
"sandbox": "read-only",
|
||||
"approval": "on-request"
|
||||
}
|
||||
```
|
||||
|
||||
All fields are optional. The tool (CLI invoked) comes from the lane itself, never the request — **a client cannot override a lane's tool**. If the lane is a Codex lane, three fields control Codex-specific behavior:
|
||||
|
||||
- **`sandbox`** — one of `read-only`, `workspace-write`, or `danger-full-access`, or omitted/empty for no sandbox. Passed to `codex -s <value>`.
|
||||
- **`approval`** — one of `on-request` or `never`, or omitted/empty for no approval prompt. Passed to `codex -a <value>`.
|
||||
- **`resumeSessionId`** or **`resumeLast: true`** — resume an earlier run instead of starting new. For Codex lanes specifically, `resumeLast: true` uses `codex resume --last`; `resumeSessionId` uses `codex resume <sessionId>`. For Claude lanes, `resumeSessionId` re-attaches a Claude session by id.
|
||||
|
||||
Error `409 ERUNLIVE` is returned if the lane already has a live run; stop it first with the `stop` action.
|
||||
|
||||
#### Preflight a destructive lane action
|
||||
|
||||
```http
|
||||
@@ -1586,7 +1614,7 @@ GET /api/run/cwds Suggested cwds (dashboard, home, recent)
|
||||
GET /api/run/history?limit=&laneId= Persisted run history; laneId narrows to one lane's runs
|
||||
GET /api/run/files?cwd=&q= Fuzzy file search inside cwd for the @-file autocomplete
|
||||
(skips node_modules, .git, dist, build, .next, .cache, coverage, vendor)
|
||||
POST /api/run Start/attach run — Body: { laneId, initialPrompt?, sandbox?, approval?, resumeLast?, ... }
|
||||
POST /api/run Start/attach run — Body: { laneId, cwd?, model?, permissionMode?, effort?, resumeSessionId?, initialPrompt? }
|
||||
GET /api/run/:id Run handle (returns live run state)
|
||||
DELETE /api/run/:id Kill (SIGTERM → SIGKILL after 5 s)
|
||||
```
|
||||
@@ -1595,14 +1623,7 @@ DELETE /api/run/:id Kill (SIGTERM → SIGKILL after 5 s)
|
||||
|
||||
**`POST /api/run` (start/attach):** Requires `laneId` (the lane this run belongs to). Creates or attaches an existing tmux session named `ccam-lane-<id>` in the lane's working directory. If that session already exists and its pane is idling at a shell prompt, the appropriate command line (including `--resume` and any initial prompt) is typed into that pane instead of being dropped; if the pane is running a program, the request adopts the session unchanged. Optionally accepts `initialPrompt` to immediately type/send into the session (if empty or omitted, the session is created/attached with no initial input). Returns `{ id, laneId, status, cwd, model, permissionMode, effort, resumeSessionId, sessionId, startedAt, promptPreview }` where `id` is the tmux session name. The dashboard self-heals a lane's `run_id`/`status` on every read if the tmux session has been killed externally.
|
||||
|
||||
For **Claude lanes**, `permissionMode` (`acceptEdits` default, or `default` / `plan` / `bypassPermissions`) is the mode the pane starts in. The pane's argv also carries `--allow-dangerously-skip-permissions`, which only makes **bypass permissions** selectable in the pane's `shift+tab` cycle — it does not enable it.
|
||||
|
||||
For **Codex lanes**, three additional body fields control the spawn behavior:
|
||||
- **`sandbox`** (boolean, default `false`) — whether to enable Codex's restricted filesystem/network mode (`-s` flag)
|
||||
- **`approval`** (boolean, default `false`) — whether to prompt for confirmation before tool execution (`-a` flag)
|
||||
- **`resumeLast`** (boolean, default `false`) — whether to resume the last Codex run (`--last` flag instead of starting new)
|
||||
|
||||
See [docs/LANES.md § Lane tool](LANES.md#lane-tool-claude-or-codex) for full details.
|
||||
`permissionMode` (`acceptEdits` default, or `default` / `plan` / `bypassPermissions`) is the mode the pane starts in. The pane's argv also carries `--allow-dangerously-skip-permissions`, which only makes **bypass permissions** selectable in the pane's `shift+tab` cycle — it does not enable it.
|
||||
|
||||
**PTY streaming:** Frames from the tmux pane are streamed to the client over `/ws-pty/:runId` as binary WebSocket frames (not JSON). The Workspace page's TerminalView component feeds these frames to xterm.js for live rendering. Simultaneously, `ccam lanes shell` can attach the same session via a real local terminal, staying in sync with the browser view.
|
||||
|
||||
|
||||
+4
-4
@@ -50,15 +50,15 @@ Both modes' path field has a **Browse** button next to it, opening a small folde
|
||||
A lane is driven by a tool: **Claude** (default) or **Codex**, chosen in the "+ Add lane" modal and immutable once the lane exists. A lane's tool determines which CLI is spawned when a run starts.
|
||||
|
||||
- **`claude` (default)** — `claude` binary is invoked; the session's hooks, messages, and tool calls flow through the dashboard. Claude lanes render Sessions, Analytics, cost, and stage-detection badges; liveness is tracked by the Claude Code session.
|
||||
- **`codex` (experimental)** — `codex` binary is invoked instead. The Run Setup panel shows model, sandbox approval, and reasoning effort toggles instead of the Claude session picker, and offers "Resume last Codex run" instead of picking a session. Resume uses `codex resume --last`.
|
||||
- **`codex` (experimental)** — `codex` binary is invoked instead. The Run Setup panel shows fields for model, sandbox, and approval mode instead of the Claude session picker, and offers "Resume last Codex run" instead of picking a session. Resume uses `codex resume --last`.
|
||||
|
||||
### How Codex arguments map
|
||||
|
||||
The Run Setup panel's model, sandbox, approval, and reasoning-effort toggles map directly onto `codex` command-line arguments:
|
||||
The Run Setup panel's fields map directly onto `codex` command-line arguments:
|
||||
|
||||
- **Model** → `codex -m <model>` (e.g. `codex -m claude-opus-5`)
|
||||
- **Sandbox** → `-s` (enables restricted filesystem/network mode)
|
||||
- **Approval** → `-a` (prompts for confirmation before tool execution)
|
||||
- **Sandbox** (optional) → `-s <mode>` where mode is one of `read-only`, `workspace-write`, or `danger-full-access`
|
||||
- **Approval** (optional) → `-a <mode>` where mode is one of `on-request` or `never`
|
||||
- **Reasoning effort** → `-c model_reasoning_effort=<level>` (e.g. `medium`)
|
||||
|
||||
A codex lane's run console shows the full command line before execution.
|
||||
|
||||
Reference in New Issue
Block a user