@withgateway/sdk 0.6.0 → 0.9.3

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 (150) hide show
  1. package/dist/agents/index.d.mts +581 -0
  2. package/dist/agents/index.d.ts +581 -0
  3. package/dist/agents/index.js +1473 -0
  4. package/dist/agents/index.js.map +1 -0
  5. package/dist/agents/index.mjs +1424 -0
  6. package/dist/agents/index.mjs.map +1 -0
  7. package/dist/apiError-DHpfbmdx.d.mts +17 -0
  8. package/dist/apiError-DHpfbmdx.d.ts +17 -0
  9. package/dist/cli.js +11611 -6845
  10. package/dist/cli.js.map +1 -1
  11. package/dist/cli.mjs +10090 -5325
  12. package/dist/cli.mjs.map +1 -1
  13. package/dist/files/index.d.mts +3 -1
  14. package/dist/files/index.d.ts +3 -1
  15. package/dist/files/index.js +371 -102
  16. package/dist/files/index.js.map +1 -1
  17. package/dist/files/index.mjs +371 -102
  18. package/dist/files/index.mjs.map +1 -1
  19. package/dist/hooks/index.js +346 -136
  20. package/dist/hooks/index.js.map +1 -1
  21. package/dist/hooks/index.mjs +346 -136
  22. package/dist/hooks/index.mjs.map +1 -1
  23. package/dist/{index-LA-PMRJT.d.ts → index-DIN14Lhg.d.ts} +1 -1
  24. package/dist/{index-Di9nNqOY.d.mts → index-DuB-eQ0Z.d.mts} +1 -1
  25. package/dist/index.d.mts +7 -4
  26. package/dist/index.d.ts +7 -4
  27. package/dist/index.js +3177 -748
  28. package/dist/index.js.map +1 -1
  29. package/dist/index.mjs +2987 -590
  30. package/dist/index.mjs.map +1 -1
  31. package/dist/media-CQUC7TkS.d.mts +39 -0
  32. package/dist/media-DQnBloaX.d.ts +39 -0
  33. package/dist/traces/index.d.mts +3 -1
  34. package/dist/traces/index.d.ts +3 -1
  35. package/dist/traces/index.js +371 -102
  36. package/dist/traces/index.js.map +1 -1
  37. package/dist/traces/index.mjs +371 -102
  38. package/dist/traces/index.mjs.map +1 -1
  39. package/dist/tracing/index.d.mts +3 -2
  40. package/dist/tracing/index.d.ts +3 -2
  41. package/dist/tracing/index.js +257 -16
  42. package/dist/tracing/index.js.map +1 -1
  43. package/dist/tracing/index.mjs +257 -16
  44. package/dist/tracing/index.mjs.map +1 -1
  45. package/dist/transport-CpRe7zgd.d.mts +123 -0
  46. package/dist/transport-CpRe7zgd.d.ts +123 -0
  47. package/dist/worlds/index.d.mts +1986 -1746
  48. package/dist/worlds/index.d.ts +1986 -1746
  49. package/dist/worlds/index.js +1470 -290
  50. package/dist/worlds/index.js.map +1 -1
  51. package/dist/worlds/index.mjs +1465 -286
  52. package/dist/worlds/index.mjs.map +1 -1
  53. package/package.json +6 -1
  54. package/runtime/gatewaysdk/environment/bundle_manifest.py +531 -0
  55. package/runtime/gatewaysdk/environment/factory_documents.py +670 -0
  56. package/runtime/gatewaysdk/environment/factory_rules.py +973 -0
  57. package/runtime/gatewaysdk/environment/factory_shapes.py +253 -0
  58. package/runtime/gatewaysdk/environment/factory_spine.py +1155 -0
  59. package/runtime/gatewaysdk/environment/factory_spine_shapes.py +480 -0
  60. package/runtime/gatewaysdk/environment/schema/__main__.py +2 -2
  61. package/runtime/gatewaysdk/environment/schema/_slack_fidelity.py +8 -23
  62. package/runtime/gatewaysdk/environment/schema/admission.py +61 -59
  63. package/runtime/gatewaysdk/environment/schema/api.py +3 -4
  64. package/runtime/gatewaysdk/environment/schema/assertions.py +7 -1
  65. package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +1 -0
  66. package/runtime/gatewaysdk/environment/schema/call_log.py +20 -0
  67. package/runtime/gatewaysdk/environment/schema/cast.py +133 -67
  68. package/runtime/gatewaysdk/environment/schema/compiler.py +16 -17
  69. package/runtime/gatewaysdk/environment/schema/database/base.py +2 -2
  70. package/runtime/gatewaysdk/environment/schema/handler_errors.py +58 -4
  71. package/runtime/gatewaysdk/environment/schema/host.py +94 -12
  72. package/runtime/gatewaysdk/environment/schema/host_browser.py +48 -0
  73. package/runtime/gatewaysdk/environment/schema/host_control.py +35 -2
  74. package/runtime/gatewaysdk/environment/schema/host_handoff.py +4 -1
  75. package/runtime/gatewaysdk/environment/schema/host_loops.py +27 -4
  76. package/runtime/gatewaysdk/environment/schema/host_metrics.py +69 -0
  77. package/runtime/gatewaysdk/environment/schema/host_requests.py +35 -0
  78. package/runtime/gatewaysdk/environment/schema/host_session.py +20 -2
  79. package/runtime/gatewaysdk/environment/schema/host_surfaces.py +6 -0
  80. package/runtime/gatewaysdk/environment/schema/host_versions.py +100 -19
  81. package/runtime/gatewaysdk/environment/schema/host_workers.py +172 -50
  82. package/runtime/gatewaysdk/environment/schema/ingest.py +12 -3
  83. package/runtime/gatewaysdk/environment/schema/journal.py +7 -2
  84. package/runtime/gatewaysdk/environment/schema/local.py +32 -7
  85. package/runtime/gatewaysdk/environment/schema/mapping.py +1 -1
  86. package/runtime/gatewaysdk/environment/schema/measured_tests.py +187 -0
  87. package/runtime/gatewaysdk/environment/schema/page_checks.py +123 -0
  88. package/runtime/gatewaysdk/environment/schema/platform.py +80 -270
  89. package/runtime/gatewaysdk/environment/schema/platform_query.py +4 -3
  90. package/runtime/gatewaysdk/environment/schema/platform_templates.py +420 -0
  91. package/runtime/gatewaysdk/environment/schema/process_memory.py +76 -0
  92. package/runtime/gatewaysdk/environment/schema/redaction.py +13 -0
  93. package/runtime/gatewaysdk/environment/schema/request_ledger.py +4 -1
  94. package/runtime/gatewaysdk/environment/schema/run_parameters.py +25 -0
  95. package/runtime/gatewaysdk/environment/schema/runtime.py +57 -5
  96. package/runtime/gatewaysdk/environment/schema/scaffold.py +386 -219
  97. package/runtime/gatewaysdk/environment/schema/session_files.py +13 -2
  98. package/runtime/gatewaysdk/environment/schema/shape_catalog.py +493 -0
  99. package/runtime/gatewaysdk/environment/schema/shape_declarations.py +219 -0
  100. package/runtime/gatewaysdk/environment/schema/skill.py +1 -0
  101. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +1 -1
  102. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +2 -2
  103. package/runtime/gatewaysdk/environment/schema/skills/factory-orchestrator/SKILL.md +147 -0
  104. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +5 -1
  105. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +8 -6
  106. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +9 -9
  107. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +33 -2
  108. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +6 -6
  109. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +17 -2
  110. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/new-world-sandbox.md +1 -1
  111. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/shape-catalog.md +59 -0
  112. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/ui-map.md +3 -2
  113. package/runtime/gatewaysdk/environment/schema/slack.py +55 -10
  114. package/runtime/gatewaysdk/environment/schema/snapshot.py +28 -2
  115. package/runtime/gatewaysdk/environment/schema/tasks.py +25 -2
  116. package/runtime/gatewaysdk/environment/schema/template_record.py +131 -0
  117. package/runtime/gatewaysdk/environment/schema/tools_world.py +7 -5
  118. package/runtime/gatewaysdk/environment/schema/ui.py +54 -33
  119. package/runtime/gatewaysdk/environment/schema/ui_interactions.py +419 -0
  120. package/runtime/gatewaysdk/environment/schema/ui_recorder.js +895 -0
  121. package/runtime/gatewaysdk/environment/schema/ui_replay.py +366 -0
  122. package/runtime/gatewaysdk/environment/schema/ui_replay_record.LICENSE +25 -0
  123. package/runtime/gatewaysdk/environment/schema/ui_replay_record.js +109 -0
  124. package/runtime/gatewaysdk/environment/schema/validation.py +24 -1
  125. package/runtime/gatewaysdk/environment/schema/worker.py +12 -5
  126. package/runtime/gatewaysdk/environment/schema/worker_key.py +38 -0
  127. package/runtime/gatewaysdk/environment/schema/worker_peaks.py +38 -0
  128. package/runtime/gatewaysdk/environment/schema/worker_watch.py +50 -0
  129. package/runtime/gatewaysdk/environment/schema/workers.py +245 -69
  130. package/runtime/gatewaysdk/environment/schema/world_host.py +96 -73
  131. package/runtime/gatewaysdk/environment/schema/world_tests.py +3 -1
  132. package/runtime/gatewaysdk/environment/secret_values.py +1 -1
  133. package/runtime/gatewaysdk/environment/world.py +34 -43
  134. package/runtime/gatewaysdk/environment/world_session_contract.py +7 -34
  135. package/skills/benchmarks-getting-started/SKILL.md +1 -1
  136. package/skills/connector-schema-authoring/SKILL.md +2 -2
  137. package/skills/connector-schema-authoring/connector-worlds.md +3 -2
  138. package/skills/connector-schema-authoring/world-schema.md +36 -23
  139. package/skills/factory-orchestrator/SKILL.md +147 -0
  140. package/skills/world-data-ingestion/ROWS.md +5 -1
  141. package/skills/world-data-ingestion/SKILL.md +8 -6
  142. package/skills/worlds-getting-started/SKILL.md +9 -9
  143. package/skills/worlds-getting-started/references/cli-mcp-map.md +33 -2
  144. package/skills/worlds-getting-started/references/gotchas.md +6 -6
  145. package/skills/worlds-getting-started/references/journal-checks.md +17 -2
  146. package/skills/worlds-getting-started/references/new-world-sandbox.md +1 -1
  147. package/skills/worlds-getting-started/references/shape-catalog.md +59 -0
  148. package/skills/worlds-getting-started/references/ui-map.md +3 -2
  149. package/dist/media-BIApiPzS.d.mts +0 -102
  150. package/dist/media-BIApiPzS.d.ts +0 -102
