@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.
Files changed (54) hide show
  1. package/CHANGELOG.md +88 -0
  2. package/README.md +351 -1
  3. package/dist/client.d.ts +29 -1
  4. package/dist/client.d.ts.map +1 -1
  5. package/dist/client.js +10 -0
  6. package/dist/client.js.map +1 -1
  7. package/dist/commands/run.d.ts.map +1 -1
  8. package/dist/commands/run.js +48 -15
  9. package/dist/commands/run.js.map +1 -1
  10. package/dist/commands/sandbox.d.ts.map +1 -1
  11. package/dist/commands/sandbox.js +62 -16
  12. package/dist/commands/sandbox.js.map +1 -1
  13. package/dist/commands/swarm.d.ts +12 -0
  14. package/dist/commands/swarm.d.ts.map +1 -0
  15. package/dist/commands/swarm.js +288 -0
  16. package/dist/commands/swarm.js.map +1 -0
  17. package/dist/commands/terminal.d.ts +3 -1
  18. package/dist/commands/terminal.d.ts.map +1 -1
  19. package/dist/commands/terminal.js +58 -1
  20. package/dist/commands/terminal.js.map +1 -1
  21. package/dist/commands/workbench.d.ts +138 -0
  22. package/dist/commands/workbench.d.ts.map +1 -0
  23. package/dist/commands/workbench.js +531 -0
  24. package/dist/commands/workbench.js.map +1 -0
  25. package/dist/index.js +5 -1
  26. package/dist/index.js.map +1 -1
  27. package/dist/utils/swarm-plan.d.ts +69 -0
  28. package/dist/utils/swarm-plan.d.ts.map +1 -0
  29. package/dist/utils/swarm-plan.js +321 -0
  30. package/dist/utils/swarm-plan.js.map +1 -0
  31. package/dist/utils/template-create.d.ts +36 -0
  32. package/dist/utils/template-create.d.ts.map +1 -0
  33. package/dist/utils/template-create.js +116 -0
  34. package/dist/utils/template-create.js.map +1 -0
  35. package/dist/workbench/actions.d.ts +1 -1
  36. package/dist/workbench/actions.d.ts.map +1 -1
  37. package/dist/workbench/actions.js +1 -0
  38. package/dist/workbench/actions.js.map +1 -1
  39. package/dist/workbench/agents.d.ts +96 -0
  40. package/dist/workbench/agents.d.ts.map +1 -0
  41. package/dist/workbench/agents.js +370 -0
  42. package/dist/workbench/agents.js.map +1 -0
  43. package/dist/workbench/commands.d.ts.map +1 -1
  44. package/dist/workbench/commands.js +7 -1
  45. package/dist/workbench/commands.js.map +1 -1
  46. package/dist/workbench/model.d.ts +5 -1
  47. package/dist/workbench/model.d.ts.map +1 -1
  48. package/dist/workbench/model.js +15 -2
  49. package/dist/workbench/model.js.map +1 -1
  50. package/dist/workbench/terminal.d.ts +1 -1
  51. package/dist/workbench/terminal.d.ts.map +1 -1
  52. package/dist/workbench/terminal.js +108 -78
  53. package/dist/workbench/terminal.js.map +1 -1
  54. 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[];