@withgateway/sdk 0.3.1 → 0.4.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 (176) hide show
  1. package/README.md +8 -6
  2. package/dist/cli.js +4372 -2265
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +4362 -2256
  5. package/dist/cli.mjs.map +1 -1
  6. package/dist/files/index.d.mts +1 -1
  7. package/dist/files/index.d.ts +1 -1
  8. package/dist/files/index.js +259 -58
  9. package/dist/files/index.js.map +1 -1
  10. package/dist/files/index.mjs +249 -50
  11. package/dist/files/index.mjs.map +1 -1
  12. package/dist/hooks/index.d.mts +1 -1
  13. package/dist/hooks/index.d.ts +1 -1
  14. package/dist/hooks/index.js +124 -11
  15. package/dist/hooks/index.js.map +1 -1
  16. package/dist/hooks/index.mjs +124 -11
  17. package/dist/hooks/index.mjs.map +1 -1
  18. package/dist/{index-C3UzD0G3.d.mts → index-CDPQBsU5.d.mts} +19 -3
  19. package/dist/{index-C3UzD0G3.d.ts → index-CDPQBsU5.d.ts} +19 -3
  20. package/dist/{index-CBqbB_0J.d.ts → index-DUHmS74p.d.ts} +1 -1
  21. package/dist/{index-D-AMnAMa.d.mts → index-mJhG3vZU.d.mts} +1 -1
  22. package/dist/index.d.mts +5 -5
  23. package/dist/index.d.ts +5 -5
  24. package/dist/index.js +2240 -789
  25. package/dist/index.js.map +1 -1
  26. package/dist/index.mjs +2150 -739
  27. package/dist/index.mjs.map +1 -1
  28. package/dist/{media-CbcAfQvd.d.mts → media-BIApiPzS.d.mts} +21 -2
  29. package/dist/{media-CbcAfQvd.d.ts → media-BIApiPzS.d.ts} +21 -2
  30. package/dist/traces/index.d.mts +1 -1
  31. package/dist/traces/index.d.ts +1 -1
  32. package/dist/traces/index.js +253 -52
  33. package/dist/traces/index.js.map +1 -1
  34. package/dist/traces/index.mjs +243 -44
  35. package/dist/traces/index.mjs.map +1 -1
  36. package/dist/tracing/index.d.mts +2 -2
  37. package/dist/tracing/index.d.ts +2 -2
  38. package/dist/tracing/index.js +75 -13
  39. package/dist/tracing/index.js.map +1 -1
  40. package/dist/tracing/index.mjs +75 -13
  41. package/dist/tracing/index.mjs.map +1 -1
  42. package/dist/worlds/index.d.mts +893 -482
  43. package/dist/worlds/index.d.ts +893 -482
  44. package/dist/worlds/index.js +1968 -669
  45. package/dist/worlds/index.js.map +1 -1
  46. package/dist/worlds/index.mjs +1960 -662
  47. package/dist/worlds/index.mjs.map +1 -1
  48. package/package.json +1 -1
  49. package/runtime/gatewaysdk/environment/_bundle.py +2 -27
  50. package/runtime/gatewaysdk/environment/_materialize.py +48 -88
  51. package/runtime/gatewaysdk/environment/_world.py +155 -237
  52. package/runtime/gatewaysdk/environment/backing.py +133 -0
  53. package/runtime/gatewaysdk/environment/core.py +2 -17
  54. package/runtime/gatewaysdk/environment/legacy_sqlite.py +288 -0
  55. package/runtime/gatewaysdk/environment/reward_keys.py +25 -0
  56. package/runtime/gatewaysdk/environment/runtime.py +8 -13
  57. package/runtime/gatewaysdk/environment/schema/__init__.py +4 -4
  58. package/runtime/gatewaysdk/environment/schema/admin_routes.py +86 -0
  59. package/runtime/gatewaysdk/environment/schema/admission.py +174 -0
  60. package/runtime/gatewaysdk/environment/schema/api.py +347 -892
  61. package/runtime/gatewaysdk/environment/schema/assertions.py +458 -0
  62. package/runtime/gatewaysdk/environment/schema/batch.py +44 -39
  63. package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +17 -5
  64. package/runtime/gatewaysdk/environment/schema/cache_layout.py +5 -0
  65. package/runtime/gatewaysdk/environment/schema/call_capture.py +309 -0
  66. package/runtime/gatewaysdk/environment/schema/call_log.py +503 -0
  67. package/runtime/gatewaysdk/environment/schema/call_redaction.py +526 -0
  68. package/runtime/gatewaysdk/environment/schema/cast.py +15 -35
  69. package/runtime/gatewaysdk/environment/schema/compiler.py +334 -158
  70. package/runtime/gatewaysdk/environment/schema/conform.py +14 -39
  71. package/runtime/gatewaysdk/environment/schema/connector.py +113 -211
  72. package/runtime/gatewaysdk/environment/schema/connectors/confluence/connector.toml +1 -12
  73. package/runtime/gatewaysdk/environment/schema/connectors/github/connector.toml +1 -0
  74. package/runtime/gatewaysdk/environment/schema/connectors/servicenow/connector.toml +2 -5
  75. package/runtime/gatewaysdk/environment/schema/cors.py +54 -0
  76. package/runtime/gatewaysdk/environment/schema/credentials.py +313 -8
  77. package/runtime/gatewaysdk/environment/schema/data.py +60 -216
  78. package/runtime/gatewaysdk/environment/schema/database/__init__.py +24 -0
  79. package/runtime/gatewaysdk/environment/schema/database/audit.py +121 -0
  80. package/runtime/gatewaysdk/environment/schema/database/base.py +936 -0
  81. package/runtime/gatewaysdk/environment/schema/database/budget.py +33 -0
  82. package/runtime/gatewaysdk/environment/schema/database/connections.py +101 -0
  83. package/runtime/gatewaysdk/environment/schema/database/engines.py +8 -0
  84. package/runtime/gatewaysdk/environment/schema/database/guard.py +215 -0
  85. package/runtime/gatewaysdk/environment/schema/database/ingest.py +154 -0
  86. package/runtime/gatewaysdk/environment/schema/database/matching.py +58 -0
  87. package/runtime/gatewaysdk/environment/schema/database/provenance.py +30 -0
  88. package/runtime/gatewaysdk/environment/schema/database/reads.py +169 -0
  89. package/runtime/gatewaysdk/environment/schema/database/rows.py +53 -0
  90. package/runtime/gatewaysdk/environment/schema/database/runtime_rows.py +39 -0
  91. package/runtime/gatewaysdk/environment/schema/database/sqlite.py +393 -0
  92. package/runtime/gatewaysdk/environment/schema/declared_routes.py +210 -0
  93. package/runtime/gatewaysdk/environment/schema/domain_migration.py +236 -0
  94. package/runtime/gatewaysdk/environment/schema/door.py +899 -0
  95. package/runtime/gatewaysdk/environment/schema/envelope.py +227 -0
  96. package/runtime/gatewaysdk/environment/schema/extract.py +6 -13
  97. package/runtime/gatewaysdk/environment/schema/grading.py +90 -103
  98. package/runtime/gatewaysdk/environment/schema/handler_errors.py +163 -12
  99. package/runtime/gatewaysdk/environment/schema/host.py +237 -1795
  100. package/runtime/gatewaysdk/environment/schema/host_control.py +144 -0
  101. package/runtime/gatewaysdk/environment/schema/host_handoff.py +370 -0
  102. package/runtime/gatewaysdk/environment/schema/host_loops.py +97 -0
  103. package/runtime/gatewaysdk/environment/schema/host_owners.py +121 -0
  104. package/runtime/gatewaysdk/environment/schema/host_proxy.py +111 -0
  105. package/runtime/gatewaysdk/environment/schema/host_requests.py +6 -0
  106. package/runtime/gatewaysdk/environment/schema/host_session.py +126 -0
  107. package/runtime/gatewaysdk/environment/schema/host_surfaces.py +79 -21
  108. package/runtime/gatewaysdk/environment/schema/host_transfers.py +127 -0
  109. package/runtime/gatewaysdk/environment/schema/host_versions.py +242 -0
  110. package/runtime/gatewaysdk/environment/schema/host_workers.py +577 -0
  111. package/runtime/gatewaysdk/environment/schema/journal.py +437 -0
  112. package/runtime/gatewaysdk/environment/schema/lanes.py +53 -0
  113. package/runtime/gatewaysdk/environment/schema/ledger_spill.py +828 -0
  114. package/runtime/gatewaysdk/environment/schema/local.py +58 -170
  115. package/runtime/gatewaysdk/environment/schema/mapping.py +5 -25
  116. package/runtime/gatewaysdk/environment/schema/openapi_import.py +112 -73
  117. package/runtime/gatewaysdk/environment/schema/openapi_paging.py +147 -0
  118. package/runtime/gatewaysdk/environment/schema/openapi_payloads.py +288 -0
  119. package/runtime/gatewaysdk/environment/schema/openapi_routes.py +97 -102
  120. package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +113 -30
  121. package/runtime/gatewaysdk/environment/schema/platform.py +137 -187
  122. package/runtime/gatewaysdk/environment/schema/platform_import.py +2 -3
  123. package/runtime/gatewaysdk/environment/schema/platform_query.py +61 -5
  124. package/runtime/gatewaysdk/environment/schema/primary_key.py +61 -0
  125. package/runtime/gatewaysdk/environment/schema/proof.py +19 -12
  126. package/runtime/gatewaysdk/environment/schema/request_body.py +238 -0
  127. package/runtime/gatewaysdk/environment/schema/request_ledger.py +958 -0
  128. package/runtime/gatewaysdk/environment/schema/route_bindings.py +25 -3
  129. package/runtime/gatewaysdk/environment/schema/route_miss.py +54 -0
  130. package/runtime/gatewaysdk/environment/schema/runtime.py +178 -308
  131. package/runtime/gatewaysdk/environment/schema/served_names.py +58 -0
  132. package/runtime/gatewaysdk/environment/schema/session_files.py +275 -0
  133. package/runtime/gatewaysdk/environment/schema/session_move.py +275 -0
  134. package/runtime/gatewaysdk/environment/schema/skills/agents/connector-template-author.md +5 -1
  135. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +10 -11
  136. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +49 -16
  137. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +39 -9
  138. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +27 -27
  139. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +33 -33
  140. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +13 -7
  141. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +49 -1
  142. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +182 -0
  143. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/openapi-import.md +50 -21
  144. package/runtime/gatewaysdk/environment/schema/slack.py +4 -8
  145. package/runtime/gatewaysdk/environment/schema/snapshot.py +516 -140
  146. package/runtime/gatewaysdk/environment/schema/spill_files.py +228 -0
  147. package/runtime/gatewaysdk/environment/schema/store_contract.py +8 -14
  148. package/runtime/gatewaysdk/environment/schema/tasks.py +267 -276
  149. package/runtime/gatewaysdk/environment/schema/tools_world.py +146 -242
  150. package/runtime/gatewaysdk/environment/schema/ui.py +24 -5
  151. package/runtime/gatewaysdk/environment/schema/ui_static/app.js +100 -130
  152. package/runtime/gatewaysdk/environment/schema/ui_static/index.html +1 -8
  153. package/runtime/gatewaysdk/environment/schema/validation.py +235 -41
  154. package/runtime/gatewaysdk/environment/schema/verbs.py +32 -36
  155. package/runtime/gatewaysdk/environment/schema/worker.py +6 -4
  156. package/runtime/gatewaysdk/environment/schema/workers.py +345 -96
  157. package/runtime/gatewaysdk/environment/schema/world_host.py +953 -0
  158. package/runtime/gatewaysdk/environment/schema/world_sql.py +81 -0
  159. package/runtime/gatewaysdk/environment/schema/world_tests.py +80 -50
  160. package/runtime/gatewaysdk/environment/score.py +57 -0
  161. package/runtime/gatewaysdk/environment/secret_values.py +36 -0
  162. package/runtime/gatewaysdk/environment/world.py +43 -4
  163. package/runtime/gatewaysdk/environment/world_session_contract.py +46 -5
  164. package/skills/agents/connector-template-author.md +5 -1
  165. package/skills/benchmarks-getting-started/SKILL.md +10 -11
  166. package/skills/connector-schema-authoring/SKILL.md +49 -16
  167. package/skills/connector-schema-authoring/connector-worlds.md +142 -11
  168. package/skills/connector-schema-authoring/world-schema.md +103 -51
  169. package/skills/world-data-ingestion/ROWS.md +39 -9
  170. package/skills/world-data-ingestion/SKILL.md +27 -27
  171. package/skills/worlds-getting-started/SKILL.md +33 -33
  172. package/skills/worlds-getting-started/references/cli-mcp-map.md +13 -7
  173. package/skills/worlds-getting-started/references/gotchas.md +49 -1
  174. package/skills/worlds-getting-started/references/journal-checks.md +182 -0
  175. package/skills/worlds-getting-started/references/openapi-import.md +50 -21
  176. package/runtime/gatewaysdk/environment/schema/store.py +0 -1013
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: worlds-getting-started
3
- description: Starter guide for building worlds and environments on the platform, end to end, for an agent (Claude Code, Cursor, Codex). Use when starting a world from scratch, building a world or environment, mocking a vendor, importing a Swagger or OpenAPI spec into a world (schema init --from-openapi), choosing between a shipped template, a workspace connector, an OpenAPI document, a vendor API capture or a custom contract, provisioning worlds for tenants in one call (worlds create), publishing with bench push, opening a session, running and grading, or iterating with pull, fork, diff and edit sessions (worlds edit status/close/rollback: version control without PRs). Every CLI step names its MCP twin (list_connectors, publish_connector, create_world, init_world_from_connector, env_write_file, env_commit, import_world_data, run_evaluation and the rest) and where the result shows in the UI.
3
+ description: Starter guide for building worlds and environments on the platform, end to end, for an agent (Claude Code, Cursor, Codex). Use when starting a world from scratch, building a world or environment, mocking a vendor, importing a Swagger or OpenAPI spec into a world (schema init --from-openapi), choosing between a shipped template, a workspace connector, an OpenAPI document, a vendor API capture or a custom contract, provisioning worlds for tenants in one call (worlds create), publishing with bench push, opening a session, reading every request a world received (worlds requests), checks over those requests (journal checks on gateway_requests, calls, verify.py, SQL verifiers; task try before you save, task regrade of past runs), running and grading, or iterating with pull, fork, diff and edit sessions (worlds edit status/close/rollback: version control without PRs). Every CLI step names its MCP twin (list_connectors, publish_connector, create_world, init_world_from_connector, env_write_file, env_commit, import_world_data, run_evaluation and the rest) and where the result shows in the UI.
4
4
  ---
