@withgateway/sdk 0.2.8 → 0.3.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 (61) hide show
  1. package/README.md +24 -8
  2. package/dist/cli.js +2695 -657
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +2675 -637
  5. package/dist/cli.mjs.map +1 -1
  6. package/dist/files/index.d.mts +1 -0
  7. package/dist/files/index.d.ts +1 -0
  8. package/dist/files/index.js +1443 -36
  9. package/dist/files/index.js.map +1 -1
  10. package/dist/files/index.mjs +1441 -28
  11. package/dist/files/index.mjs.map +1 -1
  12. package/dist/{index-Cz8Q6Keo.d.mts → index-D6oi1TWE.d.mts} +93 -34
  13. package/dist/{index-BO2SNSgy.d.ts → index-DAb-FCMg.d.ts} +93 -34
  14. package/dist/index.d.mts +4 -3
  15. package/dist/index.d.ts +4 -3
  16. package/dist/index.js +1986 -235
  17. package/dist/index.js.map +1 -1
  18. package/dist/index.mjs +1941 -218
  19. package/dist/index.mjs.map +1 -1
  20. package/dist/media-CbcAfQvd.d.mts +83 -0
  21. package/dist/media-CbcAfQvd.d.ts +83 -0
  22. package/dist/traces/index.d.mts +1 -0
  23. package/dist/traces/index.d.ts +1 -0
  24. package/dist/traces/index.js +1440 -33
  25. package/dist/traces/index.js.map +1 -1
  26. package/dist/traces/index.mjs +1438 -25
  27. package/dist/traces/index.mjs.map +1 -1
  28. package/dist/tracing/index.d.mts +2 -1
  29. package/dist/tracing/index.d.ts +2 -1
  30. package/dist/tracing/index.js +512 -11
  31. package/dist/tracing/index.js.map +1 -1
  32. package/dist/tracing/index.mjs +501 -10
  33. package/dist/tracing/index.mjs.map +1 -1
  34. package/dist/worlds/index.d.mts +614 -25
  35. package/dist/worlds/index.d.ts +614 -25
  36. package/dist/worlds/index.js +1923 -214
  37. package/dist/worlds/index.js.map +1 -1
  38. package/dist/worlds/index.mjs +1910 -201
  39. package/dist/worlds/index.mjs.map +1 -1
  40. package/package.json +1 -1
  41. package/runtime/gatewaysdk/environment/_toml.py +3 -10
  42. package/runtime/gatewaysdk/environment/schema/api.py +38 -56
  43. package/runtime/gatewaysdk/environment/schema/grading.py +1 -5
  44. package/runtime/gatewaysdk/environment/schema/host.py +53 -90
  45. package/runtime/gatewaysdk/environment/schema/local.py +15 -7
  46. package/runtime/gatewaysdk/environment/schema/runtime.py +9 -9
  47. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +3 -3
  48. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +1 -1
  49. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +18 -18
  50. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +4 -2
  51. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +5 -1
  52. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/new-world-sandbox.md +5 -3
  53. package/runtime/gatewaysdk/environment/schema/store.py +15 -6
  54. package/runtime/gatewaysdk/environment/schema/tasks.py +25 -1
  55. package/skills/benchmarks-getting-started/SKILL.md +3 -3
  56. package/skills/connector-schema-authoring/SKILL.md +1 -1
  57. package/skills/connector-schema-authoring/world-schema.md +1 -1
  58. package/skills/worlds-getting-started/SKILL.md +18 -18
  59. package/skills/worlds-getting-started/references/cli-mcp-map.md +4 -2
  60. package/skills/worlds-getting-started/references/gotchas.md +5 -1
  61. package/skills/worlds-getting-started/references/new-world-sandbox.md +5 -3
@@ -34,7 +34,7 @@ from pathlib import Path
34
34
  from typing import TYPE_CHECKING, Any, Optional
35
35
 
36
36
  from . import snapshot as snapshots
37
- from .api import WorldApp, WorldState, operation_request, vendor_credential, with_query
37
+ from .api import Via, WorldApp, WorldState, operation_request, vendor_credential, with_query
38
38
  from .dependencies import Dependency
39
39
  from .grading import Grade, GraderError, TaskGrader
40
40
  from .snapshot import SCENARIOS
