@withgateway/sdk 0.2.9 → 0.3.1

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 (58) hide show
  1. package/README.md +5 -1
  2. package/dist/cli.js +3812 -1158
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +3796 -1142
  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 +1358 -21
  9. package/dist/files/index.js.map +1 -1
  10. package/dist/files/index.mjs +1356 -13
  11. package/dist/files/index.mjs.map +1 -1
  12. package/dist/{index-BO2SNSgy.d.ts → index-CBqbB_0J.d.ts} +95 -46
  13. package/dist/{index-Cz8Q6Keo.d.mts → index-D-AMnAMa.d.mts} +95 -46
  14. package/dist/index.d.mts +4 -3
  15. package/dist/index.d.ts +4 -3
  16. package/dist/index.js +1942 -177
  17. package/dist/index.js.map +1 -1
  18. package/dist/index.mjs +1890 -146
  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 +1355 -18
  25. package/dist/traces/index.js.map +1 -1
  26. package/dist/traces/index.mjs +1353 -10
  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 +550 -30
  31. package/dist/tracing/index.js.map +1 -1
  32. package/dist/tracing/index.mjs +539 -29
  33. package/dist/tracing/index.mjs.map +1 -1
  34. package/dist/worlds/index.d.mts +648 -80
  35. package/dist/worlds/index.d.ts +648 -80
  36. package/dist/worlds/index.js +1875 -145
  37. package/dist/worlds/index.js.map +1 -1
  38. package/dist/worlds/index.mjs +1861 -131
  39. package/dist/worlds/index.mjs.map +1 -1
  40. package/package.json +1 -1
  41. package/runtime/gatewaysdk/environment/schema/api.py +43 -62
  42. package/runtime/gatewaysdk/environment/schema/cast.py +31 -4
  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/platform.py +1 -7
  47. package/runtime/gatewaysdk/environment/schema/runtime.py +9 -9
  48. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +3 -3
  49. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +2 -2
  50. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +13 -13
  51. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +2 -1
  52. package/runtime/gatewaysdk/environment/schema/tasks.py +25 -1
  53. package/skills/connector-schema-authoring/SKILL.md +3 -3
  54. package/skills/connector-schema-authoring/connector-worlds.md +12 -5
  55. package/skills/connector-schema-authoring/world-schema.md +8 -0
  56. package/skills/world-data-ingestion/SKILL.md +2 -2
  57. package/skills/worlds-getting-started/SKILL.md +13 -13
  58. package/skills/worlds-getting-started/references/cli-mcp-map.md +2 -1
@@ -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)
@@ -64,7 +64,8 @@ registration, a platform builder, live ingestion, tools, or a registry framework
64
64
  | `gateway worlds schema compile \| check \| describe PATH` | exists (#216); `compile` also writes `ui/static` (index.html, app.js, contract.json) when connector.toml declares `[ui]` (every shipped template does): the page over the routes an agent drives with `--surface ui,browser`; `[ui] generated = false` keeps a hand-written page |
65
65
  | `gateway worlds schema ui init PATH` | exists (TS CLI + `python -m … ui-init`); declares `[ui]` in connector.toml when missing (before the first `[[operations]]`) and compiles, which generates the page; refuses a world with no connector.toml (a page shows routes). `worlds serve` serves it on its own port at `/` (and at `/__ui/`) and answers its `api_path` for the pin; `generated = false` + any frontend built to static files into `ui/static` is served the same way |
66
66
  | `gateway worlds schema entity add PATH NAME --ref D \| --fields "a:string,b:integer?" \| --schema JSON --key F [--unique F,F] [--relationship F->entity]` | exists (TS CLI, local); declares one entity in `schema/world.json` without hand-editing the document: keeps `$defs`, package metadata and other entities byte-for-byte in meaning, refuses duplicate names, non-required or non-string/integer keys, unknown `$defs` and undeclared relationship targets, and writes nothing on refusal |
67
- | `gateway worlds connector route add PATH NAME --path /v1/x/{id} [-X POST] [--param q] [--entity E] [--results r] [--action create] [--filter id=id] [--body f=p] [--handler fn]` | exists (TS CLI, local); appends one `[[operations]]` (+ `[operations.api]`) to `connector.toml` leaving existing bytes untouched; validates name, method, path, entity against `schema/world.json`, filter keys against `{args}`/params, and the handler/action pairing |
67
+ | `gateway worlds schema entity remove PATH NAME` | exists (TS CLI, local); takes one entity out of `schema/world.json` with the `$defs` only it used; refused (exit 2, nothing written) while a `connector.toml` operation, a `verifiers/*.sql`, rows in `data/initial.json`, a `[dependencies.<alias>.entities]` map or another entity's relationship uses it, each named; keeps at least one entity and re-points the untouched `state_present.sql` placeholder |
68
+ | `gateway worlds connector route add PATH NAME --path /v1/x/{id} [-X POST] [--param q] [--entity E] [--results r] [--action create] [--filter id=id] [--body f=p] [--handler fn]` | exists (TS CLI, local); appends one `[[operations]]` (+ `[operations.api]`) to `connector.toml` leaving existing bytes untouched; validates name, method, path, entity against `schema/world.json`, filter keys against `{args}`/params, and the handler/action pairing; a new `connector.toml` starts with `[auth] scheme = "bearer"` (the hosted session token) and `--action handler --handler fn` writes a 501 stub into `api/handlers.py` unless `fn` is defined |
68
69
  | `gateway worlds connector publish DIR [--slug S] [-m MSG] [--tag T] [--workspace-visible] [--project-scope]` | exists; saves a template directory, or the world it was authored in, as a workspace connector (Context Hub `connector` repo, org-owned, versioned); the platform compiles the template before accepting it and answers 400 with the reason; a re-publish is a new commit and paths no longer present are removed; `data/`, `captures/`, `db/` and generated files stay behind |
69
70
  | `gateway worlds connector list [--hub] [--query Q]` / `pull SLUG [--out DIR] [--version V]` / `clone SLUG-OR-ID [--name N] [--slug S]` | exists; `list` shows this org's connectors (vendor, auth, entities, operations), `--hub` adds every connector another org published; `pull` writes the template files; `clone` copies a published connector into this org with provenance — a live reference is never made, so the publisher's later edits need a re-clone |
70
71
  | `gateway worlds schema init PATH --connector workspace:<slug>` | exists; initializes from the platform's copy through `init_bundle_from_files` (needs `GATEWAY_*` keys); the offline `python -m gatewaysdk.environment.schema init` refuses `workspace:` and names this command |
@@ -409,5 +410,4 @@ vendor routes. `gateway bench push PATH` publishes the world: for a world carryi
409
410
  `connector.toml` it packages the api-kind bundle the platform hosts on the way (root
410
411
  legacy-shaped on purpose, since the api runner refuses a schema bundle there; `server/`
411
412
  needs nothing installed). Open a session with `--surface api` and hand the client that
412
- URL; the vendor's auth scheme applies (`WORLD_API_KEY` on the host pins the credential,
413
- otherwise any non-empty one).
413
+ URL; the vendor's auth scheme applies, with the session's own api token as the credential.
@@ -84,8 +84,9 @@ reads `PROVISIONING` and the URL answers 503; that is a cold start, not a fault,
84
84
  about twenty minutes have passed. `session open` waits ten minutes by default, so on a cold
85
85
  version pass `--no-wait` and poll `gateway worlds session status <sessionId>` until `ready`.
86
86
 
87
- The world's API honours the vendor's auth scheme: with `WORLD_API_KEY` set it accepts exactly that
88
- credential, otherwise any non-empty one, and answers 401 with the body configured under
87
+ The world's API honours the vendor's auth scheme: a hosted session accepts its own api token (as a
88
+ bearer or in the vendor's header), `worlds serve` the credential `--api-key` pins (default `conform`),
89
+ and `WORLD_API_KEY` applies only to a legacy api bundle. Anything else answers 401 with the body configured under
89
90
  `[api].unauthorized` (`""` or `'null'` for a bare status with no body, the way some vendors answer).
90
91
 
91
92
  **Data.** Captures are one way in. Any agent can put rows into the world without knowing its
@@ -128,7 +129,13 @@ least one `[[operations]]` entry.
128
129
 
129
130
  `gateway worlds connector route add <world> <name>` appends one `[[operations]]` block to
130
131
  `connector.toml` without touching the bytes already there (comments and formatting survive;
131
- the TOML is parsed only to validate). Flags map onto the spec's keys:
132
+ the TOML is parsed only to validate). A world's first route creates `connector.toml` with
133
+ `[auth] scheme = "bearer"` and `secret_env = "<SLUG>_API_KEY"`: the api token a hosted session
134
+ hands the agent is a bearer, and `worlds serve` answers 401 without one and accepts the bearer
135
+ `--api-key` pins (default `conform`). `--action handler --handler fn` writes a stub
136
+ `def fn(ctx, args, query, body)` answering 501 into `api/handlers.py` unless `fn` is already
137
+ defined there; the output's `handler: {file, function, written}` says which. Flags map onto
138
+ the spec's keys:
132
139
 
