@stateset/sandbox-cli 3.3.1 → 3.6.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 (66) hide show
  1. package/CHANGELOG.md +140 -0
  2. package/README.md +467 -41
  3. package/dist/client.d.ts +131 -1
  4. package/dist/client.d.ts.map +1 -1
  5. package/dist/client.js +21 -0
  6. package/dist/client.js.map +1 -1
  7. package/dist/commands/billing.js +36 -2
  8. package/dist/commands/billing.js.map +1 -1
  9. package/dist/commands/config.js +8 -1
  10. package/dist/commands/config.js.map +1 -1
  11. package/dist/commands/run.d.ts.map +1 -1
  12. package/dist/commands/run.js +48 -15
  13. package/dist/commands/run.js.map +1 -1
  14. package/dist/commands/sandbox.d.ts.map +1 -1
  15. package/dist/commands/sandbox.js +222 -17
  16. package/dist/commands/sandbox.js.map +1 -1
  17. package/dist/commands/swarm.d.ts +18 -0
  18. package/dist/commands/swarm.d.ts.map +1 -0
  19. package/dist/commands/swarm.js +379 -0
  20. package/dist/commands/swarm.js.map +1 -0
  21. package/dist/commands/terminal.d.ts +3 -1
  22. package/dist/commands/terminal.d.ts.map +1 -1
  23. package/dist/commands/terminal.js +58 -1
  24. package/dist/commands/terminal.js.map +1 -1
  25. package/dist/commands/workbench.d.ts +138 -0
  26. package/dist/commands/workbench.d.ts.map +1 -0
  27. package/dist/commands/workbench.js +531 -0
  28. package/dist/commands/workbench.js.map +1 -0
  29. package/dist/index.js +5 -1
  30. package/dist/index.js.map +1 -1
  31. package/dist/utils/ephemeral-storage.d.ts +12 -0
  32. package/dist/utils/ephemeral-storage.d.ts.map +1 -0
  33. package/dist/utils/ephemeral-storage.js +39 -0
  34. package/dist/utils/ephemeral-storage.js.map +1 -0
  35. package/dist/utils/swarm-dispatcher.d.ts +50 -0
  36. package/dist/utils/swarm-dispatcher.d.ts.map +1 -0
  37. package/dist/utils/swarm-dispatcher.js +137 -0
  38. package/dist/utils/swarm-dispatcher.js.map +1 -0
  39. package/dist/utils/swarm-plan.d.ts +69 -0
  40. package/dist/utils/swarm-plan.d.ts.map +1 -0
  41. package/dist/utils/swarm-plan.js +321 -0
  42. package/dist/utils/swarm-plan.js.map +1 -0
  43. package/dist/utils/template-create.d.ts +36 -0
  44. package/dist/utils/template-create.d.ts.map +1 -0
  45. package/dist/utils/template-create.js +118 -0
  46. package/dist/utils/template-create.js.map +1 -0
  47. package/dist/workbench/actions.d.ts +1 -1
  48. package/dist/workbench/actions.d.ts.map +1 -1
  49. package/dist/workbench/actions.js +1 -0
  50. package/dist/workbench/actions.js.map +1 -1
  51. package/dist/workbench/agents.d.ts +96 -0
  52. package/dist/workbench/agents.d.ts.map +1 -0
  53. package/dist/workbench/agents.js +370 -0
  54. package/dist/workbench/agents.js.map +1 -0
  55. package/dist/workbench/commands.d.ts.map +1 -1
  56. package/dist/workbench/commands.js +7 -1
  57. package/dist/workbench/commands.js.map +1 -1
  58. package/dist/workbench/model.d.ts +5 -1
  59. package/dist/workbench/model.d.ts.map +1 -1
  60. package/dist/workbench/model.js +15 -2
  61. package/dist/workbench/model.js.map +1 -1
  62. package/dist/workbench/terminal.d.ts +1 -1
  63. package/dist/workbench/terminal.d.ts.map +1 -1
  64. package/dist/workbench/terminal.js +108 -78
  65. package/dist/workbench/terminal.js.map +1 -1
  66. package/package.json +15 -7
