@stateset/sandbox-cli 3.3.1 → 3.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +88 -0
- package/README.md +351 -1
- package/dist/client.d.ts +29 -1
- package/dist/client.d.ts.map +1 -1
- package/dist/client.js +10 -0
- package/dist/client.js.map +1 -1
- package/dist/commands/run.d.ts.map +1 -1
- package/dist/commands/run.js +48 -15
- package/dist/commands/run.js.map +1 -1
- package/dist/commands/sandbox.d.ts.map +1 -1
- package/dist/commands/sandbox.js +62 -16
- package/dist/commands/sandbox.js.map +1 -1
- package/dist/commands/swarm.d.ts +12 -0
- package/dist/commands/swarm.d.ts.map +1 -0
- package/dist/commands/swarm.js +288 -0
- package/dist/commands/swarm.js.map +1 -0
- package/dist/commands/terminal.d.ts +3 -1
- package/dist/commands/terminal.d.ts.map +1 -1
- package/dist/commands/terminal.js +58 -1
- package/dist/commands/terminal.js.map +1 -1
- package/dist/commands/workbench.d.ts +138 -0
- package/dist/commands/workbench.d.ts.map +1 -0
- package/dist/commands/workbench.js +531 -0
- package/dist/commands/workbench.js.map +1 -0
- package/dist/index.js +5 -1
- package/dist/index.js.map +1 -1
- package/dist/utils/swarm-plan.d.ts +69 -0
- package/dist/utils/swarm-plan.d.ts.map +1 -0
- package/dist/utils/swarm-plan.js +321 -0
- package/dist/utils/swarm-plan.js.map +1 -0
- package/dist/utils/template-create.d.ts +36 -0
- package/dist/utils/template-create.d.ts.map +1 -0
- package/dist/utils/template-create.js +116 -0
- package/dist/utils/template-create.js.map +1 -0
- package/dist/workbench/actions.d.ts +1 -1
- package/dist/workbench/actions.d.ts.map +1 -1
- package/dist/workbench/actions.js +1 -0
- package/dist/workbench/actions.js.map +1 -1
- package/dist/workbench/agents.d.ts +96 -0
- package/dist/workbench/agents.d.ts.map +1 -0
- package/dist/workbench/agents.js +370 -0
- package/dist/workbench/agents.js.map +1 -0
- package/dist/workbench/commands.d.ts.map +1 -1
- package/dist/workbench/commands.js +7 -1
- package/dist/workbench/commands.js.map +1 -1
- package/dist/workbench/model.d.ts +5 -1
- package/dist/workbench/model.d.ts.map +1 -1
- package/dist/workbench/model.js +15 -2
- package/dist/workbench/model.js.map +1 -1
- package/dist/workbench/terminal.d.ts +1 -1
- package/dist/workbench/terminal.d.ts.map +1 -1
- package/dist/workbench/terminal.js +108 -78
- package/dist/workbench/terminal.js.map +1 -1
- package/package.json +2 -2
package/CHANGELOG.md
CHANGED
|
@@ -6,6 +6,94 @@ the repository [CHANGELOG](../CHANGELOG.md). This package follows
|
|
|
6
6
|
|
|
7
7
|
## [Unreleased]
|
|
8
8
|
|
|
9
|
+
## [3.4.0] - 2026-11-13
|
|
10
|
+
|
|
11
|
+
### Added
|
|
12
|
+
|
|
13
|
+
- `stateset swarm create --plan <file.json> [--name <name>] [--json]` stores a swarm plan file
|
|
14
|
+
(what `examples/claude-agent/swarm-plan.mjs` writes) as a swarm in the service (`POST /swarms`).
|
|
15
|
+
The plan is checked against the API's limits before anything is sent: a plan with problems ends
|
|
16
|
+
in exit status 1 with the file and one line per problem on stderr, also under the global
|
|
17
|
+
`--dry-run`, which checks a plan without storing it. A task's `id` is sent as `key`; `sandbox`,
|
|
18
|
+
`union` and what else the API has no field for are left out. The name is `--name`, else the
|
|
19
|
+
plan's `name`, else the file's name without `.json`. It prints `Swarm "<name>" created: <id>`
|
|
20
|
+
and how to follow the swarm (`stateset swarm watch <id>`), or the swarm with `--json`. It starts
|
|
21
|
+
no sandbox and runs no task, and the request is sent once. A create refused because the
|
|
22
|
+
organization holds its limit of unfinished swarms (429 `CONCURRENT_LIMIT_EXCEEDED`) prints the
|
|
23
|
+
API's message and a hint about swarms (`stateset swarm cancel <id>`, `stateset swarm list
|
|
24
|
+
--status running`) in place of the one about sandboxes.
|
|
25
|
+
- `stateset swarm list [--status <s>] [--limit <n>] [--json]`, `stateset swarm get <id> [--json]`
|
|
26
|
+
and `stateset swarm cancel <id> [--json]` show and cancel the swarms the service keeps
|
|
27
|
+
(`/api/v1/swarms`). `get` prints the name, status and goal on one line, then a table of the
|
|
28
|
+
tasks (key, phase, branch, cost in dollars, blocked by). A swarm that does not exist (404) and a
|
|
29
|
+
completed or failed swarm that cannot be cancelled (409) each end in one line and exit status 1,
|
|
30
|
+
without the request being repeated. `cancel` changes the record only and stops no sandbox.
|
|
31
|
+
- `stateset swarm watch <id> [--interval <seconds>]` follows one swarm: it prints what
|
|
32
|
+
`swarm get` prints, looks again every `--interval` seconds (default 5) and ends when the swarm
|
|
33
|
+
is `completed`, `failed` or `cancelled`. It then prints `Swarm "<name>" completed` or
|
|
34
|
+
`Swarm "<name>" was cancelled` with exit status 0, or, for a failed swarm, one line on stderr
|
|
35
|
+
that names the failed tasks, with exit status 1. In a terminal the screen is cleared before each
|
|
36
|
+
look and a line says how often it looks and when it last did; in a pipe or a CI log the swarm is
|
|
37
|
+
printed again only when it has changed. A swarm that does not exist (404), on the first look or
|
|
38
|
+
a later one, ends in the line of `swarm get` and exit status 1. There is no `--json`: scripts
|
|
39
|
+
read `swarm get <id> --json`.
|
|
40
|
+
- `sandbox create --template <id>` and `run --template <id>` create the sandbox from a built-in
|
|
41
|
+
template (`stateset template list`). The id is sent unchanged as `template` on
|
|
42
|
+
`POST /sandbox/create`; without `--timeout` the template's timeout applies instead of the
|
|
43
|
+
profile default. An unknown template, or one the route refuses, is reported with the API's
|
|
44
|
+
message.
|
|
45
|
+
- `--template` now works for every built-in template, including the eight that write files or run
|
|
46
|
+
setup commands (`python-basic`, `node-basic`, `go-basic`, `rust-basic`, `node-express-api`,
|
|
47
|
+
`python-data-science`, `python-llm`, `devops-tools`). `POST /sandbox/create` refuses those with
|
|
48
|
+
a 400 naming `POST /sandbox/create-from-template`; on that answer, and no other, the CLI creates
|
|
49
|
+
the sandbox with that route. Neither request is repeated by the CLI.
|
|
50
|
+
- The spinner says that setup is running and how long the CLI waits: 510 seconds (the startup
|
|
51
|
+
wait plus the 300 the API allows a setup command), or `--startup-timeout` when given.
|
|
52
|
+
- `--isolation`, `--desktop-os` and `--credential`, which the template route has no field for,
|
|
53
|
+
are refused by name before it is called.
|
|
54
|
+
- A setup step that fails leaves the sandbox running. `sandbox create` prints the API's message
|
|
55
|
+
for each failed step and that the sandbox was kept, adds `warnings` to `--json`, and exits 1.
|
|
56
|
+
`run` does not run the command, stops the sandbox unless `--keep` is given, and exits 1.
|
|
57
|
+
- When the template route's outcome is unknown (timeout, dropped connection, 5xx) the error says
|
|
58
|
+
the sandbox may exist.
|
|
59
|
+
- `sandbox create` accepts `--json` (and the global `--json` / `--format`) and prints the created
|
|
60
|
+
sandbox, with `template` when one was asked for. `run --json` carries the same `template` key.
|
|
61
|
+
- `stateset workbench up|open|pull|down`: create claude-code sandboxes with the current
|
|
62
|
+
repository's HEAD at `/workspace/repo` and Claude Code running in a terminal in each;
|
|
63
|
+
attach to them (one Herdr tab per sandbox inside Herdr); save each one's changes since
|
|
64
|
+
the base commit as a patch file; stop only the sandboxes the workbench created.
|
|
65
|
+
`up` takes `--repo <path>`, `--base <rev>`, `--hours <n>` and `--shell`; `open`, `pull`
|
|
66
|
+
and `down` take `--repo <path>`.
|
|
67
|
+
- `stateset terminal status <sandbox-id> <terminal-id>` says whether Claude Code in the terminal is
|
|
68
|
+
working, waiting for input, or blocked on a permission prompt. `--watch` keeps going and prints each
|
|
69
|
+
change with its time until the terminal ends; `--json` prints one object per line. Needs an SDK with
|
|
70
|
+
`terminals.watchClaudeCode`.
|
|
71
|
+
- `stateset tui --agents <dir>` (repeatable; also `STATESET_AGENT_DIRS`, a PATH-style list) shows
|
|
72
|
+
what each sandbox is for from local agent records: `fleet-state.json` and `workbench.json` in the
|
|
73
|
+
named directories and one level below. The list gains `AGENT` and `PHASE` columns, sandbox
|
|
74
|
+
details add fleet, task, objective, phase, branch, pull request, cost and error, and `v` opens a
|
|
75
|
+
view of every recorded agent grouped by fleet, including those whose sandbox is gone. `*` and
|
|
76
|
+
`dup:N` flag likely duplicates: agents still working under matching names. Files are stat'ed on
|
|
77
|
+
each refresh and parsed only when changed; unusable files are skipped with one dimmed note;
|
|
78
|
+
control characters and escape sequences are removed from everything shown. No API requests are
|
|
79
|
+
added.
|
|
80
|
+
- `stateset tui` lists the sandboxes of `stateset workbench up` in the same columns and agents
|
|
81
|
+
view, without a flag: started inside a git repository, it also scans that repository's workbench
|
|
82
|
+
state directory (`.git/stateset-workbench`) once the directory exists, in addition to `--agents`
|
|
83
|
+
and `STATESET_AGENT_DIRS`. Each member of a `<name>.json` record there is an agent named by its
|
|
84
|
+
label and grouped under the workbench, with the phase `interactive`, `creating`, `failed` (with
|
|
85
|
+
the error) or `stopped`. Other files in that directory are ignored without a note; the size
|
|
86
|
+
limit, parse-only-when-changed and control-character rules apply as for the other records. A
|
|
87
|
+
`workbench.json` in an `--agents` directory may hold this format or the older `benches` one.
|
|
88
|
+
|
|
89
|
+
### Fixed
|
|
90
|
+
|
|
91
|
+
- `stateset swarm get` and `stateset swarm cancel` said `Swarm "<id>" not found` for every 404.
|
|
92
|
+
They say so now only when the API answered `SWARM_NOT_FOUND` (the SDK error's `wireCode`); any
|
|
93
|
+
other 404 prints the line of `stateset swarm list` for an API without swarm routes.
|
|
94
|
+
- `stateset swarm cancel` repeated a cancel the service failed on top of the SDK's own retries
|
|
95
|
+
(16 requests for a service that always answers 500). It now makes the SDK call once: 4 requests.
|
|
96
|
+
|
|
9
97
|
## [3.3.1] - 2026-11-04
|
|
10
98
|
|
|
11
99
|
The first npm registry release since 1.0.6. 3.x has been built from this repository since the
|
package/README.md
CHANGED
|
@@ -112,7 +112,7 @@ Startup equivalents are `--runtime-image`, `--inference`, `--inference-secret`
|
|
|
112
112
|
and `--inference-limit`. The default gateway cap is 20000 output tokens/hour;
|
|
113
113
|
in-flight calls can overshoot. Local Docker retains its existing `--image`
|
|
114
114
|
setting and rejects hosted gateway options.
|
|
115
|
-
Use `/` to search sandbox IDs, statuses or creating Herdr panes, Enter for
|
|
115
|
+
Use `/` to search sandbox IDs, statuses, agent names or creating Herdr panes, Enter for
|
|
116
116
|
details, and `?` for keyboard help. PageUp/PageDown and Home/End navigate the
|
|
117
117
|
filtered list; details and help wrap and scroll inside narrow panes.
|
|
118
118
|
Press `a` for session activity across all sandboxes. Start with
|
|
@@ -121,6 +121,61 @@ search also accepts pasted IDs.
|
|
|
121
121
|
The list shows allocations and a live expiry countdown. Press `o` for status
|
|
122
122
|
counts and running allocation totals, or `t` to sort by ID, expiry, status or
|
|
123
123
|
newest. Start with `--sort expiry` to prioritize upcoming deadlines.
|
|
124
|
+
|
|
125
|
+
To see what each sandbox is for, name the directories that hold your agent
|
|
126
|
+
records: `stateset tui --agents ./fleets --agents ~/desk`, or set
|
|
127
|
+
`STATESET_AGENT_DIRS` to a PATH-style list (`:` between entries, `;` on
|
|
128
|
+
Windows). Each directory and its immediate subdirectories are checked for
|
|
129
|
+
`fleet-state.json` (written by `examples/claude-agent/fleet.mjs`) and
|
|
130
|
+
`workbench.json` (`{ "benches": [{ "name", "sandbox_id", "terminal_id",
|
|
131
|
+
"error"?, "stopped"? }] }`). Only these local files are read, on every refresh:
|
|
132
|
+
each is stat'ed and parsed again only when it has changed, and nothing is
|
|
133
|
+
requested from the API for them.
|
|
134
|
+
|
|
135
|
+
Workbenches started with [`stateset workbench up`](#stateset-workbench) need
|
|
136
|
+
no flag. When the dashboard is started inside a git repository, the directory
|
|
137
|
+
where that repository's workbenches are recorded (`.git/stateset-workbench`,
|
|
138
|
+
shared by its worktrees) is scanned as well, from the moment it exists, in
|
|
139
|
+
addition to the `--agents` and `STATESET_AGENT_DIRS` directories. Every
|
|
140
|
+
`<name>.json` in it that is a workbench record adds one agent per sandbox:
|
|
141
|
+
named by its label (`feat-1`), grouped under the workbench's name, with the
|
|
142
|
+
phase `interactive` (ready), `creating`, `failed` (with the error) or
|
|
143
|
+
`stopped` (after `workbench down`, or when `down` found that the sandbox was
|
|
144
|
+
never created). A failed member stays `failed` after `down`. These records are
|
|
145
|
+
read under the same rules as the others: parsed only when changed, never when
|
|
146
|
+
larger than 8 MiB, and at most 200 files. Anything else in that directory is
|
|
147
|
+
ignored without a note. The workbenches of another repository are not found
|
|
148
|
+
this way; start the dashboard in that repository. A `workbench.json` in an
|
|
149
|
+
`--agents` directory may hold either format.
|
|
150
|
+
|
|
151
|
+
- The list gains `AGENT` and `PHASE` columns once a listed sandbox has a
|
|
152
|
+
record. They share the ID column's room, so IDs are shortened and long names
|
|
153
|
+
cut; panes under 46 columns keep the ID alone. `+N` counts further agents in
|
|
154
|
+
the same sandbox. Search matches agent, phase and fleet names.
|
|
155
|
+
- Enter adds the fleet or workbench name, task name, the first four lines of
|
|
156
|
+
the objective, phase, branch, pull request URL, cost, any error, and the
|
|
157
|
+
record's path to the sandbox details.
|
|
158
|
+
- `v` (also in the F2 menu) lists agents instead of sandboxes: every fleet
|
|
159
|
+
member and bench, grouped by fleet or workbench, with phase, branch and pull
|
|
160
|
+
request, and the sandbox's status or `not listed` when it is gone. `v` or
|
|
161
|
+
Esc returns.
|
|
162
|
+
- `*` marks likely duplicates and the title shows `dup:N`: two agents both
|
|
163
|
+
still working whose names are equal, or one contained in the other, after
|
|
164
|
+
lower-casing and dropping punctuation, spaces and common words (`the`, `a`,
|
|
165
|
+
`of`, `to`, ...). "Fix the Login-Redirect!" matches "fix_login redirect"
|
|
166
|
+
and "login redirect". Containment is plain, so a very short name such as
|
|
167
|
+
"ui" also matches "build"; treat the mark as a prompt to look. Details and
|
|
168
|
+
the agents view name the other agent of each pair. "Still working" comes
|
|
169
|
+
from the record alone: fleet phases `planned`, `prepared`, `dispatched` and
|
|
170
|
+
`dispatch_unknown`, benches without `stopped` or `error`, and workbench
|
|
171
|
+
members that are `interactive` or `creating`; finished agents are never
|
|
172
|
+
flagged. A stale record of an agent that died without
|
|
173
|
+
updating its file can therefore still be flagged; the agents view shows
|
|
174
|
+
whether its sandbox is still listed.
|
|
175
|
+
- A `fleet-state.json` or `workbench.json` that is unreadable, malformed or
|
|
176
|
+
not in a known format is skipped, and one dimmed line above the selection
|
|
177
|
+
summary counts the skipped files and names the first two. Control characters and terminal escape sequences are
|
|
178
|
+
removed from every value read from these files before it is drawn.
|
|
124
179
|
Press F2 or `:` for a searchable action menu with availability explanations.
|
|
125
180
|
It also works from sandbox details and keeps its original target selected.
|
|
126
181
|
Press `c` for connection diagnostics and full refresh errors. Delayed reads
|
|
@@ -441,6 +496,88 @@ stateset sandbox ls-files <id> # List directory contents
|
|
|
441
496
|
| `-m, --memory <memory>` | Memory limit | `--memory 1Gi` |
|
|
442
497
|
| `-i, --isolation <level>` | Isolation level | `--isolation gvisor` |
|
|
443
498
|
| `-e, --env <KEY=VALUE>` | Environment variables (repeatable) | `-e FOO=bar -e BAZ=qux` |
|
|
499
|
+
| `--template <id>` | Built-in template to create from, with its files and setup commands if it has any | `--template python-data-science` |
|
|
500
|
+
| `--startup-timeout <seconds>` | How long to wait for the create to answer (1-600, default 210; a template with setup gets 300 more unless this is set) | `--startup-timeout 600` |
|
|
501
|
+
| `--json` | Print the created sandbox as JSON | `--json` |
|
|
502
|
+
|
|
503
|
+
**Templates.** `--template <id>` creates the sandbox from any built-in template;
|
|
504
|
+
`stateset template list` shows the ids and `stateset template describe <id>` what
|
|
505
|
+
each one sets. `stateset run` takes the same flag.
|
|
506
|
+
|
|
507
|
+
```bash
|
|
508
|
+
stateset sandbox create --template claude-code
|
|
509
|
+
stateset sandbox create --template claude-code --timeout 900 --cpus 1 -e FOO=bar
|
|
510
|
+
stateset --json sandbox create --template claude-code | jq -r '.id, .template'
|
|
511
|
+
stateset run --template claude-code -- claude --version
|
|
512
|
+
stateset sandbox create --template python-data-science # writes files, runs pip install
|
|
513
|
+
stateset run --template node-basic -- node index.js
|
|
514
|
+
```
|
|
515
|
+
|
|
516
|
+
- The id is sent as typed in the `template` field of `POST /sandbox/create`.
|
|
517
|
+
- The template supplies the image and the defaults for CPUs, memory, timeout and
|
|
518
|
+
env. `--cpus`, `--memory` and `--timeout` replace the template's values, `-e`
|
|
519
|
+
entries are merged over its env, and `run --image` replaces its image.
|
|
520
|
+
- **Templates with setup.** Eight built-in templates write files or run setup
|
|
521
|
+
commands (the `Files` and `Setup Commands` sections of `template describe`):
|
|
522
|
+
`python-basic`, `node-basic`, `go-basic`, `rust-basic`, `node-express-api`,
|
|
523
|
+
`python-data-science`, `python-llm` and `devops-tools`. `POST /sandbox/create`
|
|
524
|
+
refuses them with a 400 that names `POST /sandbox/create-from-template`, and
|
|
525
|
+
the CLI then sends the same options to that route. `GET /templates` does not
|
|
526
|
+
say which kind a template is, so the CLI learns it from that 400, which creates
|
|
527
|
+
nothing; any other error is reported as it is, and neither request is sent a
|
|
528
|
+
second time by the CLI.
|
|
529
|
+
- Setup runs inside the create request. The spinner says so (`Creating sandbox
|
|
530
|
+
and running the setup of template <id> ...; waiting up to 510s...`): the API
|
|
531
|
+
allows one setup command 300 seconds, so the default 210 second startup wait
|
|
532
|
+
becomes 510. A `--startup-timeout` you give is used as the whole wait.
|
|
533
|
+
- The template route has no field for `--isolation`, `--desktop-os` (other than
|
|
534
|
+
`linux`) or `--credential`. With a template that has setup they are refused by
|
|
535
|
+
name before that route is called, and no sandbox is created. `--timeout`,
|
|
536
|
+
`--cpus`, `--memory`, `-e`, `--durable`, `--resource-class`, the egress and
|
|
537
|
+
budget flags and `run --image` are sent.
|
|
538
|
+
- **A setup step that fails does not undo the create.** The API keeps the
|
|
539
|
+
sandbox, running and billed, and lists the failed steps. `sandbox create`
|
|
540
|
+
prints the sandbox, then on stderr each step in the API's words (`Setup command
|
|
541
|
+
exited 1: pip install ...`, `Template files were not written: ...`) and that the
|
|
542
|
+
sandbox was kept, and exits 1; `--json` carries the steps as `warnings`.
|
|
543
|
+
`run` does not run the command: it stops the sandbox (or keeps it with
|
|
544
|
+
`--keep`), says which, and exits 1.
|
|
545
|
+
- If the template route times out, loses its connection or answers 5xx, the CLI
|
|
546
|
+
does not send it again: the sandbox may exist with its setup still running, so
|
|
547
|
+
look at `stateset sandbox list` before creating another.
|
|
548
|
+
- Without `--timeout`, a create with `--template` sends no timeout, so the
|
|
549
|
+
template's applies (3600 seconds for `claude-code`) and not the profile's default
|
|
550
|
+
timeout. Without `--template` the profile default is sent as before.
|
|
551
|
+
- A refusal is shown in the API's words. An unknown id is `Template "<id>" not
|
|
552
|
+
found`.
|
|
553
|
+
- The create response does not name the template, so the `Template:` line and the
|
|
554
|
+
`template` key of `--json` repeat the id that was sent. `run --json` carries the
|
|
555
|
+
same `template` key. Both are absent when no template was asked for.
|
|
556
|
+
|
|
557
|
+
### `stateset terminal` and `stateset ssh`
|
|
558
|
+
|
|
559
|
+
A terminal is a real shell (or any command) on a pseudo-terminal in the
|
|
560
|
+
sandbox. It keeps running when you detach or lose the connection. See
|
|
561
|
+
[docs/TERMINAL_SESSIONS.md](../docs/TERMINAL_SESSIONS.md).
|
|
562
|
+
|
|
563
|
+
```bash
|
|
564
|
+
stateset ssh <id> # start a shell and attach
|
|
565
|
+
stateset ssh <id> -c "npm test" # run one command and exit
|
|
566
|
+
stateset ssh <id> --line-mode # old behaviour: each line is its own command
|
|
567
|
+
|
|
568
|
+
stateset terminal create <id> [command...] # start a terminal and attach (alias: stateset term)
|
|
569
|
+
stateset terminal create <id> -d --name build # start it detached and print its id
|
|
570
|
+
stateset terminal ls <id>
|
|
571
|
+
stateset terminal attach <id> <terminal-id> # --from-start replays all retained output
|
|
572
|
+
stateset terminal screen <id> <terminal-id> # print what it is displaying; --scrollback <n>, --json
|
|
573
|
+
stateset terminal search <id> <terminal-id> <text> # --case-sensitive, --limit <n>, --json
|
|
574
|
+
stateset terminal record <id> <terminal-id> -o session.cast # asciicast v2; --idle-time-limit <seconds>
|
|
575
|
+
stateset terminal kill <id> <terminal-id>
|
|
576
|
+
```
|
|
577
|
+
|
|
578
|
+
While attached, `Ctrl-]` detaches and leaves the terminal running. `screen`,
|
|
579
|
+
`search` and `record` need no attachment and work on a terminal someone else
|
|
580
|
+
(or an agent) is using.
|
|
444
581
|
|
|
445
582
|
### `stateset checkpoint`
|
|
446
583
|
|
|
@@ -601,6 +738,172 @@ omit command contents and environment values.
|
|
|
601
738
|
| `--cpus <cpus>` | CPU allocation (default: 2) |
|
|
602
739
|
| `--memory <memory>` | Memory allocation (default: 4Gi) |
|
|
603
740
|
|
|
741
|
+
### `stateset swarm`
|
|
742
|
+
|
|
743
|
+
Create, see, watch and cancel swarms: one goal split into tasks with dependencies, as the
|
|
744
|
+
service keeps it (`/api/v1/swarms`, "Swarms" in [docs/API_REFERENCE.md](../docs/API_REFERENCE.md)).
|
|
745
|
+
The service stores the plan and what a coordinator reports about each task; it starts
|
|
746
|
+
and stops no sandbox, and neither do these commands: `create` stores a plan and runs
|
|
747
|
+
none of its tasks.
|
|
748
|
+
|
|
749
|
+
```bash
|
|
750
|
+
stateset swarm create --plan plan.json # Check the plan file, then store it as a swarm
|
|
751
|
+
stateset swarm create --plan plan.json --name "Swarm API" # Under this name
|
|
752
|
+
stateset swarm create --plan plan.json --json # The stored swarm with its tasks, as the API answers
|
|
753
|
+
stateset --dry-run swarm create --plan plan.json # Check the plan; send nothing
|
|
754
|
+
stateset swarm list # Newest first: id, name, status, created
|
|
755
|
+
stateset swarm list --status running --limit 50
|
|
756
|
+
stateset swarm list --json # { "swarms": [...], "next_cursor": null }
|
|
757
|
+
stateset swarm get <id> # Header line, then one row per task
|
|
758
|
+
stateset swarm get <id> --json # The swarm with its tasks, as the API answers
|
|
759
|
+
stateset swarm watch <id> # `get`, drawn again every 5 seconds until the swarm has ended
|
|
760
|
+
stateset swarm watch <id> --interval 30 # Look every 30 seconds
|
|
761
|
+
stateset swarm cancel <id> # Cancel the swarm and its unfinished tasks
|
|
762
|
+
stateset --dry-run swarm cancel <id> # Say what would be sent; send nothing
|
|
763
|
+
```
|
|
764
|
+
|
|
765
|
+
| Flag | Description |
|
|
766
|
+
|------|-------------|
|
|
767
|
+
| `--plan <file>` | `create`: the plan file, JSON (required) |
|
|
768
|
+
| `--name <name>` | `create`: the swarm's name (default: the plan's `name`, else the file's name without `.json`) |
|
|
769
|
+
| `--status <status>` | `list`: only `planned`, `running`, `completed`, `failed` or `cancelled` swarms |
|
|
770
|
+
| `--limit <n>` | `list`: the most swarms to show (default: 25). Above 100 the CLI reads further pages |
|
|
771
|
+
| `-i, --interval <seconds>` | `watch`: seconds between two looks, a positive integer (default: 5) |
|
|
772
|
+
| `--json` | `create`, `list`, `get`, `cancel`: print JSON instead of a table or a line; the global `--json` and `--format json` do the same |
|
|
773
|
+
|
|
774
|
+
`swarm create` reads a plan file, checks it and stores it as a swarm (`POST /swarms`). A
|
|
775
|
+
plan file is what [`examples/claude-agent/swarm-plan.mjs`](../examples/claude-agent/swarm-plan.mjs)
|
|
776
|
+
writes, or the same written by hand:
|
|
777
|
+
|
|
778
|
+
```json
|
|
779
|
+
{
|
|
780
|
+
"goal": "Give the controller a place to keep a swarm.",
|
|
781
|
+
"repository": { "path": "/home/me/app", "base": "4f2c1d9" },
|
|
782
|
+
"defaults": { "timeout_seconds": 3600 },
|
|
783
|
+
"sandbox": { "template": "claude-code", "memory": "4Gi", "cpus": "2" },
|
|
784
|
+
"tasks": [
|
|
785
|
+
{ "id": "schema", "name": "Schema", "objective": "Add the migration." },
|
|
786
|
+
{ "id": "routes", "name": "Routes", "objective": "Add the routes.", "depends_on": ["schema"] }
|
|
787
|
+
]
|
|
788
|
+
}
|
|
789
|
+
```
|
|
790
|
+
|
|
791
|
+
The plan is checked against the API's limits before anything is sent:
|
|
792
|
+
|
|
793
|
+
| Part of the plan | What it must be |
|
|
794
|
+
|------------------|-----------------|
|
|
795
|
+
| The file | At most 4 MB of JSON: an object with its list of tasks in `tasks` |
|
|
796
|
+
| The swarm's name | 1 to 128 characters, on one line and without control characters |
|
|
797
|
+
| `goal` | A string of 1 to 16000 characters, without a NUL character |
|
|
798
|
+
| `repository`, `defaults` | Each a JSON object of at most 16384 characters as JSON, without a NUL character, or left out |
|
|
799
|
+
| `tasks` | 1 to 50 tasks, each an object |
|
|
800
|
+
| A task's `id` | Kebab-case (lowercase letters and digits joined by single hyphens), at most 64 characters, and the id of no other task |
|
|
801
|
+
| A task's `name` | As the swarm's name |
|
|
802
|
+
| A task's `objective` | As `goal` |
|
|
803
|
+
| A task's `depends_on` | A list of ids of other tasks of the plan, or left out; the dependencies form no cycle |
|
|
804
|
+
|
|
805
|
+
The lengths of the name, the goal, a task's name and an objective are counted without
|
|
806
|
+
the spaces around them. A plan with problems is refused with exit status 1 and nothing is
|
|
807
|
+
sent, under `--dry-run` too. Stderr names the file, then has one line per problem, which
|
|
808
|
+
names the task it is about (at most 20 problems; a last line says how many more there
|
|
809
|
+
are):
|
|
810
|
+
|
|
811
|
+
```text
|
|
812
|
+
Plan file "plan.json" has 2 problems:
|
|
813
|
+
- Task 1: id "Bad_Id" is not kebab-case (lowercase letters and digits joined by single hyphens, at most 64 characters).
|
|
814
|
+
- Task "routes": depends_on names "nowhere", which is not the id of a task in this plan.
|
|
815
|
+
```
|
|
816
|
+
|
|
817
|
+
A file that does not exist, cannot be read, is over 4 MB or is not JSON is refused the
|
|
818
|
+
same way, in one line.
|
|
819
|
+
|
|
820
|
+
What is sent is the body of `POST /swarms`: the name, the goal, `repository` and
|
|
821
|
+
`defaults` as the plan has them, and of every task its `id` as `key`, its `name`, its
|
|
822
|
+
`objective` and its `depends_on`, each dependency once. `sandbox`, `union`, `max_local`,
|
|
823
|
+
a task's `files` and anything else the API has no field for are left out: the service
|
|
824
|
+
stores a plan, not how to run it. The swarm's name is `--name`, else the plan's own
|
|
825
|
+
`name`, else the name of the file without `.json` (`plans/run-7.json` is stored as
|
|
826
|
+
`run-7`).
|
|
827
|
+
|
|
828
|
+
```text
|
|
829
|
+
✔ Swarm "run-7" created: 0b9f6c1e-2f0a-4a51-9d3e-6a1f5a0c7e11
|
|
830
|
+
Follow it with: stateset swarm watch 0b9f6c1e-2f0a-4a51-9d3e-6a1f5a0c7e11
|
|
831
|
+
No sandbox was started: the service keeps the plan; a coordinator runs the tasks and reports them.
|
|
832
|
+
```
|
|
833
|
+
|
|
834
|
+
With `--json` the stored swarm is printed as the API answers it, with its id and its
|
|
835
|
+
tasks (`ready` when a task depends on nothing, `waiting` otherwise), and nothing else.
|
|
836
|
+
`stateset --dry-run swarm create --plan <file>` checks the plan, prints the name, the
|
|
837
|
+
number of tasks and the file, and sends nothing. `create` starts no sandbox and runs no
|
|
838
|
+
task: the swarm is `planned` until a coordinator reports a task, which the CLI does not
|
|
839
|
+
do, and it counts among the organization's unfinished swarms until it has ended or is
|
|
840
|
+
cancelled. `stateset swarm watch <id>` follows it from there. Creating is not
|
|
841
|
+
idempotent: the request is sent once, and running the command again stores a second
|
|
842
|
+
swarm.
|
|
843
|
+
|
|
844
|
+
`swarm list` prints `No swarms found` for an empty answer. When there are more swarms
|
|
845
|
+
than `--limit`, the table is followed by a line saying so, and `--json` carries the
|
|
846
|
+
API's `next_cursor` (`null` when the list is complete). A swarm in a list has no tasks.
|
|
847
|
+
|
|
848
|
+
`swarm get` prints the name, the status and the goal on one line, then a table of the
|
|
849
|
+
tasks: key, phase, branch, cost and blocked by.
|
|
850
|
+
|
|
851
|
+
```text
|
|
852
|
+
Swarm API (running): Give the controller a place to keep a swarm.
|
|
853
|
+
╔════════╤══════════╤══════════════╤════════╤════════════╗
|
|
854
|
+
║ Key │ Phase │ Branch │ Cost │ Blocked by ║
|
|
855
|
+
╟────────┼──────────┼──────────────┼────────┼────────────╢
|
|
856
|
+
║ schema │ accepted │ swarm/schema │ $0.95 │ - ║
|
|
857
|
+
╟────────┼──────────┼──────────────┼────────┼────────────╢
|
|
858
|
+
║ routes │ failed │ swarm/routes │ $12.34 │ - ║
|
|
859
|
+
╟────────┼──────────┼──────────────┼────────┼────────────╢
|
|
860
|
+
║ docs │ blocked │ - │ $0.00 │ routes ║
|
|
861
|
+
╚════════╧══════════╧══════════════╧════════╧════════════╝
|
|
862
|
+
```
|
|
863
|
+
|
|
864
|
+
The API stores a task's cost in cents (`cost_cents`); the table prints dollars, and
|
|
865
|
+
`--json` keeps the cents. The header shows the first 240 characters of the goal on one
|
|
866
|
+
line, with control characters replaced by `?`; `--json` has the goal whole.
|
|
867
|
+
|
|
868
|
+
`swarm watch` follows one swarm: it prints what `swarm get` prints, looks again every
|
|
869
|
+
`--interval` seconds, and ends on the first look that finds the swarm `completed`,
|
|
870
|
+
`failed` or `cancelled`, which may be the first one. That look is printed too, followed
|
|
871
|
+
by one line. Only a failed swarm is an error:
|
|
872
|
+
|
|
873
|
+
| The swarm | Last line | Exit status |
|
|
874
|
+
|-----------|-----------|-------------|
|
|
875
|
+
| `completed` | `Swarm "<name>" completed` | 0 |
|
|
876
|
+
| `cancelled` | `Swarm "<name>" was cancelled` | 0 |
|
|
877
|
+
| `failed` | On stderr: `Swarm "<name>" failed: <keys of the failed tasks>` | 1 |
|
|
878
|
+
|
|
879
|
+
In a terminal the screen is cleared before each look is drawn, and a line under the
|
|
880
|
+
table says how often the swarm is looked at, that Ctrl+C stops the watch, and when the
|
|
881
|
+
swarm was last read. When the output is not a terminal (a pipe, a CI log), nothing is
|
|
882
|
+
cleared, that line is left out, and the swarm is printed again only when what is printed
|
|
883
|
+
has changed: the log holds one table per change, not one per look. `watch` only reads,
|
|
884
|
+
and it has no `--json`: a script reads `swarm get <id> --json`. An error on any look,
|
|
885
|
+
the first or a later one, ends the watch as it ends `swarm get`.
|
|
886
|
+
|
|
887
|
+
`swarm cancel` marks the swarm and its unfinished tasks `cancelled` in the service and
|
|
888
|
+
prints the cancelled swarm with `--json`. It stops no sandbox: a coordinator still
|
|
889
|
+
running the swarm goes on until it is stopped where it runs. Cancelling a swarm that is
|
|
890
|
+
already cancelled succeeds. It does not ask for confirmation.
|
|
891
|
+
|
|
892
|
+
Errors are one line on stderr with exit status 1 (for a plan with problems, one more per
|
|
893
|
+
problem), and the request is not repeated:
|
|
894
|
+
|
|
895
|
+
| Answer | Line |
|
|
896
|
+
|--------|------|
|
|
897
|
+
| A plan with problems on `create`: nothing is sent | `Plan file "<file>" has <n> problems:`, then one line per problem |
|
|
898
|
+
| `429` on `create` (the organization holds its limit of unfinished swarms) | The API's message, e.g. `Maximum unfinished swarms per organization (20) exceeded`, then how to get under it: `stateset swarm cancel <id>` or waiting for a swarm to end; `stateset swarm list --status running` and `--status planned` show the unfinished ones |
|
|
899
|
+
| `400` on `create` (the service refuses a plan the check let through) | The API's message, which names the field |
|
|
900
|
+
| `404` on `get`, `watch` or `cancel` | `Swarm "<id>" not found` |
|
|
901
|
+
| `409` on `cancel` (the swarm is completed or failed) | The API's message, e.g. `Swarm is already completed; there is nothing to cancel.` |
|
|
902
|
+
| `404` on `list` or `create` | `This API has no swarm routes (a deployment without a database, or an older controller).` |
|
|
903
|
+
|
|
904
|
+
Any other error (a `--status` or an id the API refuses, an expired login) is reported
|
|
905
|
+
as for the other commands.
|
|
906
|
+
|
|
604
907
|
### `stateset tunnel`
|
|
605
908
|
|
|
606
909
|
Expose sandbox services via tunnels.
|
|
@@ -670,6 +973,52 @@ requires a positive acknowledgement and reports acceptance, which does not
|
|
|
670
973
|
establish that every existing forwarded connection has ended. `--public` remains
|
|
671
974
|
a compatibility flag; the current controller still requires token authentication.
|
|
672
975
|
|
|
976
|
+
### `stateset workbench`
|
|
977
|
+
|
|
978
|
+
Several sandboxes, each with this repository at `/workspace/repo` and Claude
|
|
979
|
+
Code running in a terminal session there. Run it from inside a git repository, or
|
|
980
|
+
name one with `--repo <path>` (accepted by all four subcommands).
|
|
981
|
+
|
|
982
|
+
```bash
|
|
983
|
+
stateset workbench up feat 3 # 3 claude-code sandboxes, HEAD uploaded, Claude Code started
|
|
984
|
+
stateset workbench up fix 2 --base v1.4 --hours 4 --shell # from tag v1.4, 4-hour lifetime, a shell instead
|
|
985
|
+
stateset workbench open feat # attach: one Herdr tab per sandbox, or print the commands
|
|
986
|
+
stateset workbench pull feat -o patches # patches/feat-1.patch ... (changes since the base commit)
|
|
987
|
+
stateset workbench down feat # stop the sandboxes this workbench created
|
|
988
|
+
```
|
|
989
|
+
|
|
990
|
+
**Up options:** `--repo <path>` (the repository to upload; default the current
|
|
991
|
+
directory), `--base <rev>` (the commit the sandboxes start from; default `HEAD`),
|
|
992
|
+
`--hours <n>` (sandbox lifetime, 1 to 24; replaces `--timeout`), `--shell` (start a
|
|
993
|
+
shell in each terminal instead of Claude Code; nothing is installed),
|
|
994
|
+
`--template <template>` (default `claude-code`), `--timeout <seconds>`
|
|
995
|
+
(default 7200), `--cpus`, `--memory`, `--inference-secret <name>` (the secret holding
|
|
996
|
+
the Anthropic credentials Claude Code uses), `--claude-code-version <x.y.z>` (installed
|
|
997
|
+
only when the image has no `claude`). Every subcommand accepts `--json`.
|
|
998
|
+
|
|
999
|
+
- **up** uploads the committed `HEAD`, or `--base` (uncommitted changes are not
|
|
1000
|
+
sent; it warns), as a `git archive`, checked by hash in the sandbox and made a
|
|
1001
|
+
one-commit repository holding every file of that commit, including committed
|
|
1002
|
+
files that `.gitignore` matches. A sandbox that cannot be prepared is reported
|
|
1003
|
+
with the reason and the others still start; the command then exits 1. A workbench
|
|
1004
|
+
that is up cannot be started again until `down`; nor can one whose creates were
|
|
1005
|
+
never confirmed (an interrupted `up`), until `down` has looked for their sandboxes.
|
|
1006
|
+
- **open** inside Herdr (`HERDR_ENV=1`) opens one tab per sandbox, each running
|
|
1007
|
+
`stateset terminal attach`; elsewhere it prints those commands. Ctrl-] detaches
|
|
1008
|
+
and leaves Claude Code running.
|
|
1009
|
+
- **pull** captures commits, uncommitted edits and new files that `.gitignore`
|
|
1010
|
+
does not exclude, without touching the agent's git index or writing anything
|
|
1011
|
+
under the sandbox repository's `.git`. Each download is
|
|
1012
|
+
checked against the size and hash the sandbox reported. Apply a patch on the
|
|
1013
|
+
base commit with `git apply <file>`. A sandbox with no changes writes no file.
|
|
1014
|
+
- **down** stops only sandboxes recorded as created by this workbench, including
|
|
1015
|
+
one whose create response was lost (found by the session ID it was given).
|
|
1016
|
+
|
|
1017
|
+
State lives in `.git/stateset-workbench/<name>.json`, so it is never committed and is
|
|
1018
|
+
shared by the repository's worktrees. `stateset tui` started in the repository reads
|
|
1019
|
+
these files and shows each sandbox's label and phase in its `AGENT` and `PHASE`
|
|
1020
|
+
columns and its agents view (`v`), without `--agents`.
|
|
1021
|
+
|
|
673
1022
|
### `stateset pool`
|
|
674
1023
|
|
|
675
1024
|
Monitor the warm pod pool.
|
|
@@ -737,6 +1086,7 @@ Most commands support `--json` for machine-readable output, useful for scripting
|
|
|
737
1086
|
```bash
|
|
738
1087
|
stateset sandbox list --json | jq '.[0].id'
|
|
739
1088
|
stateset pool stats --json
|
|
1089
|
+
stateset swarm get <id> --json | jq '.tasks[] | {key, phase, cost_cents}'
|
|
740
1090
|
stateset grade --json
|
|
741
1091
|
```
|
|
742
1092
|
|
package/dist/client.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import type { SandboxInfo, ExecuteResult, AgentSession, AgentEvent, StreamCallbacks, TaskRegistryApi, AuditReadMetadata, CreateTunnelOptions } from '@stateset/sandbox-sdk';
|
|
1
|
+
import type { SandboxInfo, ExecuteResult, AgentSession, AgentEvent, StreamCallbacks, TaskRegistryApi, AuditReadMetadata, CreateTunnelOptions, CreateSwarmOptions, ListSwarmsOptions, Swarm, SwarmPage } from '@stateset/sandbox-sdk';
|
|
2
2
|
export interface CheckpointInfo {
|
|
3
3
|
id: string;
|
|
4
4
|
sandbox_id: string;
|
|
@@ -154,6 +154,19 @@ export interface CliTerminals {
|
|
|
154
154
|
caseSensitive?: boolean;
|
|
155
155
|
limit?: number;
|
|
156
156
|
}) => Promise<TerminalSearchInfo>;
|
|
157
|
+
/** A Claude Code session's state, then each change, until the terminal ends; absent on an SDK that predates it. */
|
|
158
|
+
watchClaudeCode?: (sandboxId: string, terminalId: string, options?: {
|
|
159
|
+
intervalMs?: number;
|
|
160
|
+
settleMs?: number;
|
|
161
|
+
signal?: AbortSignal;
|
|
162
|
+
}) => AsyncGenerator<ClaudeCodeStatusInfo, TerminalScreenInfo | undefined>;
|
|
163
|
+
}
|
|
164
|
+
/** What a Claude Code session in a terminal is doing, read off its screen. */
|
|
165
|
+
export interface ClaudeCodeStatusInfo {
|
|
166
|
+
state: 'working' | 'waiting' | 'permission' | 'unknown';
|
|
167
|
+
/** The permission dialog's title, or the spinner's line while working. */
|
|
168
|
+
detail?: string;
|
|
169
|
+
screen: TerminalScreenInfo;
|
|
157
170
|
}
|
|
158
171
|
export interface TerminalSearchInfo {
|
|
159
172
|
matches: Array<{
|
|
@@ -215,6 +228,8 @@ export interface CliClient {
|
|
|
215
228
|
maxBytes?: number;
|
|
216
229
|
}) => AsyncIterable<Uint8Array>;
|
|
217
230
|
create: (options: Record<string, unknown>) => Promise<SandboxInfo>;
|
|
231
|
+
/** POST /sandbox/create-from-template: writes the template's files and runs its setup commands. */
|
|
232
|
+
createFromTemplate: (templateId: string, options?: Record<string, unknown>) => Promise<SandboxInfo>;
|
|
218
233
|
list: () => Promise<{
|
|
219
234
|
sandboxes: SandboxInfo[];
|
|
220
235
|
}>;
|
|
@@ -447,6 +462,19 @@ export interface CliClient {
|
|
|
447
462
|
name: string;
|
|
448
463
|
}>;
|
|
449
464
|
};
|
|
465
|
+
swarms: {
|
|
466
|
+
/**
|
|
467
|
+
* Store a plan. The SDK sends a random `Idempotency-Key` of its own with each call, which the caller cannot
|
|
468
|
+
* set, so a second call stores a second swarm; the service gives the first answer only to the same key,
|
|
469
|
+
* within 24 hours. Within a call the SDK sends it again, with the same key, only when the service certainly
|
|
470
|
+
* did not act on it.
|
|
471
|
+
*/
|
|
472
|
+
create: (options: CreateSwarmOptions) => Promise<Swarm>;
|
|
473
|
+
/** One page, newest first, without tasks. */
|
|
474
|
+
list: (options?: ListSwarmsOptions) => Promise<SwarmPage>;
|
|
475
|
+
get: (swarmId: string) => Promise<Swarm>;
|
|
476
|
+
cancel: (swarmId: string) => Promise<Swarm>;
|
|
477
|
+
};
|
|
450
478
|
secrets: {
|
|
451
479
|
list: () => Promise<{
|
|
452
480
|
secrets: SecretInfo[];
|