@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.
- package/CHANGELOG.md +140 -0
- package/README.md +467 -41
- package/dist/client.d.ts +131 -1
- package/dist/client.d.ts.map +1 -1
- package/dist/client.js +21 -0
- package/dist/client.js.map +1 -1
- package/dist/commands/billing.js +36 -2
- package/dist/commands/billing.js.map +1 -1
- package/dist/commands/config.js +8 -1
- package/dist/commands/config.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 +222 -17
- package/dist/commands/sandbox.js.map +1 -1
- package/dist/commands/swarm.d.ts +18 -0
- package/dist/commands/swarm.d.ts.map +1 -0
- package/dist/commands/swarm.js +379 -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/ephemeral-storage.d.ts +12 -0
- package/dist/utils/ephemeral-storage.d.ts.map +1 -0
- package/dist/utils/ephemeral-storage.js +39 -0
- package/dist/utils/ephemeral-storage.js.map +1 -0
- package/dist/utils/swarm-dispatcher.d.ts +50 -0
- package/dist/utils/swarm-dispatcher.d.ts.map +1 -0
- package/dist/utils/swarm-dispatcher.js +137 -0
- package/dist/utils/swarm-dispatcher.js.map +1 -0
- 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 +118 -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 +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
|