package/CHANGELOG.md CHANGED
@@ -6,6 +6,146 @@ the repository [CHANGELOG](../CHANGELOG.md). This package follows
6
6
 
7
7
  ## [Unreleased]
8
8
 
9
+ ## [3.6.0] - 2026-11-18
10
+
11
+ - `stateset sandbox health <id> [--json]` shows a sandbox's status, CPU, memory and ephemeral storage as used / limit (percent), near-limit warnings, restarts with the last reason, why and when it ended, its last samples, its events and how long the history of an ended sandbox is kept (`GET /sandboxes/{id}/health`); `--json` prints the API's body unchanged.
12
+ - `stateset config setup` whose input closes before the prompts are answered (Ctrl-D, Ctrl-C, or no terminal on stdin) now prints `Setup was cancelled before it finished. Nothing was saved.` and exits 1. Before, it ended in an `ExitPromptError` stack trace with exit status 0.
13
+ - Dependencies: `conf` (the config store) moved from 13 to 15 (15.1.0), not 16, whose `engines` (`node: >=22`) drops Node 20.19+. The config files keep their location (`<config dir>/stateset-sandbox-nodejs/config.json`, likewise the `-context` and `-aliases` stores) and JSON format, so an existing config is read as before.
14
+
15
+ ## [3.5.0] - 2026-11-14
16
+
17
+ ### Added
18
+
19
+ - `stateset sandbox create --ephemeral-storage <size>` asks for ephemeral storage as whole Gi from
20
+ `1Gi` to `50Gi` (`ephemeral_storage`); anything else is refused, naming the flag, before a request
21
+ is sent. `--strict` (`strict: true`) fails instead of creating a sandbox with less ephemeral
22
+ storage than asked for. The API grants a size up to the lower of the platform's limit and the
23
+ plan's and reports it; when the create asked for a size (the flag's, else the one its template
24
+ declares) the output has a line `Ephemeral storage: <granted>`, and `--json` has the API's
25
+ `ephemeral_storage_grant` under `ephemeralStorageGrant` (as nested keys with `--format yaml`, as
26
+ JSON in one cell with `--format csv`). When less was granted, the sandbox is created, the exit
27
+ status stays 0, and a warning is printed on stderr in every output format: `Ephemeral storage:
28
+ 20Gi granted, 30Gi requested (platform limit 20Gi). Use --strict to fail instead.` (`plan limit`
29
+ for the plan's). With `--strict` the API refuses such a create with a 400 and creates nothing:
30
+ the CLI prints the API's message, which names the size and the limit, and exits 1. For a template
31
+ with setup, `--strict` is sent to `POST /sandbox/create-from-template` and the grant in its
32
+ response is printed the same way; `--ephemeral-storage` is refused by name before that route is
33
+ called, since it has no such field. Both flags are in the `--dry-run` summary. `stateset run`
34
+ and the workbench are unchanged.
35
+ - `stateset sandbox summary [--json]` prints the organization's sandboxes in aggregate from
36
+ `GET /sandboxes/summary`: the total with the running, starting, paused and stopped counts; the
37
+ vCPU, memory and storage (ephemeral and workspace) held by running sandboxes; the counts by
38
+ template and by isolation, highest first; and today's estimated spend (UTC) in dollars, or `not
39
+ available` when the API gives none. An organization with no sandboxes prints zeros and exits 0.
40
+ `--json` (or the global `--format json`) prints the API's body unchanged. Needs the
41
+ `sandbox:read` scope.
42
+
43
+ ## [3.4.0] - 2026-11-13
44
+
45
+ ### Added
46
+
47
+ - `stateset swarm create --plan <file.json> [--name <name>] [--json]` stores a swarm plan file
48
+ (what `examples/claude-agent/swarm-plan.mjs` writes) as a swarm in the service (`POST /swarms`).
49
+ The plan is checked against the API's limits before anything is sent: a plan with problems ends
50
+ in exit status 1 with the file and one line per problem on stderr, also under the global
51
+ `--dry-run`, which checks a plan without storing it. A task's `id` is sent as `key`; `sandbox`,
52
+ `union` and what else the API has no field for are left out. The name is `--name`, else the
53
+ plan's `name`, else the file's name without `.json`. It prints `Swarm "<name>" created: <id>`
54
+ and how to follow the swarm (`stateset swarm watch <id>`), or the swarm with `--json`. It starts
55
+ no sandbox and runs no task, and the request is sent once. A create refused because the
56
+ organization holds its limit of unfinished swarms (429 `CONCURRENT_LIMIT_EXCEEDED`) prints the
57
+ API's message and a hint about swarms (`stateset swarm cancel <id>`, `stateset swarm list
58
+ --status running`) in place of the one about sandboxes.
59
+ - `stateset swarm list [--status <s>] [--limit <n>] [--json]`, `stateset swarm get <id> [--json]`
60
+ and `stateset swarm cancel <id> [--json]` show and cancel the swarms the service keeps
61
+ (`/api/v1/swarms`). `get` prints the name, status and goal on one line, then a table of the
62
+ tasks (key, phase, branch, cost in dollars, blocked by). A swarm that does not exist (404) and a
63
+ completed or failed swarm that cannot be cancelled (409) each end in one line and exit status 1,
64
+ without the request being repeated. `cancel` changes the record only and stops no sandbox.
65
+ - `stateset swarm watch <id> [--interval <seconds>]` follows one swarm: it prints what
66
+ `swarm get` prints, looks again every `--interval` seconds (default 5) and ends when the swarm
67
+ is `completed`, `failed` or `cancelled`. It then prints `Swarm "<name>" completed` or
68
+ `Swarm "<name>" was cancelled` with exit status 0, or, for a failed swarm, one line on stderr
69
+ that names the failed tasks, with exit status 1. In a terminal the screen is cleared before each
70
+ look and a line says how often it looks and when it last did; in a pipe or a CI log the swarm is
71
+ printed again only when it has changed. A swarm that does not exist (404), on the first look or
72
+ a later one, ends in the line of `swarm get` and exit status 1. There is no `--json`: scripts
73
+ read `swarm get <id> --json`.
74
+ - `stateset swarm list`, `swarm get` and `swarm watch` take `--dispatcher <home-dir>` and then
75
+ print one more line: what the swarm dispatcher with that home directory
76
+ (`examples/claude-agent/swarm-dispatch.mjs`) is doing, and why it takes nothing from its
77
+ backlog if it waits. A dispatcher reports nothing to the service; the line is read from
78
+ `status.json` in its home directory, on this machine. It is
79
+ `Dispatcher <home>: waiting since <since> (<limit>): <reason>` with the dispatcher's own reason
80
+ whole (it names the time or the branches to merge that release the limit),
81
+ `Dispatcher <home>: <state>.` for one that waits for nothing,
82
+ `Dispatcher <home>: not running (status.json says "<state>", written <updated_at>).` when no
83
+ dispatcher is running or the process the file names is gone, and
84
+ `Dispatcher <home>: no status could be read (<why>).` for a file that is missing, not JSON or
85
+ no status. `list` prints it last, `get` after the task table, and `watch` under the table at
86
+ every look, reading the file anew: in a pipe or a CI log a reason that changed or cleared is
87
+ printed once. A status that cannot be read changes neither the swarms printed nor the exit
88
+ status. With `--json` or the global JSON format the output is unchanged and the line is left
89
+ out. The option has no default and no environment variable, and `create` and `cancel` do not
90
+ take it. The dashboard's Swarms page does not show the line: it reads swarms from the service,
91
+ which is not sent the dispatcher's status.
92
+ - `sandbox create --template <id>` and `run --template <id>` create the sandbox from a built-in
93
+ template (`stateset template list`). The id is sent unchanged as `template` on
94
+ `POST /sandbox/create`; without `--timeout` the template's timeout applies instead of the
95
+ profile default. An unknown template, or one the route refuses, is reported with the API's
96
+ message.
97
+ - `--template` now works for every built-in template, including the eight that write files or run
98
+ setup commands (`python-basic`, `node-basic`, `go-basic`, `rust-basic`, `node-express-api`,
99
+ `python-data-science`, `python-llm`, `devops-tools`). `POST /sandbox/create` refuses those with
100
+ a 400 naming `POST /sandbox/create-from-template`; on that answer, and no other, the CLI creates
101
+ the sandbox with that route. Neither request is repeated by the CLI.
102
+ - The spinner says that setup is running and how long the CLI waits: 510 seconds (the startup
103
+ wait plus the 300 the API allows a setup command), or `--startup-timeout` when given.
104
+ - `--isolation`, `--desktop-os` and `--credential`, which the template route has no field for,
105
+ are refused by name before it is called.
106
+ - A setup step that fails leaves the sandbox running. `sandbox create` prints the API's message
107
+ for each failed step and that the sandbox was kept, adds `warnings` to `--json`, and exits 1.
108
+ `run` does not run the command, stops the sandbox unless `--keep` is given, and exits 1.
109
+ - When the template route's outcome is unknown (timeout, dropped connection, 5xx) the error says
110
+ the sandbox may exist.
111
+ - `sandbox create` accepts `--json` (and the global `--json` / `--format`) and prints the created
112
+ sandbox, with `template` when one was asked for. `run --json` carries the same `template` key.
113
+ - `stateset workbench up|open|pull|down`: create claude-code sandboxes with the current
114
+ repository's HEAD at `/workspace/repo` and Claude Code running in a terminal in each;
115
+ attach to them (one Herdr tab per sandbox inside Herdr); save each one's changes since
116
+ the base commit as a patch file; stop only the sandboxes the workbench created.
117
+ `up` takes `--repo <path>`, `--base <rev>`, `--hours <n>` and `--shell`; `open`, `pull`
118
+ and `down` take `--repo <path>`.
119
+ - `stateset terminal status <sandbox-id> <terminal-id>` says whether Claude Code in the terminal is
120
+ working, waiting for input, or blocked on a permission prompt. `--watch` keeps going and prints each
121
+ change with its time until the terminal ends; `--json` prints one object per line. Needs an SDK with
122
+ `terminals.watchClaudeCode`.
123
+ - `stateset tui --agents <dir>` (repeatable; also `STATESET_AGENT_DIRS`, a PATH-style list) shows
124
+ what each sandbox is for from local agent records: `fleet-state.json` and `workbench.json` in the
125
+ named directories and one level below. The list gains `AGENT` and `PHASE` columns, sandbox
126
+ details add fleet, task, objective, phase, branch, pull request, cost and error, and `v` opens a
127
+ view of every recorded agent grouped by fleet, including those whose sandbox is gone. `*` and
128
+ `dup:N` flag likely duplicates: agents still working under matching names. Files are stat'ed on
129
+ each refresh and parsed only when changed; unusable files are skipped with one dimmed note;
130
+ control characters and escape sequences are removed from everything shown. No API requests are
131
+ added.
132
+ - `stateset tui` lists the sandboxes of `stateset workbench up` in the same columns and agents
133
+ view, without a flag: started inside a git repository, it also scans that repository's workbench
134
+ state directory (`.git/stateset-workbench`) once the directory exists, in addition to `--agents`
135
+ and `STATESET_AGENT_DIRS`. Each member of a `<name>.json` record there is an agent named by its
136
+ label and grouped under the workbench, with the phase `interactive`, `creating`, `failed` (with
137
+ the error) or `stopped`. Other files in that directory are ignored without a note; the size
138
+ limit, parse-only-when-changed and control-character rules apply as for the other records. A
139
+ `workbench.json` in an `--agents` directory may hold this format or the older `benches` one.
140
+
141
+ ### Fixed
142
+
143
+ - `stateset swarm get` and `stateset swarm cancel` said `Swarm "<id>" not found` for every 404.
144
+ They say so now only when the API answered `SWARM_NOT_FOUND` (the SDK error's `wireCode`); any
145
+ other 404 prints the line of `stateset swarm list` for an API without swarm routes.
146
+ - `stateset swarm cancel` repeated a cancel the service failed on top of the SDK's own retries
147
+ (16 requests for a service that always answers 500). It now makes the SDK call once: 4 requests.
148
+
9
149
  ## [3.3.1] - 2026-11-04
10
150
 
11
151
  The first npm registry release since 1.0.6. 3.x has been built from this repository since the