@withgateway/sdk 0.2.8 → 0.2.9
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/README.md +24 -8
- package/dist/cli.js +332 -163
- package/dist/cli.js.map +1 -1
- package/dist/cli.mjs +332 -163
- package/dist/cli.mjs.map +1 -1
- package/dist/files/index.js +119 -15
- package/dist/files/index.js.map +1 -1
- package/dist/files/index.mjs +119 -15
- package/dist/files/index.mjs.map +1 -1
- package/dist/index.d.mts +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.js +229 -120
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +220 -120
- package/dist/index.mjs.map +1 -1
- package/dist/traces/index.js +119 -15
- package/dist/traces/index.js.map +1 -1
- package/dist/traces/index.mjs +119 -15
- package/dist/traces/index.mjs.map +1 -1
- package/dist/tracing/index.js +1 -1
- package/dist/tracing/index.js.map +1 -1
- package/dist/tracing/index.mjs +1 -1
- package/dist/tracing/index.mjs.map +1 -1
- package/dist/worlds/index.d.mts +78 -9
- package/dist/worlds/index.d.ts +78 -9
- package/dist/worlds/index.js +219 -119
- package/dist/worlds/index.js.map +1 -1
- package/dist/worlds/index.mjs +220 -120
- package/dist/worlds/index.mjs.map +1 -1
- package/package.json +1 -1
- package/runtime/gatewaysdk/environment/_toml.py +3 -10
- package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +3 -3
- package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +1 -1
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +11 -11
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +3 -2
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +5 -1
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/new-world-sandbox.md +5 -3
- package/runtime/gatewaysdk/environment/schema/store.py +15 -6
- package/skills/benchmarks-getting-started/SKILL.md +3 -3
- package/skills/connector-schema-authoring/SKILL.md +1 -1
- package/skills/connector-schema-authoring/world-schema.md +1 -1
- package/skills/worlds-getting-started/SKILL.md +11 -11
- package/skills/worlds-getting-started/references/cli-mcp-map.md +3 -2
- package/skills/worlds-getting-started/references/gotchas.md +5 -1
- package/skills/worlds-getting-started/references/new-world-sandbox.md +5 -3
package/package.json
CHANGED
|
@@ -1,13 +1,6 @@
|
|
|
1
|
-
"""The one TOML reader for every Python
|
|
1
|
+
"""The one TOML reader for the SDK: the stdlib ``tomllib`` (every supported Python ships it).
|
|
2
|
+
Import it from here so a future fallback lives in one place."""
|
|
2
3
|
|
|
3
|
-
|
|
4
|
-
``tomli; python_version < '3.11'``). Import ``tomllib`` from here, never the
|
|
5
|
-
stdlib module directly, so the fallback lives in one place.
|
|
6
|
-
"""
|
|
7
|
-
|
|
8
|
-
try:
|
|
9
|
-
import tomllib
|
|
10
|
-
except ModuleNotFoundError: # pragma: no cover - python 3.10
|
|
11
|
-
import tomli as tomllib # type: ignore[no-redef]
|
|
4
|
+
import tomllib
|
|
12
5
|
|
|
13
6
|
__all__ = ["tomllib"]
|
|
@@ -48,7 +48,7 @@ Segmentation, so one substrate never crashes into the other's infrastructure:
|
|
|
48
48
|
## 0. Authenticate
|
|
49
49
|
|
|
50
50
|
```bash
|
|
51
|
-
npm install -g @withgateway/sdk # the gateway CLI (TypeScript; python3 >= 3.
|
|
51
|
+
npm install -g @withgateway/sdk # the gateway CLI (TypeScript; python3 >= 3.12 runs the local runtime)
|
|
52
52
|
gateway auth login --host https://<your-gateway> --public-key pk-lf-... --api-key sk-lf-...
|
|
53
53
|
```
|
|
54
54
|
|
|
@@ -57,7 +57,7 @@ gateway auth login --host https://<your-gateway> --public-key pk-lf-... --api-ke
|
|
|
57
57
|
is reachable and prints the exact plan when it is not; `dry-run --hosted` runs the same one task on
|
|
58
58
|
the benchmark runner (harbor's oracle, no model), so a machine with nothing but the npm CLI and project
|
|
59
59
|
keys can author, dry-run, push and run a container benchmark; on a world it opens the task's session
|
|
60
|
-
in the bundled Python runtime (python3 >= 3.
|
|
60
|
+
in the bundled Python runtime (python3 >= 3.12) and prints the plan when there is none.
|
|
61
61
|
|
|
62
62
|
## A. A harbor (container) benchmark: init → validate → dry-run → push → run → results
|
|
63
63
|
|
|
@@ -409,7 +409,7 @@ reward is for the untouched world; an agent's rollout is what `benchmarks run` g
|
|
|
409
409
|
|
|
410
410
|
A verifier that cannot run — bad SQL, a missing entity — prints `FAIL verifier 'x': …` with SQLite's
|
|
411
411
|
words and exits 1; that is what the dry run is for. A reward of 1.0 here means the verifier passes
|
|
412
|
-
before any agent acts: rewrite it. Without the bundled runtime (no python3 >= 3.
|
|
412
|
+
before any agent acts: rewrite it. Without the bundled runtime (no python3 >= 3.12) the four steps
|
|
413
413
|
print and the run is marked not executed, exit 0.
|
|
414
414
|
|
|
415
415
|
A hand-driven rollout, the way an agent's session goes:
|
|
@@ -193,7 +193,7 @@ When adding a bridge command to `schema/platform.py`, mirror it as a typed wrapp
|
|
|
193
193
|
`worldSchemaRuntime.ts` (`compileWorldFiles` / `applyWorldBatch` are the pattern: file map
|
|
194
194
|
in, `{entries, report, ...}` out, errors as `SchemaBridgeError`), cover it in
|
|
195
195
|
`tests/environment/test_schema_platform.py`, and let the agent tool call the wrapper, never
|
|
196
|
-
the subprocess. The bridge needs Python ≥ 3.
|
|
196
|
+
the subprocess. The bridge needs Python ≥ 3.12 (`tomllib`, and the store's sqlite `setconfig`); set `GATEWAY_SCHEMA_PYTHON`
|
|
197
197
|
when the default interpreter is older.
|
|
198
198
|
|
|
199
199
|
Use `worldSchemaRuntime.ts` for platform validation and `schema.platform` for
|
|
@@ -29,22 +29,22 @@ gateway auth login --host https://<your-gateway> --public-key pk-lf-... --api-ke
|
|
|
29
29
|
gateway auth status # or export GATEWAY_HOST / GATEWAY_PUBLIC_KEY / GATEWAY_SECRET_KEY
|
|
30
30
|
```
|
|
31
31
|
|
|
32
|
-
The npm package bundles the schema runtime (stdlib-only Python). With a `python3 >= 3.
|
|
32
|
+
The npm package bundles the schema runtime (stdlib-only Python). With a `python3 >= 3.12` on the
|
|
33
33
|
machine every runtime command runs locally, including `worlds serve` and a local `connector
|
|
34
34
|
capture`, with no pip and no login; without one, the CLI sends the world's files to the platform
|
|
35
35
|
(`POST /api/public/worlds/runtime`) and the same code runs there (`worlds serve` then opens a hosted
|
|
36
36
|
api session, `connector capture` needs `--remote`). `GATEWAY_RUNTIME=local|platform` forces a side.
|
|
37
37
|
|
|
38
|
-
The interpreter: `GATEWAY_PYTHON` when set, else the first of `python3.13`, `python3.12`, `python3
|
|
39
|
-
`python`, then `uv python find` that is 3.
|
|
38
|
+
The interpreter: `GATEWAY_PYTHON` when set, else the first of `python3.13`, `python3.12`, `python3`,
|
|
39
|
+
`python`, then `uv python find` that is 3.12 or newer. A Mac whose `python3` is the system 3.9 is not a dead end: the
|
|
40
40
|
CLI prints one line naming what it found and what to set — `GATEWAY_PYTHON="$(brew --prefix python@3.12)/bin/python3.12"`
|
|
41
41
|
or `GATEWAY_PYTHON="$(uv python find 3.12)"` (Brex retrospective: this used to be discovered by hand).
|
|
42
42
|
|
|
43
43
|
Or export `GATEWAY_HOST`, `GATEWAY_PUBLIC_KEY`, `GATEWAY_SECRET_KEY` (env wins over the config file). A file of them
|
|
44
44
|
works as written by a person, not only as the shell sources it: `GATEWAY_ENV_FILE=.env gateway …` accepts `KEY = value`
|
|
45
45
|
(spaces around `=`), quoted values, `export KEY=value` and `#` comments; a variable already in the shell's environment
|
|
46
|
-
wins, and vendor keys named by `connector.toml` ride along for a local capture. Every command below accepts `--host
|
|
47
|
-
Keys are project keys: the world lands in that project.
|
|
46
|
+
wins, and vendor keys named by `connector.toml` ride along for a local capture. Every command below accepts `--host`; `GATEWAY_TIMEOUT_MS` (default 120000) bounds one request, and a host that never answers is one line: cause + next step.
|
|
47
|
+
Keys are project keys: the world lands in that project. Every verb whose output is JSON takes `--json` as a no-op.
|
|
48
48
|
|
|
49
49
|
MCP: the server is authenticated by the same project API key (or a PAT). Call `describe_project({})`
|
|
50
50
|
first, then `guide({ topic: "connectors" })` for the connector loop and `guide({ topic: "world-data" })` for data.
|
|
@@ -323,7 +323,7 @@ gateway worlds session reset <SESSION_ID> # back to the snapsh
|
|
|
323
323
|
gateway worlds session grade <SESSION_ID> [--timeout S] # {reward, rewards, raw}; exploratory → {reward: null, reason: "no grader"}
|
|
324
324
|
gateway worlds session export <SESSION_ID> --out calls.jsonl
|
|
325
325
|
gateway worlds data ingest x calls.jsonl --transform shape.py # the calls back in as rows, shaped by your code or --map ingest.toml (world-data-ingestion §2c)
|
|
326
|
-
gateway worlds session close <SESSION_ID>
|
|
326
|
+
gateway worlds session close <SESSION_ID> # a closed session reopens by id, same URLs + token, from its last checkpoint: gateway worlds session reopen <SESSION_ID>
|
|
327
327
|
```
|
|
328
328
|
|
|
329
329
|
**A task outside the bundle.** `-t <name>` picks a scenario the version ships. On a World Host
|
|
@@ -391,15 +391,15 @@ gateway bench dispatch <RUN_CONFIG_ID> # each stored task
|
|
|
391
391
|
The first session on a freshly pushed version takes about fifteen minutes: the pod is
|
|
392
392
|
scheduled and the runner sidecar pulled; the session reads `PROVISIONING` and the api URL
|
|
393
393
|
answers 503. That is a cold start, not a fault, until about twenty minutes have passed.
|
|
394
|
-
`session open` waits ten minutes
|
|
394
|
+
`session open` prints `session <id> opening — gateway worlds session status <id>` on stderr at once, then waits ten minutes; on a cold version use `--no-wait` and poll. `open` and
|
|
395
395
|
`status` print `idleExpiresAt` (null once pinned) + `pinned`; `status` warns under 5 minutes. A call
|
|
396
396
|
body over 4mb is refused client-side: `{status: "error", code: "payload_too_large"}`, exit 2.
|
|
397
397
|
|
|
398
398
|
The world's API honours the vendor's auth scheme; `WORLD_API_KEY` on the host pins the
|
|
399
399
|
credential, otherwise any non-empty one is accepted.
|
|
400
400
|
|
|
401
|
-
MCP: `
|
|
402
|
-
|
|
401
|
+
MCP: `seed_world_session`, `export_world_session`, `save_world_session_task`; open/call/close are CLI or REST only.
|
|
402
|
+
Find what you opened: `gateway worlds session list` / `sandbox list`; `session pin <id>` stops the reaper.
|
|
403
403
|
|
|
404
404
|
## Test the world (not the agent)
|
|
405
405
|
|
|
@@ -479,8 +479,8 @@ schema|data|test|serve|call …` on the working copy with nothing on your machin
|
|
|
479
479
|
`session open`) stop inside the sandbox by design: it holds no platform credential, and never write one
|
|
480
480
|
into its tree — `check`/`commit` hold back scratch, credential-shaped files (`.env`, `.gateway-env`, `*.env`,
|
|
481
481
|
`*.pem`…) and symlinks (`ignored` + `warnings`, paths only); over 2000 files or 128 MB is refused before
|
|
482
|
-
any read. `worlds run --path` on a clean `bench pull` checkout files runs pinned to the base version.
|
|
483
|
-
Sandbox twins and every limit: `references/cli-mcp-map.md`.
|
|
482
|
+
any read. `sandbox commit <id> -m why --rebase` replays your edits onto a branch that moved since `open`; a path changed on both sides is a 409, one `conflict: <path> (<reason>)` line each on stderr, exit 1. `worlds run --path` on a clean `bench pull` checkout files runs pinned to the base version.
|
|
483
|
+
Work is saved while a sandbox sits idle and resumes by id, but after 7 idle days (`status` shows `idleExpiresAt`) the platform closes it even with uncommitted files, and a closed sandbox cannot be reopened: commit before you walk away. `sandbox close <id>` refuses uncommitted files (exit 1, their paths on stderr) unless `--force`. Sandbox twins and every limit: `references/cli-mcp-map.md`.
|
|
484
484
|
|
|
485
485
|
MCP: `list_world_edits({ slug })`, `close_world_edit`, `discard_world_edit`, `rollback_world_edit({ slug, sessionId })`; `env_diff({ containerId })`, `env_run_tests`, `env_get_run`; proposals (`env_propose`, `env_list_proposals`, `env_apply_proposal`, `env_dismiss_proposal`) are the legacy PR-style door.
|
|
486
486
|
|
|
@@ -17,9 +17,10 @@ Reference for `worlds-getting-started`: every CLI step and its MCP twin, then ho
|
|
|
17
17
|
| `worlds migrate <slug> [--apply] [--force]` / `--all` | `migrate_world` |
|
|
18
18
|
| `bench push` | `env_write_file` + `env_commit`, or `create_environment_version` (one file) |
|
|
19
19
|
| `worlds data import` | `import_world_data` |
|
|
20
|
-
| `worlds session open [-t\|--task-id\|--task-file]` (none: exploratory) / `status` / `call` / `close`
|
|
20
|
+
| `worlds session open [-t\|--task-id\|--task-file]` (none: exploratory) / `status` / `call` / `close` / `list` / `pin` | none on the public MCP server — CLI or REST only (`/api/public/world-sessions[/{id}[/calls]]`; the open answers `idleExpiresAt` + `pinned`) |
|
|
21
21
|
| `worlds session seed` | `seed_world_session` |
|
|
22
22
|
| `worlds session export` | `export_world_session` |
|
|
23
|
+
| `worlds session reopen <id>` | — (no MCP twin; `POST /api/public/world-sessions/{id}/reopen`: a closed session back under the same id, URLs and token from its last checkpoint, answering what `status` answers; 409 `session_not_closed` / `session_no_checkpoint` / `session_reopen_in_progress` / `session_version_unavailable`) |
|
|
23
24
|
| `worlds data calls pull` / `worlds data ingest [--transform\|--map]` | — (no MCP twin yet; `run_gateway_cli data ingest` on a sandboxed directory) |
|
|
24
25
|
| `files upload <local>... [--to]` | `request_file_upload` + `confirm_file_upload` (`upload_file` for ≤25 MB inline) |
|
|
25
26
|
| `files list [path]` / `files get <path>` / `files download\|cat <path>` | `list_files` / `get_file` (a presigned URL; the CLI streams it) |
|
|
@@ -35,7 +36,7 @@ Reference for `worlds-getting-started`: every CLI step and its MCP twin, then ho
|
|
|
35
36
|
| `environment link-task-set` / `create-task` | `create_task_set`, `create_task`, `link_task_set` |
|
|
36
37
|
| `bench diff` / `propose` | `env_diff`, `env_propose` (proposals are the legacy PR-style door; edit sessions below are the version-control loop) |
|
|
37
38
|
| `worlds\|bench edit status\|list\|close\|discard\|rollback <slug>` | `list_world_edits({ slug, status?, limit? })`, `close_world_edit({ slug, sessionId?, force?, message? })`, `discard_world_edit`, `rollback_world_edit({ slug, sessionId, force?, message? })` (`GET /api/public/worlds/{slug}/edits`, `POST …/edits/close\|discard\|rollback`). After a world's first version every push, sandbox commit, data import, agent `env_commit` and UI save lands on the credential's open edit session — a private `edit/<id>` branch only that credential reads as `main` (`describe`, `pull`, `log`, `session open`, `sandbox open`); the write's JSON carries `editSessionId` + a hint. `close`, or 60 minutes without an edit, seals the session: the shared `main` moves to its tip (every version stays in `log`; the session is the rollback unit); a `main` that moved meanwhile is rebased when the paths differ, else the session parks as `conflict` (`close --force` takes its content). `rollback` restores source + data snapshot from before a sealed session as a new sealed session (`--force` when later sessions would be undone too). UI: world › History › Edit sessions |
|
|
38
|
-
| `worlds\|bench sandbox open\|status\|read\|write\|exec\|check\|commit\|close` | `open_world_sandbox`, `get_world_sandbox`, `read_world_sandbox_file`, `write_world_sandbox_file` (base64), `exec_in_world_sandbox`, `check_world_sandbox`, `commit_world_sandbox`, `close_world_sandbox` (`/api/public/benchmark-containers/sandboxes[/{id}[/file\|exec\|check\|commit]]`; the source tree only — no data snapshot, nothing on the caller's disk; `commit` lands on the recorded base). `open` reports `cli: {version, digest}` — the platform's own `gateway` CLI and a `sqlite3` are on PATH inside `exec`, so `gateway worlds schema entity add\|verifier add\|task add\|compile\|check .`, `gateway worlds data import\|show\|query .`, `gateway worlds test .`, `gateway worlds serve . --port 8080 & sleep 2; gateway worlds call http://localhost:8080 <tool> …` (one `exec`; a served world lives only as long as that command) and `sqlite3 db/state.sqlite "…"` run on the working copy; remote verbs (push, run, session open) stop in the sandbox by design — `check`/`commit` from your machine. `cli: null` + `warnings[]` means the image cannot host the runtime (python3 < 3.
|
|
39
|
+
| `worlds\|bench sandbox open\|status\|read\|write\|exec\|check\|commit\|close` | `open_world_sandbox`, `get_world_sandbox`, `read_world_sandbox_file`, `write_world_sandbox_file` (base64), `exec_in_world_sandbox`, `check_world_sandbox`, `commit_world_sandbox`, `close_world_sandbox({ sandboxId, force? })` (`/api/public/benchmark-containers/sandboxes[/{id}[/file\|exec\|check\|commit]]`; `close` with uncommitted work is a 409 `sandbox_uncommitted` naming the paths, nothing closed, unless `force: true` / `--force`; the source tree only — no data snapshot, nothing on the caller's disk; `commit` lands on the recorded base; `commit --rebase` sends `rebase: true` and replays onto a branch head that moved, a 409 naming each conflicting path). `open` reports `cli: {version, digest}` — the platform's own `gateway` CLI and a `sqlite3` are on PATH inside `exec`, so `gateway worlds schema entity add\|verifier add\|task add\|compile\|check .`, `gateway worlds data import\|show\|query .`, `gateway worlds test .`, `gateway worlds serve . --port 8080 & sleep 2; gateway worlds call http://localhost:8080 <tool> …` (one `exec`; a served world lives only as long as that command) and `sqlite3 db/state.sqlite "…"` run on the working copy; remote verbs (push, run, session open) stop in the sandbox by design — `check`/`commit` from your machine. `cli: null` + `warnings[]` means the image cannot host the runtime (python3 < 3.12 or node < 18); plain shell still runs |
|
|
39
40
|
| `worlds\|bench sandbox open --new <slug> --from custom\|<template>` | `open_world_sandbox({ new, from })` (same route, body `{new, from}`; a world that does not exist yet — `baseVersionId`/`containerId`/`baseContentHash` null, `branch: main`, `pendingSlug`; `custom` = the `schema init` scaffold, else a shipped template (`GET /api/public/worlds/templates`; unknown → 400 naming the list); taken slug → 409 `world_exists`, never renamed; `check_world_sandbox` runs the first commit's gate; the first `commit_world_sandbox` creates the world on `main` through the `worlds create --from <dir>` door, later commits land on the new base; the same staged CLI runs on the scaffold) |
|
|
40
41
|
| `worlds skill <name>` / `worlds connector skill` | `get_connector_authoring_skill`, `guide` |
|
|
41
42
|
| `worlds connector capture --remote` / poll + download | `start_connector_capture`, `get_connector_capture` (platform agent only) |
|
package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md
CHANGED
|
@@ -6,7 +6,7 @@ The things that bite once and never again, moved out of `SKILL.md` to keep it un
|
|
|
6
6
|
bundled runtime: no host, no keys, no config file read. Only `--connector workspace:<slug>`
|
|
7
7
|
needs the platform — without `gateway auth login` or the `GATEWAY_*` keys (the agent's
|
|
8
8
|
local-only `run_gateway_cli` included) `schema init` refuses it and names `--host`,
|
|
9
|
-
`GATEWAY_HOST` and the login command. No `python3 >= 3.
|
|
9
|
+
`GATEWAY_HOST` and the login command. No `python3 >= 3.12`? A shipped template scaffolds
|
|
10
10
|
on the platform instead, so there it does need a host.
|
|
11
11
|
- `bench push` (the TS CLI) on a world with `connector.toml` still packages an api-kind bundle
|
|
12
12
|
on the way up; `worlds create --from ./x` stores the tree as it is, and `worlds migrate`
|
|
@@ -18,6 +18,10 @@ The things that bite once and never again, moved out of `SKILL.md` to keep it un
|
|
|
18
18
|
- Never commit `captures/`; never merge a customer's world as an SDK template.
|
|
19
19
|
- A seed (scenario overlay or runner admin endpoint) is the whole state, not an increment.
|
|
20
20
|
- Never set `max_tokens` on any model call used to run or grade.
|
|
21
|
+
- A platform request that never gets an answer fails in one line: the request, the host, the cause
|
|
22
|
+
(`connection refused`, `DNS lookup failed`, `timed out after 120s`) and the next step, exit 1. Each
|
|
23
|
+
request waits `GATEWAY_TIMEOUT_MS` (default 120000); polls (session ready, grades) are many short
|
|
24
|
+
requests, so a long wait is never cut by it, and sandbox requests always allow 660 s.
|
|
21
25
|
|
|
22
26
|
- A world that declares an environment secret (`environment_secret_name` in `release/manifest.json`, or `${NAME:?}` in a task's `docker-compose.yaml`) is refused at `session open`
|
|
23
27
|
with 400 `missing_env_secrets` naming `gateway bench secrets set --env <slug> --key <NAME>` before
|
|
@@ -6,7 +6,7 @@ does not exist yet in the key's project. Nothing is needed on the caller's disk
|
|
|
6
6
|
checkout, not `schema init`.
|
|
7
7
|
|
|
8
8
|
```bash
|
|
9
|
-
gateway worlds sandbox open --new acme-crm --from custom
|
|
9
|
+
gateway worlds sandbox open --new acme-crm --from custom # or --from slack|github|…
|
|
10
10
|
gateway worlds sandbox exec <id> "gateway worlds schema entity add . crm_accounts --fields id:string,name:string --key id"
|
|
11
11
|
gateway worlds sandbox exec <id> "gateway worlds schema compile . && gateway worlds schema check ."
|
|
12
12
|
gateway worlds sandbox check <id> # the push gate the first commit will run
|
|
@@ -37,5 +37,7 @@ The first `commit`:
|
|
|
37
37
|
no-change).
|
|
38
38
|
|
|
39
39
|
Two new-world sandboxes racing for one slug: exactly one first commit wins; the other gets a
|
|
40
|
-
409 `world_exists` and keeps its tree intact
|
|
41
|
-
the files across with `read`/`write
|
|
40
|
+
409 `world_exists` and keeps its tree intact. To keep that work, open a new sandbox with another
|
|
41
|
+
slug (`sandbox open --new <other> --from custom`), copy the files across with `read`/`write`,
|
|
42
|
+
then `sandbox close <id> --force` the loser. A never-committed `--new` sandbox counts as
|
|
43
|
+
uncommitted (its base is empty), so a plain `close` exits 1; a closed sandbox cannot be reopened.
|
|
@@ -4,6 +4,7 @@ from __future__ import annotations
|
|
|
4
4
|
|
|
5
5
|
import json
|
|
6
6
|
import sqlite3
|
|
7
|
+
import sys
|
|
7
8
|
import threading
|
|
8
9
|
import uuid
|
|
9
10
|
from contextlib import contextmanager
|
|
@@ -234,12 +235,7 @@ class SQLiteStore:
|
|
|
234
235
|
)
|
|
235
236
|
self._conn.row_factory = sqlite3.Row
|
|
236
237
|
try:
|
|
237
|
-
|
|
238
|
-
# a string literal, so `WHERE "status" = 'ACTIVE'` against a table
|
|
239
|
-
# with no status column compares two literals and scores 0 without
|
|
240
|
-
# a word (Brex retrospective). Refuse the fallback: name a column
|
|
241
|
-
# that does not exist and the statement fails, saying which.
|
|
242
|
-
self._conn.setconfig(sqlite3.SQLITE_DBCONFIG_DQS_DML, False)
|
|
238
|
+
self.forbid_double_quoted_literals(self._conn)
|
|
243
239
|
self._conn.execute("PRAGMA foreign_keys = ON")
|
|
244
240
|
if self._conn.execute("PRAGMA foreign_keys").fetchone()[0] != 1:
|
|
245
241
|
fail("sqlite", "Foreign-key enforcement is required")
|
|
@@ -260,6 +256,19 @@ class SQLiteStore:
|
|
|
260
256
|
self.path.unlink(missing_ok=True)
|
|
261
257
|
raise
|
|
262
258
|
|
|
259
|
+
@staticmethod
|
|
260
|
+
def forbid_double_quoted_literals(conn: Any) -> None:
|
|
261
|
+
"""SQLite reads a double-quoted name that is not a column as a string literal, so a
|
|
262
|
+
verifier naming a missing column compares two literals and scores 0 without a word.
|
|
263
|
+
Switch the fallback off, or refuse to open where Python cannot (``setconfig`` is 3.12+)."""
|
|
264
|
+
if not hasattr(conn, "setconfig"):
|
|
265
|
+
fail(
|
|
266
|
+
"python_version",
|
|
267
|
+
f"Python {sys.version_info.major}.{sys.version_info.minor} cannot turn off SQLite's "
|
|
268
|
+
"double-quoted string literals; the world store needs Python 3.12 or newer.",
|
|
269
|
+
)
|
|
270
|
+
conn.setconfig(sqlite3.SQLITE_DBCONFIG_DQS_DML, False)
|
|
271
|
+
|
|
263
272
|
@classmethod
|
|
264
273
|
def create(cls, path: str | Path, contract: Contract) -> "SQLiteStore":
|
|
265
274
|
return cls(Path(path), contract, create=True)
|
|
@@ -48,7 +48,7 @@ Segmentation, so one substrate never crashes into the other's infrastructure:
|
|
|
48
48
|
## 0. Authenticate
|
|
49
49
|
|
|
50
50
|
```bash
|
|
51
|
-
npm install -g @withgateway/sdk # the gateway CLI (TypeScript; python3 >= 3.
|
|
51
|
+
npm install -g @withgateway/sdk # the gateway CLI (TypeScript; python3 >= 3.12 runs the local runtime)
|
|
52
52
|
gateway auth login --host https://<your-gateway> --public-key pk-lf-... --api-key sk-lf-...
|
|
53
53
|
```
|
|
54
54
|
|
|
@@ -57,7 +57,7 @@ gateway auth login --host https://<your-gateway> --public-key pk-lf-... --api-ke
|
|
|
57
57
|
is reachable and prints the exact plan when it is not; `dry-run --hosted` runs the same one task on
|
|
58
58
|
the benchmark runner (harbor's oracle, no model), so a machine with nothing but the npm CLI and project
|
|
59
59
|
keys can author, dry-run, push and run a container benchmark; on a world it opens the task's session
|
|
60
|
-
in the bundled Python runtime (python3 >= 3.
|
|
60
|
+
in the bundled Python runtime (python3 >= 3.12) and prints the plan when there is none.
|
|
61
61
|
|
|
62
62
|
## A. A harbor (container) benchmark: init → validate → dry-run → push → run → results
|
|
63
63
|
|
|
@@ -409,7 +409,7 @@ reward is for the untouched world; an agent's rollout is what `benchmarks run` g
|
|
|
409
409
|
|
|
410
410
|
A verifier that cannot run — bad SQL, a missing entity — prints `FAIL verifier 'x': …` with SQLite's
|
|
411
411
|
words and exits 1; that is what the dry run is for. A reward of 1.0 here means the verifier passes
|
|
412
|
-
before any agent acts: rewrite it. Without the bundled runtime (no python3 >= 3.
|
|
412
|
+
before any agent acts: rewrite it. Without the bundled runtime (no python3 >= 3.12) the four steps
|
|
413
413
|
print and the run is marked not executed, exit 0.
|
|
414
414
|
|
|
415
415
|
A hand-driven rollout, the way an agent's session goes:
|
|
@@ -193,7 +193,7 @@ When adding a bridge command to `schema/platform.py`, mirror it as a typed wrapp
|
|
|
193
193
|
`worldSchemaRuntime.ts` (`compileWorldFiles` / `applyWorldBatch` are the pattern: file map
|
|
194
194
|
in, `{entries, report, ...}` out, errors as `SchemaBridgeError`), cover it in
|
|
195
195
|
`tests/environment/test_schema_platform.py`, and let the agent tool call the wrapper, never
|
|
196
|
-
the subprocess. The bridge needs Python ≥ 3.
|
|
196
|
+
the subprocess. The bridge needs Python ≥ 3.12 (`tomllib`, and the store's sqlite `setconfig`); set `GATEWAY_SCHEMA_PYTHON`
|
|
197
197
|
when the default interpreter is older.
|
|
198
198
|
|
|
199
199
|
Use `worldSchemaRuntime.ts` for platform validation and `schema.platform` for
|
|
@@ -540,7 +540,7 @@ the version commit transaction. Capture is bounded and read-only; world tools
|
|
|
540
540
|
mutate only the copied world. See [Environment Files](./environment-files.md#populated-slack-world-jobs)
|
|
541
541
|
and [Slack capture permissions](../integrations/slack.md#structured-world-capture).
|
|
542
542
|
|
|
543
|
-
The server needs Python 3.
|
|
543
|
+
The server needs Python 3.12+ and the trusted SDK schema runtime.
|
|
544
544
|
`GATEWAY_SCHEMA_PYTHON` defaults to `python3`; `GATEWAY_SCHEMA_RUNTIME_PATH`
|
|
545
545
|
overrides runtime discovery. Production images install it at `/opt/gateway-schema`;
|
|
546
546
|
local development can discover the checkout. Compiler children receive no
|
|
@@ -29,22 +29,22 @@ gateway auth login --host https://<your-gateway> --public-key pk-lf-... --api-ke
|
|
|
29
29
|
gateway auth status # or export GATEWAY_HOST / GATEWAY_PUBLIC_KEY / GATEWAY_SECRET_KEY
|
|
30
30
|
```
|
|
31
31
|
|
|
32
|
-
The npm package bundles the schema runtime (stdlib-only Python). With a `python3 >= 3.
|
|
32
|
+
The npm package bundles the schema runtime (stdlib-only Python). With a `python3 >= 3.12` on the
|
|
33
33
|
machine every runtime command runs locally, including `worlds serve` and a local `connector
|
|
34
34
|
capture`, with no pip and no login; without one, the CLI sends the world's files to the platform
|
|
35
35
|
(`POST /api/public/worlds/runtime`) and the same code runs there (`worlds serve` then opens a hosted
|
|
36
36
|
api session, `connector capture` needs `--remote`). `GATEWAY_RUNTIME=local|platform` forces a side.
|
|
37
37
|
|
|
38
|
-
The interpreter: `GATEWAY_PYTHON` when set, else the first of `python3.13`, `python3.12`, `python3
|
|
39
|
-
`python`, then `uv python find` that is 3.
|
|
38
|
+
The interpreter: `GATEWAY_PYTHON` when set, else the first of `python3.13`, `python3.12`, `python3`,
|
|
39
|
+
`python`, then `uv python find` that is 3.12 or newer. A Mac whose `python3` is the system 3.9 is not a dead end: the
|
|
40
40
|
CLI prints one line naming what it found and what to set — `GATEWAY_PYTHON="$(brew --prefix python@3.12)/bin/python3.12"`
|
|
41
41
|
or `GATEWAY_PYTHON="$(uv python find 3.12)"` (Brex retrospective: this used to be discovered by hand).
|
|
42
42
|
|
|
43
43
|
Or export `GATEWAY_HOST`, `GATEWAY_PUBLIC_KEY`, `GATEWAY_SECRET_KEY` (env wins over the config file). A file of them
|
|
44
44
|
works as written by a person, not only as the shell sources it: `GATEWAY_ENV_FILE=.env gateway …` accepts `KEY = value`
|
|
45
45
|
(spaces around `=`), quoted values, `export KEY=value` and `#` comments; a variable already in the shell's environment
|
|
46
|
-
wins, and vendor keys named by `connector.toml` ride along for a local capture. Every command below accepts `--host
|
|
47
|
-
Keys are project keys: the world lands in that project.
|
|
46
|
+
wins, and vendor keys named by `connector.toml` ride along for a local capture. Every command below accepts `--host`; `GATEWAY_TIMEOUT_MS` (default 120000) bounds one request, and a host that never answers is one line: cause + next step.
|
|
47
|
+
Keys are project keys: the world lands in that project. Every verb whose output is JSON takes `--json` as a no-op.
|
|
48
48
|
|
|
49
49
|
MCP: the server is authenticated by the same project API key (or a PAT). Call `describe_project({})`
|
|
50
50
|
first, then `guide({ topic: "connectors" })` for the connector loop and `guide({ topic: "world-data" })` for data.
|
|
@@ -323,7 +323,7 @@ gateway worlds session reset <SESSION_ID> # back to the snapsh
|
|
|
323
323
|
gateway worlds session grade <SESSION_ID> [--timeout S] # {reward, rewards, raw}; exploratory → {reward: null, reason: "no grader"}
|
|
324
324
|
gateway worlds session export <SESSION_ID> --out calls.jsonl
|
|
325
325
|
gateway worlds data ingest x calls.jsonl --transform shape.py # the calls back in as rows, shaped by your code or --map ingest.toml (world-data-ingestion §2c)
|
|
326
|
-
gateway worlds session close <SESSION_ID>
|
|
326
|
+
gateway worlds session close <SESSION_ID> # a closed session reopens by id, same URLs + token, from its last checkpoint: gateway worlds session reopen <SESSION_ID>
|
|
327
327
|
```
|
|
328
328
|
|
|
329
329
|
**A task outside the bundle.** `-t <name>` picks a scenario the version ships. On a World Host
|
|
@@ -391,15 +391,15 @@ gateway bench dispatch <RUN_CONFIG_ID> # each stored task
|
|
|
391
391
|
The first session on a freshly pushed version takes about fifteen minutes: the pod is
|
|
392
392
|
scheduled and the runner sidecar pulled; the session reads `PROVISIONING` and the api URL
|
|
393
393
|
answers 503. That is a cold start, not a fault, until about twenty minutes have passed.
|
|
394
|
-
`session open` waits ten minutes
|
|
394
|
+
`session open` prints `session <id> opening — gateway worlds session status <id>` on stderr at once, then waits ten minutes; on a cold version use `--no-wait` and poll. `open` and
|
|
395
395
|
`status` print `idleExpiresAt` (null once pinned) + `pinned`; `status` warns under 5 minutes. A call
|
|
396
396
|
body over 4mb is refused client-side: `{status: "error", code: "payload_too_large"}`, exit 2.
|
|
397
397
|
|
|
398
398
|
The world's API honours the vendor's auth scheme; `WORLD_API_KEY` on the host pins the
|
|
399
399
|
credential, otherwise any non-empty one is accepted.
|
|
400
400
|
|
|
401
|
-
MCP: `
|
|
402
|
-
|
|
401
|
+
MCP: `seed_world_session`, `export_world_session`, `save_world_session_task`; open/call/close are CLI or REST only.
|
|
402
|
+
Find what you opened: `gateway worlds session list` / `sandbox list`; `session pin <id>` stops the reaper.
|
|
403
403
|
|
|
404
404
|
## Test the world (not the agent)
|
|
405
405
|
|
|
@@ -479,8 +479,8 @@ schema|data|test|serve|call …` on the working copy with nothing on your machin
|
|
|
479
479
|
`session open`) stop inside the sandbox by design: it holds no platform credential, and never write one
|
|
480
480
|
into its tree — `check`/`commit` hold back scratch, credential-shaped files (`.env`, `.gateway-env`, `*.env`,
|
|
481
481
|
`*.pem`…) and symlinks (`ignored` + `warnings`, paths only); over 2000 files or 128 MB is refused before
|
|
482
|
-
any read. `worlds run --path` on a clean `bench pull` checkout files runs pinned to the base version.
|
|
483
|
-
Sandbox twins and every limit: `references/cli-mcp-map.md`.
|
|
482
|
+
any read. `sandbox commit <id> -m why --rebase` replays your edits onto a branch that moved since `open`; a path changed on both sides is a 409, one `conflict: <path> (<reason>)` line each on stderr, exit 1. `worlds run --path` on a clean `bench pull` checkout files runs pinned to the base version.
|
|
483
|
+
Work is saved while a sandbox sits idle and resumes by id, but after 7 idle days (`status` shows `idleExpiresAt`) the platform closes it even with uncommitted files, and a closed sandbox cannot be reopened: commit before you walk away. `sandbox close <id>` refuses uncommitted files (exit 1, their paths on stderr) unless `--force`. Sandbox twins and every limit: `references/cli-mcp-map.md`.
|
|
484
484
|
|
|
485
485
|
MCP: `list_world_edits({ slug })`, `close_world_edit`, `discard_world_edit`, `rollback_world_edit({ slug, sessionId })`; `env_diff({ containerId })`, `env_run_tests`, `env_get_run`; proposals (`env_propose`, `env_list_proposals`, `env_apply_proposal`, `env_dismiss_proposal`) are the legacy PR-style door.
|
|
486
486
|
|
|
@@ -17,9 +17,10 @@ Reference for `worlds-getting-started`: every CLI step and its MCP twin, then ho
|
|
|
17
17
|
| `worlds migrate <slug> [--apply] [--force]` / `--all` | `migrate_world` |
|
|
18
18
|
| `bench push` | `env_write_file` + `env_commit`, or `create_environment_version` (one file) |
|
|
19
19
|
| `worlds data import` | `import_world_data` |
|
|
20
|
-
| `worlds session open [-t\|--task-id\|--task-file]` (none: exploratory) / `status` / `call` / `close`
|
|
20
|
+
| `worlds session open [-t\|--task-id\|--task-file]` (none: exploratory) / `status` / `call` / `close` / `list` / `pin` | none on the public MCP server — CLI or REST only (`/api/public/world-sessions[/{id}[/calls]]`; the open answers `idleExpiresAt` + `pinned`) |
|
|
21
21
|
| `worlds session seed` | `seed_world_session` |
|
|
22
22
|
| `worlds session export` | `export_world_session` |
|
|
23
|
+
| `worlds session reopen <id>` | — (no MCP twin; `POST /api/public/world-sessions/{id}/reopen`: a closed session back under the same id, URLs and token from its last checkpoint, answering what `status` answers; 409 `session_not_closed` / `session_no_checkpoint` / `session_reopen_in_progress` / `session_version_unavailable`) |
|
|
23
24
|
| `worlds data calls pull` / `worlds data ingest [--transform\|--map]` | — (no MCP twin yet; `run_gateway_cli data ingest` on a sandboxed directory) |
|
|
24
25
|
| `files upload <local>... [--to]` | `request_file_upload` + `confirm_file_upload` (`upload_file` for ≤25 MB inline) |
|
|
25
26
|
| `files list [path]` / `files get <path>` / `files download\|cat <path>` | `list_files` / `get_file` (a presigned URL; the CLI streams it) |
|
|
@@ -35,7 +36,7 @@ Reference for `worlds-getting-started`: every CLI step and its MCP twin, then ho
|
|
|
35
36
|
| `environment link-task-set` / `create-task` | `create_task_set`, `create_task`, `link_task_set` |
|
|
36
37
|
| `bench diff` / `propose` | `env_diff`, `env_propose` (proposals are the legacy PR-style door; edit sessions below are the version-control loop) |
|
|
37
38
|
| `worlds\|bench edit status\|list\|close\|discard\|rollback <slug>` | `list_world_edits({ slug, status?, limit? })`, `close_world_edit({ slug, sessionId?, force?, message? })`, `discard_world_edit`, `rollback_world_edit({ slug, sessionId, force?, message? })` (`GET /api/public/worlds/{slug}/edits`, `POST …/edits/close\|discard\|rollback`). After a world's first version every push, sandbox commit, data import, agent `env_commit` and UI save lands on the credential's open edit session — a private `edit/<id>` branch only that credential reads as `main` (`describe`, `pull`, `log`, `session open`, `sandbox open`); the write's JSON carries `editSessionId` + a hint. `close`, or 60 minutes without an edit, seals the session: the shared `main` moves to its tip (every version stays in `log`; the session is the rollback unit); a `main` that moved meanwhile is rebased when the paths differ, else the session parks as `conflict` (`close --force` takes its content). `rollback` restores source + data snapshot from before a sealed session as a new sealed session (`--force` when later sessions would be undone too). UI: world › History › Edit sessions |
|
|
38
|
-
| `worlds\|bench sandbox open\|status\|read\|write\|exec\|check\|commit\|close` | `open_world_sandbox`, `get_world_sandbox`, `read_world_sandbox_file`, `write_world_sandbox_file` (base64), `exec_in_world_sandbox`, `check_world_sandbox`, `commit_world_sandbox`, `close_world_sandbox` (`/api/public/benchmark-containers/sandboxes[/{id}[/file\|exec\|check\|commit]]`; the source tree only — no data snapshot, nothing on the caller's disk; `commit` lands on the recorded base). `open` reports `cli: {version, digest}` — the platform's own `gateway` CLI and a `sqlite3` are on PATH inside `exec`, so `gateway worlds schema entity add\|verifier add\|task add\|compile\|check .`, `gateway worlds data import\|show\|query .`, `gateway worlds test .`, `gateway worlds serve . --port 8080 & sleep 2; gateway worlds call http://localhost:8080 <tool> …` (one `exec`; a served world lives only as long as that command) and `sqlite3 db/state.sqlite "…"` run on the working copy; remote verbs (push, run, session open) stop in the sandbox by design — `check`/`commit` from your machine. `cli: null` + `warnings[]` means the image cannot host the runtime (python3 < 3.
|
|
39
|
+
| `worlds\|bench sandbox open\|status\|read\|write\|exec\|check\|commit\|close` | `open_world_sandbox`, `get_world_sandbox`, `read_world_sandbox_file`, `write_world_sandbox_file` (base64), `exec_in_world_sandbox`, `check_world_sandbox`, `commit_world_sandbox`, `close_world_sandbox({ sandboxId, force? })` (`/api/public/benchmark-containers/sandboxes[/{id}[/file\|exec\|check\|commit]]`; `close` with uncommitted work is a 409 `sandbox_uncommitted` naming the paths, nothing closed, unless `force: true` / `--force`; the source tree only — no data snapshot, nothing on the caller's disk; `commit` lands on the recorded base; `commit --rebase` sends `rebase: true` and replays onto a branch head that moved, a 409 naming each conflicting path). `open` reports `cli: {version, digest}` — the platform's own `gateway` CLI and a `sqlite3` are on PATH inside `exec`, so `gateway worlds schema entity add\|verifier add\|task add\|compile\|check .`, `gateway worlds data import\|show\|query .`, `gateway worlds test .`, `gateway worlds serve . --port 8080 & sleep 2; gateway worlds call http://localhost:8080 <tool> …` (one `exec`; a served world lives only as long as that command) and `sqlite3 db/state.sqlite "…"` run on the working copy; remote verbs (push, run, session open) stop in the sandbox by design — `check`/`commit` from your machine. `cli: null` + `warnings[]` means the image cannot host the runtime (python3 < 3.12 or node < 18); plain shell still runs |
|
|
39
40
|
| `worlds\|bench sandbox open --new <slug> --from custom\|<template>` | `open_world_sandbox({ new, from })` (same route, body `{new, from}`; a world that does not exist yet — `baseVersionId`/`containerId`/`baseContentHash` null, `branch: main`, `pendingSlug`; `custom` = the `schema init` scaffold, else a shipped template (`GET /api/public/worlds/templates`; unknown → 400 naming the list); taken slug → 409 `world_exists`, never renamed; `check_world_sandbox` runs the first commit's gate; the first `commit_world_sandbox` creates the world on `main` through the `worlds create --from <dir>` door, later commits land on the new base; the same staged CLI runs on the scaffold) |
|
|
40
41
|
| `worlds skill <name>` / `worlds connector skill` | `get_connector_authoring_skill`, `guide` |
|
|
41
42
|
| `worlds connector capture --remote` / poll + download | `start_connector_capture`, `get_connector_capture` (platform agent only) |
|
|
@@ -6,7 +6,7 @@ The things that bite once and never again, moved out of `SKILL.md` to keep it un
|
|
|
6
6
|
bundled runtime: no host, no keys, no config file read. Only `--connector workspace:<slug>`
|
|
7
7
|
needs the platform — without `gateway auth login` or the `GATEWAY_*` keys (the agent's
|
|
8
8
|
local-only `run_gateway_cli` included) `schema init` refuses it and names `--host`,
|
|
9
|
-
`GATEWAY_HOST` and the login command. No `python3 >= 3.
|
|
9
|
+
`GATEWAY_HOST` and the login command. No `python3 >= 3.12`? A shipped template scaffolds
|
|
10
10
|
on the platform instead, so there it does need a host.
|
|
11
11
|
- `bench push` (the TS CLI) on a world with `connector.toml` still packages an api-kind bundle
|
|
12
12
|
on the way up; `worlds create --from ./x` stores the tree as it is, and `worlds migrate`
|
|
@@ -18,6 +18,10 @@ The things that bite once and never again, moved out of `SKILL.md` to keep it un
|
|
|
18
18
|
- Never commit `captures/`; never merge a customer's world as an SDK template.
|
|
19
19
|
- A seed (scenario overlay or runner admin endpoint) is the whole state, not an increment.
|
|
20
20
|
- Never set `max_tokens` on any model call used to run or grade.
|
|
21
|
+
- A platform request that never gets an answer fails in one line: the request, the host, the cause
|
|
22
|
+
(`connection refused`, `DNS lookup failed`, `timed out after 120s`) and the next step, exit 1. Each
|
|
23
|
+
request waits `GATEWAY_TIMEOUT_MS` (default 120000); polls (session ready, grades) are many short
|
|
24
|
+
requests, so a long wait is never cut by it, and sandbox requests always allow 660 s.
|
|
21
25
|
|
|
22
26
|
- A world that declares an environment secret (`environment_secret_name` in `release/manifest.json`, or `${NAME:?}` in a task's `docker-compose.yaml`) is refused at `session open`
|
|
23
27
|
with 400 `missing_env_secrets` naming `gateway bench secrets set --env <slug> --key <NAME>` before
|
|
@@ -6,7 +6,7 @@ does not exist yet in the key's project. Nothing is needed on the caller's disk
|
|
|
6
6
|
checkout, not `schema init`.
|
|
7
7
|
|
|
8
8
|
```bash
|
|
9
|
-
gateway worlds sandbox open --new acme-crm --from custom
|
|
9
|
+
gateway worlds sandbox open --new acme-crm --from custom # or --from slack|github|…
|
|
10
10
|
gateway worlds sandbox exec <id> "gateway worlds schema entity add . crm_accounts --fields id:string,name:string --key id"
|
|
11
11
|
gateway worlds sandbox exec <id> "gateway worlds schema compile . && gateway worlds schema check ."
|
|
12
12
|
gateway worlds sandbox check <id> # the push gate the first commit will run
|
|
@@ -37,5 +37,7 @@ The first `commit`:
|
|
|
37
37
|
no-change).
|
|
38
38
|
|
|
39
39
|
Two new-world sandboxes racing for one slug: exactly one first commit wins; the other gets a
|
|
40
|
-
409 `world_exists` and keeps its tree intact
|
|
41
|
-
the files across with `read`/`write
|
|
40
|
+
409 `world_exists` and keeps its tree intact. To keep that work, open a new sandbox with another
|
|
41
|
+
slug (`sandbox open --new <other> --from custom`), copy the files across with `read`/`write`,
|
|
42
|
+
then `sandbox close <id> --force` the loser. A never-committed `--new` sandbox counts as
|
|
43
|
+
uncommitted (its base is empty), so a plain `close` exits 1; a closed sandbox cannot be reopened.
|