@@ -654,12 +654,6 @@ class SnapshotRuntime(WorldRuntime):
654
654
  }
655
655
 
656
656
 
657
- # --------------------------------------------------------------------------- #
658
- # Shared by the runtimes and the local session: an operation by name, the
659
- # client grant, the task card.
660
- # --------------------------------------------------------------------------- #
661
-
662
-
663
657
  def client_grant(app: WorldApp | None, credential: str | None) -> str | None:
664
658
  """The bearer an ``oauth2`` world's routes take when the session itself
665
659
  calls them (the page's api prefix, an operation by name); None for any
@@ -682,7 +676,8 @@ def call_operation(
682
676
  """An operation of connector.toml called by name (:func:`operation_request`
683
677
  reads the args: ``path``/``query``/``body``, or leftover top-level keys as
684
678
  the body); the world's own credential is presented, as the host presents a
685
- session's. The answer is the route's ``{status, body}``."""
679
+ session's. The call is logged ``via: tool``. The answer is the route's
680
+ ``{status, body}``."""
686
681
  spec = app.router.spec
687
682
  operation = spec.operations.get(name)
688
683
  if operation is None:
@@ -696,7 +691,12 @@ def call_operation(
696
691
  method, target, raw = operation_request(spec, operation, args)
697
692
  headers, credential_query = vendor_credential(spec, credential, grant=grant)
698
693
  status, answer, _ = app.handle(
699
- method, with_query(target, credential_query), {"content-type": "application/json", **headers}, raw, "127.0.0.1"
694
+ method,
695
+ with_query(target, credential_query),
696
+ {"content-type": "application/json", **headers},
697
+ raw,
698
+ "127.0.0.1",
699
+ via=Via.TOOL,
700
700
  )
701
701
  return {"status": status, "body": answer}
702
702
 
@@ -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.11 runs the local runtime)
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.11) and prints the plan when there is none.
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.11) the four steps
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.11 (`tomllib`); set `GATEWAY_SCHEMA_PYTHON`
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.11` on the
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.11`, `python3`,
39
- `python`, then `uv python find` that is 3.11 or newer. A Mac whose `python3` is the system 3.9 is not a dead end: the
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
@@ -341,10 +341,10 @@ verifiers) is refused `world_kind_retired`; one on an api bundle opens and lists
341
341
  "metadata": { "externalUserId": "u_42" } }
342
342
  ```
343
343
 
344
- `instruction` is what the agent is told; `seed` (`{mode?, rows}`, the live-seed contract) is
345
- laid on the clone and re-applied by `reset`; `grader` is `assertions` (`entity`, `where`,
346
- `exists|absent|count|all|any`, `field op value`; each check's `id` becomes a `rewards` key),
347
- `{kind: "python", source}` (a `verify.py` body) or `{kind: "rubric", rubric, criteria?, model?}`
344
+ `instruction` is what the agent is told; `seed` (`{mode?, rows}`, the live-seed contract) is laid on the clone and re-applied by `reset`;
345
+ `grader` is `assertions` (`entity`, `where`, `exists|absent|count|all|any`, `field op value`; each check's `id` becomes a `rewards` key;
346
+ `entity: "calls"` reads the call log — `operation`, `args`, `selectors`, `status`, `rows`, `found`, and `via`: `ui` from the page's `api_path`,
347
+ `api` from the api origin, `tool` by name), `{kind: "python", source}` (a `verify.py` body) or `{kind: "rubric", rubric, criteria?, model?}`
348
348
  (an LLM judge over end state + call log, graded on the platform: `grade` answers pending until
349
349
  the worker finalizes it); `tools: [names]` narrows the operations the session may call to
350
350
  exactly those (a name the world does not serve is a 400); `metadata` rides the session. At most one of
@@ -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 by default; on a cold version use `--no-wait` and poll. `open` and
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: `open_world_session({ slug, task? | taskId? | taskSpec? })` (none: exploratory), `get_world_session`,
402
- `call_world_tool`, `seed_world_session({ sessionId, rows, mode? })`, `export_world_session`, `close_world_session`.
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
 
@@ -456,8 +456,7 @@ gateway environment rollouts <container-id>
456
456
  ```
457
457
 
458
458
  MCP: `run_evaluation({ models | runConfigId, versionId?, numExamples?, rolloutsPerExample? })`,
459
- `create_task_set`, `create_task`, `link_task_set`, `list_rollouts`, `get_rollout_samples`,
460
- `get_task_performance`; `promote_failure_to_scenario({...})` turns a failed rollout into a scenario.
459
+ `create_task_set`, `create_task`, `link_task_set`, `list_rollouts`, `get_rollout_samples`, `get_task_performance`; `promote_failure_to_scenario({...})` turns a failed rollout into a scenario.
461
460
 
462
461
  ## 8. Iterate
463
462
 
@@ -467,6 +466,7 @@ gateway bench fork x --into x-experiment # a new container sh
467
466
  gateway worlds edit status x # your open EDIT SESSION: every push / sandbox commit / data import after the first version lands there; only this credential reads it as main
468
467
  gateway worlds edit close x -m "why" # seal it: main moves to the session's tip for everyone; each version stays in `log`, `edit rollback` undoes the whole session (60 idle minutes seal it too). `edit list x` = history, `edit discard x` drops it unseen
469
468
  gateway worlds edit rollback x <sessionId> # undo a sealed session (source + data together) as a new sealed session; --force when later sessions would go too
469
+ gateway worlds task edit close <task> -m "why" # a change across a TASK's worlds: seal them all in ONE step or none (`task edit status <task>` first: your unsealed worlds, only you see them; `task edit rollback <task> --group <groupId>` undoes the group)
470
470
  gateway worlds sandbox open x@main # no local checkout: write|exec|check|commit|close <id> edit the tree server-side; `bench sandbox` is the same set
471
471
  gateway worlds sandbox exec <id> 'gateway worlds schema entity add . tickets --fields id:string,title:string -k id && gateway worlds schema compile . && gateway worlds data import . rows.json && gateway worlds schema check . && gateway worlds test .'
472
472
  gateway worlds sandbox open --new y --from custom # a world that does not exist yet (no base); its first `commit` creates it — references/new-world-sandbox.md
@@ -479,10 +479,10 @@ 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
- 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.
485
+ MCP: `list_world_edits({ slug })`, `close_world_edit`, `discard_world_edit`, `rollback_world_edit({ slug, sessionId })`; across a task's worlds `get_task_edit({ task })`, `close_task_edit({ task, requireAll?, force? })`, `rollback_task_edit({ task, groupId })`; `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
 
487
487
  ## 9. Where it shows in the UI, the CLI to MCP map, gotchas
488
488
 
@@ -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` | `open_world_session` (`slug` or `versionId`, at most one of `task`/`taskId`/`taskSpec`), `get_world_session`, `call_world_tool`, `close_world_session` (`/api/public/world-sessions[/{id}[/calls]]`; the open answers `idleExpiresAt` + `pinned`) |
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,8 @@ 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.11 or node < 18); plain shell still runs |
39
+ | `worlds task edit status\|close\|rollback <task>` (task id, spec file with `worlds`, or `task up` manifest) | `get_task_edit({ task })`, `close_task_edit({ task, requireAll?, force?, message? })`, `rollback_task_edit({ task, groupId, force?, message? })` (`POST /api/public/world-task-edits/status\|close\|rollback`). The same edit sessions across every world a task names: `status` shows each world's unsealed edits (open and `parked` in conflict) and what closing would do (`fast-forward`, `rebase`, `conflict`) — your own `task up` opens them at your tip (`private: true`), everyone else still gets shared `main`; `close` seals every world in ONE transaction (a conflict, a missing world, a ref other than `main` or a parked session anywhere seals nothing, and the 409 names every world's problem; worlds with no edit are skipped unless `--require-all`), and the sessions share a `groupId`; `rollback --group` restores every world together to the `main` the group replaced, refused when anything reached a world's `main` after the group (a later session or a write outside sessions) unless `--force` |
40
+ | `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
41
  | `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
42
  | `worlds skill <name>` / `worlds connector skill` | `get_connector_authoring_skill`, `guide` |
41
43
  | `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.11`? A shipped template scaffolds
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 --json # or --from slack|github|…
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 — close it, or reopen with another slug and copy
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
- # SQLite quietly reads a double-quoted name that is not a column as
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)
@@ -126,6 +126,12 @@ class TaskSpec:
126
126
  #: declare an entity by either name (the compiler refuses it), so a check on
127
127
  #: one is never a typo for a row entity; a seed may not target them.
128
128
  RESERVED_STATE_KEYS = frozenset({"calls", "snapshot"})
129
+ CALL_LOG = "calls"
130
+ DOOR_FIELD = "via"
131
+
132
+
133
+ class GraderError(Exception):
134
+ """A grader that could not deliver a grade, with the reason a reader acts on."""
129
135
 
130
136
 
131
137
  def unknown_task_entities(spec: TaskSpec, defined: Iterable[str]) -> list[str]:
@@ -594,8 +600,26 @@ def _rows_of(state: dict, entity: str) -> list[dict]:
594
600
  return []
595
601
 
596
602
 
603
+ def _names_the_door(check: dict) -> bool:
604
+ entity = check["entity"]
605
+ on_call_log = entity == CALL_LOG or entity.endswith(f".{CALL_LOG}")
606
+ return on_call_log and (check.get("field") == DOOR_FIELD or DOOR_FIELD in (check.get("where") or {}))
607
+
608
+
609
+ def _require_the_door(check: dict, state: dict, rows: list[dict]) -> None:
610
+ """A door check over no call log, or a log that does not record the door,
611
+ would select nothing (``absent`` passes) or miss the key (``neq`` passes):
612
+ ungraded."""
613
+ if not _names_the_door(check):
614
+ return
615
+ if check["entity"] not in state or any(DOOR_FIELD not in row for row in rows):
616
+ raise GraderError(f"this engine's call log does not record the door ({DOOR_FIELD})")
617
+
618
+
597
619
  def evaluate_check(check: dict, state: dict) -> bool:
598
- selected = [row for row in _rows_of(state, check["entity"]) if _matches_where(row, check.get("where"))]
620
+ rows = _rows_of(state, check["entity"])
621
+ _require_the_door(check, state, rows)
622
+ selected = [row for row in rows if _matches_where(row, check.get("where"))]
599
623
  assertion = check["assert"]
600
624
  if assertion == "exists":
601
625
  return bool(selected)
@@ -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.11 runs the local runtime)
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.11) and prints the plan when there is none.
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.11) the four steps
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.11 (`tomllib`); set `GATEWAY_SCHEMA_PYTHON`
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.11+ and the trusted SDK schema runtime.
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.11` on the
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.11`, `python3`,
39
- `python`, then `uv python find` that is 3.11 or newer. A Mac whose `python3` is the system 3.9 is not a dead end: the
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
@@ -341,10 +341,10 @@ verifiers) is refused `world_kind_retired`; one on an api bundle opens and lists
341
341
  "metadata": { "externalUserId": "u_42" } }
342
342
  ```
343
343
 
344
- `instruction` is what the agent is told; `seed` (`{mode?, rows}`, the live-seed contract) is
345
- laid on the clone and re-applied by `reset`; `grader` is `assertions` (`entity`, `where`,
346
- `exists|absent|count|all|any`, `field op value`; each check's `id` becomes a `rewards` key),
347
- `{kind: "python", source}` (a `verify.py` body) or `{kind: "rubric", rubric, criteria?, model?}`
344
+ `instruction` is what the agent is told; `seed` (`{mode?, rows}`, the live-seed contract) is laid on the clone and re-applied by `reset`;
345
+ `grader` is `assertions` (`entity`, `where`, `exists|absent|count|all|any`, `field op value`; each check's `id` becomes a `rewards` key;
346
+ `entity: "calls"` reads the call log — `operation`, `args`, `selectors`, `status`, `rows`, `found`, and `via`: `ui` from the page's `api_path`,
347
+ `api` from the api origin, `tool` by name), `{kind: "python", source}` (a `verify.py` body) or `{kind: "rubric", rubric, criteria?, model?}`
348
348
  (an LLM judge over end state + call log, graded on the platform: `grade` answers pending until
349
349
  the worker finalizes it); `tools: [names]` narrows the operations the session may call to
350
350
  exactly those (a name the world does not serve is a 400); `metadata` rides the session. At most one of
@@ -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 by default; on a cold version use `--no-wait` and poll. `open` and
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: `open_world_session({ slug, task? | taskId? | taskSpec? })` (none: exploratory), `get_world_session`,
402
- `call_world_tool`, `seed_world_session({ sessionId, rows, mode? })`, `export_world_session`, `close_world_session`.
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
 
@@ -456,8 +456,7 @@ gateway environment rollouts <container-id>
456
456
  ```
457
457
 
458
458
  MCP: `run_evaluation({ models | runConfigId, versionId?, numExamples?, rolloutsPerExample? })`,
459
- `create_task_set`, `create_task`, `link_task_set`, `list_rollouts`, `get_rollout_samples`,
460
- `get_task_performance`; `promote_failure_to_scenario({...})` turns a failed rollout into a scenario.
459
+ `create_task_set`, `create_task`, `link_task_set`, `list_rollouts`, `get_rollout_samples`, `get_task_performance`; `promote_failure_to_scenario({...})` turns a failed rollout into a scenario.
461
460
 
462
461
  ## 8. Iterate
463
462
 
@@ -467,6 +466,7 @@ gateway bench fork x --into x-experiment # a new container sh
467
466
  gateway worlds edit status x # your open EDIT SESSION: every push / sandbox commit / data import after the first version lands there; only this credential reads it as main
468
467
  gateway worlds edit close x -m "why" # seal it: main moves to the session's tip for everyone; each version stays in `log`, `edit rollback` undoes the whole session (60 idle minutes seal it too). `edit list x` = history, `edit discard x` drops it unseen
469
468
  gateway worlds edit rollback x <sessionId> # undo a sealed session (source + data together) as a new sealed session; --force when later sessions would go too
469
+ gateway worlds task edit close <task> -m "why" # a change across a TASK's worlds: seal them all in ONE step or none (`task edit status <task>` first: your unsealed worlds, only you see them; `task edit rollback <task> --group <groupId>` undoes the group)
470
470
  gateway worlds sandbox open x@main # no local checkout: write|exec|check|commit|close <id> edit the tree server-side; `bench sandbox` is the same set
471
471
  gateway worlds sandbox exec <id> 'gateway worlds schema entity add . tickets --fields id:string,title:string -k id && gateway worlds schema compile . && gateway worlds data import . rows.json && gateway worlds schema check . && gateway worlds test .'
472
472
  gateway worlds sandbox open --new y --from custom # a world that does not exist yet (no base); its first `commit` creates it — references/new-world-sandbox.md
@@ -479,10 +479,10 @@ 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
- 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.
485
+ MCP: `list_world_edits({ slug })`, `close_world_edit`, `discard_world_edit`, `rollback_world_edit({ slug, sessionId })`; across a task's worlds `get_task_edit({ task })`, `close_task_edit({ task, requireAll?, force? })`, `rollback_task_edit({ task, groupId })`; `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
 
487
487
  ## 9. Where it shows in the UI, the CLI to MCP map, gotchas
488
488
 
@@ -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` | `open_world_session` (`slug` or `versionId`, at most one of `task`/`taskId`/`taskSpec`), `get_world_session`, `call_world_tool`, `close_world_session` (`/api/public/world-sessions[/{id}[/calls]]`; the open answers `idleExpiresAt` + `pinned`) |
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,8 @@ 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.11 or node < 18); plain shell still runs |
39
+ | `worlds task edit status\|close\|rollback <task>` (task id, spec file with `worlds`, or `task up` manifest) | `get_task_edit({ task })`, `close_task_edit({ task, requireAll?, force?, message? })`, `rollback_task_edit({ task, groupId, force?, message? })` (`POST /api/public/world-task-edits/status\|close\|rollback`). The same edit sessions across every world a task names: `status` shows each world's unsealed edits (open and `parked` in conflict) and what closing would do (`fast-forward`, `rebase`, `conflict`) — your own `task up` opens them at your tip (`private: true`), everyone else still gets shared `main`; `close` seals every world in ONE transaction (a conflict, a missing world, a ref other than `main` or a parked session anywhere seals nothing, and the 409 names every world's problem; worlds with no edit are skipped unless `--require-all`), and the sessions share a `groupId`; `rollback --group` restores every world together to the `main` the group replaced, refused when anything reached a world's `main` after the group (a later session or a write outside sessions) unless `--force` |
40
+ | `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
41
  | `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
42
  | `worlds skill <name>` / `worlds connector skill` | `get_connector_authoring_skill`, `guide` |
41
43
  | `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.11`? A shipped template scaffolds
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 --json # or --from slack|github|…
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 — close it, or reopen with another slug and copy
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.