@withgateway/sdk 0.6.0 → 0.9.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (119) hide show
  1. package/dist/agents/index.d.mts +573 -0
  2. package/dist/agents/index.d.ts +573 -0
  3. package/dist/agents/index.js +1443 -0
  4. package/dist/agents/index.js.map +1 -0
  5. package/dist/agents/index.mjs +1394 -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 +5019 -1599
  10. package/dist/cli.js.map +1 -1
  11. package/dist/cli.mjs +5003 -1584
  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 +2689 -401
  28. package/dist/index.js.map +1 -1
  29. package/dist/index.mjs +2650 -394
  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 +1983 -1745
  48. package/dist/worlds/index.d.ts +1983 -1745
  49. package/dist/worlds/index.js +1295 -226
  50. package/dist/worlds/index.js.map +1 -1
  51. package/dist/worlds/index.mjs +1290 -222
  52. package/dist/worlds/index.mjs.map +1 -1
  53. package/package.json +6 -1
  54. package/runtime/gatewaysdk/environment/bundle_manifest.py +243 -0
  55. package/runtime/gatewaysdk/environment/schema/__main__.py +2 -2
  56. package/runtime/gatewaysdk/environment/schema/_slack_fidelity.py +8 -23
  57. package/runtime/gatewaysdk/environment/schema/api.py +3 -4
  58. package/runtime/gatewaysdk/environment/schema/assertions.py +7 -1
  59. package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +1 -0
  60. package/runtime/gatewaysdk/environment/schema/call_log.py +20 -0
  61. package/runtime/gatewaysdk/environment/schema/database/base.py +2 -2
  62. package/runtime/gatewaysdk/environment/schema/host.py +74 -11
  63. package/runtime/gatewaysdk/environment/schema/host_browser.py +48 -0
  64. package/runtime/gatewaysdk/environment/schema/host_control.py +33 -2
  65. package/runtime/gatewaysdk/environment/schema/host_handoff.py +4 -1
  66. package/runtime/gatewaysdk/environment/schema/host_requests.py +14 -0
  67. package/runtime/gatewaysdk/environment/schema/host_session.py +13 -2
  68. package/runtime/gatewaysdk/environment/schema/host_surfaces.py +6 -0
  69. package/runtime/gatewaysdk/environment/schema/host_versions.py +96 -19
  70. package/runtime/gatewaysdk/environment/schema/journal.py +7 -2
  71. package/runtime/gatewaysdk/environment/schema/local.py +32 -7
  72. package/runtime/gatewaysdk/environment/schema/page_checks.py +123 -0
  73. package/runtime/gatewaysdk/environment/schema/platform.py +23 -267
  74. package/runtime/gatewaysdk/environment/schema/platform_templates.py +332 -0
  75. package/runtime/gatewaysdk/environment/schema/request_ledger.py +4 -1
  76. package/runtime/gatewaysdk/environment/schema/run_parameters.py +25 -0
  77. package/runtime/gatewaysdk/environment/schema/runtime.py +43 -5
  78. package/runtime/gatewaysdk/environment/schema/scaffold.py +367 -217
  79. package/runtime/gatewaysdk/environment/schema/session_files.py +13 -2
  80. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +1 -1
  81. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +1 -2
  82. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +4 -2
  83. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +7 -7
  84. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +32 -2
  85. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +6 -6
  86. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +17 -2
  87. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/new-world-sandbox.md +1 -1
  88. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/ui-map.md +3 -2
  89. package/runtime/gatewaysdk/environment/schema/slack.py +55 -10
  90. package/runtime/gatewaysdk/environment/schema/snapshot.py +28 -2
  91. package/runtime/gatewaysdk/environment/schema/tasks.py +25 -2
  92. package/runtime/gatewaysdk/environment/schema/template_record.py +131 -0
  93. package/runtime/gatewaysdk/environment/schema/tools_world.py +7 -5
  94. package/runtime/gatewaysdk/environment/schema/ui.py +54 -33
  95. package/runtime/gatewaysdk/environment/schema/ui_interactions.py +419 -0
  96. package/runtime/gatewaysdk/environment/schema/ui_recorder.js +895 -0
  97. package/runtime/gatewaysdk/environment/schema/ui_replay.py +366 -0
  98. package/runtime/gatewaysdk/environment/schema/ui_replay_record.LICENSE +25 -0
  99. package/runtime/gatewaysdk/environment/schema/ui_replay_record.js +109 -0
  100. package/runtime/gatewaysdk/environment/schema/validation.py +10 -1
  101. package/runtime/gatewaysdk/environment/schema/worker.py +5 -1
  102. package/runtime/gatewaysdk/environment/schema/workers.py +8 -1
  103. package/runtime/gatewaysdk/environment/schema/world_host.py +44 -15
  104. package/runtime/gatewaysdk/environment/secret_values.py +1 -1
  105. package/runtime/gatewaysdk/environment/world.py +34 -43
  106. package/runtime/gatewaysdk/environment/world_session_contract.py +7 -34
  107. package/skills/benchmarks-getting-started/SKILL.md +1 -1
  108. package/skills/connector-schema-authoring/SKILL.md +1 -2
  109. package/skills/connector-schema-authoring/connector-worlds.md +2 -2
  110. package/skills/connector-schema-authoring/world-schema.md +29 -23
  111. package/skills/world-data-ingestion/SKILL.md +4 -2
  112. package/skills/worlds-getting-started/SKILL.md +7 -7
  113. package/skills/worlds-getting-started/references/cli-mcp-map.md +32 -2
  114. package/skills/worlds-getting-started/references/gotchas.md +6 -6
  115. package/skills/worlds-getting-started/references/journal-checks.md +17 -2
  116. package/skills/worlds-getting-started/references/new-world-sandbox.md +1 -1
  117. package/skills/worlds-getting-started/references/ui-map.md +3 -2
  118. package/dist/media-BIApiPzS.d.mts +0 -102
  119. package/dist/media-BIApiPzS.d.ts +0 -102
@@ -146,14 +146,25 @@ class ProvenTemplate:
146
146
  os.replace(record, self.proof_path)
147
147
 
148
148
 
149
+ def restore_vouches_pages(restore: object) -> bool:
150
+ """No restore, a worker's own recovery, or an export whose host named its page recorder: every earlier
151
+ life of the session recorded its pages."""
152
+ if not isinstance(restore, dict):
153
+ return True
154
+ return restore.get("recovered") is not None or isinstance(restore.get("recorder"), str)
155
+
156
+
149
157
  class ExportFile(NamedTuple):
150
- """A session export on this host's disk and the sha256 the platform recorded for it."""
158
+ """A session export on this host's disk, the sha256 the platform recorded for it, and the page
159
+ recorder the host that took it named."""
151
160
 
152
161
  path: Path
153
162
  sha256: str
163
+ recorder: object = None
154
164
 
155
165
  def for_worker(self) -> dict[str, str]:
156
- return {"path": str(self.path), "sha256": self.sha256}
166
+ named = {"recorder": self.recorder} if isinstance(self.recorder, str) else {}
167
+ return {"path": str(self.path), "sha256": self.sha256, **named}
157
168
 
158
169
  def checkpoint(self, engine: type[WorldDatabase], runtime: type[WorldRuntime]) -> SessionExport:
159
170
  return SessionExport.verified(self, engine)
@@ -326,7 +326,7 @@ fields and the reward signature against the verifiers version you install.
326
326
 
327
327
  ```bash
328
328
  gateway benchmarks init ./crm-bench # custom contract: example entity, three tools, one verifier, one task
329
- gateway benchmarks init ./slack-bench --connector slack # a shipped template: the vendor's entities, routes and tools
329
+ gateway benchmarks init ./slack-bench --connector slack # an official template (needs a login): the vendor's entities, routes and tools
330
330
  gateway benchmarks init ./x --task onboard --prompt "Create an account for Acme." --model openai/gpt-5-mini -k 3
331
331
  ```
332
332
 
@@ -174,7 +174,7 @@ No `upsert`: `get`, then `insert` or `update`. Read-only SQL: `gateway_env.db.on
174
174
 
175
175
  ### 7. Ship the template; register platform integration only when in scope
176
176
 
177
- - [ ] SDK-shipped: commit authored files under `gatewaysdk/sdk/src/gatewaysdk/environment/schema/connectors/<slug>/`; `list_templates()` and `test_schema_scaffold.py` cover the slug and preserve its authored dependencies/provenance during initialization. Schema-only templates declare an empty tools map and have no operation handlers.
177
+ - [ ] Official: an official editor pushes the template tree into the official organization (`gateway worlds create <slug> --from <dir>` with `GATEWAY_TOKEN` + `GATEWAY_PROJECT_ID`, then publish it), and every reader serves it from that world's head (`gateway worlds schema templates`, `schema init --connector <slug>`, `worlds create --from <slug>`). Authored trees still sit under `gatewaysdk/sdk/src/gatewaysdk/environment/schema/connectors/<slug>/` until O4 moves them out; `tests/test_official_template_world.py` pins that a world built from the files is byte-identical to the old directory init. Schema-only templates declare an empty tools map and have no operation handlers.
178
178
  - [ ] Platform integration, if separately in scope: map an existing source kind in `schemaWorldTemplates.ts` so "Build from connector" offers it. Do not register a native provider or invent a source kind for an SDK-only schema milestone.
179
179
  - [ ] Treat `connectionMode` as the primary authentication path, not the only setup path. A managed connector may retain `remoteMcpPreset` as a fallback; render that action from the preset's presence. For native source connectors such as Slack, the source-backed Link action is the managed authentication path because native-provider dispatch intentionally precedes Merge.
180
180
  - [ ] User-added templates can use `--connector custom` and SDK publication. Generic schema upload and shared/project registry infrastructure remain unimplemented.
@@ -265,7 +265,6 @@ Python SDK as package data so an agent in any repository can install it.
265
265
  Revalidated 2026-09-07 while integrating `ba89fe16` with `015d6b25`:
266
266
  `schema/scaffold.py`, `schema/platform.py`, `tests/environment/test_schema_scaffold.py`,
267
267
  `worldSchemaPublication.ts`, `worldSchemaRuntime.ts`, `environmentBundleTester.ts`,
268
- `environmentBuildWorkbench.ts`, `environmentSchemaSandbox.ts`,
269
268
  `NativeSlackService.ts`, and `deploy/benchmark-runner/engines/{session_server,schema_session}.py`.
270
269
  Full source paths and runtime boundaries are listed in [world-schema.md](../../../documentation/features/world-schema.md).
271
270
  These source checks do not imply live-provider validation or executed fidelity scores.
@@ -140,6 +140,7 @@ gateway worlds data import <WORLD> rows.json --redact apply # run the w
140
140
  gateway worlds data import <slug> export.jsonl -m "Q3 tenants" # platform: chunked upload, new version
141
141
  gateway worlds data import <slug> export.jsonl --per-chunk --publish later --report refusals.jsonl
142
142
  gateway worlds data import <slug> export.jsonl --resume # pick a dead upload back up
143
+ gateway worlds data import <slug> rows.jsonl --state q4-messy # into a world state only: no version, main untouched
143
144
  gateway worlds data check <WORLD> rows.json --report refusals.jsonl # the dry run on its own; exit 2 on refusals
144
145
  ```
145
146
 
@@ -162,6 +163,7 @@ state}` and `gateway worlds data status <batchId> [--report <file>]` reads it la
162
163
  published, 2 refused (the report is written when `--report` is given: JSONL of refusal
163
164
  records, at most 10,000 then `{"truncated": true, "total": N}`), 1 error.
164
165
 
166
+ `--state <name>` lands the batch in that world state (`worlds state create` first): `published`, no `versionId`, `worldState` in the view; `worlds state show|pull` reads it on any version (`--ref`); `--rebase` rebuilds a state its rows cannot follow on main's data; `--publish later` is refused.
165
167
  A manifest at `.gateway/imports/<batchId>.json` records every chunk's digest as it lands;
166
168
  `--resume` reopens the newest incomplete batch for that slug and files and uploads only the
167
169
  chunks the platform does not already hold. `--publish later` applies without a version;
@@ -178,7 +180,7 @@ refused row is a tool error naming the field, and nothing is written.
178
180
  ### 2a. Pull a connector's data through an active connection
179
181
 
180
182
  For a schema world created from a connector template (`worlds create --from-connection`, or
181
- the Connectors page), the provider is the source — no rows file:
183
+ the WorldHub page), the provider is the source — no rows file:
182
184
 
183
185
  ```bash
184
186
  gateway worlds data pull <slug> --connection google_drive # connector slug when the project has one connection for it
@@ -194,7 +196,7 @@ contract like `data import`. `replace` (default) rebuilds the mapped entities fr
194
196
  `pulled|unchanged <slug> from <connector> connection <id> (<mode>, <n> calls[, k unmatched (tool…)])
195
197
  <hash> [entity=count …]`; `changed: false` in `--json` when the pull reproduced the tip (no new
196
198
  version). The key reaches the connections shared with its project; a personal connection serves
197
- its owner alone (the Connectors page, or the MCP tool as that user) and is refused here. An
199
+ its owner alone (the WorldHub page, or the MCP tool as that user) and is refused here. An
198
200
  inactive connection, a world without a contract, or a template that does not read the connector
199
201
  is a refusal (exit 1) and nothing is written; a provider failure is reported as
200
202
  `provider tool failed (HTTP n)` with no provider body.
@@ -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, 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.
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 an official 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
@@ -55,7 +55,7 @@ first, then `guide({ topic: "connectors" })` for the connector loop and `guide({
55
55
  `schema init` writes: `schema/world.json` (the contract), `gateway-env.toml` with `[schema]`,
56
56
  and on top of it, optional, `tools/handlers.py` (tools, the `list_messages` style) and
57
57
  `connector.toml` + `api/handlers.py` (the vendor's HTTP routes) with a `[ui]` section for the
58
- page over those routes (every shipped template declares one; `schema compile` generates
58
+ page over those routes (every official template declares one; `schema compile` generates
59
59
  `ui/static` from the contract, `gateway worlds schema ui init ./x` declares it for a world of
60
60
  your own, `[ui] generated = false` keeps a hand-written page — the UI-twin templates such as
61
61
  notion, servicenow and zendesk ship a built twin under `ui/static` that way). It is stored as it is, and
@@ -75,7 +75,7 @@ browser; the tools are always there). Everything else is derived or retired (own
75
75
 
76
76
  | You have | Path | First command |
77
77
  | --- | --- | --- |
78
- | A vendor the SDK ships a template for (`gateway worlds schema templates`: github, slack, salesforce, jira, linear, workday, netsuite, microsoft-teams, google-drive, google-calendar, jamf, kandji, apple-business-manager, constella) | shipped template | `gateway worlds schema init ./x --connector github` |
78
+ | A vendor with an official template (`gateway worlds schema templates`: github, slack, salesforce, jira, linear, workday, netsuite, microsoft-teams, google-drive, google-calendar, jamf, kandji, apple-business-manager, …; fetched from the platform, so log in first) | official template | `gateway worlds schema init ./x --connector github` |
79
79
  | A connector someone in your org (or any org) already published | workspace connector | `gateway worlds connector list --hub` then `schema init ./x --connector workspace:<slug>` |
80
80
  | A Swagger 2.0 / OpenAPI 3.x document (JSON or YAML; a file, `drive:<path>` or a URL) | OpenAPI import | `gateway worlds schema init ./x --from-openapi petstore.yaml` — entities + routes from the spec, plan printed first; §2 "From an OpenAPI spec" |
81
81
  | A vendor API with a dev key and no template | vendor API capture | `schema init ./x --connector custom`, write `connector.toml`, capture, ingest (`documentation/features/connector-worlds.md`) |
@@ -231,7 +231,7 @@ makes the world under a PAT session; under an API key it returns the initialized
231
231
  For a world you provision rather than iterate on (a tenant's Slack, one per customer):
232
232
 
233
233
  ```bash
234
- gateway worlds create acme-slack --from slack --rows rows.json --name "Acme Slack" # shipped template + their rows
234
+ gateway worlds create acme-slack --from slack --rows rows.json --name "Acme Slack" # official template + their rows
235
235
  gateway worlds create acme-crm --from workspace:acme-crm --overlay ./overlay --json # hub connector + your edits
236
236
  gateway worlds create acme-custom --from ./x # a directory, any kind
237
237
  gateway worlds create acme-drive --from-connection google_drive # the connector's template filled from an active connection (id or slug); `--from <template>` picks the template
@@ -246,7 +246,7 @@ version, attributed to the key (`apikey:<id>`), owned by nobody. 409 when the sl
246
246
  project. `--layout api-bundle` (body `layout`) packages the tree as its api bundle instead —
247
247
  deprecated, and the answer's `deprecations` says so. A legacy tools bundle, a Harbor tree or a
248
248
  verifiers package is a 400 `world_kind_retired`. `--from-connection` binds an active connection
249
- (Connectors page) shared with the key's project — a personal one serves its owner alone (MCP as
249
+ (WorldHub page) shared with the key's project — a personal one serves its owner alone (MCP as
250
250
  that user); an inactive connection or a template that does not read the connector is refused,
251
251
  nothing created. Refresh later with `gateway worlds data pull <slug> --connection …`.
252
252
 
@@ -256,7 +256,7 @@ is the same request and answer; a PAT session reaches its own personal connectio
256
256
 
257
257
  ### Migrate a stored world: `worlds migrate`
258
258
 
259
- The platform's connector worlds (the ones the Connectors page lists — containers created from
259
+ The platform's connector worlds (the ones the WorldHub page lists — containers created from
260
260
  a template) that were stored as api bundles become schema trees again:
261
261
 
262
262
  ```bash
@@ -321,7 +321,7 @@ gateway worlds session state <SESSION_ID> # every entity's row
321
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
322
322
  gateway worlds session grade <SESSION_ID> [--timeout S] # {reward, rewards, raw}; exploratory → {reward: null, reason: "no grader"}
323
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|webhook] [--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)
324
+ gateway worlds requests x [--session <SESSION_ID>] [--via api|ui|tool|webhook|page] [--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
  ```
@@ -16,12 +16,17 @@ 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
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) |
21
+ | `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 |
22
+ | `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 |
23
+ | `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 |
24
+ | `worlds state delete <world> <name>` | `delete_world_state({ slug, name })` (`DELETE …/states/{name}`): `{ state, deleted: true, runCount }` |
25
+ | `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
26
  | `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
27
  | `worlds session seed` | `seed_world_session` |
23
28
  | `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 |
29
+ | `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
30
  | `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
31
  | `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
32
  | `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 +53,31 @@ Reference for `worlds-getting-started`: every CLI step and its MCP twin, then ho
48
53
  | `worlds skill <name>` / `worlds connector skill` | `get_connector_authoring_skill`, `guide` |
49
54
  | `worlds connector capture --remote` / poll + download | `start_connector_capture`, `get_connector_capture` (platform agent only) |
50
55
 
56
+ ## Agents that build worlds (the agent SDK)
57
+
58
+ An agent (instructions, a model, the tool servers it may use: `sandbox`, `drive`, `web`, `docs`) runs on the
59
+ platform as your project key, in a thread per input; it builds worlds through the same CLI (`run_gateway_cli`) and
60
+ asks you through `ask_user`. Create it once and edit it live: every edit is a tracked version, live unless
61
+ `--no-deploy`, and a run keeps the version it was sent on. A key, not a personal token, drives all of these.
62
+
63
+ | CLI | MCP |
64
+ | --- | --- |
65
+ | `agents create <name> --instructions <text> [--model] [--effort] [--max-turns] [--tool <server[:tool,…]>]…` | `create_agent({ name, instructions, model?, effort?, maxTurns?, tools? })` |
66
+ | `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? })` |
67
+ | `agents versions <name>` | `list_agent_versions({ name })` |
68
+ | `agents rollback <name> <versionId> [--force]` | `rollback_agent({ name, versionId, from?, force? })` |
69
+ | `agents push <file.mjs[#export]\|file.py[:attr]\|file.json> [--deploy]` | `push_agent_definition({ definition, deploy? })` |
70
+ | `agents deploy <name> <versionId> [--force]` | `deploy_agent_definition({ agent, versionId, force? })` |
71
+ | `threads create --agent <name> [--autonomy provisionWorlds=true …]` | `create_agent_thread({ agent, title?, autonomy? })` |
72
+ | `threads send <thread> <input> [--watch]`, `agents run <name> <input>` | `send_agent_message({ threadId, input, version? })` |
73
+ | `threads watch <thread> [--run] [--after <cursor>]` (exit 4: it waits for a person) | `get_agent_run({ threadId, runId, waitSeconds? })` |
74
+ | `threads resolve <thread> --action <id> --answer <text>` | `answer_agent_run({ threadId, runId, actionId, answer })` |
75
+ | `threads cancel <thread> [--run]` | `cancel_agent_run({ threadId, runId })` |
76
+
77
+ SDKs: `@withgateway/sdk` (`Gateway`, `tools`; `gateway.agents.create(...)` returns a live `Agent` with `update`,
78
+ `tools.attach|detach`, `versions`, `rollback`, `run`; `defineAgent` + `agents.push` for CI) and `gatewaysdk.agents`
79
+ (the same in snake_case).
80
+
51
81
  ## Size and time limits (one source: `packages/shared/src/world/limits.ts`)
52
82
 
53
83
  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"`,
@@ -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")