@withgateway/sdk 0.4.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 (157) 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 +5655 -1890
  10. package/dist/cli.js.map +1 -1
  11. package/dist/cli.mjs +5769 -2005
  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 +418 -120
  16. package/dist/files/index.js.map +1 -1
  17. package/dist/files/index.mjs +418 -120
  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-DUHmS74p.d.ts → index-DIN14Lhg.d.ts} +27 -4
  24. package/dist/{index-mJhG3vZU.d.mts → index-DuB-eQ0Z.d.mts} +27 -4
  25. package/dist/index.d.mts +7 -4
  26. package/dist/index.d.ts +7 -4
  27. package/dist/index.js +2862 -438
  28. package/dist/index.js.map +1 -1
  29. package/dist/index.mjs +2820 -431
  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/replay/index.d.mts +1 -1
  34. package/dist/replay/index.d.ts +1 -1
  35. package/dist/replay/index.js.map +1 -1
  36. package/dist/replay/index.mjs.map +1 -1
  37. package/dist/traces/index.d.mts +3 -1
  38. package/dist/traces/index.d.ts +3 -1
  39. package/dist/traces/index.js +418 -120
  40. package/dist/traces/index.js.map +1 -1
  41. package/dist/traces/index.mjs +418 -120
  42. package/dist/traces/index.mjs.map +1 -1
  43. package/dist/tracing/index.d.mts +3 -2
  44. package/dist/tracing/index.d.ts +3 -2
  45. package/dist/tracing/index.js +257 -16
  46. package/dist/tracing/index.js.map +1 -1
  47. package/dist/tracing/index.mjs +257 -16
  48. package/dist/tracing/index.mjs.map +1 -1
  49. package/dist/transport-CpRe7zgd.d.mts +123 -0
  50. package/dist/transport-CpRe7zgd.d.ts +123 -0
  51. package/dist/worlds/index.d.mts +2086 -1749
  52. package/dist/worlds/index.d.ts +2086 -1749
  53. package/dist/worlds/index.js +1471 -269
  54. package/dist/worlds/index.js.map +1 -1
  55. package/dist/worlds/index.mjs +1466 -265
  56. package/dist/worlds/index.mjs.map +1 -1
  57. package/package.json +6 -1
  58. package/runtime/gatewaysdk/environment/_bundle.py +4 -6
  59. package/runtime/gatewaysdk/environment/_world.py +24 -1
  60. package/runtime/gatewaysdk/environment/bundle_manifest.py +243 -0
  61. package/runtime/gatewaysdk/environment/runtime.py +45 -2
  62. package/runtime/gatewaysdk/environment/schema/__main__.py +2 -2
  63. package/runtime/gatewaysdk/environment/schema/_slack_fidelity.py +8 -23
  64. package/runtime/gatewaysdk/environment/schema/api.py +27 -7
  65. package/runtime/gatewaysdk/environment/schema/assertions.py +7 -1
  66. package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +2 -0
  67. package/runtime/gatewaysdk/environment/schema/call_capture.py +13 -1
  68. package/runtime/gatewaysdk/environment/schema/call_log.py +66 -0
  69. package/runtime/gatewaysdk/environment/schema/call_redaction.py +6 -0
  70. package/runtime/gatewaysdk/environment/schema/compiler.py +4 -1
  71. package/runtime/gatewaysdk/environment/schema/conform.py +32 -8
  72. package/runtime/gatewaysdk/environment/schema/connector.py +5 -0
  73. package/runtime/gatewaysdk/environment/schema/connectors/custom/handlers.py +2 -1
  74. package/runtime/gatewaysdk/environment/schema/connectors/github/api/handlers.py +217 -58
  75. package/runtime/gatewaysdk/environment/schema/connectors/github/connector.toml +9 -19
  76. package/runtime/gatewaysdk/environment/schema/connectors/github/scenarios/default/seed/github_webhooks.json +10 -2
  77. package/runtime/gatewaysdk/environment/schema/connectors/github/tests/webhooks.json +47 -0
  78. package/runtime/gatewaysdk/environment/schema/connectors/github/world.json +21 -0
  79. package/runtime/gatewaysdk/environment/schema/connectors/jamf/api/handlers.py +185 -18
  80. package/runtime/gatewaysdk/environment/schema/connectors/jamf/connector.toml +29 -14
  81. package/runtime/gatewaysdk/environment/schema/connectors/jamf/provenance.json +43 -12
  82. package/runtime/gatewaysdk/environment/schema/connectors/jamf/scenarios/default/seed/jamf_webhooks.json +2 -2
  83. package/runtime/gatewaysdk/environment/schema/connectors/jamf/scope.toml +4 -17
  84. package/runtime/gatewaysdk/environment/schema/connectors/jamf/tests/webhooks.json +107 -0
  85. package/runtime/gatewaysdk/environment/schema/connectors/jamf/vendor-openapi.json +1 -1
  86. package/runtime/gatewaysdk/environment/schema/connectors/linear/api/handlers.py +85 -1
  87. package/runtime/gatewaysdk/environment/schema/connectors/linear/connector.toml +19 -31
  88. package/runtime/gatewaysdk/environment/schema/connectors/linear/provenance.json +18 -8
  89. package/runtime/gatewaysdk/environment/schema/connectors/linear/scenarios/default/seed/webhooks.json +19 -3
  90. package/runtime/gatewaysdk/environment/schema/connectors/linear/tests/test_webhooks.py +71 -0
  91. package/runtime/gatewaysdk/environment/schema/database/base.py +2 -2
  92. package/runtime/gatewaysdk/environment/schema/database/guard.py +2 -1
  93. package/runtime/gatewaysdk/environment/schema/handler_errors.py +27 -1
  94. package/runtime/gatewaysdk/environment/schema/host.py +74 -11
  95. package/runtime/gatewaysdk/environment/schema/host_browser.py +48 -0
  96. package/runtime/gatewaysdk/environment/schema/host_control.py +33 -2
  97. package/runtime/gatewaysdk/environment/schema/host_handoff.py +4 -1
  98. package/runtime/gatewaysdk/environment/schema/host_requests.py +14 -0
  99. package/runtime/gatewaysdk/environment/schema/host_session.py +13 -2
  100. package/runtime/gatewaysdk/environment/schema/host_surfaces.py +6 -0
  101. package/runtime/gatewaysdk/environment/schema/host_versions.py +96 -19
  102. package/runtime/gatewaysdk/environment/schema/journal.py +10 -4
  103. package/runtime/gatewaysdk/environment/schema/local.py +33 -7
  104. package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +20 -5
  105. package/runtime/gatewaysdk/environment/schema/page_checks.py +123 -0
  106. package/runtime/gatewaysdk/environment/schema/platform.py +33 -480
  107. package/runtime/gatewaysdk/environment/schema/platform_templates.py +332 -0
  108. package/runtime/gatewaysdk/environment/schema/request_ledger.py +4 -1
  109. package/runtime/gatewaysdk/environment/schema/run_parameters.py +25 -0
  110. package/runtime/gatewaysdk/environment/schema/runtime.py +49 -4
  111. package/runtime/gatewaysdk/environment/schema/scaffold.py +369 -218
  112. package/runtime/gatewaysdk/environment/schema/session_files.py +13 -2
  113. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +1 -1
  114. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/CONNECTORS.md +3 -3
  115. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +20 -24
  116. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +11 -11
  117. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +9 -9
  118. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +45 -12
  119. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +40 -9
  120. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +17 -2
  121. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/new-world-sandbox.md +1 -1
  122. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/ui-map.md +3 -2
  123. package/runtime/gatewaysdk/environment/schema/slack.py +55 -10
  124. package/runtime/gatewaysdk/environment/schema/snapshot.py +30 -4
  125. package/runtime/gatewaysdk/environment/schema/tasks.py +25 -2
  126. package/runtime/gatewaysdk/environment/schema/template_record.py +131 -0
  127. package/runtime/gatewaysdk/environment/schema/tools_world.py +26 -5
  128. package/runtime/gatewaysdk/environment/schema/ui.py +54 -33
  129. package/runtime/gatewaysdk/environment/schema/ui_interactions.py +419 -0
  130. package/runtime/gatewaysdk/environment/schema/ui_recorder.js +895 -0
  131. package/runtime/gatewaysdk/environment/schema/ui_replay.py +366 -0
  132. package/runtime/gatewaysdk/environment/schema/ui_replay_record.LICENSE +25 -0
  133. package/runtime/gatewaysdk/environment/schema/ui_replay_record.js +109 -0
  134. package/runtime/gatewaysdk/environment/schema/validation.py +10 -1
  135. package/runtime/gatewaysdk/environment/schema/verbs.py +6 -0
  136. package/runtime/gatewaysdk/environment/schema/webhooks.py +687 -0
  137. package/runtime/gatewaysdk/environment/schema/worker.py +5 -1
  138. package/runtime/gatewaysdk/environment/schema/workers.py +8 -1
  139. package/runtime/gatewaysdk/environment/schema/world_host.py +64 -18
  140. package/runtime/gatewaysdk/environment/schema/world_tests.py +74 -0
  141. package/runtime/gatewaysdk/environment/secret_values.py +1 -1
  142. package/runtime/gatewaysdk/environment/world.py +34 -43
  143. package/runtime/gatewaysdk/environment/world_session_contract.py +7 -34
  144. package/skills/benchmarks-getting-started/SKILL.md +1 -1
  145. package/skills/connector-schema-authoring/CONNECTORS.md +3 -3
  146. package/skills/connector-schema-authoring/SKILL.md +20 -24
  147. package/skills/connector-schema-authoring/connector-worlds.md +155 -13
  148. package/skills/connector-schema-authoring/world-schema.md +36 -29
  149. package/skills/world-data-ingestion/SKILL.md +11 -11
  150. package/skills/worlds-getting-started/SKILL.md +9 -9
  151. package/skills/worlds-getting-started/references/cli-mcp-map.md +45 -12
  152. package/skills/worlds-getting-started/references/gotchas.md +40 -9
  153. package/skills/worlds-getting-started/references/journal-checks.md +17 -2
  154. package/skills/worlds-getting-started/references/new-world-sandbox.md +1 -1
  155. package/skills/worlds-getting-started/references/ui-map.md +3 -2
  156. package/dist/media-BIApiPzS.d.mts +0 -102
  157. package/dist/media-BIApiPzS.d.ts +0 -102
@@ -23,12 +23,12 @@ session](#raw-ingestion-schema-gated-sql), and connector
23
23
  | SDK `gwenv.init_from_path` | Checks artifacts and materializes isolated schema-aware worlds. |
24
24
  | Direct benchmark `mock-tools` runner | Reuses SDK materialization and `World` enforcement. |
25
25
  | SDK/public and platform publication, including READY/dedup/fork/ref promotion | Verifies the stored SHA-256, generated artifacts and exact lock through the trusted compiler/materializer using actual archive bytes; uploaded Python is parsed, not imported during publication. |
26
- | Worker builder, bundle tester, and workbench | Materialize through the shared schema store; tester/workbench execution uses an isolated sandbox with an installed trusted runtime. No legacy seed-SQL fallback. |
26
+ | Worker Environment Actions (`BundleTester`, `BundleCompleteness`) | Never run a schema world: Environment Actions skip every check for it, and the tester and the completeness gate refuse a schema tree (`WORLD_SCHEMA_UNSUPPORTED`). The environment builder and its E2B workbench were deleted (2026-10-13). |
27
27
  | Hosted `mock-tools` sessions | Use the shared `World` in a child process for validated calls, reset and grading; dependency worlds are unsupported. |
28
- | Platform agent (`create_custom_world`, `ingest_records_to_world`, `ingest_to_world`) | Authors and fills arbitrary schema worlds through the trusted bridge (`platform.py compile` / `apply-batch`) and publishes each result as one immutable READY version via `worldPublicationService`; see [agent.md](./agent.md#platform-actions-worlds-tasks-rollouts-connectors-ingestion-self-schedules). |
28
+ | Platform agent (`run_gateway_cli`) | Edits schema worlds in its sandbox with the `gateway worlds` CLI and publishes as the user through its doors (`create`, `push`, `data import <slug>`), checked like any CLI push; see [agent.md](./agent.md#platform-actions-worlds-tasks-rollouts-connectors-ingestion-self-schedules). |
29
29
  | SDK Harbor worlds and Harbor/API/verifiers engines | Retain their separate unsupported-mode guards; do not combine their bundle markers with schema mode. |
30
30
 
31
- Environment Actions remain advisory. See [Environment Builder](./environment-builder.md) and
31
+ Environment Actions remain advisory. See [Environment Actions](../../system-architecture/worlds/environment-actions.md) and
32
32
  [Benchmark Container Hub](./benchmark-containers.md).
33
33
 
34
34
  ## Bundle layout and authoring
@@ -280,7 +280,8 @@ facade over it admitting exactly `get, list, list_where, insert, update, delete,
280
280
  lineage, counts` — the one list in `environment/schema/store_contract.py` (`STORE_METHODS`, read off
281
281
  `WorldDatabase` so it cannot drift). `gateway worlds schema check` refuses any other `store.<name>`
282
282
  statically at file:line with that list; a hosted call into a handler whose own code raises
283
- `AttributeError`/`TypeError`/`NameError` answers 400 `{error: "handler", detail, handler}`, any other
283
+ `AttributeError`/`TypeError`/`NameError` answers 400 `{error: "handler", detail, handler}`,
284
+ `raise Refusal(status, body)` (from `gateway_env`, a 4xx) answers that status and body, any other
284
285
  handler failure 500 `{error: "engine", detail, handler}` — never a bare exception string. There is
285
286
  no `upsert`: `get`, then `insert` or `update`.
286
287
 
@@ -402,12 +403,13 @@ committed and a rejected session.
402
403
 
403
404
  ## Connector templates and `init`
404
405
 
405
- The SDK ships authored `gateway-world/1` contracts under
406
- `gatewaysdk/sdk/src/gatewaysdk/environment/schema/connectors/`: `slack`, `github`,
407
- `linear`, `jira`, `google-drive`, `google-calendar`, `salesforce`,
408
- `microsoft-teams`, and a one-entity `custom` template. They declare entities,
409
- keys, and relationships. Tools are optional; templates contain authored inputs,
410
- and `init` produces generated artifacts. The
406
+ Vendor templates are authored `gateway-world/1` contracts kept under
407
+ `gatewaysdk/sdk/src/gatewaysdk/environment/schema/connectors/` until O4, and served
408
+ from the official organization: each one is an ordinary schema world built from its
409
+ template (`init_official_world`), which keeps every file the template brought and
410
+ records `schema/template.json` (`connector`, `digest`: the template's
411
+ `template_digest`, the digest every world made from it pins). Only the one-entity
412
+ `custom` template ships in code. The
411
413
  [Microsoft Teams guide](./microsoft-teams-schema.md) documents its schema-only
412
414
  Graph v1.0 base, synthetic sample, and provisional subset assessment.
413
415
 
@@ -417,17 +419,23 @@ gateway worlds schema init ./teams-world --connector microsoft-teams
417
419
  gateway worlds schema init ./acme-crm --connector custom --name acme-crm
418
420
  ```
419
421
 
420
- `init` (also `init_bundle(path, connector=..., name=...)`) writes the manifest,
421
- the authored template's schema definitions and metadata under `schema/`, shared
422
- `schema/base.json`, `tools/handlers.py`, and a starter verifier into a new or empty
423
- directory. Supporting files must be flat regular `.json`, `.md`, or `.toml`
424
- files; symlinks, generated filenames, and collisions with shared `base.json`
425
- reject. Real `__pycache__` directories created by package installation are ignored;
426
- `api/` (the connection's `api/handlers.py`) and `scenarios/` copy verbatim to the
427
- world root, exactly as `init_bundle_from_files` treats a workspace connector;
428
- other directories reject. Supporting bytes are preserved except Slack's
429
- `capabilities.json`, whose defaults expand as described below. Descriptive
430
- metadata is not a compiler dependency or lock input; referenced schemas are.
422
+ `init --connector <slug>` reads the official world's head and copies it under the
423
+ new name (`init_bundle_from_world`, the runtime's `init-world-files`): the package id
424
+ and the manifest's name change, the contract is compiled again and its data follows
425
+ it; nothing is rebuilt from the template. `worlds create <slug> --from <template>` is
426
+ the same copy on the platform, and the new world's first version records
427
+ `forkedFromVersionId` = the official version. Building a world from template files
428
+ (`init_bundle_from_files`, a workspace connector or an official world's own build)
429
+ writes the manifest, the template's schema definitions and metadata under `schema/`,
430
+ shared `schema/base.json`, `tools/handlers.py`, and a starter verifier into a new or
431
+ empty directory. Supporting files must be flat regular `.json`, `.md`, or `.toml`
432
+ files; symlinks and collisions with shared `base.json` reject, and generated names
433
+ (`README.md`, `lock.json`, …) are not laid out. `api/`, `scenarios/`, `tests/` and
434
+ `ui/` copy verbatim to the world root, as do the carried `verifiers/`, `openapi/`,
435
+ `readers/`, `evidence/`, `reports/` and `tasks.json`; other directories reject.
436
+ Supporting bytes are preserved except Slack's `capabilities.json`, whose defaults
437
+ expand as described below. Descriptive metadata is not a compiler dependency or lock
438
+ input; referenced schemas are.
431
439
 
432
440
  Initialization compiles the contract and writes a zero-mutation
433
441
  `data/initial.json`, so the world starts empty and is filled by ingestion or
@@ -525,7 +533,7 @@ world back against the document it came from.
525
533
  **Build from connector** for Slack creates a durable populated world job in
526
534
  Gateway. Other registered source kinds show their CLI twin under **Use the CLI instead**:
527
535
  `gateway worlds schema init`, `schema check`, then `gateway worlds create <slug> --from <dir>`.
528
- A blank (custom) contract starts from the Connectors page's **New connector** form. SDK template
536
+ A blank (custom) contract starts from the WorldHub page's **New connector** form. SDK template
529
537
  availability does not register a platform source kind or supply a live mapper;
530
538
  Teams remains schema-only. The SDK checks the contract before push, and the
531
539
  shared publication validator checks actual stored bundle bytes before the world
@@ -575,7 +583,7 @@ remain exposed.
575
583
 
576
584
  ### Populated Slack worlds in Gateway
577
585
 
578
- The Connectors page offers synthetic data or selected public/private channels
586
+ The WorldHub page offers synthetic data or selected public/private channels
579
587
  from the caller's native Slack connection. Synthetic worlds include fictional
580
588
  collaboration data and a graded scenario. Live jobs create a dedicated import,
581
589
  read projected evidence, verify each artifact, map it through the shared store,
@@ -616,13 +624,13 @@ as a credential-free subprocess (`GATEWAY_SCHEMA_PYTHON`, `GATEWAY_SCHEMA_RUNTIM
616
624
  | Command | Used by | Effect |
617
625
  | ------------------------------ | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
618
626
  | `validate`, `validate-archive` | publication | Verify SHA-256, regenerated artifacts and exact lock of an existing tree/archive. |
619
- | `init-template` | `create_connector_world`, `create_custom_world --template` | Scaffold a connector template into a tree. |
627
+ | `init-template` | `create_connector_world`, `worlds create --from TEMPLATE` | Scaffold a connector template into a tree. |
620
628
  | `init-openapi` | `worlds schema init --from-openapi` (both CLIs; the TypeScript CLI through `POST /api/public/worlds/runtime` only when no runtime is here) | `{source, document (base64), destination, plan_only?, include?, exclude?, name?}` → the import plan and, when written, the compiled tree as `files[]` (at most 2000). The bridge never opens a caller-named path or URL; the CLI stages the bytes. A YAML document needs PyYAML in the Python that reads it, and is refused naming the fix without it. |
621
- | `compile` | `create_custom_world`, `ingest_to_world` on schema worlds | Compile an authored tree (`compileWorldFiles`): returns the full entry map with generated artifacts + lock, the schema report and which files were added/retargeted. |
622
- | `apply-batch` | `ingest_records_to_world` | Apply `insert\|update\|delete` mutations as one batch (`applyWorldBatch`): validated row by row against the compiled schema, appended as `data/batches/<batchId>.json` with `source` provenance; replaying the same `batchId` is a no-op. |
629
+ | `compile` | `POST /api/public/worlds/runtime` | Compile an authored tree (`compileWorldFiles`): returns the full entry map with generated artifacts + lock, the schema report and which files were added/retargeted. |
630
+ | `import-data` | `importWorldData`: `worlds create --rows`, `import_world_data` on a world without a contract, `gateway worlds data import <dir>` (the CLI's bundled runtime, else `POST /api/public/worlds/runtime`) | Lay `{entity: [row]}` rows into the tree through the world's own gate (`data.import_rows`, `append` or `replace`: the contract of a schema world, `db/schema.sql` of a mock-tools one), rebuild a schema world's snapshot and return the updated tree; a refused row writes nothing. |
623
631
  | `build-slack`, `refresh-slack` | connector worlds | Slack capture → batches (durable job). |
624
632
 
625
- Every agent write therefore passes through the schema: `ingest_to_world` recompiles a schema world before it becomes head, and `ingest_records_to_world` refuses invalid rows with the field path instead of publishing a partial batch.
633
+ Every agent write still passes through the schema, now through the CLI's own doors (`run_gateway_cli`, 2026-10-10): `create` and `push` land as versions checked like any CLI push, and `data import <slug>` validates every row through the contract in a data batch, with refusals naming the field.
626
634
 
627
635
  ## Compilation, locks, and compatibility
628
636
 
@@ -722,14 +730,13 @@ Revalidated during the merge of `ba89fe16` and `015d6b25` on 2026-09-07:
722
730
  - `deploy/benchmark-runner/engines/{mock_tools_runner,session_server,api_runner,harbor_runner,verifiers_runner}.py`
723
731
  - `gateway/packages/shared/src/domain/worldSchema.ts`
724
732
  - `gateway/web/src/features/benchmark-hub/server/{worldSchemaPublication,containerVersionService}.ts`
725
- - `gateway/worker/src/features/environmentBuild/{environmentBundleCompleteness,environmentBundleTester,environmentBuildWorkbench}.ts`
733
+ - `gateway/worker/src/features/environmentOperator/{environmentBundleCompleteness,environmentBundleTester}.ts` (moved from `environmentBuild/` on 2026-10-13, when the builder and its workbench were deleted)
726
734
  - `samples/schema-worlds/`
727
735
  - `gateway/web/src/features/environment-files/{schemaWorldTemplates.ts,components/BuildSchemaWorldDialog.tsx}`
728
736
 
729
737
  Additional sources: `gateway/packages/shared/src/server/services/worldSchemaRuntime.ts`
730
738
  (template digest and trusted bridge), `gateway/web/src/features/environment-files/server/connectorWorldService.ts`
731
739
  (durable job), `gatewaysdk/sdk/src/gatewaysdk/environment/schema/{slack,_slack_fidelity,platform}.py`,
732
- `gateway/worker/src/features/environmentBuild/environmentSchemaSandbox.ts`,
733
740
  `gateway/packages/shared/src/server/services/NativeSlackService.ts`, and
734
741
  `deploy/benchmark-runner/engines/{session_server,schema_session}.py`.
735
742
 
@@ -109,7 +109,7 @@ gateway worlds data query <WORLD> users --where email=jo@acme.test --resolve #
109
109
  gateway worlds data sql <WORLD> 'SELECT id, name FROM users LIMIT 5' # read-only SQL, any engine
110
110
  ```
111
111
 
112
- `data sql` runs ONE read-only statement (joins, `GROUP BY`, counts) over a schema world's entity tables,
112
+ `data sql` runs ONE read-only statement (joins, `GROUP BY`, counts) over a schema world's entity tables (and `json_each` / `json_tree` over their JSON),
113
113
  whatever its database engine: a write, `ATTACH`, `PRAGMA` or a second statement is refused; at most 1000 rows
114
114
  (`--limit`). MCP twin: `sql_world_data({ slug, sql, limit? })`. A db/schema.sql world is a SQLite file: `sqlite3`.
115
115
 
@@ -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.
@@ -220,13 +222,11 @@ policy (`drop`, `hash` as `sha256:<hex>` of `<slug>:<value>`, `preserve` as a sa
220
222
  same-character-class hash for identifiers, `round`) unless `--no-redact`. Output is tagged
221
223
  JSONL; the summary `{"read", "rows", "unknownFields", "redacted"}` is on stderr.
222
224
 
223
- Platform agent (console): the same `import_world_data`, plus `sandboxPath` for a rows file
224
- already in the sandbox (any ROWS form above; `entity` for bare arrays/JSONL) instead of
225
- `rows` — build the file with code, then import; do not paste 4 MiB through `rows`.
226
- `run_gateway_cli({ command: "data show" | "data check" | "data import" | "data extract", args: ["/workspace/<world>", ...] })`
227
- is the local-directory form for a world you `load_world_to_sandbox`ed (same flags as above, no remote
228
- slugs); land the result with `ingest_to_world`. Capture pages are not rows: `get_connector_capture(downloadTo)` →
229
- `run_gateway_cli connector ingest` → `ingest_to_world`.
225
+ Platform agent (console): the same CLI, through `run_gateway_cli` in its sandbox. Build the rows
226
+ file with code, then `run_gateway_cli({ command: "data import", args: ["<slug>", "./rows.jsonl", "--dry-run"] })`
227
+ and again without `--dry-run`; a slug reaches the platform as the user, a `./dir` stays in the
228
+ sandbox. Capture pages are not rows: `get_connector_capture(downloadTo)` →
229
+ `run_gateway_cli connector ingest ./<world>` → `push ./<world>`.
230
230
 
231
231
  ### 2c. Turn tool calls into rows: pull, transform, ingest
232
232
 
@@ -362,7 +362,7 @@ operations route by name; `captureToolCalls(tools, sink)` records the calls). Py
362
362
  redact="off", dry_run=False)` and `ingest_tool_calls`; `capture_tool_calls`. Bridge:
363
363
  `ingest-calls {files, records, map?, redact?, dry_run?, mode?}` → the report + `projected`
364
364
  rows (+ `files` when the tree changed); transforms never run in the bridge. No MCP twin yet;
365
- the console agent has `run_gateway_cli data ingest` on a sandboxed directory.
365
+ the console agent runs the same `data ingest` through `run_gateway_cli`.
366
366
 
367
367
  ### 2d. Rows generated or downloaded inside a sandbox
368
368
 
@@ -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`) |
@@ -155,7 +155,7 @@ environment; land them with `env_commit({ containerId, changeReason })` (one ver
155
155
  Tool handlers (`tools/*.py`) reach the world's rows through `from gateway_env import store`. It has
156
156
  exactly these methods; `gateway worlds schema check .` refuses any other `store.<name>` at file:line
157
157
  with this list, and a hosted call into such a handler answers 400 `{error: "handler", detail, handler}`
158
- (an `AttributeError`/`TypeError`/`NameError` is the author's bug; anything else a handler raises is a
158
+ (an `AttributeError`/`TypeError`/`NameError` is the author's bug; `raise Refusal(404, body)` (imported from `gateway_env` at module top) answers that 4xx and body; anything else a handler raises is a
159
159
  500 `{error: "engine", detail, handler}`; never a bare exception string).
160
160
 
161
161
  - `get(entity: str, key: dict) -> dict | None` — one row by primary key, or `None`.
@@ -192,7 +192,7 @@ gateway worlds describe ./x # entities, keys, re
192
192
  gateway worlds data show ./x # kind + entity counts
193
193
  gateway worlds data query ./x users --where email=jo@acme.test --resolve # the rows you mean; plaintext into a hashed field
194
194
  gateway worlds data import ./x rows.json # rows file: {entity: [rows]} | JSONL | .csv/.tsv --entity (cells cast by the schema; --delimiter)
195
- gateway files fetch https://example.test/rows.csv --to imports/rows.csv --header "Authorization: Bearer {{secret:API_KEY}}" # the platform fetches; the secret never leaves it
195
+ gateway files fetch https://example.test/rows.csv --to imports/rows.csv --header "Authorization: Bearer {{secret:API_KEY}}" # the platform fetches; the secret goes only to origins it lists (gateway secret origins API_KEY https://example.test)
196
196
  gateway worlds connector capture ./x --op <name> --arg k=v # from the real vendor, redacted
197
197
  gateway worlds connector ingest ./x # captures -> data/initial.json; `--dry-run --report` checks only, nothing written
198
198
  gateway worlds data calls pull calls.jsonl --from traces --session <id> # an agent's real calls, raw; prints records per tool + result shapes
@@ -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] [--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,21 +16,27 @@ 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] [--operation <name>] [--status 200\|2xx\|4xx\|5xx] [--since <time>] [--until <time>] [--limit N] [--cursor <c>] [--json]` | `list_world_requests({ slug, sessionId?, versionId?, via?, operation?, status?, since?, until?, cursor?, limit? })` (`GET /api/public/worlds/{slug}/requests`): every request the world received, from every session, version and door (`via` api, ui, tool), newest first, a page of at most 200 with `nextCursor`; metadata only (method, path, query, status, rows, found, duration, each body's size and `truncated`). The world keeps them for its life under the project's retention setting, and reading records nothing in any session's ledger. `--since`/`--until` take an ISO 8601 date or time (no zone is UTC); a bad filter is exit 2 before any request. UI: the world's Requests view, the session page's activity feed |
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 |
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 |
27
33
  | `worlds session reopen <id>` | — (no MCP twin; `POST /api/public/world-sessions/{id}/reopen`: a closed session back under the same id, URLs and token from its last checkpoint, answering what `status` answers; 409 `session_not_closed` / `session_no_checkpoint` / `session_reopen_in_progress` / `session_version_unavailable`) |
28
34
  | `worlds session restart <id> [--version <pin>]` | `restart_world_session` (`POST /api/public/world-sessions/{id}/restart` `{version?}`: a running or closed session's world started over on its pin's current version, or `version`, which becomes the pin, under the same id, URLs and token; base data plus the task's seed. The route and the CLI answer what `status` answers plus `restart: {previousVersionId, versionId, pin, boundarySeq, boundaryAt}`; the MCP tool answers the `restart` block with `sessionId`. A request the old world received has an `at` before `boundaryAt`, and a grade reads only those after it. 409 `session_not_restartable` / `session_version_unavailable` / `session_reopen_in_progress` / `no_open_door`; 503 when the new world did not open) |
29
- | `worlds data calls pull` / `worlds data ingest [--transform\|--map]` | — (no MCP twin yet; `run_gateway_cli data ingest` on a sandboxed directory) |
35
+ | `worlds data calls pull` / `worlds data ingest [--transform\|--map]` | — (no MCP twin yet; the platform agent runs it through `run_gateway_cli`) |
30
36
  | `files upload <local>... [--to]` | `request_file_upload` + `confirm_file_upload` (`upload_file` for ≤25 MB inline) |
31
37
  | `files list [path]` / `files get <path>` / `files download\|cat <path>` | `list_files` / `get_file` (a presigned URL; the CLI streams it) |
32
38
  | `files delete` / `files move` / `files mkdir` | `delete_file` / `move_file` / `create_folder` |
33
- | `files fetch <url> --to <path> [--header "Name: value"]...` | `download_url_to_drive` (`POST /api/public/files/fetch`; the platform fetches, nothing passes through the caller's machine; a header value may name a project secret as `{{secret:NAME}}`, expanded on the platform and never returned; `--local` fetches from the caller's machine instead, without secrets) |
39
+ | `files fetch <url> --to <path> [--header "Name: value"]...` | `download_url_to_drive` (`POST /api/public/files/fetch`; the platform fetches, nothing passes through the caller's machine; a header value may name a project secret as `{{secret:NAME}}`, expanded on the platform, never returned, and sent only to the origins that secret lists (`secret set --allowed-origin`, `secret origins NAME <origin>...`; a redirect elsewhere is refused); `--local` fetches from the caller's machine instead, without secrets) |
34
40
  | `worlds sandbox import <id> <path-in-sandbox> [--entity] [--mode] [--report <file>]` | `import_world_sandbox_data` (`POST /api/public/benchmark-containers/sandboxes/{id}/import`; the platform reads the file from the sandbox tree into the platform world — the sandbox never holds credentials; `commit` versions the source tree only) |
35
41
  | `files connectors list\|sync <id>` | `list_file_connectors` / `sync_file_connector` (`GET\|POST /api/public/files/connectors[/sync]`) |
36
42
  | `traces list\|get\|export [--observations]` | `get_trace`, `get_observations` (`GET /api/public/traces[/{id}]`, `/observations`) |
@@ -47,6 +53,31 @@ Reference for `worlds-getting-started`: every CLI step and its MCP twin, then ho
47
53
  | `worlds skill <name>` / `worlds connector skill` | `get_connector_authoring_skill`, `guide` |
48
54
  | `worlds connector capture --remote` / poll + download | `start_connector_capture`, `get_connector_capture` (platform agent only) |
49
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
+
50
81
  ## Size and time limits (one source: `packages/shared/src/world/limits.ts`)
51
82
 
52
83
  Every door enforces the same number and names it in the refusal; the CLI checks the file
@@ -66,11 +97,13 @@ before it makes a request.
66
97
 
67
98
  ## The platform agent
68
99
 
69
- The platform (console) agent has every MCP tool in this table as an agent tool of the
70
- same name, plus `run_gateway_cli` for the *local* CLI rows (`schema init|templates|compile|check|describe|api-bundle`,
71
- `connector validate|conform|ingest|skill`, `data show|import|check|extract`, `skill`) inside its sandbox
72
- — structured `{ command, args }` with this CLI's exact flags (the TypeScript `gateway`, run as
73
- `node /tmp/gateway-cli/cli.js worlds …`), paths under `/workspace`, no remote flags, no platform
74
- credentials — and `spawn_subagent` / `wait_for_subagent` to hand one world or connector
75
- each to a tool-restricted child. Everything that writes to the platform goes through the
76
- MCP-twin tools, gated by capabilities and the session's autonomy settings.
100
+ The platform (console) agent edits worlds with this CLI, through `run_gateway_cli` in its
101
+ sandbox: structured `{ command, args }` with the CLI's exact flags (the TypeScript `gateway`,
102
+ run as `node /tmp/gateway-cli/cli.js worlds …`), paths under `/workspace`. A `./dir` runs in
103
+ the sandbox; a slug (`list`, `describe`, `create`, `pull`, `push`, `data …`, `test`, `session …`,
104
+ `requests …`, `edit …`, `connector list|pull|publish|clone`) reaches the platform as the user,
105
+ through a key minted for that one call, valid only on the routes that verb calls and deleted
106
+ when the call ends. A read verb needs read access, a write verb world-write access; `create`
107
+ and `session open` also need the session's `provisionWorlds` (or `confirm: true`),
108
+ `connector publish|clone` its `allowConnectorWrites`. `spawn_subagent` / `wait_for_subagent` hand one world or connector each to a
109
+ tool-restricted child.
@@ -2,15 +2,15 @@
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 agent's
8
- local-only `run_gateway_cli` included) `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.
11
- - `bench push` (the TS CLI) on a world with `connector.toml` still packages an api-kind bundle
12
- on the way up; `worlds create --from ./x` stores the tree as it is, and `worlds migrate`
13
- turns a pushed bundle back into the tree. Either way, edit the schema world, not the bundle.
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
+ - `bench push` and `worlds create --from ./x` store the tree as it is; nothing is repackaged into
12
+ an api-kind bundle on the way up. `worlds migrate` turns a bundle pushed before that back into
13
+ the tree. Either way, edit the schema world, not a bundle.
14
14
  - The World Host is the engine for every world, `[dependencies]` included (it opens each linked
15
15
  world beside the root); a session never falls back to a slower engine, and a deployment
16
16
  without a host refuses the open by name.
@@ -41,6 +41,9 @@ The things that bite once and never again, moved out of `SKILL.md` to keep it un
41
41
  anything is provisioned — the same preflight a run dispatch applies; set the secret, then open.
42
42
  - `gateway secret set NAME` is an upsert: the same name again rotates the value and answers
43
43
  `updated: true`; `bench secrets set` does the same for a benchmark's environment.
44
+ - A project secret is sent in a `files fetch` header only to the https origins it lists
45
+ (`gateway secret set NAME --allowed-origin https://host`, or `gateway secret origins NAME <origin>...`
46
+ without the value); one with none is refused by name, and so is a redirect to an unlisted origin.
44
47
  - Imported data survives every edit that cannot touch a stored row. After `gateway worlds data import
45
48
  <slug>` the world's tree carries `db/snapshot.json` (the hosted snapshot) and not the rows; in
46
49
  `worlds sandbox open <slug>@main`, adding a tool, a handler, a route, a test or a documentation
@@ -76,3 +79,31 @@ The things that bite once and never again, moved out of `SKILL.md` to keep it un
76
79
  `check` and is first refused at that open: open a session on the version after a handler edit.
77
80
  Compile from a fresh `sandbox open` rather than copying in artifacts compiled
78
81
  elsewhere: the pin proves its data's domain from the `schema/lock.json` it started with.
82
+
83
+ ## Transcribing a vendor spec by hand
84
+
85
+ Met building an AgentMail world from its OpenAPI document (2026-10-10).
86
+
87
+ - An entity's payload must be a closed object. A vendor `$def` without `additionalProperties:
88
+ false` is refused by `schema entity add` (`An entity payload must be a closed object`): close
89
+ every object def that declares `properties`, and leave map types (a schema-valued
90
+ `additionalProperties`, such as `metadata` or `headers`) as they are.
91
+ - A primary key must be a direct `string` or `integer` property. A vendor id wrapped in a named
92
+ alias (`"inbox_id": {"$ref": "#/$defs/InboxId"}`, where `InboxId` is a string) is refused
93
+ (`Primary key field … must be a string or integer property`): inline scalar aliases (the
94
+ target's schema, the property's own `description` kept) before `entity add`.
95
+ - A vendor refusal (not found, validation) is `raise Refusal(404, body)`, imported from `gateway_env`
96
+ at module top: tools and routes answer that status and body, unchecked against the tool's
97
+ `output`. Anything else raised is the world's bug: `AttributeError`, `TypeError`, `NameError`
98
+ answer 400 `handler`, the rest 500 `engine`.
99
+ - Arrays and nested objects are not SQL columns: they live in the row's `payload` JSON. Read them with
100
+ `json_extract(payload, '$.labels')`, or expand them with `json_each(payload, '$.labels')` in verifier
101
+ SQL and `worlds data sql`.
102
+ - Routes and tools can share one engine. The tools loader puts the world root on `sys.path` and
103
+ skips `tools/_*.py` as handler modules, so logic in `tools/_engine.py` is imported as `from
104
+ tools._engine import Engine` by `tools/handlers.py`. `api/handlers.py` is loaded by path with no
105
+ `sys.path` entry: insert the world root first (`sys.path.insert(0,
106
+ str(Path(__file__).resolve().parent.parent))`). Give the engine a small port (`rows`, `get`,
107
+ `insert`, `update`, `delete`, `now`, `uuid`) with one adapter over `ctx` and one over `store`.
108
+
109
+ - **A vendor that notifies needs `[webhooks]`, not just a subscriptions entity.** Rows written by `POST /webhooks` send nothing on their own. Declare `[webhooks]` in `connector.toml` (the subscriptions entity, its url/events/secret/enabled/scope fields, `signing = "svix"|"github"|"linear"|"stripe"|"hmac-sha256"|"none"`), then send from the write: `ctx.deliver(event_type, body, scope={...})` in a route handler, `gateway_env.webhooks.deliver(...)` in a tool. Each matching subscription gets one signed delivery, kept only when the call commits and recorded in the request ledger as `via: webhook` with the event type as `operation` (`worlds requests <slug> --via webhook`; checks read `gateway_requests`; a receiver's answer is a separate `<event>.answer` entry, so it never inflates a count of the event). To receive them on your machine: `gateway worlds session listen <id> --forward-to http://localhost:3000/webhooks` (signed as the vendor signs; the receiver's status lands in the ledger); `gateway worlds session webhooks <id>` lists the subscriptions. For receivers on the internet, a project admin turns on Settings → General → World webhooks and the platform posts each delivery itself (https 443, public addresses only). Spec: `documentation/features/connector-worlds.md` → Webhooks.
@@ -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` |