133
140
  | Flag | Key |
134
141
  | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------- |
@@ -175,8 +182,8 @@ does all of that from the same `connector.toml`:
175
182
  (function allow-list, quota, blocked IP) hold on plain reads and writes as much as on handlers;
176
183
  handlers and the gate may answer with headers too (`SpyCloud-Error`, `Retry-After`).
177
184
  - An oauth2 world answers the vendor's token route before any authorization, so a client that
178
- performs the grant first works unchanged; with `WORLD_API_KEY` pinned, the client secret must
179
- be that key.
185
+ performs the grant first works unchanged; a hosted session checks the client secret against its
186
+ own api token, `worlds serve` against the `--api-key` pin.
180
187
 
181
188
  The handlers ship inside the api bundle beside the world, so the hosted container runs them
182
189
  with nothing installed. The abstraction is the platform's; the handlers are the customer's.
@@ -140,6 +140,14 @@ string/integer fields, unknown `$defs`, and any file that is not a `gateway-worl
140
140
  document; a refusal leaves the file untouched. Source:
141
141
  `gatewaysdk/sdk-ts/src/cli/runtime/scaffold.ts`.
142
142
 
143
+ `gateway worlds schema entity remove ./x records` takes one entity out again, with the `$defs`
144
+ only it used (the custom scaffold's example `records` entity once yours are declared). It is
145
+ refused, naming each reference and writing nothing, while a `connector.toml` operation answers
146
+ from it, a `verifiers/*.sql` reads it, `data/initial.json` holds rows of it, a
147
+ `[dependencies.<alias>.entities]` map names it or another entity relates to it; the world keeps
148
+ at least one entity, and the untouched `state_present.sql` placeholder is re-pointed at one that
149
+ stays. Source: `gatewaysdk/sdk-ts/src/cli/runtime/scaffoldEntityRemove.ts`.
150
+
143
151
  ## Supported payload language
144
152
 
145
153
  | Construct | `gateway-world/1` semantics |
@@ -269,7 +269,7 @@ level}]}`; text before the JSON is skipped; `input`/`output` decoded as JSON or
269
269
  ```
270
270
 
271
271
  A `gateway worlds session export` line (`{seq, kind, tool, args, result, error, completedAt}`)
272
- is accepted as it is: `kind != "call"` and a failed call are skipped and counted, never
272
+ is accepted as it is: `kind != "call"` (a grade, or a `--requests` line of kind `request`) and a failed call are skipped and counted, never
273
273
  silently dropped. `captureToolCalls` (TS) / `capture_tool_calls` (Python) write the same
274
274
  record at the source.
275
275
 
@@ -388,7 +388,7 @@ gateway worlds session open <slug> -t <scenario> --surface api # prints s
388
388
  gateway worlds session seed <SESSION_ID> rows.json # kind:"seed" call, waits for the result
389
389
  gateway worlds session seed <SESSION_ID> rows.json --redact refuse # same, refusing plaintext in a redacted field (apply hashes it first)
390
390
  gateway worlds session seed <SESSION_ID> rows.json --mode replace # swap the named entities
391
- curl -H 'x-api-key: any' "$API_URL/<route>" # read it back through the vendor's route
391
+ curl -H "Authorization: Bearer $API_TOKEN" "$API_URL/<route>" # read it back (api.token from session open)
392
392
  ```
393
393
 
394
394
  Prints `{sessionId, mode, result}`. MCP: `seed_world_session({ sessionId, rows, mode? })` waits
@@ -134,7 +134,7 @@ gateway worlds connector route add ./x create_account -X POST --path /v1/account
134
134
 
135
135
  Each refuses (and writes nothing) on a duplicate name, an undeclared entity or `$defs` reference, a key that is not a
136
136
  required string/integer field, or a filter on an unknown argument. A create route mints its single-field primary key (`uuid` for strings, `int` for integers) unless `--body` maps it;
137
- `--generate field=uuid|int|now` and `--default field=value` fill the rest. A custom world's first `route add` creates `connector.toml`; `schema init` prints `kind: "schema"`, `api` and the `next` commands in order (custom: entity add → route add → task add → compile → check → import → serve → `worlds create`).
137
+ `--generate field=uuid|int|now` and `--default field=value` fill the rest. A custom world's first `route add` creates `connector.toml` with `[auth] scheme = "bearer"` (a hosted session's api token; `worlds serve` answers 401 without one); `--action handler --handler fn` writes a 501 stub `fn(ctx, args, query, body)` into `api/handlers.py` unless it is defined. The custom scaffold's example entity is `records`: `gateway worlds schema entity remove ./x records` once yours are declared (refused, naming each reference, while a route, verifier, row, dependency map or relationship uses it). `schema init` prints `kind: "schema"`, `api` and the `next` commands in order (custom: entity add → entity remove records → route add → task add → compile → check → import → serve → `worlds create`).
138
138
  Manifest `kind` is `schema` (older trees: `mock-tools`). Handlers: `def name(ctx, args, query, body)`; `ctx` reads and writes the store and keeps the clock.
139
139
 
140
140
  ### From an OpenAPI spec (Swagger 2.0, OpenAPI 3.x)
@@ -188,7 +188,7 @@ MCP: `validate_connector_template({ files, slug? })` compiles without writing; a
188
188
  ## 4. Data
189
189
 
190
190
  ```bash
191
- gateway worlds describe ./x # entities, keys, relationships, row counts, [redact] per field
191
+ gateway worlds describe ./x # entities, keys, relationships, row counts, enum values, [redact] per field
192
192
  gateway worlds data show ./x # kind + entity counts
193
193
  gateway worlds data query ./x users --where email=jo@acme.test --resolve # the rows you mean; plaintext into a hashed field
194
194
  gateway worlds data import ./x rows.json # rows file: {entity: [rows]} | JSONL | .csv/.tsv --entity (cells cast by the schema; --delimiter)
@@ -321,7 +321,7 @@ gateway worlds session seed <SESSION_ID> rows.json # rows into this ses
321
321
  gateway worlds session state <SESSION_ID> # every entity's rows, the dump a grader reads
322
322
  gateway worlds session reset <SESSION_ID> # back to the snapshot (+ the task's seed)
323
323
  gateway worlds session grade <SESSION_ID> [--timeout S] # {reward, rewards, raw}; exploratory → {reward: null, reason: "no grader"}
324
- gateway worlds session export <SESSION_ID> --out calls.jsonl
324
+ gateway worlds session export <SESSION_ID> --out calls.jsonl [--requests] # the platform's ledger; --requests (live session, one state call) adds the world's own request log, kind "request" with via
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
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
  ```
@@ -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
@@ -395,11 +395,11 @@ answers 503. That is a cold start, not a fault, until about twenty minutes have
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
- The world's API honours the vendor's auth scheme; `WORLD_API_KEY` on the host pins the
399
- credential, otherwise any non-empty one is accepted.
398
+ The world's API honours the vendor's auth scheme and accepts the session's own api token (bearer or
399
+ the vendor's header); `worlds serve` accepts the `--api-key` pin (default `conform`).
400
400
 
401
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.
402
+ Find what you opened: `gateway worlds session list` (every state; the live ones are `--state RUNNING` and `--state IDLE`) / `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
@@ -482,7 +482,7 @@ into its tree — `check`/`commit` hold back scratch, credential-shaped files (`
482
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
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
 
@@ -36,7 +36,8 @@ Reference for `worlds-getting-started`: every CLI step and its MCP twin, then ho
36
36
  | `environment link-task-set` / `create-task` | `create_task_set`, `create_task`, `link_task_set` |
37
37
  | `bench diff` / `propose` | `env_diff`, `env_propose` (proposals are the legacy PR-style door; edit sessions below are the version-control loop) |
38
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 |
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
+ | `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`; a sandbox whose machine was replaced gets its tree back (latest snapshot, or the base) and the next verb answers 409 `sandbox_recreated` once — look at the tree, redo lost edits, retry; 503 `sandbox_restore_failed` means retry; 409 `sandbox_tree_missing` means the world root was deleted, so close and reopen; 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 |
40
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) |
41
42
  | `worlds skill <name>` / `worlds connector skill` | `get_connector_authoring_skill`, `guide` |
42
43
  | `worlds connector capture --remote` / poll + download | `start_connector_capture`, `get_connector_capture` (platform agent only) |