5
5
 
6
6
  # Worlds: getting started
@@ -17,7 +17,7 @@ The shortest correct path from nothing to a hosted world with data, a session, a
17
17
  CLI first; the MCP twin sits under each step for an agent that talks to the platform over MCP instead of a shell.
18
18
  Deeper references are linked by path, not repeated.
19
19
 
20
- Vocabulary (from `gateway_documentation/pages/glossary.mdx`): **world** (the sealed replica), **scenario** (a task in
20
+ Vocabulary (from https://docs.surfacearea.ai/glossary): **world** (the sealed replica), **scenario** (a task in
21
21
  it), **rollout** (one attempt), **run** (a filed set of rollouts), **eval** (the grade), **gate** (the bar).
22
22
  Identifiers keep the old words: `environment`, `container`, `task set`, `bench`.
23
23
 
@@ -168,7 +168,7 @@ with this list, and a hosted call into such a handler answers 400 `{error: "hand
168
168
  - `lineage(entity: str, key: dict) -> list[dict]` — the batches that wrote the row at `key`, oldest first.
169
169
  - `counts() -> dict[str, int]` — rows per entity, `{entity: count}`.
170
170
 
171
- No `upsert`: `get`, then `insert` or `update`. Read-only SQL: `gateway_env.db.one/all`; raw SQL writes are refused. The scaffolded `tools/handlers.py` docstring carries the same table.
171
+ No `upsert`: `get`, then `insert` or `update`. Read-only SQL: `gateway_env.db.one/all`; raw SQL writes are refused. The scaffolded `tools/handlers.py` docstring carries the same table. Every tool call and every route call (handler routes too) is one transaction: one that raises, breaks the contract or answers 4xx/5xx keeps no writes or `ctx.emit` events and is still logged with its status. A route's handler answers like a tool's on every door, an answer JSON cannot carry (a `datetime`, a set, NaN) is its 400, and a route answering bytes (a `404 text/plain`) comes back through `call` as `{status, body}` with the body as text.
172
172
 
173
173
  ## 3. Check
174
174
 
@@ -181,7 +181,7 @@ gateway worlds serve ./x --port 8080 # answers the vendor
181
181
  ```
182
182
 
183
183
  `check` validates the compiled bundle; `conform` drives every declared route against the
184
- vendor's document and exits non-zero on a mismatch. Its FAIL list is the work list.
184
+ vendor's document and exits non-zero on a mismatch. Its FAIL list is the work list. Routes are never tools: an agent reaches a world's routes over HTTP (the api url and token `session open --surface api` prints, or `worlds serve` and a request to `http://127.0.0.1:<port>/<path>`), and gets a tool only where `x-gateway.tools` declares one with a handler. A call by a route's name is refused (`not_a_tool`, naming the api URL). A task's `tools` lists declared tools only, and a task that lists any closes the session's routes (403 `route_not_allowed`). An api bundle serves no tools, so the benchmark runner refuses to run one: `gateway worlds migrate <slug> --apply` turns it into a schema world.
185
185
 
186
186
  MCP: `validate_connector_template({ files, slug? })` compiles without writing; answers `{ valid, reason? }`.
187
187
 
@@ -220,8 +220,7 @@ gateway worlds connector publish ./x --slug x -m "first cut" # the template as
220
220
 
221
221
  `bench push` makes the version sessions and runs address (`slug@version`). `connector publish` saves the contract
222
222
  (never `data/`, `captures/`, `db/`) so anyone in the org can `schema init --connector workspace:x`. The world's
223
- `tests/`, `tasks.json`, `verifiers/` and `openapi/` travel with the connector into every world initialized from it
224
- (they used to be left behind, so the new world had no suite to run). Both, for a world you expect to rebuild.
223
+ `tests/`, `tasks.json`, `verifiers/` and `openapi/` travel with the connector into every world initialized from it. Both, for a world you expect to rebuild.
225
224
 
226
225
  MCP: `publish_connector({ slug, files, message? })` is the template write path. `init_world_from_connector({ slug, name })`
227
226
  makes the world under a PAT session; under an API key it returns the initialized files plus the publish steps
@@ -314,14 +313,15 @@ gateway worlds session open x -t default # prints {sessionId,
314
313
  gateway worlds session open x -t default --surface api # asks for api.url explicitly: the vendor's routes, hosted (400 on a tree with no connector.toml)
315
314
  gateway worlds session open x -t default --surface ui,browser # + ui.entry (the page, token once then cookie) and browser.wsUrl (a pool Chromium); 400 without [ui] or without a pool; --browser-tier standard (spot, may be reclaimed; the SDK repairs + reconnects, raises BrowserReconnected on a lost click/type) | premium (on-demand), default: the org's setting
316
315
  gateway worlds session browse <SESSION_ID> [--path /#/accounts] [--screenshot p.png] # open the page in the browser surface; prints url, title, text
317
- gateway worlds session open x [--no-wait] # EXPLORATORY: no task, no grader (task.source "none"); --no-wait returns at once on a cold version
316
+ gateway worlds session open x [--no-wait|--timeout S] # EXPLORATORY: no task, no grader (task.source "none"); waits up to S seconds (600) for ready, --no-wait not at all
318
317
  gateway worlds session open x --task-file task.json --surface api # the session's own task (below)
319
318
  gateway worlds session status <SESSION_ID> # poll until ready
320
319
  gateway worlds session seed <SESSION_ID> rows.json # rows into this session only
321
320
  gateway worlds session state <SESSION_ID> # every entity's rows, the dump a grader reads
322
- gateway worlds session reset <SESSION_ID> # back to the snapshot (+ the task's seed)
321
+ gateway worlds session reset <SESSION_ID> # back to the snapshot (+ the task's seed); `session restart <SESSION_ID> [--version <pin>]` does it on what its pin (x@ref; unpinned = newest you may read) points to NOW, same id, URLs + token, running or closed; a grade then reads only the requests after its session.restart ledger entry
323
322
  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 [--requests] # the platform's ledger; --requests (live session, one state call) adds the world's own request log, kind "request" with via
323
+ gateway worlds session export <SESSION_ID> --out calls.jsonl [--requests] # the platform's ledger; --requests adds the session's entries from the world's request ledger (kind "request": via, status, sizes; bodies by result.requestId), live or closed
324
+ gateway worlds requests x [--session <SESSION_ID>] [--via api|ui|tool] [--status 4xx] [--since 2026-10-05] [--json] # every request the world received (every session, version and door), newest first, kept for its life; reading records nothing; `requests show x <REQUEST_ID> [--out f]` adds headers + bodies, `session requests <SESSION_ID>` lists one session's (exit 3: its engine records no requests, only World Host sessions do)
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
  ```
@@ -344,7 +344,7 @@ verifiers) is refused `world_kind_retired`; one on an api bundle opens and lists
344
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
345
  `grader` is `assertions` (`entity`, `where`, `exists|absent|count|all|any`, `field op value`; each check's `id` becomes a `rewards` key;
346
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?}`
347
+ `api` from the api origin, `tool` for a declared tool's call; a credential-named or secret-shaped field reads `[redacted]`; `rows`/`found` are null where the answer declares no rows, a request too large to keep names what it lacks in `withheld`, and a check grades whenever the calls it can read decide it, ungraded only where those could change the result; on a World Host session `calls` is read from the session's journal, every door and no bound, and `entity: "gateway_requests"` matches every request its world received — `operation`, `method`, `path`, `query.<k>`, `response.status`, `request.body.<path>`, `response.body.<path>`, with `before`/`after` to order them — failing closed, with the reason, where a journal missing requests cannot decide a check: `references/journal-checks.md`), `{kind: "python", source, timeoutSeconds?, readsJournal?, acceptsIncompleteJournal?}` (a `verify.py` body; it reads the state as JSON on stdin — `{"<entity>": {"<primary key>": row}, "calls": [...], "report": "<the agent's report>"}`, a verifier's entities as `<alias>.<entity>` — and prints ONE flat JSON object as the last line of stdout, `reward` plus a number from 0 to 1 per check — `true`/`false` read as 1/0, `null` or a string as ungraded, no `reward` leaves the task ungraded, and a nested object or array (a `rewards` map included), a number outside 0..1 or NaN/Infinity fails the grade by key and value; it must exit 0 within `timeoutSeconds`, default and most 30, or the grade fails with the reason) 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
@@ -352,7 +352,7 @@ exactly those (a name the world does not serve is a 400); `metadata` rides the s
352
352
  `task` block is `{source: "inline", name, hash, metadata}`. SDK: `openSession(slug, { task: spec })` / `openSession(slug)` (TS), `open_session(slug, spec)` / `open_session(slug)` (Python);
353
353
  `runSessions` / `run_sessions` take a mixed list of names and specs. Over several worlds, `worlds: {alias: {slug, …}}` opens one session per alias
354
354
  (`task up|grade|export|down`, `open_task`/`openTask`); a question spanning them is a `verifiers[]` entry (`name`, `scope`, assertions|python over
355
- `<alias>.<entity>` / `<alias>.calls`), graded on the platform only, rewards `x.<name>` (worlds/sessions.mdx).
355
+ `<alias>.<entity>` / `<alias>.calls`), graded on the platform only, rewards `x.<name>`, so no world is aliased `x` (worlds/sessions.mdx).
356
356
 
357
357
  **A stored task.** The same spec kept as a project resource, versioned by content, so many
358
358
  sessions open it by id and grades attribute to the task and its version:
@@ -366,21 +366,20 @@ gateway worlds task update <TASK_ID> --spec task2.json # a changed spec is
366
366
  gateway worlds session open x --task-id <TASK_ID> [--task-version 1] --surface api
367
367
  gateway worlds session task save <SESSION_ID> --name acme-q3 # promote a session's inline task into a stored one
368
368
  gateway worlds task delete <TASK_ID>
369
+ gateway worlds task try task.json --session <SESSION_ID> # a spec (or <TASK_ID>) graded on a stored World Host session, each check with the requests it matched; saves nothing
370
+ gateway worlds task regrade <TASK_ID> [--run <EVAL_ID>|--all-runs|--session <ID>] [--version N] # past runs graded again in place, no agent; default the latest run
369
371
  ```
370
372
 
371
- SDK: `createTask / listTasks / getTask / updateTask / validateTask / deleteTask`,
372
- `openSession(slug, { task: { id, version? } })`, `session.saveTask(name)` (TS);
373
- `create_task` … `delete_task`, `open_session(slug, {"id": …})`, `session.save_task(name)`
374
- (Python). MCP: `create_world_task`, `update_world_task`, `list_world_tasks`, `get_world_task`,
375
- `validate_world_task`, `delete_world_task`, `save_world_session_task`. The world's Scenarios
376
- tab lists the tasks pinned to it under a `world` kind chip.
373
+ SDK: `createTask / listTasks / getTask / updateTask / validateTask / deleteTask`, `openSession(slug, { task: { id, version? } })`, `session.saveTask(name)`, `new TaskGrades().try / regrade` (TS);
374
+ `create_task` … `delete_task`, `open_session(slug, {"id": …})`, `session.save_task(name)`, `TaskGrades().try_task / regrade` (Python). MCP: `create_world_task`, `update_world_task`, `list_world_tasks`, `get_world_task`,
375
+ `validate_world_task`, `delete_world_task`, `save_world_session_task`, `try_world_task`, `regrade_world_task`. The world's Scenarios tab lists the tasks pinned to it under a `world` kind chip.
377
376
 
378
377
  **Stored tasks as a hosted eval.** A run config dispatches EITHER the bundle's scenarios
379
378
  (`--tasks`) OR stored tasks (`--world-tasks`), never both:
380
379
 
381
380
  ```bash
382
381
  gateway bench run-configs create --name nightly --models openai/gpt-5-mini --world-tasks <TASK_ID>,<OTHER_ID>@2
383
- gateway bench dispatch <RUN_CONFIG_ID> # each stored task is a sample; rubric tasks are refused at dispatch
382
+ gateway bench dispatch <RUN_CONFIG_ID> # each stored task is a sample; rubric tasks and tasks whose checks read calls or requests are refused at dispatch
384
383
  ```
385
384
 
386
385
  `<id>` runs the task's current version at dispatch time, `<id>@N` that version forever. SDK:
@@ -391,14 +390,14 @@ gateway bench dispatch <RUN_CONFIG_ID> # each stored task
391
390
  The first session on a freshly pushed version takes about fifteen minutes: the pod is
392
391
  scheduled and the runner sidecar pulled; the session reads `PROVISIONING` and the api URL
393
392
  answers 503. That is a cold start, not a fault, until about twenty minutes have passed.
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
393
+ `session open` prints `session <id> opening — gateway worlds session status <id>` on stderr at once while the World Host opens the session, then waits for ready up to `--timeout` seconds (600): a failed open exits 1 naming the reason and code (`browser_capacity` and `host_unavailable` are worth retrying), and a wait that runs out prints `ready: false`, exits 1 and leaves it opening; on a cold version use `--no-wait` and poll. A call on a session still opening waits up to 30 s, then 409 `session_starting`. `open` and
395
394
  `status` print `idleExpiresAt` (null once pinned) + `pinned`; `status` warns under 5 minutes. A call
396
395
  body over 4mb is refused client-side: `{status: "error", code: "payload_too_large"}`, exit 2.
397
396
 
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`).
397
+ The world's API mirrors the vendor's auth as `[auth]` declares it: the session's api token after an `Authorization` word the vendor takes, in its header, as its Basic user or password, its query key, a token the world's `[auth.login]` minted, or an
398
+ `[auth.downloads]` link; your own tooling sends it in `X-World-Session` (the SDKs' `apiHeaders`) or as a bearer, on every world. No auth for an eval: `session open --auth open` (or `mode = "open"` under `[auth]`) prints `api.auth: open` and a capability URL that needs no credential. `worlds serve` takes the `--api-key` pin (default `conform`) the vendor's ways alone (connector-worlds.md, "The door").
400
399
 
401
- MCP: `seed_world_session`, `export_world_session`, `save_world_session_task`; open/call/close are CLI or REST only.
400
+ MCP: `seed_world_session`, `export_world_session`, `save_world_session_task`, `list_world_requests`, `get_world_request`; open/call/close are CLI or REST only.
402
401
  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
402
 
404
403
  ## Test the world (not the agent)
@@ -412,10 +411,10 @@ gateway worlds test my-world # the same suite on the platform,
412
411
  gateway bench tests my-world # every run the platform kept (push, CLI, API)
413
412
  ```
414
413
 
415
- A case: `{"name": "...", "request": {"method": "GET", "path": "/v1/accounts", "auth": true},
416
- "expect": {"status": 200, "length": {"path": "$", "min": 1}}}`. Put `[actions]` `on_push = ["tests"]`
417
- in `gateway-env.toml` and the platform runs the suite on each push (world page → Tests tab). Public
418
- API: `POST/GET /api/public/worlds/{slug}/tests`. Details: `documentation/features/world-tests.md`.
414
+ A case: `{"name": "...", "request": {"method": "GET", "path": "/v1/accounts"}, "expect": {"status": 200}}`.
415
+ A `test_*.py` gets `WORLD_URL`, `WORLD_API_KEY` and, with `[ui]`, `WORLD_UI_URL` (the page on its own origin; the
416
+ platform's runner has no browser, so check the page over HTTP there). `[actions]` `on_push = ["tests"]` in
417
+ `gateway-env.toml` runs the suite on each push (Tests tab); `POST/GET /api/public/worlds/{slug}/tests`; `documentation/features/world-tests.md`.
419
418
 
420
419
  ## Act on a world as an outside agent (local)
421
420
 
@@ -433,12 +432,12 @@ gateway worlds call http://localhost:8080 slack.list_channels --args '{...}' --c
433
432
  `GET /__session/{task,tools,state}`, `POST /__session/{call,grade,reset,seed,close}`; `--task` and
434
433
  `--scenario` belong to `serve`. A directory target (`worlds call ./x <tool>`) opens and closes its
435
434
  own session per call. A HOSTED session is not a served url (the World Host serves no `/__session/*`;
436
- its `api.url` takes the session's bearer): act on it by id, `gateway worlds call <sessionId> <tool> --state --grade --close`.
435
+ its `api.url` takes the session's token): act on it by id, `gateway worlds call <sessionId> <tool> --state --grade --close`.
437
436
 
438
437
  ## 7. Run and grade
439
438
 
440
439
  ```bash
441
- gateway worlds run x -a agent.mjs --all # TS CLI: agent module (default export async (session, task) => void), every task; -t <task> for one; x is a slug[@ref] or a pushed dir
440
+ gateway worlds run x -a agent.mjs --all # TS CLI: agent.mjs[#export] (the default export unless #name) async (session, task) => void, every task; -t <task> for one; x is a slug[@ref] or a pushed dir
442
441
  gateway worlds run x -a agent.py:agent # Python CLI: agent callable module:function; --path ./x runs a local dir, --no-file grades without filing
443
442
  gateway worlds ci ./x -a agent.mjs --min-score 0.8 # push the working tree, run, gate (CI); --run-config <file> instead of -a; Python: --path ./x -a agent.py:agent
444
443
  gateway environment run x -m <provider/model> -k 3 # hosted runner, one job per model; -k is 1–64
@@ -463,18 +462,18 @@ MCP: `run_evaluation({ models | runConfigId, versionId?, numExamples?, rolloutsP
463
462
  ```bash
464
463
  gateway bench pull x # reconstruct the head version's tree; `bench status ./x` = branch, base, local edits
465
464
  gateway bench fork x --into x-experiment # a new container sharing content; `bench diff <base> <head>` per-file, `bench log x` versions
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
465
+ gateway worlds edit status x # your open EDIT SESSION: every push / sandbox commit / data import after the first version lands there; only your unpinned reads see it (no @ref: describe x, session open x, pull x, test x); x@main, version pins, runs and tasks get SEALED versions only
467
466
  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
468
467
  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
- 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
468
+ 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, which every `task up` and run skips until sealed; `task edit rollback <task> --group <groupId>` undoes the group)
469
+ gateway worlds sandbox open x # no local checkout (no @ref: your open edit's tip, else main; x@main is the sealed main): write|exec|check|commit|close <id> edit the tree server-side; `bench sandbox` is the same set
471
470
  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
471
  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
473
472
  gateway worlds sandbox import <id> data/trips.csv --entity trip # rows a sandbox made or curl'ed → the PLATFORM world, read by the platform; `commit` carries the source tree only
474
473
  ```
475
474
 
476
475
  The sandbox carries the platform's `gateway` CLI and `sqlite3` on PATH: `exec` runs `worlds
477
- schema|data|test|serve|call …` on the working copy with nothing on your machine. `open` prints
476
+ schema|data|test|serve|call …` on the working copy with nothing on your machine; on a world whose data is a hosted snapshot, `data show|sql`, `test` and `call` read its rows (laid beside the tree before each `exec`), a tool, handler, route, new entity or optional field compiles and keeps that data, any other domain edit is refused (`references/gotchas.md`). `open` prints
478
477
  `cli: {version, digest}`, or `cli: null` plus the reason under `warnings`. Remote verbs (`push`, `run`,
479
478
  `session open`) stop inside the sandbox by design: it holds no platform credential, and never write one
480
479
  into its tree — `check`/`commit` hold back scratch, credential-shaped files (`.env`, `.gateway-env`, `*.env`,
@@ -489,6 +488,7 @@ MCP: `list_world_edits({ slug })`, `close_world_edit`, `discard_world_edit`, `ro
489
488
  - `references/ui-map.md`: every route, per thing (connector page, world tabs, Worlds › Map, sessions, tests, stored tasks).
490
489
  - `references/cli-mcp-map.md`: every CLI step with its MCP twin, the steps that have none, and how the platform (console) agent reaches the same surface (`run_gateway_cli`, `spawn_subagent`).
491
490
  - `references/gotchas.md`: offline vs platform scaffolding, `bench push` vs `worlds create`, the World Host as the only engine, sharing, seeds, `max_tokens`, secret preflight, `secret set` upsert.
491
+ - `references/journal-checks.md`: checks over the requests a session's world received (declarative, `verify.py`, SQL), fail-closed reasons, `task try` and `task regrade`.
492
492
 
493
493
  ## Related
494
494
 
@@ -497,4 +497,4 @@ MCP: `list_world_edits({ slug })`, `close_world_edit`, `discard_world_edit`, `ro
497
497
  - `documentation/features/connector-worlds.md` (`connector.toml`, capture, conform, serving), `workspace-connectors.md`
498
498
  (the connector object, sharing, MCP surface), `world-schema.md` (the `gateway-world/1` contract and store API);
499
499
  the first and last ship with the npm package (`gateway worlds skill connector-schema-authoring --install .`).
500
- - Consumer pages: `gateway_documentation/pages/worlds/{getting-started,sessions,data,custom-connections,slack}.mdx`.
500
+ - Consumer pages (docs.surfacearea.ai): `worlds/getting-started`, `worlds/sessions`, `worlds/data`, `worlds/custom-connections`, `worlds/slack`.
@@ -17,16 +17,21 @@ 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 data sql <world> '<sql>' [--limit] [--scenario] [--json]` | `sql_world_data` (`POST /api/public/worlds/{slug}/data/sql`; ONE read-only statement over a schema world's rows, whatever its engine; a write, `ATTACH`, `PRAGMA` or a second statement is refused; at most 1000 rows. A db/schema.sql world is a SQLite file: `sqlite3` in a sandbox) |
20
21
  | `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
22
  | `worlds session seed` | `seed_world_session` |
22
23
  | `worlds session export` | `export_world_session` |
24
+ | `worlds requests [list] <slug> [--session <id>] [--version <ref>] [--via api\|ui\|tool] [--operation <name>] [--status 200\|2xx\|4xx\|5xx] [--since <time>] [--until <time>] [--limit N] [--cursor <c>] [--json]` | `list_world_requests({ slug, sessionId?, versionId?, via?, operation?, status?, since?, until?, cursor?, limit? })` (`GET /api/public/worlds/{slug}/requests`): every request the world received, from every session, version and door (`via` api, ui, tool), newest first, a page of at most 200 with `nextCursor`; metadata only (method, path, query, status, rows, found, duration, each body's size and `truncated`). The world keeps them for its life under the project's retention setting, and reading records nothing in any session's ledger. `--since`/`--until` take an ISO 8601 date or time (no zone is UTC); a bad filter is exit 2 before any request. UI: the world's Requests view, the session page's activity feed |
25
+ | `worlds requests show <slug> <requestId> [--json] [--out <file>]` | `get_world_request({ slug, requestId })` (`GET /api/public/worlds/{slug}/requests/{requestId}`): the request's headers (credentials `[redacted]`) and the first 64 KB of each body as text (`null` for a body that is not text; `bodyBytes` is the full size, `truncated` says it was cut); `--out` writes the whole entry as JSON. MCP only: the console agent's `get_world_request` is a different tool (it polls a world build) |
26
+ | `worlds session requests <sessionId>` (the list's filters but `--session`/`--version`) | `list_world_requests({ slug, sessionId })` (the CLI reads `GET /api/public/world-sessions/{id}/requests`, the world's list for one session; both MCP tools call the platform's `WorldRequestLedger` directly). A session whose engine is not the World Host records no requests: the route answers 409 `requests_not_recorded`, the CLI prints its one line and exits 3, and `session export --requests` notes the same line on stderr and writes the call log. `worlds requests <slug> --session <id>` and `list_world_requests({ slug, sessionId })` answer such a session the same way: 409, exit 3, the tool's error naming the engine |
23
27
  | `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`) |
28
+ | `worlds session restart <id> [--version <pin>]` | `restart_world_session` (`POST /api/public/world-sessions/{id}/restart` `{version?}`: a running or closed session's world started over on its pin's current version, or `version`, which becomes the pin, under the same id, URLs and token; base data plus the task's seed. The route and the CLI answer what `status` answers plus `restart: {previousVersionId, versionId, pin, boundarySeq, boundaryAt}`; the MCP tool answers the `restart` block with `sessionId`. A request the old world received has an `at` before `boundaryAt`, and a grade reads only those after it. 409 `session_not_restartable` / `session_version_unavailable` / `session_reopen_in_progress` / `no_open_door`; 503 when the new world did not open) |
24
29
  | `worlds data calls pull` / `worlds data ingest [--transform\|--map]` | — (no MCP twin yet; `run_gateway_cli data ingest` on a sandboxed directory) |
25
30
  | `files upload <local>... [--to]` | `request_file_upload` + `confirm_file_upload` (`upload_file` for ≤25 MB inline) |
26
31
  | `files list [path]` / `files get <path>` / `files download\|cat <path>` | `list_files` / `get_file` (a presigned URL; the CLI streams it) |
27
32
  | `files delete` / `files move` / `files mkdir` | `delete_file` / `move_file` / `create_folder` |
28
33
  | `files fetch <url> --to <path> [--header "Name: value"]...` | `download_url_to_drive` (`POST /api/public/files/fetch`; the platform fetches, nothing passes through the caller's machine; a header value may name a project secret as `{{secret:NAME}}`, expanded on the platform and never returned; `--local` fetches from the caller's machine instead, without secrets) |
29
- | `worlds sandbox import <id> <path-in-sandbox> [--entity] [--mode]` | `import_world_sandbox_data` (`POST /api/public/benchmark-containers/sandboxes/{id}/import`; the platform reads the file from the sandbox tree into the platform world — the sandbox never holds credentials; `commit` versions the source tree only) |
34
+ | `worlds sandbox import <id> <path-in-sandbox> [--entity] [--mode] [--report <file>]` | `import_world_sandbox_data` (`POST /api/public/benchmark-containers/sandboxes/{id}/import`; the platform reads the file from the sandbox tree into the platform world — the sandbox never holds credentials; `commit` versions the source tree only) |
30
35
  | `files connectors list\|sync <id>` | `list_file_connectors` / `sync_file_connector` (`GET\|POST /api/public/files/connectors[/sync]`) |
31
36
  | `traces list\|get\|export [--observations]` | `get_trace`, `get_observations` (`GET /api/public/traces[/{id}]`, `/observations`) |
32
37
  | `traces sessions list\|get [--io]` | `get_session` (`GET /api/public/sessions[/{id}?includeIO=true]`) |
@@ -35,9 +40,9 @@ Reference for `worlds-getting-started`: every CLI step and its MCP twin, then ho
35
40
  | `environment run` / `worlds run` | `run_evaluation` |
36
41
  | `environment link-task-set` / `create-task` | `create_task_set`, `create_task`, `link_task_set` |
37
42
  | `bench diff` / `propose` | `env_diff`, `env_propose` (proposals are the legacy PR-style door; edit sessions below are the version-control loop) |
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 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 |
43
+ | `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's unpinned reads see (no `@ref`, no version: `describe`, `pull`, `log`, `session open`, `sandbox open`, `test`); `slug@main`/`@latest`, an exact version pin, every run, task and stored pin resolve to sealed versions only (an unsealed version id answers only its own author); 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 |
44
+ | `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`) — every `task up`, run config and schedule, yours included, keeps the sealed `main` until the close; `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` |
45
+ | `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; 503 `sandbox_unresponsive` / `sandbox_unavailable` / `sandbox_replacing` mean nothing changed: call again after `retryAfterSeconds` (a sandbox silent for 5 minutes is then replaced from its latest snapshot and answers 409 `sandbox_recreated`); 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\|sql .`, `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 |
41
46
  | `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) |
42
47
  | `worlds skill <name>` / `worlds connector skill` | `get_connector_authoring_skill`, `guide` |
43
48
  | `worlds connector capture --remote` / poll + download | `start_connector_capture`, `get_connector_capture` (platform agent only) |
@@ -49,11 +54,12 @@ before it makes a request.
49
54
 
50
55
  | Door | Limit | Over it |
51
56
  |---|---|---|
52
- | `sandbox write`, `write_world_sandbox_file`, `env_write_file`, `propose_task_fix` | 256 KB per file | refused, naming the limit; rows → `worlds data import <slug> <file>`; a big source file → `gateway files upload`, then fetch it inside the sandbox with `sandbox exec`; the whole tree → `bench push` |
53
- | `sandbox exec --timeout`, `exec_in_world_sandbox timeoutMs` | default 60 s, at most 600 s | refused, not clamped |
57
+ | `sandbox write` | 256 MB per file (past 4 MB the CLIs send it in parts, checked by size and SHA-256 before it lands); `--from <dir>` writes every file under it but `.git/`, `.gateway/` and scratch (`node_modules/`, `__pycache__/`, `*.pyc`, ...), and says what it skipped | refused before any request, naming the limit; generate bigger data in the sandbox (`sandbox exec`) and load it with `sandbox import` |
58
+ | `write_world_sandbox_file`, `env_write_file`, `propose_task_fix` | 256 KB per call | refused, naming the limit; a bigger file → `sandbox write`; rows → `worlds data import <slug> <file>`; the whole tree → `bench push` |
59
+ | `sandbox exec --timeout`, `exec_in_world_sandbox timeoutMs` | default 60 s, at most 600 s | refused, not clamped; a start gets the sandbox ready, then waits for the command until 40 s have passed in all, and a command not done by then answers `running` with an `execId` (the CLIs wait again by themselves; `exec_in_world_sandbox` takes `execId` to wait); a timeout returns what it printed; a start whose getting ready took over 45 s is a 409 `sandbox_exec_deferred` with nothing started, its `warnings` saying what getting ready found (the CLIs start again and print them; what getting ready did is kept, a snapshot lay that failed too, so the next start is quick); a job whose runner died is a 409 `sandbox_exec_lost`, and a runner the sandbox cannot prepare a 503 `sandbox_exec_start_failed` (nothing started) |
54
60
  | Sandbox tree at `check`/`commit`, `bench push` unpacked | 128 MB of source, 2000 files | refused, naming the limit, before a byte is read; move data to `worlds data import`, delete scratch files or list them in `.gatewayignore` |
55
61
  | Sandbox tree at `check`/`commit`: credential-shaped files (`.env`, `*.pem`, `id_rsa`, `credentials.json`…; `.env.example` stays), symlinks, sockets/devices | held back, never in the version | listed under `ignored`, each named in `warnings` (path only); use `bench secrets set` for a key the world needs |
56
- | `worlds data query` / `data show` on a stored version | none beyond the version's own caps | the platform opens the version's tree and snapshot in a prepared directory it owns; no size travels through the request |
62
+ | `worlds data query` / `data sql` / `data show` on a stored version | none beyond the version's own caps | the platform opens the version's tree and snapshot in a prepared directory it owns; no size travels through the request |
57
63
  | `bench push` / `worlds create --from` compressed bundle | 64 MB (16 MB from the browser) | refused, naming the limit |
58
64
  | A single manifest / metadata file in a bundle | 1 MB | refused |
59
65
  | `sandbox write` HTTP body | 1 MB (framework cap; only reachable by a body no schema would accept) | 413 |
@@ -14,6 +14,9 @@ The things that bite once and never again, moved out of `SKILL.md` to keep it un
14
14
  - The World Host is the engine for every world, `[dependencies]` included (it opens each linked
15
15
  world beside the root); a session never falls back to a slower engine, and a deployment
16
16
  without a host refuses the open by name.
17
+ - A `[dependencies]` pin never resolves to an open edit, yours included: `@main` is the sealed
18
+ `main`, and a hash, semver or version id must name a sealed version. Seal the linked world's
19
+ edit (`gateway worlds edit close <slug>`) before you push the world that links it.
17
20
  - Sharing is publish + clone, never a live reference; later edits reach a clone only on re-clone.
18
21
  - Never commit `captures/`; never merge a customer's world as an SDK template.
19
22
  - A seed (scenario overlay or runner admin endpoint) is the whole state, not an increment.
@@ -21,10 +24,55 @@ The things that bite once and never again, moved out of `SKILL.md` to keep it un
21
24
  - A platform request that never gets an answer fails in one line: the request, the host, the cause
22
25
  (`connection refused`, `DNS lookup failed`, `timed out after 120s`) and the next step, exit 1. Each
23
26
  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.
27
+ requests, so a long wait is never cut by it; a sandbox `exec` waits in 40 s requests until its
28
+ command ends, and other sandbox requests (and MCP tool calls through either proxy) wait 290 s,
29
+ under Node's 300 s fetch limit, on both twins. An edge answer that is not the platform's JSON (an
30
+ HTML 502/503/504 from a load balancer) is named, never printed.
31
+ - A version that holds dot or root files and was committed, by any door but a directory push, before
32
+ the platform hashed every stored file carries a content hash over its archive files only. Deleting
33
+ its only dot or root file (a `.gatewayignore`, say) and changing nothing else is refused, naming the
34
+ version and the files: commit the deletion with another change, or put the file back. An unchanged
35
+ tree on such a version commits the same files under the new hash, and `check` and `commit` say so,
36
+ unless those files are ones a sandbox never commits (scratch such as `__pycache__/`, or `.env`):
37
+ then an untouched sandbox is refused until it carries another change.
25
38
 
26
39
  - 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`
27
40
  with 400 `missing_env_secrets` naming `gateway bench secrets set --env <slug> --key <NAME>` before
28
41
  anything is provisioned — the same preflight a run dispatch applies; set the secret, then open.
29
42
  - `gateway secret set NAME` is an upsert: the same name again rotates the value and answers
30
43
  `updated: true`; `bench secrets set` does the same for a benchmark's environment.
44
+ - Imported data survives every edit that cannot touch a stored row. After `gateway worlds data import
45
+ <slug>` the world's tree carries `db/snapshot.json` (the hosted snapshot) and not the rows; in
46
+ `worlds sandbox open <slug>@main`, adding a tool, a handler, a route, a test or a documentation
47
+ file then `schema compile .` and `schema check .` pass and the commit keeps the snapshot, no
48
+ re-import, and `gateway bench fork <slug>` takes the data with it. Adding an entity or a field
49
+ that is not required (or another `domain_version`) carries the data too: `sandbox check` says
50
+ the commit migrates the snapshot, and `sandbox commit` migrates it as a job and re-pins the tree:
51
+ the CLI follows the batch (each phase on stderr, up to `--wait` seconds) and prints the new
52
+ version, or exits 1 naming the refusal (`storage`, `timeout`, `checkout_cap`, `refused`,
53
+ `base_moved`); MCP `commit_world_sandbox` answers `{batchId}` to poll with `get_data_batch` when the
54
+ job outlasts its wait. While the batch runs, `commit` and `import` are refused
55
+ (`sandbox_commit_pending`); once it lands a sandbox used in the last 15 minutes takes the version
56
+ at once when none of the files it rewrites changed since the commit, else its next `commit`,
57
+ `import` or `exec` takes it and says what it found (`commit` and `import` say it on a refusal
58
+ too; `close` takes it silently), and `sandbox check` shows it first without writing anything. A `sandbox import` stands the sandbox on the data version it published, so
59
+ the next commit needs no `--rebase`; when another door moved `main`, `sandbox check` says
60
+ `baseMoved` and `--rebase` carries the edit and the imported rows onto the tip. A `--rebase` whose
61
+ base sits on an edit session still open, still closing, or stopped in conflict is
62
+ refused (`rebase_unrelated`) naming the session and what to do: close an open one (`edit close
63
+ <slug> --session <id>`), wait for one that is closing, and land one in conflict over `main`
64
+ (`edit close <slug> --session <id> --force`) or drop it (`edit discard <slug> --session <id>`);
65
+ then `--rebase` again. `worlds push` from a pulled tree keeps the snapshot for the edits that cannot touch a row, and refuses a domain
66
+ change, naming the sandbox: make that one there. No file is
67
+ deleted by hand: compile drops the `db/state.*` the tree's own data files built, which the pin
68
+ replaces, and check never refuses them. In the sandbox `data show|sql`, `worlds test` and
69
+ `worlds call` read the hosted rows, which the platform lays beside the tree (never in it) before
70
+ each `exec`, after taking a batch that landed; `exec`'s warnings say when it could not.
71
+ Removing, retyping or requiring a field, or changing a key, a relationship or a description, is
72
+ refused, naming what changed: keep it as it was, or remove `db/snapshot.json` and import every
73
+ row again. `check` reports
74
+ the handlers `not_run` there, since a session needs the hosted rows; `gateway worlds session open
75
+ <slug>` runs them, so a handler that cannot be imported (a syntax error, a missing module) passes
76
+ `check` and is first refused at that open: open a session on the version after a handler edit.
77
+ Compile from a fresh `sandbox open` rather than copying in artifacts compiled
78
+ elsewhere: the pin proves its data's domain from the `schema/lock.json` it started with.
@@ -0,0 +1,182 @@
1
+ # Journal checks: verifiers over the requests a session's world received
2
+
3
+ A World Host session records every request its world receives, through every door: the api origin,
4
+ the page's `api_path` (ui) and a declared tool's call. Before a grade the platform waits until the
5
+ host has stored every request it holds for the session (the flush barrier), reads them back and
6
+ hands the grader those requests with whether they are all of them. Three ways to check them, one
7
+ implementation underneath: a declarative check, a `verify.py`, a SQL verifier.
8
+
9
+ Only the World Host records requests. A stored task whose checks read them is refused at validation
10
+ and at dispatch on any other engine, a run config included (`checks on the session's journal
11
+ (gateway_requests, calls, a python grader that reads it) need the World Host`). A local `worlds serve`
12
+ session reads `calls` from its own call log; there and in `benchmarks dry-run` the rest fails closed
13
+ as `not recorded`, whatever the grader accepts.
14
+
15
+ ## What a grader reads
16
+
17
+ `gateway_requests`, one row per request, oldest first:
18
+
19
+ ```json
20
+ { "seq": 2, "id": "0a1b…", "at": "2026-10-05T12:00:01.000Z", "durationMs": 12.5,
21
+ "via": "api", "operation": "create_record", "method": "POST", "path": "/records",
22
+ "query": { "dry_run": "false" }, "rows": 1, "found": true,
23
+ "request": { "headers": { "content-type": "application/json" }, "body": { "name": "Acme" },
24
+ "bodyBytes": 16, "truncated": false, "contentType": "application/json" },
25
+ "response": { "status": 201, "body": { "id": "rec_1" }, "bodyBytes": 15, "truncated": false,
26
+ "contentType": "application/json" } }
27
+ ```
28
+
29
+ - `via` is `api`, `ui` or `tool`; a tool call has no `method` or `path`.
30
+ - A JSON body reads as JSON, any other as text. Bodies are what the ledger stored: redacted when
31
+ captured, the first 64 KB (`truncated: true` past that). A request past the grade's budget (2,000
32
+ bodies, 8 MiB) carries `withheld: ["request.headers", "request.body", "response.body"]`.
33
+ - `gateway_journal` is the summary: `{ "complete": true, "reason": null, "requests": 4, "withheld": 0 }`.
34
+ `complete` is false when the host shed bodies or lost requests, did not answer the barrier, the
35
+ platform refused some, the session was reopened from a checkpoint or recovered after its worker or
36
+ host stopped, fewer requests remain than a past grade read, or the session holds more than 20,000;
37
+ `reason` says which. `withheld` counts the requests whose bodies the grade's budget left out.
38
+ - What a session's world was asked, to write a check against: `gateway worlds session requests
39
+ <SESSION_ID> --json` (MCP `list_world_requests`), or the `asked:` lines `task try` prints.
40
+
41
+ ## 1. Declarative checks (`assertions`)
42
+
43
+ ```json
44
+ { "kind": "assertions", "checks": [
45
+ { "id": "created", "entity": "gateway_requests",
46
+ "where": { "operation": "create_record", "response.status": 201 } },
47
+ { "id": "no_deletes", "entity": "gateway_requests", "where": { "method": "DELETE" }, "assert": "absent" },
48
+ { "id": "one_create", "entity": "gateway_requests", "where": { "operation": "create_record" },
49
+ "assert": "count", "count": { "eq": 1 } },
50
+ { "id": "looked_first", "entity": "gateway_requests", "where": { "operation": "get_record" },
51
+ "before": { "operation": "update_record" } },
52
+ { "id": "named_acme", "entity": "gateway_requests", "where": { "operation": "create_record" },
53
+ "assert": "all", "field": "request.body.name", "value": "Acme" }
54
+ ] }
55
+ ```
56
+
57
+ - `where`, `field`, `before` and `after` name `seq`, `id`, `at`, `durationMs`, `via`, `operation`,
58
+ `method`, `path`, `rows`, `found`, `request.body`, `request.bodyBytes`, `request.truncated`,
59
+ `request.contentType`, `response.status`, `response.body`, `response.bodyBytes`,
60
+ `response.truncated`, `response.contentType`, or a path under `query.`, `request.headers.`,
61
+ `request.body.`, `response.body.`. Anything else is refused with the field it meant:
62
+ `gateway_requests has no field response.stauts; did you mean response.status?`.
63
+ - `before: {…}` keeps the requests before the first one it matches (all of them when none does);
64
+ `after: {…}` keeps the requests after the first one it matches (none when none does). They go on
65
+ `gateway_requests` and `calls` checks only.
66
+ - `entity: "calls"` on a World Host session is the call log's view of the same requests: every
67
+ door, tool calls included, with no bound (`operation`, `args`, `query`, `body`, `selectors`,
68
+ `via`, `status`, `rows`, `found`). A request no route took and a tool call the door refused stay
69
+ in `gateway_requests` only.
70
+
71
+ ## 2. A `verify.py` that reads the journal
72
+
73
+ ```json
74
+ { "kind": "python", "readsJournal": true, "source": "<verify.py below>" }
75
+ ```
76
+
77
+ ```python
78
+ import json, sys
79
+
80
+ state = json.load(sys.stdin)
81
+ creates = [r for r in state["gateway_requests"]
82
+ if r["operation"] == "create_record" and r["response"]["status"] == 201]
83
+ print(json.dumps({"reward": 1 if len(creates) == 1 else 0, "one_create": len(creates) == 1}))
84
+ ```
85
+
86
+ Only a grader that declares `readsJournal: true` gets `gateway_requests` and `gateway_journal` on
87
+ stdin, beside the rows, `calls` and `report`. On an incomplete journal, or one whose bodies were
88
+ withheld, it scores 0 with the reason unless it also declares `acceptsIncompleteJournal: true`; then
89
+ it runs and reads `state["gateway_journal"]` itself (a body cut at 64 KB says `truncated: true`).
90
+ With no journal recorded at all it scores 0 either way.
91
+
92
+ ## 3. A SQL verifier (`verifiers/<name>.sql`, a `[[tasks]]` world)
93
+
94
+ ```sql
95
+ SELECT CASE WHEN COUNT(*) = 0 THEN 1.0 ELSE 0.0 END
96
+ FROM gateway_requests WHERE method = 'DELETE';
97
+ ```
98
+
99
+ ```sql
100
+ SELECT CASE WHEN COUNT(*) = 1 THEN 1.0 ELSE 0.0 END
101
+ FROM gateway_requests
102
+ WHERE operation = 'create_record' AND status = 201
103
+ AND json_extract(request_body, '$.name') = 'Acme';
104
+ ```
105
+
106
+ `gateway_requests` columns: `seq, id, at, duration_ms, via, operation, method, path, query, status,
107
+ rows, found, request_headers, request_body, request_body_bytes, request_truncated,
108
+ request_content_type, response_body, response_body_bytes, response_truncated,
109
+ response_content_type, withheld` (query, headers and bodies are the stored text: read them with
110
+ `json_extract`). `gateway_journal(complete, reason, requests, withheld)`. A verifier that reads
111
+ either on an incomplete journal, or reads a body column while a body was withheld or cut at 64 KB,
112
+ scores 0, and the grade names why under `reasons`, unless `gateway-env.toml` lets it (a read counts
113
+ however the statement reaches the table, joins included):
114
+
115
+ ```toml
116
+ [verifiers.created_at_least_once]
117
+ accepts_incomplete_journal = true
118
+ ```
119
+
120
+ Let only a check that a missing request can only make fail accept an incomplete journal: `COUNT(*) >
121
+ 0`, not `= 0` or `= 1`, which pass on a journal that lost a request they count. No flag grades a
122
+ journal never recorded, nor a linked world's verifier that reads one: the session's journal is the
123
+ root world's.
124
+
125
+ An entity may not be named `gateway_…` (the compiler refuses it), so the names never collide.
126
+
127
+ ## Fail closed
128
+
129
+ A check the stored requests do not decide fails and says why:
130
+
131
+ ```
132
+ FAIL no_deletes — journal incomplete (the World Host lost 2 requests): the 4 requests it holds do not decide this check
133
+ ```
134
+
135
+ A check they do decide still grades: `created` passes on an incomplete journal that holds the
136
+ request. Every World Host grade but a rubric's takes the barrier and records how complete the
137
+ journal was, so a later `try` or `regrade` of the session knows. A `calls` check on `args`, `body`
138
+ or `selectors` has the bodies fetched for it; one on `operation` or `status` alone does not need
139
+ them.
140
+
141
+ ## Try, save, regrade
142
+
143
+ ```bash
144
+ gateway worlds task try task.json --session <SESSION_ID> # a spec not saved yet; files nothing
145
+ gateway worlds task try <TASK_ID> --session <SESSION_ID> --version 3 --json
146
+ gateway worlds task update <TASK_ID> --spec task.json # save: the next version
147
+ gateway worlds task validate <TASK_ID>
148
+ gateway worlds task regrade <TASK_ID> # the task's latest run, whole, by the current version
149
+ gateway worlds task regrade <TASK_ID> --run <EVALUATION_ID> --version 3
150
+ gateway worlds task regrade <TASK_ID> --all-runs --limit 20
151
+ gateway worlds task regrade <TASK_ID> --session <SESSION_ID> # one rollout; its run then shows the versions it mixes
152
+ ```
153
+
154
+ ```
155
+ try the spec on session ses_01: graded live
156
+ journal: 4 requests, incomplete (the World Host lost 2 requests)
157
+ PASS created — matched #2 api POST create_record 201 (+1 more)
158
+ FAIL no_deletes — journal incomplete (the World Host lost 2 requests): the 4 requests it holds do not decide this check
159
+ reward 0.5
160
+ asked:
161
+ 1x api GET list_records 200 /records
162
+ 2x api POST create_record 201 /records
163
+ ```
164
+
165
+ `try` grades a live session in place, and a closed one on an ephemeral copy restored from the
166
+ checkpoint its last grade took, over the requests that grade read. A session no grade checkpointed
167
+ refuses checks over rows; checks over `gateway_requests` and `calls` still run. A check on an entity
168
+ the session's world does not define is refused, as an open refuses it.
169
+
170
+ `regrade` grades each rollout's session the way `try` does and replaces the rollout's grade in
171
+ place: the grade it held moves to `info.grades`, `info.verifierVersion` names the version that
172
+ graded it, and the run's metrics and label (`verifier v3`, or `verifiers v2, v3` for a mixed run)
173
+ follow. A release gate reads the new rewards on its next read. Exit 1 when nothing was regraded, a
174
+ rollout kept its grade (already graded by that version, so a rerun adds no history; no checkpoint
175
+ for a check over rows) or a rollout was regraded to no score (`--json` holds its reasons). A run or
176
+ session that is not the task's is refused. A task over several worlds is not regraded, and `try` on
177
+ one of its sessions grades that world's own grader, not the cross-world verifiers.
178
+
179
+ | CLI | MCP | REST | SDK |
180
+ | --- | --- | --- | --- |
181
+ | `worlds task try` | `try_world_task({ sessionId, taskId \| spec, version? })` (MEMBER and above: it runs your verify.py) | `POST /api/public/world-tasks/try` | `new TaskGrades(opts).try(sessionId, target)` / `TaskGrades().try_task(session_id, task_id=… \| spec=…)` |
182
+ | `worlds task regrade` | `regrade_world_task({ taskId, version?, runs?, allRuns?, sessions?, limit? })` | `POST /api/public/world-tasks/{taskId}/regrade` | `.regrade(taskId, scope)` / `.regrade(task_id, …)` |