@@ -16,12 +16,18 @@ Reference for `worlds-getting-started`: every CLI step and its MCP twin, then ho
16
16
  | `worlds create <slug> --from … [--overlay] [--rows] [--batch] [--layout]` | `create_world` |
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
- | `worlds data import` | `import_world_data` |
19
+ | `worlds data import [--state <name>]` | `import_world_data` (`worldState`: the rows land in that world state; main's data and versions do not move; the bulk lane is `request_data_upload` with `worldState`, refused with `publish: "later"`) |
20
+ | `worlds describe <world> [--entity <e>] [--json]` | `describe_world({ slug, ref?, entity? })` (`GET /api/public/worlds/{slug}?ref=&entity=`): entities with keys, row counts and each field's `[redact]` form, plus `catalog` (enumerations, JSON columns, custom fields, ids, sequences, the redaction legend, answer shapes per route; `references/shape-catalog.md`); an unknown entity is refused naming the entities |
20
21
  | `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) |
22
+ | `worlds state list <world>` | `list_world_states({ slug })` (`GET /api/public/worlds/{slug}/states`): the world's states by name, each with its `bindings` and `dataSnapshotId` (null = the state opens on the version's own data). A world state is a named starting point: data plus knob values, opened on any version |
23
+ | `worlds state show <world> <name> [--ref <ref>]` | `get_world_state({ slug, name, ref? })` (`GET …/states/{name}?ref=`): how the state opens on that version (`opens`: `source` `version`\|`state`\|`carried`, `snapshot`, `bindings`, `fingerprint`), or why it does not (`refusal.code`: `state_knobs`, `state_not_carried`, `state_carrying`, `state_data_not_dispatched`); a world with no READY version answers `versionId`, `opens` and `refusal` null |
24
+ | `worlds state create <world> <name> [--description <text>] [--param <k=v>]… [--from-snapshot <id> \| --from-state <name>]` | `create_world_state({ slug, name, description?, bindings?, fromSnapshot?, fromState? })` (`POST …/states`, secret key, 201): answers what `show` answers on main, and a `refusal` there still means the state exists (the CLI prints it as `warning:` and exits 0); a taken name is 409 `state_exists`, both sources 400 |
25
+ | `worlds state delete <world> <name>` | `delete_world_state({ slug, name })` (`DELETE …/states/{name}`): `{ state, deleted: true, runCount }` |
26
+ | `worlds state pull <world> <name> [--ref <ref>] [--out <dir>] [--force]` | `pull_world_state({ slug, name, ref? })` (`GET …/states/{name}/pull`): `opens` plus `download` `{url, expiresAt}`, a signed GET (1 h) of the gzipped SQLite snapshot, null when the state opens on the version's own tree files; the MCP twin hands back the URL, the CLI downloads it into `state.json` + `state.sqlite` and checks the un-gzipped file against `opens.snapshot.sha256` |
21
27
  | `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`) |
22
28
  | `worlds session seed` | `seed_world_session` |
23
29
  | `worlds session export` | `export_world_session` |
24
- | `worlds requests [list] <slug> [--session <id>] [--version <ref>] [--via api\|ui\|tool\|webhook] [--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, webhook), 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 |
30
+ | `worlds requests [list] <slug> [--session <id>] [--version <ref>] [--via api\|ui\|tool\|webhook\|page] [--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, webhook, page), 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
31
  | `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
32
  | `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 |
27
33
  | `worlds session webhooks <sessionId> [--json]` · `worlds session listen <sessionId> --forward-to <url> [--once] [--replay] [--interval-ms N] [--json]` | — (TypeScript CLI only). `webhooks` reads `GET /api/public/world-sessions/{id}/webhooks` (read key): the subscriptions the world's `[webhooks]` finds and how many deliveries each was sent, never a secret. `listen` polls `POST` the same route (secret key) and replays each delivery to `--forward-to` with its signed headers and exact body, then sends the receiver's status back, kept in the request ledger as `via: webhook` (`query.answer`), once per delivery; only deliveries sent from now unless `--replay`. A session on another engine: 409 `webhooks_not_served`, exit 1 |
@@ -48,6 +54,31 @@ Reference for `worlds-getting-started`: every CLI step and its MCP twin, then ho
48
54
  | `worlds skill <name>` / `worlds connector skill` | `get_connector_authoring_skill`, `guide` |
49
55
  | `worlds connector capture --remote` / poll + download | `start_connector_capture`, `get_connector_capture` (platform agent only) |
50
56
 
57
+ ## Agents that build worlds (the agent SDK)
58
+
59
+ An agent (instructions, a model, the tool servers it may use: `sandbox`, `drive`, `web`, `docs`) runs on the
60
+ platform as your project key, in a thread per input; it builds worlds through the same CLI (`run_gateway_cli`) and
61
+ asks you through `ask_user`. Create it once and edit it live: every edit is a tracked version, live unless
62
+ `--no-deploy`, and a run keeps the version it was sent on. A key, not a personal token, drives all of these.
63
+
64
+ | CLI | MCP |
65
+ | --- | --- |
66
+ | `agents create <name> --instructions <text> [--model] [--effort] [--max-turns] [--tool <server[:tool,…]>]…` | `create_agent({ name, instructions, model?, effort?, maxTurns?, tools? })` |
67
+ | `agents update <name> [--instructions\|--model\|--effort\|--clear-effort\|--max-turns] [--from] [--no-deploy]`, `agents tools attach <name> <server[:tool,…]>…`, `agents tools detach <name> <server>…` | `edit_agent({ name, set?, attach?, detach?, from?, deploy? })` |
68
+ | `agents versions <name>` | `list_agent_versions({ name })` |
69
+ | `agents rollback <name> <versionId> [--force]` | `rollback_agent({ name, versionId, from?, force? })` |
70
+ | `agents push <file.mjs[#export]\|file.py[:attr]\|file.json> [--deploy]` | `push_agent_definition({ definition, deploy? })` |
71
+ | `agents deploy <name> <versionId> [--force]` | `deploy_agent_definition({ agent, versionId, force? })` |
72
+ | `threads create --agent <name> [--autonomy provisionWorlds=true …]` | `create_agent_thread({ agent, title?, autonomy? })` |
73
+ | `threads send <thread> <input> [--watch]`, `agents run <name> <input>` | `send_agent_message({ threadId, input, version? })` |
74
+ | `threads watch <thread> [--run] [--after <cursor>]` (exit 4: it waits for a person) | `get_agent_run({ threadId, runId, waitSeconds? })` |
75
+ | `threads resolve <thread> --action <id> --answer <text>` | `answer_agent_run({ threadId, runId, actionId, answer })` |
76
+ | `threads cancel <thread> [--run]` | `cancel_agent_run({ threadId, runId })` |
77
+
78
+ SDKs: `@withgateway/sdk` (`Gateway`, `tools`; `gateway.agents.create(...)` returns a live `Agent` with `update`,
79
+ `tools.attach|detach`, `versions`, `rollback`, `run`; `defineAgent` + `agents.push` for CI) and `gatewaysdk.agents`
80
+ (the same in snake_case).
81
+
51
82
  ## Size and time limits (one source: `packages/shared/src/world/limits.ts`)
52
83
 
53
84
  Every door enforces the same number and names it in the refusal; the CLI checks the file
@@ -2,12 +2,12 @@
2
2
 
3
3
  The things that bite once and never again, moved out of `SKILL.md` to keep it under 500 lines.
4
4
 
5
- - A shipped template (`schema init ./x --connector salesforce`) scaffolds offline through the
6
- bundled runtime: no host, no keys, no config file read. Only `--connector workspace:<slug>`
7
- needs the platform — without `gateway auth login` or the `GATEWAY_*` keys (the platform
8
- agent's `run_gateway_cli` included: its local commands carry no key) `schema init` refuses it and names `--host`,
9
- `GATEWAY_HOST` and the login command. No `python3 >= 3.12`? A shipped template scaffolds
10
- on the platform instead, so there it does need a host.
5
+ - Connector templates live on the platform as official worlds: `schema init ./x --connector salesforce`
6
+ fetches the template's current version (`GET /api/public/worlds/templates/salesforce`) and needs a login
7
+ (`gateway auth login` or the `GATEWAY_*` keys); without one it exits 2 and says so, and `schema templates`
8
+ lists `custom` alone with a note. Only `--connector custom` scaffolds offline. The platform agent's
9
+ `run_gateway_cli` has no platform credentials: open a sandbox from the template instead
10
+ (`sandbox open --new <slug> --from salesforce`). No `python3 >= 3.12`? The platform's runtime builds it.
11
11
  - `bench push` and `worlds create --from ./x` store the tree as it is; nothing is repackaged into
12
12
  an api-kind bundle on the way up. `worlds migrate` turns a bundle pushed before that back into
13
13
  the tree. Either way, edit the schema world, not a bundle.
@@ -1,7 +1,8 @@
1
1
  # Journal checks: verifiers over the requests a session's world received
2
2
 
3
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
4
+ the page's `api_path` (ui) and a declared tool's call; and, on a UI world, every interaction on its
5
+ page (page). Before a grade the platform waits until the
5
6
  host has stored every request it holds for the session (the flush barrier), reads them back and
6
7
  hands the grader those requests with whether they are all of them. Three ways to check them, one
7
8
  implementation underneath: a declarative check, a `verify.py`, a SQL verifier.
@@ -26,7 +27,21 @@ as `not recorded`, whatever the grader accepts.
26
27
  "contentType": "application/json" } }
27
28
  ```
28
29
 
29
- - `via` is `api`, `ui` or `tool`; a tool call has no `method` or `path`.
30
+ - `via` is `api`, `ui`, `tool`, `webhook` or `page`; a tool call has no `method` or `path`.
31
+ - `page` is a UI world's page:
32
+ - **Operations:** `ui.click`, `ui.dblclick`, `ui.contextmenu`, `ui.hover`, `ui.change`, `ui.submit`, `ui.key`, `ui.copy`, `ui.cut`, `ui.paste`, `ui.drag`, `ui.drop`, `ui.file`, `ui.scroll`, `ui.visibility`, `ui.open` and `ui.navigate`. Each has no `method` and the page as its `path`.
33
+ - **The body:** `request.body` (`args` in `calls`) holds the `target`:
34
+ - `name`, `role`, `id`, `testid`, `selector`, `xpath`;
35
+ - `checked`, `expanded`, `pressed`, `selected`, `disabled`;
36
+ - `group` and `options` (a radio's legend and every option, a select's every option);
37
+ - `within` (the enclosing dialog or region) and `context` (the text of its row or card).
38
+
39
+ It also holds the `value`, a `point`, `files`, a drop's `source`, and the page load's `load` and `seq`; `load` and `seq` are in the entry's `query` too, so a journal read without bodies still shows a gap.
40
+ - **Who sees page rows:** only a check that names the page (`via: page`, a `ui.*` operation, or an `args.target.*` / `request.body.target.*` path). Every other check reads what it read before. SQL and python graders see page rows in `gateway_requests` and filter on `via`; before reading them, require one `ui.recording` row and no `ui.unrecorded` row (the host's notes, path `/`, one per UI session: a row count or a `path = '/'` match includes them).
41
+ - **When a check is ungraded:** if the grade has no journal (a cross-world `<alias>.calls` check, or a grade off the platform), if the journal does not show every life of the session recorded its pages (no `ui.recording`, which a World Host with the recorder writes when it first opens a UI session, or a `ui.unrecorded`, which a restore writes when the export it restores came from a host from before the recorder), if pages were served and none reported (a page that never ran the recorder), or if a page load's numbered interactions have a gap (a report lost). A check that names the page on a world with no ui is refused when the session opens.
42
+ - **What is recorded:** clicks and keys count only when trusted; an agent's `el.click()` by script is not a click. A value set by script still counts as a `ui.change`.
43
+ - **Trust:** an interaction is what the page reported. The session's token holder can send one without a browser.
44
+ - **Example** (picked High out of Low, Normal and High): `{"entity": "calls", "where": {"via": "page", "operation": "ui.change", "args.target.group": "Priority", "args.target.name": "High", "args.value": "true"}}`
30
45
  - A JSON body reads as JSON, any other as text. Bodies are what the ledger stored: redacted when
31
46
  captured, the first 64 KB (`truncated: true` past that). A request past the grade's budget (2,000
32
47
  bodies, 8 MiB) carries `withheld: ["request.headers", "request.body", "response.body"]`.
@@ -19,7 +19,7 @@ What `open` does and does not do:
19
19
  - The slug goes through the one world slug validator and must be free in the project. A taken
20
20
  slug is a 409 `world_exists`; the sandbox never renames it (pick another slug).
21
21
  - `--from custom` seeds the working tree with exactly what `gateway worlds schema init <slug>`
22
- writes; `--from <template>` with a shipped template (`gateway worlds schema templates`,
22
+ writes; `--from <template>` with an official template (`gateway worlds schema templates`,
23
23
  `GET /api/public/worlds/templates`). An unknown template is a 400 that names the list.
24
24
  - No world, container or version is created at open. `open`/`status` say so:
25
25
  `containerId: null`, `baseVersionId: null`, `baseContentHash: null`, `branch: "main"`,
@@ -0,0 +1,59 @@
1
+ # The shape catalog
2
+
3
+ Reference for `worlds-getting-started`: what `gateway worlds describe <world> --json` carries under
4
+ `catalog`, where each part comes from, and how a world declares what nothing else says.
5
+
6
+ ```bash
7
+ gateway worlds describe x --json # the whole catalog (a platform world: GET /api/public/worlds/x)
8
+ gateway worlds describe x --entity tickets --json # one entity's fields and catalog entries; answers stay whole (?entity=tickets)
9
+ ```
10
+
11
+ MCP: `describe_world({ slug, ref?, entity? })` answers the same document. An entity the world does not
12
+ declare is refused naming the ones it does.
13
+
14
+ ## What it holds
15
+
16
+ | Key | What | Read from |
17
+ | --- | --- | --- |
18
+ | `enumerations` | `{entity, pointer, values, labels?}`: the values a field allows, at any depth (`/events/*/kind`); a union that also admits other values lists none | JSON Schema `enum`, `const`, `oneOf`/`anyOf` of `const` (a `title` is the label) |
19
+ | `columns`, `types` | `{entity, field, schema}` for every JSON field; the definitions they reach, keyed `<file>.<Name>` (`world.Event`, `types.Link`) | the entity's schema as the compiler resolves it, sibling `schema/*.json` files included, annotations left out |
20
+ | `customFields` | `{entity, field, definitions, key, where, pairs?, add}`: a JSON field's keys are rows of `definitions`; `add` is the row that defines one more | `custom_fields` on the entity |
21
+ | `ids` | `{entity, pointer, target: {entity, key, where}}` or `{entity, pointer, values: [{id, label}]}` | `ids` on the entity (top-level foreign keys stay `entities[].relationships`) |
22
+ | `sequences` | `{entity, field, scope, start, source, operations}`: dense numbers, one counter per `scope` value | `sequences` on the entity; `[operations.api] generate = { f = "int" }` |
23
+ | `redaction` | `legend` for `[hash]` `[preserve]` `[round]` `[drop]`, and `writes`: capture stores these forms, an import, seed or upload only with `--redact apply`, every other write (a factory write too) as written | `[redact]` |
24
+ | `answers` | per route: `records`, `id`, `fields`, `count`, `total`, `cursor`, `cursorParam`, `declared` (JSON pointers, `""` the root) | the route's `[api]` envelope, `hits_key`, `cursor_key`, paging and the entity's key; `[operations.answer]` |
25
+
26
+ A write that fills a JSON field writes the shape under `columns`; a key under `customFields` needs its
27
+ definitions row first (`add` names it); an id under `ids` must be one of the target's rows or values.
28
+
29
+ `catalog` is `null` when describe could not read it: the entities still list, and a local describe adds
30
+ `catalogRefused` with the refusal (for a built world, a `[ui] static` without its `index.html`, say).
31
+
32
+ ## Declaring what nothing else says
33
+
34
+ In `schema/world.json`, on the entity (all optional; none changes stored rows):
35
+
36
+ ```json
37
+ "custom_fields": [{"field": "properties", "definitions": "acme_fields", "key": "name", "where": {"object_type": "tickets"}}],
38
+ "ids": [{"pointer": "/links/*/type_id", "values": [{"id": 1, "label": "parent"}, {"id": 2, "label": "duplicate"}]}],
39
+ "sequences": [{"field": "number", "scope": ["queue_id"], "start": 100}]
40
+ ```
41
+
42
+ `pairs: {"id": "id", "value": "value"}` says the field is an array of id/value items instead of an
43
+ object. In `connector.toml`, under an `[[operations]]` entry whose answer the route settings cannot
44
+ describe (a handler's own shape):
45
+
46
+ ```toml
47
+ [operations.answer]
48
+ records = "/results"
49
+ id = "ticket_id"
50
+ fields = ["status"]
51
+ count = "/count"
52
+ total = "/meta/total"
53
+ ```
54
+
55
+ `gateway worlds schema compile` and `check` refuse a declaration naming a field or entity the world
56
+ does not have, a sequence on a non-integer field, an id with both `entity` and `values`, a pointer
57
+ that is not a JSON Pointer, or a scoped sequence (or one with its own `start`) on a field a route
58
+ generates as `int`, which the world numbers across the whole entity from 1 (`catalog` / `spec` codes,
59
+ with the location).
@@ -5,8 +5,9 @@ is the world's container.
5
5
 
6
6
  | Thing | Where |
7
7
  | --- | --- |
8
- | Connectors, shipped and workspace, with Create world / Clone; New connector | Connectors page `/project/{projectId}/connectors` |
9
- | One connector: Overview (verdict + schema), API (served routes, tools), Worlds (built from it, Cancel/Retry) | `/project/{projectId}/connectors/{slug}` |
8
+ | Public worlds of every organization, then connectors, shipped and workspace, with Create world / Clone; New connector | WorldHub `/project/{projectId}/worldhub` (`/connectors` redirects) |
9
+ | One connector: Overview (verdict + schema), API (served routes, tools), Worlds (built from it, Cancel/Retry), UI | `/project/{projectId}/worldhub/{slug}` |
10
+ | A public world as another organization sees it: Overview (schema of `main`), API, History (code changes only) | `/project/{projectId}/worldhub/worlds/{containerId}` |
10
11
  | A world: tabs Overview, Scenarios, Schema, Results, Evals, History | `/project/{projectId}/world?env={containerId}&tab=<tab>` |
11
12
  | Schema tab: entities, tool schemas, the pin back to the connector, and the Redaction tile (per-field hash / preserve / round / drop, salt = connector slug) | `...&tab=schema` |
12
13
  | Overview: provenance (type, "Created from <connector> <version>", author), then Relationships — Links picture, Uses (pin → resolved version, entity mappings with transform chains), Used by; unresolved pins shown, never omitted | `...&tab=overview` |
@@ -11,16 +11,19 @@ import hashlib
11
11
  from pathlib import Path
12
12
  import shutil
13
13
  import tempfile
14
+ from typing import Mapping
14
15
 
15
16
  from .compiler import Contract, check_bundle
16
- from .scaffold import init_bundle
17
+ from .scaffold import TemplateWorld
18
+ from .template_record import TemplateRecord
17
19
  from .database import WorldDatabase
18
20
  from .validation import encoded, fail, read_json
19
- from ._slack_fidelity import fidelity_report, load_capabilities, slack_template_digest
21
+ from ._slack_fidelity import fidelity_report, load_capabilities
20
22
  from ._slack_scenario import write_scenario
21
23
 
22
24
  FORMAT = "gateway-slack-evidence/1"
23
25
  MAPPING = {"id": "slack-evidence", "version": "1"}
26
+ PUBLISHED_CAPABILITIES = "schema/capabilities.json"
24
27
 
25
28
 
26
29
  def _merge(old, patch):
@@ -657,12 +660,21 @@ def synthetic_slack_evidence() -> dict:
657
660
  }
658
661
 
659
662
 
660
- def build_slack_bundle(destination: str | Path, *, evidence: dict | None = None, name: str | None = None) -> Contract:
661
- """Create a populated executable Slack bundle in a new/empty directory."""
663
+ def build_slack_bundle(
664
+ destination: str | Path,
665
+ *,
666
+ template: Mapping[str, bytes],
667
+ evidence: dict | None = None,
668
+ name: str | None = None,
669
+ ) -> Contract:
670
+ """Create a populated executable Slack bundle in a new/empty directory from the
671
+ official Slack world's files (the world the platform serves for the Slack template)."""
662
672
  evidence = synthetic_slack_evidence() if evidence is None else evidence
663
673
  workspace, principal = _envelope(evidence)
664
674
  destination = Path(destination)
665
- contract = init_bundle(destination, connector="slack", name=name or "slack-world")
675
+ official = TemplateWorld(template, location="/template")
676
+ contract = official.write(destination, name=name or "slack-world")
677
+ capabilities = load_capabilities(official.files, PUBLISHED_CAPABILITIES)
666
678
  try:
667
679
  diagnostics = {}
668
680
  batch = map_slack_evidence(evidence, contract, diagnostics=diagnostics)
@@ -677,22 +689,43 @@ def build_slack_bundle(destination: str | Path, *, evidence: dict | None = None,
677
689
  encoded({"workspace_id": workspace["id"], "user_id": principal["user_id"]})
678
690
  )
679
691
  (destination / "fidelity.json").write_bytes(
680
- encoded(fidelity_report(contract, evidence, batch, diagnostics, mapping=MAPPING))
692
+ encoded(
693
+ fidelity_report(
694
+ contract,
695
+ evidence,
696
+ batch,
697
+ diagnostics,
698
+ mapping=MAPPING,
699
+ capabilities=capabilities,
700
+ template_digest=official.digest,
701
+ )
702
+ )
681
703
  )
682
- (destination / "capabilities.json").write_bytes(encoded(load_capabilities()))
704
+ (destination / "capabilities.json").write_bytes(encoded(capabilities))
683
705
  write_scenario(destination, evidence, batch, entities=contract.entities)
684
706
  (destination / "slack-imports.json").write_bytes(
685
707
  encoded({batch["id"]: hashlib.sha256(encoded(evidence)).hexdigest()})
686
708
  )
687
709
  check_bundle(destination)
710
+ TemplateRecord.of_world(destination, connector=official.record.connector, digest=official.digest).write(
711
+ destination
712
+ )
688
713
  return contract
689
714
  except BaseException:
690
715
  shutil.rmtree(destination)
691
716
  raise
692
717
 
693
718
 
694
- def refresh_slack_bundle(destination: str | Path, evidence: dict | None = None, *, batch_id: str | None = None) -> dict:
719
+ def refresh_slack_bundle(
720
+ destination: str | Path,
721
+ evidence: dict | None = None,
722
+ *,
723
+ template: Mapping[str, bytes],
724
+ batch_id: str | None = None,
725
+ ) -> dict:
695
726
  """Validate then append one refresh batch; preserve original batch and lineage.
727
+ ``template`` is the official Slack world's files: a world built from another template
728
+ version is refused.
696
729
 
697
730
  Call this only on an isolated copy while constructing a new immutable version.
698
731
  The publisher owns expected-parent CAS and immutable version promotion.
@@ -705,7 +738,9 @@ def refresh_slack_bundle(destination: str | Path, evidence: dict | None = None,
705
738
  fail("slack_evidence", "Refresh cannot change the bound workspace or principal", "/evidence/principal")
706
739
  contract = check_bundle(destination)
707
740
  previous_report = read_json(destination / "fidelity.json")
708
- if previous_report.get("template_digest") != slack_template_digest():
741
+ official = TemplateWorld(template, location="/template")
742
+ official.record.verify(official.files, "/template")
743
+ if previous_report.get("template_digest") != official.digest:
709
744
  fail(
710
745
  "slack_template_mismatch",
711
746
  "Refresh requires the original template package; create a new world with the current template",
@@ -747,7 +782,17 @@ def refresh_slack_bundle(destination: str | Path, evidence: dict | None = None,
747
782
  imports[batch_id] = digest
748
783
  (destination / "slack-imports.json").write_bytes(encoded(imports))
749
784
  (destination / "fidelity.json").write_bytes(
750
- encoded(fidelity_report(contract, evidence, batch, diagnostics, mapping=MAPPING))
785
+ encoded(
786
+ fidelity_report(
787
+ contract,
788
+ evidence,
789
+ batch,
790
+ diagnostics,
791
+ mapping=MAPPING,
792
+ capabilities=load_capabilities(official.files, PUBLISHED_CAPABILITIES),
793
+ template_digest=official.digest,
794
+ )
795
+ )
751
796
  )
752
797
  write_scenario(destination, evidence, state, entities=contract.entities)
753
798
  return result
@@ -66,6 +66,7 @@ from .domain_migration import DomainMigration
66
66
  from .validation import ContractError, canonical, fail, read_json
67
67
 
68
68
  SIDECAR = "state.json"
69
+ SNAPSHOT_OUTPUTS = frozenset({*(engine.snapshot_name for engine in WorldDatabase.engines()), SIDECAR})
69
70
  PIN = "snapshot.json"
70
71
  DEFAULT_DIR = "db"
71
72
  SCENARIOS = "scenarios"
@@ -406,9 +407,29 @@ def scenario_dirs(world: str | Path) -> dict[str, Path]:
406
407
  return out
407
408
 
408
409
 
409
- def scenario_seed_files(scenario: Path) -> list[Path]:
410
+ SCENARIO_GRADERS = "checks"
411
+
412
+
413
+ def scenario_seed_dir(scenario: Path) -> Path:
414
+ """Where a scenario's rows live: a directory inside the scenario, neither the scenario itself
415
+ (its built snapshot sits there) nor its graders, so a copy that keeps a scenario's code and
416
+ drops its data can tell the two apart by path."""
410
417
  table = tomllib.loads((scenario / "scenario.toml").read_text(encoding="utf-8"))
411
- seed_dir = scenario / str(table.get("seed") or "seed")
418
+ name = str(table.get("seed") or "seed")
419
+ root = scenario.resolve()
420
+ seed_dir = (scenario / name).resolve()
421
+ inside = seed_dir != root and seed_dir.is_relative_to(root)
422
+ if not inside or seed_dir.is_relative_to(root / SCENARIO_GRADERS):
423
+ fail(
424
+ "scenario",
425
+ f"{scenario.name}/scenario.toml seed {name!r} must name a directory inside the scenario, not the scenario itself or {SCENARIO_GRADERS}/",
426
+ f"/{SCENARIOS}/{scenario.name}",
427
+ )
428
+ return seed_dir
429
+
430
+
431
+ def scenario_seed_files(scenario: Path) -> list[Path]:
432
+ seed_dir = scenario_seed_dir(scenario)
412
433
  return sorted(seed_dir.glob("*.json")) if seed_dir.is_dir() else []
413
434
 
414
435
 
@@ -527,6 +548,11 @@ def verify(snapshot: Path, contract: Contract, remedy: str = REBUILD_REMEDY) ->
527
548
  return sidecar
528
549
 
529
550
 
551
+ def is_snapshot_output(path: str) -> bool:
552
+ """A built snapshot or its sidecar: an output of a tree, never a source. Twin of ``isWorldSnapshotOutput``."""
553
+ return path.rsplit("/", 1)[-1] in SNAPSHOT_OUTPUTS
554
+
555
+
530
556
  def snapshot_name(contract: Contract) -> str:
531
557
  """The file name the contract's engine writes a snapshot to."""
532
558
  return WorldDatabase.for_contract(contract).snapshot_name
@@ -76,12 +76,14 @@ class TaskSpec:
76
76
  def allows_tool(self, tool: str) -> bool:
77
77
  return self.tools is None or tool in self.tools
78
78
 
79
+ def grader_checks(self) -> list[dict]:
80
+ return list(self.grader["checks"]) if self.grader is not None and self.grader["kind"] == "assertions" else []
81
+
79
82
  def entities(self) -> list[str]:
80
83
  named: list[str] = []
81
84
  if self.seed is not None:
82
85
  named.extend(self.seed["rows"])
83
- if self.grader is not None and self.grader["kind"] == "assertions":
84
- named.extend(check["entity"] for check in self.grader["checks"])
86
+ named.extend(check["entity"] for check in self.grader_checks())
85
87
  # A session task is named for its alias: only checks under it name this world's entities.
86
88
  own = f"{self.name}."
87
89
  for verifier in self.verifiers:
@@ -96,6 +98,27 @@ JOURNAL = "gateway_requests"
96
98
  JOURNAL_META = "gateway_journal"
97
99
  RESERVED_STATE_KEYS = frozenset({CALL_LOG, "snapshot", JOURNAL})
98
100
  DOOR_FIELD = "via"
101
+ PAGE_DOOR = "page"
102
+ PAGE_SERVED = "ui.served"
103
+ PAGE_RECORDING = "ui.recording"
104
+ PAGE_UNRECORDED_LIFE = "ui.unrecorded"
105
+ PAGE_NOTES = frozenset({PAGE_SERVED, PAGE_RECORDING, PAGE_UNRECORDED_LIFE})
106
+ PAGE_UNJOURNALED = (
107
+ "a check on the page's interactions is decided from the session's journal, which shows whether its pages "
108
+ "were recorded; this grade has none (a cross-world check, or a grade off the platform): ungraded"
109
+ )
110
+ PAGE_UNRECORDED = (
111
+ "no World Host noted that it recorded every part of this session's pages (a host from before the page "
112
+ "recorder served some of them), so a check on the page's interactions cannot be decided: ungraded"
113
+ )
114
+ PAGE_UNHEARD = (
115
+ "the session served its ui's pages but no page reported an interaction (a page that never ran the "
116
+ "recorder), so a check on the page's interactions cannot be decided: ungraded"
117
+ )
118
+ PAGE_GAP = (
119
+ "the page numbered {missing} interactions it never reported (a report lost on the way), so a check "
120
+ "on the page's interactions cannot be decided: ungraded"
121
+ )
99
122
  WITHHELD_FIELD = "withheld"
100
123
  ROW_FIELDS = ("found", "rows")
101
124
  ORDER_KEYS = ("before", "after")
@@ -0,0 +1,131 @@
1
+ """``schema/template.json``: the template a world was built from, the template's digest, the compiler outputs the
2
+ build produced, and the sha256 of every other file the built world holds. A reader trusts the digest only while the
3
+ world still holds exactly those files (twin: ``TemplateRecord`` in gateway/packages/shared/src/world/templateRecord.ts;
4
+ the outputs a record may name are pinned by conformance/template-record.json)."""
5
+
6
+ from __future__ import annotations
7
+
8
+ import hashlib
9
+ import json
10
+ from dataclasses import dataclass
11
+ from pathlib import Path, PurePosixPath
12
+ from typing import Any, Mapping
13
+
14
+ from ..world import WorldTree
15
+ from .compiler import GENERATED, LOCK
16
+ from .snapshot import is_snapshot_output
17
+ from .ui import GENERATED_FILES, is_generated, read_ui_declaration
18
+ from .validation import fail, tree_path
19
+
20
+ RECORD = "schema/template.json"
21
+ COMPILED_OUTPUTS = (*GENERATED, LOCK)
22
+ _SHA256 = frozenset("0123456789abcdef")
23
+
24
+
25
+ def is_template_output(path: str) -> bool:
26
+ return path in COMPILED_OUTPUTS or PurePosixPath(path).name in GENERATED_FILES
27
+
28
+
29
+ @dataclass(frozen=True)
30
+ class TemplateRecord:
31
+ connector: str
32
+ digest: str
33
+ outputs: tuple[str, ...]
34
+ sources: Mapping[str, str]
35
+
36
+ @classmethod
37
+ def of_world(cls, root: Path, *, connector: str, digest: str) -> "TemplateRecord":
38
+ outputs = tuple(sorted(_compiled_outputs(root)))
39
+ sources = {
40
+ path: hashlib.sha256((root / path).read_bytes()).hexdigest()
41
+ for path in WorldTree.from_dir(root).hashed_paths()
42
+ if _covered(path, outputs)
43
+ }
44
+ return cls(connector, digest, outputs, sources)
45
+
46
+ @classmethod
47
+ def parse(cls, files: Mapping[str, bytes], location: str) -> "TemplateRecord":
48
+ where = f"{location}/{RECORD}"
49
+ try:
50
+ raw = json.loads(files[RECORD].decode("utf-8")) if RECORD in files else None
51
+ except (UnicodeDecodeError, ValueError):
52
+ raw = None
53
+ if not isinstance(raw, dict):
54
+ fail("template", f"The world carries no readable {RECORD}", where)
55
+ return cls(
56
+ _text(raw.get("connector"), "connector", where),
57
+ _sha256(raw.get("digest"), "digest", where),
58
+ _outputs(raw.get("outputs"), where),
59
+ _sources(raw.get("sources"), where),
60
+ )
61
+
62
+ def verify(self, files: Mapping[str, bytes], location: str) -> None:
63
+ """Refuse a world that no longer holds, byte for byte, every file it was built with: an edit in place."""
64
+ held = {path for path in files if _covered(path, self.outputs)}
65
+ changed = sorted(
66
+ path
67
+ for path in held | set(self.sources)
68
+ if path not in held
69
+ or path not in self.sources
70
+ or hashlib.sha256(files[path]).hexdigest() != self.sources[path]
71
+ )
72
+ if changed:
73
+ fail(
74
+ "template",
75
+ f"The world no longer holds the files it was built with from its template ({', '.join(changed[:5])}); "
76
+ "rebuild it from its template",
77
+ location,
78
+ )
79
+
80
+ def write(self, root: Path) -> None:
81
+ document = {
82
+ "connector": self.connector,
83
+ "digest": self.digest,
84
+ "outputs": list(self.outputs),
85
+ "sources": dict(sorted(self.sources.items())),
86
+ }
87
+ (root / RECORD).write_bytes((json.dumps(document, indent=2) + "\n").encode("utf-8"))
88
+
89
+
90
+ def _covered(path: str, outputs: tuple[str, ...]) -> bool:
91
+ return path != RECORD and path not in outputs and not is_snapshot_output(path)
92
+
93
+
94
+ def _compiled_outputs(root: Path) -> list[str]:
95
+ outputs = [path for path in COMPILED_OUTPUTS if (root / path).is_file()]
96
+ ui = read_ui_declaration(root)
97
+ static = PurePosixPath(ui.static).as_posix() if ui is not None else None
98
+ if static is None or ui.generated is not True or not is_generated(root / static / "index.html"):
99
+ return outputs
100
+ return [*outputs, *(f"{static}/{name}" for name in GENERATED_FILES if (root / static / name).is_file())]
101
+
102
+
103
+ def _text(value: Any, field: str, where: str) -> str:
104
+ if not isinstance(value, str) or not value:
105
+ fail("template", f"{RECORD} names no {field}", where)
106
+ return value
107
+
108
+
109
+ def _sha256(value: Any, field: str, where: str) -> str:
110
+ if not isinstance(value, str) or len(value) != 64 or not set(value) <= _SHA256:
111
+ fail("template", f"{RECORD} {field} is not a sha256 hex digest", where)
112
+ return value
113
+
114
+
115
+ def _outputs(value: Any, where: str) -> tuple[str, ...]:
116
+ if not isinstance(value, list) or not all(isinstance(path, str) for path in value):
117
+ fail("template", f"{RECORD} names no outputs list", where)
118
+ for path in value:
119
+ tree_path(path, where)
120
+ if not is_template_output(path):
121
+ fail("template", f"{RECORD} names {path} as an output; only compiler outputs are", where)
122
+ return tuple(value)
123
+
124
+
125
+ def _sources(value: Any, where: str) -> dict[str, str]:
126
+ if not isinstance(value, dict) or not value:
127
+ fail("template", f"{RECORD} names no source files", where)
128
+ for path, digest in value.items():
129
+ tree_path(path, where)
130
+ _sha256(digest, f"source {path}", where)
131
+ return dict(value)
@@ -208,7 +208,7 @@ def _scenario_task(name: str, scenario: Path) -> ToolsTask:
208
208
  table = tomllib.loads((scenario / "scenario.toml").read_text(encoding="utf-8"))
209
209
  instruction = scenario / "instruction.md"
210
210
  prompt = instruction.read_text(encoding="utf-8") if instruction.is_file() else str(table.get("instruction") or "")
211
- verify = scenario / "checks" / "verify.py"
211
+ verify = scenario / snapshots.SCENARIO_GRADERS / "verify.py"
212
212
  return ToolsTask(
213
213
  id=name,
214
214
  prompt=prompt.strip() or f"Drive the world into the state the scenario '{name}' checks.",
@@ -262,8 +262,8 @@ def load_tasks(bundle: Path, manifest: _bundle.EnvManifest, verifiers: list[str]
262
262
  def load_tools_version(
263
263
  bundle: Path,
264
264
  template: Path,
265
- snapshot: dict[str, str] | None,
266
265
  *,
266
+ fetched: bool,
267
267
  run_handlers: bool,
268
268
  ) -> ToolsVersion:
269
269
  if not is_tools_bundle(bundle):
@@ -278,15 +278,13 @@ def load_tools_version(
278
278
  "`gateway worlds schema init` starts one that does",
279
279
  )
280
280
  contract = check_bundle(bundle)
281
- if snapshot:
282
- snapshots.fetch(bundle, contract, snapshot["url"], snapshot["sha256"], snapshot["digest"])
283
281
  # connector.toml is read as the api runtime reads it, so an unservable route is refused at cache time.
284
282
  spec = settings = None
285
283
  if (bundle / SPEC).is_file():
286
284
  spec = load_spec(bundle)
287
285
  settings = load_api_settings(bundle, spec)
288
286
  read_fields = RouteBindings.served(spec, settings, contract)
289
- proven = ProvenTemplate.prove(bundle, template, contract, fetched=bool(snapshot), read_fields=read_fields)
287
+ proven = ProvenTemplate.prove(bundle, template, contract, fetched=fetched, read_fields=read_fields)
290
288
  verifiers = verifier_names(bundle)
291
289
  if REWARD in verifiers:
292
290
  fail("host", f"verifier name '{REWARD}' is reserved for the scalar grade")
@@ -351,6 +349,7 @@ class ToolsWorld:
351
349
  allowed: frozenset[str] | None = None,
352
350
  dependencies: dict[str, DependencyWorld] | None = None,
353
351
  calls: CallLog | None = None,
352
+ parameters: dict[str, str] | None = None,
354
353
  ) -> None:
355
354
  if version.handlers is None:
356
355
  fail("host", "a mock-tools session runs world-authored handlers; only a version worker opens one")
@@ -361,6 +360,7 @@ class ToolsWorld:
361
360
  self.task = self._task_of(version, task)
362
361
  self.allowed = allowed
363
362
  self.calls = calls
363
+ self.parameters = dict(parameters or {})
364
364
  self.dependencies = dict(dependencies or {})
365
365
  self.served = served_with_dependencies(version, self.dependencies)
366
366
  self._task_seed = seed
@@ -429,6 +429,8 @@ class ToolsWorld:
429
429
  scenario_id = str(self.task.metadata.get("scenario_id") or self.task.id)
430
430
  for world in (self.world, *self.worlds.values()):
431
431
  world.set_task_context(scenario_id)
432
+ if self.parameters:
433
+ self.world.set_run_parameters(self.parameters)
432
434
  self._attach()
433
435
 
434
436
  def _attach(self) -> None: