@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.
Files changed (45) hide show
  1. package/README.md +24 -8
  2. package/dist/cli.js +332 -163
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +332 -163
  5. package/dist/cli.mjs.map +1 -1
  6. package/dist/files/index.js +119 -15
  7. package/dist/files/index.js.map +1 -1
  8. package/dist/files/index.mjs +119 -15
  9. package/dist/files/index.mjs.map +1 -1
  10. package/dist/index.d.mts +1 -1
  11. package/dist/index.d.ts +1 -1
  12. package/dist/index.js +229 -120
  13. package/dist/index.js.map +1 -1
  14. package/dist/index.mjs +220 -120
  15. package/dist/index.mjs.map +1 -1
  16. package/dist/traces/index.js +119 -15
  17. package/dist/traces/index.js.map +1 -1
  18. package/dist/traces/index.mjs +119 -15
  19. package/dist/traces/index.mjs.map +1 -1
  20. package/dist/tracing/index.js +1 -1
  21. package/dist/tracing/index.js.map +1 -1
  22. package/dist/tracing/index.mjs +1 -1
  23. package/dist/tracing/index.mjs.map +1 -1
  24. package/dist/worlds/index.d.mts +78 -9
  25. package/dist/worlds/index.d.ts +78 -9
  26. package/dist/worlds/index.js +219 -119
  27. package/dist/worlds/index.js.map +1 -1
  28. package/dist/worlds/index.mjs +220 -120
  29. package/dist/worlds/index.mjs.map +1 -1
  30. package/package.json +1 -1
  31. package/runtime/gatewaysdk/environment/_toml.py +3 -10
  32. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +3 -3
  33. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +1 -1
  34. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +11 -11
  35. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +3 -2
  36. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +5 -1
  37. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/new-world-sandbox.md +5 -3
  38. package/runtime/gatewaysdk/environment/schema/store.py +15 -6
  39. package/skills/benchmarks-getting-started/SKILL.md +3 -3
  40. package/skills/connector-schema-authoring/SKILL.md +1 -1
  41. package/skills/connector-schema-authoring/world-schema.md +1 -1
  42. package/skills/worlds-getting-started/SKILL.md +11 -11
  43. package/skills/worlds-getting-started/references/cli-mcp-map.md +3 -2
  44. package/skills/worlds-getting-started/references/gotchas.md +5 -1
  45. package/skills/worlds-getting-started/references/new-world-sandbox.md +5 -3
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@withgateway/sdk",
3
- "version": "0.2.8",
3
+ "version": "0.2.9",
4
4
  "description": "Gateway SDK for TypeScript - A/B experiments, tracing, and observability",
5
5
  "main": "./dist/index.js",
6
6
  "module": "./dist/index.mjs",
@@ -1,13 +1,6 @@
1
- """The one TOML reader for every Python the SDK supports.
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
- 3.11+ ships ``tomllib``; 3.10 gets ``tomli`` (declared in pyproject as
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.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
@@ -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
 
@@ -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` | `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,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.11 or node < 18); plain shell still runs |
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.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)
@@ -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
@@ -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
 
@@ -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` | `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,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.11 or node < 18); plain shell still runs |
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.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.