@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.
- package/dist/agents/index.d.mts +573 -0
- package/dist/agents/index.d.ts +573 -0
- package/dist/agents/index.js +1443 -0
- package/dist/agents/index.js.map +1 -0
- package/dist/agents/index.mjs +1394 -0
- package/dist/agents/index.mjs.map +1 -0
- package/dist/apiError-DHpfbmdx.d.mts +17 -0
- package/dist/apiError-DHpfbmdx.d.ts +17 -0
- package/dist/cli.js +5655 -1890
- package/dist/cli.js.map +1 -1
- package/dist/cli.mjs +5769 -2005
- package/dist/cli.mjs.map +1 -1
- package/dist/files/index.d.mts +3 -1
- package/dist/files/index.d.ts +3 -1
- package/dist/files/index.js +418 -120
- package/dist/files/index.js.map +1 -1
- package/dist/files/index.mjs +418 -120
- package/dist/files/index.mjs.map +1 -1
- package/dist/hooks/index.js +346 -136
- package/dist/hooks/index.js.map +1 -1
- package/dist/hooks/index.mjs +346 -136
- package/dist/hooks/index.mjs.map +1 -1
- package/dist/{index-DUHmS74p.d.ts → index-DIN14Lhg.d.ts} +27 -4
- package/dist/{index-mJhG3vZU.d.mts → index-DuB-eQ0Z.d.mts} +27 -4
- package/dist/index.d.mts +7 -4
- package/dist/index.d.ts +7 -4
- package/dist/index.js +2862 -438
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +2820 -431
- package/dist/index.mjs.map +1 -1
- package/dist/media-CQUC7TkS.d.mts +39 -0
- package/dist/media-DQnBloaX.d.ts +39 -0
- package/dist/replay/index.d.mts +1 -1
- package/dist/replay/index.d.ts +1 -1
- package/dist/replay/index.js.map +1 -1
- package/dist/replay/index.mjs.map +1 -1
- package/dist/traces/index.d.mts +3 -1
- package/dist/traces/index.d.ts +3 -1
- package/dist/traces/index.js +418 -120
- package/dist/traces/index.js.map +1 -1
- package/dist/traces/index.mjs +418 -120
- package/dist/traces/index.mjs.map +1 -1
- package/dist/tracing/index.d.mts +3 -2
- package/dist/tracing/index.d.ts +3 -2
- package/dist/tracing/index.js +257 -16
- package/dist/tracing/index.js.map +1 -1
- package/dist/tracing/index.mjs +257 -16
- package/dist/tracing/index.mjs.map +1 -1
- package/dist/transport-CpRe7zgd.d.mts +123 -0
- package/dist/transport-CpRe7zgd.d.ts +123 -0
- package/dist/worlds/index.d.mts +2086 -1749
- package/dist/worlds/index.d.ts +2086 -1749
- package/dist/worlds/index.js +1471 -269
- package/dist/worlds/index.js.map +1 -1
- package/dist/worlds/index.mjs +1466 -265
- package/dist/worlds/index.mjs.map +1 -1
- package/package.json +6 -1
- package/runtime/gatewaysdk/environment/_bundle.py +4 -6
- package/runtime/gatewaysdk/environment/_world.py +24 -1
- package/runtime/gatewaysdk/environment/bundle_manifest.py +243 -0
- package/runtime/gatewaysdk/environment/runtime.py +45 -2
- package/runtime/gatewaysdk/environment/schema/__main__.py +2 -2
- package/runtime/gatewaysdk/environment/schema/_slack_fidelity.py +8 -23
- package/runtime/gatewaysdk/environment/schema/api.py +27 -7
- package/runtime/gatewaysdk/environment/schema/assertions.py +7 -1
- package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +2 -0
- package/runtime/gatewaysdk/environment/schema/call_capture.py +13 -1
- package/runtime/gatewaysdk/environment/schema/call_log.py +66 -0
- package/runtime/gatewaysdk/environment/schema/call_redaction.py +6 -0
- package/runtime/gatewaysdk/environment/schema/compiler.py +4 -1
- package/runtime/gatewaysdk/environment/schema/conform.py +32 -8
- package/runtime/gatewaysdk/environment/schema/connector.py +5 -0
- package/runtime/gatewaysdk/environment/schema/connectors/custom/handlers.py +2 -1
- package/runtime/gatewaysdk/environment/schema/connectors/github/api/handlers.py +217 -58
- package/runtime/gatewaysdk/environment/schema/connectors/github/connector.toml +9 -19
- package/runtime/gatewaysdk/environment/schema/connectors/github/scenarios/default/seed/github_webhooks.json +10 -2
- package/runtime/gatewaysdk/environment/schema/connectors/github/tests/webhooks.json +47 -0
- package/runtime/gatewaysdk/environment/schema/connectors/github/world.json +21 -0
- package/runtime/gatewaysdk/environment/schema/connectors/jamf/api/handlers.py +185 -18
- package/runtime/gatewaysdk/environment/schema/connectors/jamf/connector.toml +29 -14
- package/runtime/gatewaysdk/environment/schema/connectors/jamf/provenance.json +43 -12
- package/runtime/gatewaysdk/environment/schema/connectors/jamf/scenarios/default/seed/jamf_webhooks.json +2 -2
- package/runtime/gatewaysdk/environment/schema/connectors/jamf/scope.toml +4 -17
- package/runtime/gatewaysdk/environment/schema/connectors/jamf/tests/webhooks.json +107 -0
- package/runtime/gatewaysdk/environment/schema/connectors/jamf/vendor-openapi.json +1 -1
- package/runtime/gatewaysdk/environment/schema/connectors/linear/api/handlers.py +85 -1
- package/runtime/gatewaysdk/environment/schema/connectors/linear/connector.toml +19 -31
- package/runtime/gatewaysdk/environment/schema/connectors/linear/provenance.json +18 -8
- package/runtime/gatewaysdk/environment/schema/connectors/linear/scenarios/default/seed/webhooks.json +19 -3
- package/runtime/gatewaysdk/environment/schema/connectors/linear/tests/test_webhooks.py +71 -0
- package/runtime/gatewaysdk/environment/schema/database/base.py +2 -2
- package/runtime/gatewaysdk/environment/schema/database/guard.py +2 -1
- package/runtime/gatewaysdk/environment/schema/handler_errors.py +27 -1
- package/runtime/gatewaysdk/environment/schema/host.py +74 -11
- package/runtime/gatewaysdk/environment/schema/host_browser.py +48 -0
- package/runtime/gatewaysdk/environment/schema/host_control.py +33 -2
- package/runtime/gatewaysdk/environment/schema/host_handoff.py +4 -1
- package/runtime/gatewaysdk/environment/schema/host_requests.py +14 -0
- package/runtime/gatewaysdk/environment/schema/host_session.py +13 -2
- package/runtime/gatewaysdk/environment/schema/host_surfaces.py +6 -0
- package/runtime/gatewaysdk/environment/schema/host_versions.py +96 -19
- package/runtime/gatewaysdk/environment/schema/journal.py +10 -4
- package/runtime/gatewaysdk/environment/schema/local.py +33 -7
- package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +20 -5
- package/runtime/gatewaysdk/environment/schema/page_checks.py +123 -0
- package/runtime/gatewaysdk/environment/schema/platform.py +33 -480
- package/runtime/gatewaysdk/environment/schema/platform_templates.py +332 -0
- package/runtime/gatewaysdk/environment/schema/request_ledger.py +4 -1
- package/runtime/gatewaysdk/environment/schema/run_parameters.py +25 -0
- package/runtime/gatewaysdk/environment/schema/runtime.py +49 -4
- package/runtime/gatewaysdk/environment/schema/scaffold.py +369 -218
- package/runtime/gatewaysdk/environment/schema/session_files.py +13 -2
- package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +1 -1
- package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/CONNECTORS.md +3 -3
- package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +20 -24
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +11 -11
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +9 -9
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +45 -12
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +40 -9
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +17 -2
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/new-world-sandbox.md +1 -1
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/ui-map.md +3 -2
- package/runtime/gatewaysdk/environment/schema/slack.py +55 -10
- package/runtime/gatewaysdk/environment/schema/snapshot.py +30 -4
- package/runtime/gatewaysdk/environment/schema/tasks.py +25 -2
- package/runtime/gatewaysdk/environment/schema/template_record.py +131 -0
- package/runtime/gatewaysdk/environment/schema/tools_world.py +26 -5
- package/runtime/gatewaysdk/environment/schema/ui.py +54 -33
- package/runtime/gatewaysdk/environment/schema/ui_interactions.py +419 -0
- package/runtime/gatewaysdk/environment/schema/ui_recorder.js +895 -0
- package/runtime/gatewaysdk/environment/schema/ui_replay.py +366 -0
- package/runtime/gatewaysdk/environment/schema/ui_replay_record.LICENSE +25 -0
- package/runtime/gatewaysdk/environment/schema/ui_replay_record.js +109 -0
- package/runtime/gatewaysdk/environment/schema/validation.py +10 -1
- package/runtime/gatewaysdk/environment/schema/verbs.py +6 -0
- package/runtime/gatewaysdk/environment/schema/webhooks.py +687 -0
- package/runtime/gatewaysdk/environment/schema/worker.py +5 -1
- package/runtime/gatewaysdk/environment/schema/workers.py +8 -1
- package/runtime/gatewaysdk/environment/schema/world_host.py +64 -18
- package/runtime/gatewaysdk/environment/schema/world_tests.py +74 -0
- package/runtime/gatewaysdk/environment/secret_values.py +1 -1
- package/runtime/gatewaysdk/environment/world.py +34 -43
- package/runtime/gatewaysdk/environment/world_session_contract.py +7 -34
- package/skills/benchmarks-getting-started/SKILL.md +1 -1
- package/skills/connector-schema-authoring/CONNECTORS.md +3 -3
- package/skills/connector-schema-authoring/SKILL.md +20 -24
- package/skills/connector-schema-authoring/connector-worlds.md +155 -13
- package/skills/connector-schema-authoring/world-schema.md +36 -29
- package/skills/world-data-ingestion/SKILL.md +11 -11
- package/skills/worlds-getting-started/SKILL.md +9 -9
- package/skills/worlds-getting-started/references/cli-mcp-map.md +45 -12
- package/skills/worlds-getting-started/references/gotchas.md +40 -9
- package/skills/worlds-getting-started/references/journal-checks.md +17 -2
- package/skills/worlds-getting-started/references/new-world-sandbox.md +1 -1
- package/skills/worlds-getting-started/references/ui-map.md +3 -2
- package/dist/media-BIApiPzS.d.mts +0 -102
- 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
|
|
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
|
-
|
|
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 #
|
|
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
|
|
package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/CONNECTORS.md
CHANGED
|
@@ -68,9 +68,9 @@ real row; captured exports from that tenant become the goldens.
|
|
|
68
68
|
| Slug | State | Notes |
|
|
69
69
|
| --- | --- | --- |
|
|
70
70
|
| slack | package 2.1.1 / domain 2.0.0 / mapping 1, spec-derived fields (wave 1) | base; 34 normalized entities / 72 `$defs` / 27 tools; `connector.toml` serves 56 Web API operations from `api/handlers.py` (bearer `SLACK_BOT_TOKEN`, Slack `ok`/`error` envelopes); `scenarios/default` seeds 34 entities / 84 synthetic rows; `vendor-openapi.json` (trimmed, response schemas relocated to OpenAPI 3 `content`) — `connector conform` 51/54 documented operations pass, 3 fail on channel-keyed `file.shares.public` that the 2020 spec stubs empty, `bookmarks.*` undocumented there. `subset`: no live round trip. Empty init or populated synthetic/selected capture → immutable hosted world; [on-demand fixtures](../../../samples/schema-worlds/README.md#slack-fixtures) |
|
|
71
|
-
| github | spec-derived, wave 2 (domain 4.0.0) | base; pinned GitHub REST OpenAPI (`adb01e9`, 2026-09-15) plus the GraphQL review-state declaration. 45 entities / 5,365 recursive fields / 4 tools / 203 served operations (`connector.toml` + `api/handlers.py`; `scenarios/default` seeds 111 rows across every entity; `vendor-openapi.json` trimmed to the served paths, 203/203 conform). The fullest vendor read form is each entity's root (full-repository, public-user, organization-full, team-full, ...) with the narrower forms' required lists intersected where scope.toml lists several read_forms; route containment and nested-scalar projections are direct fields so keys and relationships are enforceable; many-to-many links are membership entities. Issue state/state-reason come from declared REST sibling value blocks; review state from `PullRequestReviewState`; user `type` stays open. 1,026 documented routes unserved, pagination not emulated; `subset` until a test-org round trip and synthetic goldens exist. |
|
|
71
|
+
| github | spec-derived, wave 2 (domain 4.0.0) | base; pinned GitHub REST OpenAPI (`adb01e9`, 2026-09-15) plus the GraphQL review-state declaration. 45 entities / 5,365 recursive fields / 4 tools / 203 served operations (`connector.toml` + `api/handlers.py`; `scenarios/default` seeds 111 rows across every entity; `vendor-openapi.json` trimmed to the served paths, 203/203 conform). The fullest vendor read form is each entity's root (full-repository, public-user, organization-full, team-full, ...) with the narrower forms' required lists intersected where scope.toml lists several read_forms; route containment and nested-scalar projections are direct fields so keys and relationships are enforceable; many-to-many links are membership entities. Issue state/state-reason come from declared REST sibling value blocks; review state from `PullRequestReviewState`; user `type` stays open. 1,026 documented routes unserved, pagination not emulated; `subset` until a test-org round trip and synthetic goldens exist. Sends GitHub's webhooks (`[webhooks]`, `github` signing): `ping`, `issues`, `issue_comment`, `pull_request`, `push`; JSON only, repository hooks only. |
|
|
72
72
|
| salesforce | docs-derived, wave 2 (full-parity expansion) | tenant-shaped skeleton from 99 pinned Winter '27 (API 68.0, doc 264.0) Object Reference pages plus 32 REST API Developer Guide resource pages: 99 entities / 2,519 top-level fields (2,695 recursive) / 215 restrict relationships / 102 closed enums / 14 unique constraints / 4 tools; `connector.toml` serves 332 operations (Resources by Version, Describe Global, sObject Basic Information, sObject Describe, `/query` SOQL subset, `/search` SOSL subset, and per-object retrieve/create/update/delete exactly where each page's Supported Calls lists them) with `api/handlers.py` for the computed routes; `scenarios/default` seeds 2 synthetic rows in every entity (198 rows). **Describe-on-bind is required** for the org's actual fields, relationships, picklists, custom schema, record types and permissions; the served `/describe` answers from the skeleton and says so. Only Restricted picklists with an explicit vendor value block become enums; org-controlled picklists (StageName, Lead.Status, Case Status/Priority/Origin, ...) remain open strings. Single-target `Refers To` fields become relationships; polymorphic (`WhoId`, `WhatId`, Group-or-User owners: 39) and references to unmodelled objects (183) remain ids. Not served, reported: upsert by external id, deleted/updated, queryAll, composite, limits, Bulk/Tooling/Metadata/Streaming, blob bodies. Conformance not applicable: Salesforce publishes only an org-generated OAS3 beta. `subset`: no org describe, Developer Edition/scratch-org round trip or goldens. |
|
|
73
|
-
| linear | SDL-derived, wave 2 | base; transcribed from the pinned linear/linear `packages/sdk/src/schema.graphql` (commit `23f11eb4`). 32 entities / 600 fields / 114 restrict relationships / 16 enums / 4 tools; 150 REST-shaped `connector.toml` operations (55 read, 24 create, 28 update, 23 delete, 20 handler) with a synthetic `default` scenario for every entity. Vendor camelCase is kept; GraphQL non-null is required, nullable is required-but-null. `Project.state` stays despite `@deprecated` because the brief requires it; `Issue.priority` is integer 0..4 from the description. `linear_roadmaps` has no routes because every roadmap root field is `@deprecated`. OpenAPI conformance is not applicable (GraphQL only, no vendor OpenAPI). `subset`: 90 Node types excluded, 28 generated `<field>Id` names unconfirmed, no live introspection or workspace round trip. |
|
|
73
|
+
| linear | SDL-derived, wave 2 | base; transcribed from the pinned linear/linear `packages/sdk/src/schema.graphql` (commit `23f11eb4`). 32 entities / 600 fields / 114 restrict relationships / 16 enums / 4 tools; 150 REST-shaped `connector.toml` operations (55 read, 24 create, 28 update, 23 delete, 20 handler) with a synthetic `default` scenario for every entity. Vendor camelCase is kept; GraphQL non-null is required, nullable is required-but-null. `Project.state` stays despite `@deprecated` because the brief requires it; `Issue.priority` is integer 0..4 from the description. `linear_roadmaps` has no routes because every roadmap root field is `@deprecated`. OpenAPI conformance is not applicable (GraphQL only, no vendor OpenAPI). `subset`: 90 Node types excluded, 28 generated `<field>Id` names unconfirmed, no live introspection or workspace round trip. Sends Linear's webhooks (`[webhooks]`, `linear` signing) for `Issue` and `Comment` create/update/remove, filtered by `resourceTypes` and team. |
|
|
74
74
|
| jira | spec-derived, schema-worlds pass | mixed; `$defs` transcribed from the pinned Jira Cloud platform REST v3 OpenAPI (1001.0.0-SNAPSHOT, 2,473,385 bytes) and the Jira Software Cloud OpenAPI (1001.0.0) for boards/sprints. 21 entities / 65 `$defs` (477 properties) / 32 relationships / 5 tools / 78 `connector.toml` operations (78/78 conform against the trimmed `vendor-openapi.json`). Issues are keyed by immutable `id` with `key` unique; transitions by (`issueId`, `id`); sprint membership is a link entity. `IssueBean.fields` is `{}` in the vendor document, so an authored `IssueFields` `$def` types 38 system-field members and stays open for `customfield_*` overlay values. Enums only where the vendor declares them (`projectTypeKey`, `accountType`, `style`, `assigneeType`, sprint `state` from the `getAllSprints` filter); `StatusCategory.key` stays open. `scenarios/default` seeds every entity synthetically. `subset`: no Jira Cloud round trip, no goldens, Rovo MCP tool parity unverified. |
|
|
75
75
|
| microsoft-teams | authored base, wave 3 (served) | [Usage, artifacts, scope, and pinned evidence](../../../documentation/features/microsoft-teams-schema.md). 19 entities / 81 vendor `$defs` / 0 tools; teams, channels (incoming, shared-with), chats, chat views, team/channel/chat members, channel messages, replies, chat messages, hosted contents, tags, tag members, pinned messages, async operations. `connector.toml`: 99 Graph v1.0 operations (`auth.scheme = "none"`), all `action = "handler"` because Graph answers carry `@odata.*` annotations and hide the capture-context key column; documented statuses 200/201/202/204/207. `scenarios/default`: 65 synthetic rows. `vendor-openapi.json`: pinned Graph OpenAPI trimmed to the 68 served path items (302 KB) with `2XX`/`204` success keys rewritten to the documented concrete statuses (listed in the sidecar); `connector conform` 98/99, the miss being `DELETE .../incomingChannels/{id}/$ref` which the docs describe but the OpenAPI omits. Not served: user-scoped aliases, `getAllMessages`/delta exports, `$value` binaries, apps/tabs/photo/schedule/permissionGrants. `subset`: no sandbox round trip or goldens. |
|
|
76
76
|
| google-drive | discovery-derived, wave 2 | base; derived from the pinned Drive v3 Discovery document (revision 20260904, sha256 `6d38b6c8e1d1a45fa1b30744523dc6c400ad612997f8e67d112271b573e4948e`), no vendor OpenAPI exists. 10 entities / 34 `$defs` / 410 recursive fields / 4 tools; `drive_folders` is gone (folders are files by `mimeType`). All ten documented resources are entities (Drive, File, Permission, Revision, Comment, Reply, Label, App, AccessProposal, Approval); 49 of 64 documented methods are served from `connector.toml` (changes, channels, about, export/download, CSE tokens, operations and the deprecated `teamdrives.*` are not). Child rows carry route-context `fileId`/`commentId` keys; `parents` stays the vendor array and is not a relationship. Enums are the vendor's declared arrays plus the value lists its descriptions state, recorded separately in `provenance.json`. `vendor-openapi.json` is generated from the Discovery document and trimmed to the served operations; `connector conform` 49/49 against it after seeding `scenarios/default`. `subset`: prose-enum completeness and list-envelope constants unverified, no test-domain round trip or goldens. |
|
|
@@ -80,7 +80,7 @@ real row; captured exports from that tenant become the goldens.
|
|
|
80
80
|
| custom | hand-authored, worked example | the blank starting point for any arbitrary connector, now a worked example of the authoring contract with no vendor behind it: 1 entity (`records`, the only name the scaffold test allows) / 15 fields / 3 tools, showing a primary key, a sparse unique key (`slug`), a self-relationship (`parent_id -> records`, restrict), an enum in `$defs` (`status`), optional (`owner_email`) vs optional-nullable (`parent_id`, `priority`, `due_at`) vs required-nullable (`source.external_id`), a closed nested object and an open bag. Only the original five fields (`id`, `kind`, `name`, `attributes`, `updated_at`) are required and `kind` stays an open string: the SDK test suite uses this template as its blank fixture and inserts rows of that shape, so the example grows by optional fields only. No `connector.toml` ships: the redaction tests need a policy-free world and the same tests create `connector.toml`, `api/` and `scenarios/` themselves and read back an exact template file set, so the template also ships no `api/handlers.py`, no `scenarios/default` seed and no `vendor-openapi.json` (conformance not applicable). Everything is synthetic; `schema init --connector custom` renames the world and drops the tools unless `--with-example-tool`. |
|
|
81
81
|
| workday | hand-authored, wave 3 + REST expansion | tenant-shaped skeleton from pinned public WWS v46.2 WSDL/XSD files (Human Resources, Staffing, Absence Management, Compensation) plus five pinned public Workday REST Swagger 2.0 documents (common v1, staffing v7, absenceManagement v5, compensation v3, person v4, dated 2026-09-12): 27 entities (7 `workday_*` WWS + 20 `workday_rest_*`) / 729 recursive fields / 14 relationships / 3 tools. `connector.toml` serves 62 of the 332 documented REST operations (OAuth2, offset/limit `data[]` envelope, PII redaction, six handler-backed workflow routes); unmodelled routes are listed in `provenance.json`. `scenarios/default` seeds synthetic rows for every entity; `vendor-openapi.json` (OAS 3.0.3 converted and trimmed from the Swagger sources) conforms 62/62. **Describe-on-bind is required** for an actual tenant (tenant WSDL, REST host and OAuth client, custom objects/fields, RaaS). WWS and REST identifier systems stay separate entities until a tenant overlay maps them. Workday-namespaced `wd:enumeration` blocks are used only where the selected reference-ID types declare them; tenant business values remain open. `xsd:date` maps to `format: date`; `xsd:time` remains unformatted because the source permits a missing timezone. `subset`: no tenant round trip, no live capture, timeTracking v6 unreachable. |
|
|
82
82
|
| kandji | hand-authored, wave 3 (expanded 2026-09-15) | base; transcribed from the pinned vendor Postman collection rendered by api-docs.iru.com (135 requests), with the community OpenAPI (`MScottBlake/kandji-openapi@46fa742`) used only as a cross-check. 21 entities / 234 recursive fields / 25 `$defs` / 3 tools; `connector.toml` serves 48 operations (49 of the 135 documented requests: devices, apps, library-item statuses, parameters, commands, activity, notes CRUD, blueprints CRUD + templates + library-item assignment, library-item status/activity, users, tags CRUD, custom apps/profiles/scripts, in-house apps, self-service categories) with 21 handler routes; `scenarios/default` seeds 57 synthetic rows. Device `user` stays as the vendor's nested object-or-empty-string shape; `/user/id` is enforced when assigned and the empty-string sentinel is treated as absent. Nine vendor-declared value blocks (blueprint type, library-item status, activity type, parameter status, integer command status codes, custom-app install type/enforcement, script frequency); platform values are example-derived and completeness remains unverified. Apple-family app shape only; Windows/Android forms need a polymorphic-key model. Trimmed community OpenAPI shipped as `vendor-openapi.json` (18 paths / 26 ops): `connector conform` 16/26 pass; the 10 failures are the community document's inferred types (booleans as integer, arrays as object, nullable `next` as string, blueprint DELETE 200) contradicted by the vendor examples. Not served: device details/Prism, actions, secrets, ADE, threats, vulnerabilities, audit, blueprint routing, upload handshakes. `subset`: no vendor OpenAPI, no account-team sandbox, tenant round trip, or goldens. |
|
|
83
|
-
| jamf | docs-derived, wave 4 | mixed; generated from the OpenAPI 3.0.1 fragments embedded in every pinned developer.jamf.com reference page (Jamf Pro API 11.32.0: 825 pages / 823 operations; Classic API 11.32.0: 689 pages / 613 operations; all fetched 2026-09-15 and hashed in provenance.json) because no per-instance `/api/schema` was available. 66 entities / 166 `$defs` / 2099 recursive fields / 4 tools. Pro resources keep string ids, Classic resources integer ids (root `id` = `general.id`); static and smart groups share one entity per platform; computer and mobile-device group membership are join entities with both foreign keys, prestages and DEP devices point at their device enrollment (7 relationships, all `restrict`); group-name uniqueness is asserted because the create routes document `422 Duplicate group name`, nothing else is. connector.toml serves 302 documented routes (178 Pro under `/api`, 124 Classic under `/JSSResource`; 110 handlers for paged lists, membership and group writes, 90 reads, 25 updates, 77 deletes); the 1134 documented-but-unserved operations are listed per path family in scope.toml `[unserved]`. `vendor-openapi.json` is the two aggregates trimmed to the served routes and their schemas (431 KB; untrimmed hashes in provenance.json) and `connector conform` passes 302/302 after seeding scenarios/default (66 seed files, 198 synthetic rows). Classic list responses follow the pinned array-of-wrapper schema, not the live envelope; Classic XML writes are not
|
|
83
|
+
| jamf | docs-derived, wave 4 | mixed; generated from the OpenAPI 3.0.1 fragments embedded in every pinned developer.jamf.com reference page (Jamf Pro API 11.32.0: 825 pages / 823 operations; Classic API 11.32.0: 689 pages / 613 operations; all fetched 2026-09-15 and hashed in provenance.json) because no per-instance `/api/schema` was available. 66 entities / 166 `$defs` / 2099 recursive fields / 4 tools. Pro resources keep string ids, Classic resources integer ids (root `id` = `general.id`); static and smart groups share one entity per platform; computer and mobile-device group membership are join entities with both foreign keys, prestages and DEP devices point at their device enrollment (7 relationships, all `restrict`); group-name uniqueness is asserted because the create routes document `422 Duplicate group name`, nothing else is. connector.toml serves 302 documented routes (178 Pro under `/api`, 124 Classic under `/JSSResource`; 110 handlers for paged lists, membership and group writes, 90 reads, 25 updates, 77 deletes); the 1134 documented-but-unserved operations are listed per path family in scope.toml `[unserved]`. `vendor-openapi.json` is the two aggregates trimmed to the served routes and their schemas (431 KB; untrimmed hashes in provenance.json) and `connector conform` passes 302/302 after seeding scenarios/default (66 seed files, 198 synthetic rows). Classic list responses follow the pinned array-of-wrapper schema, not the live envelope; Classic XML writes are served only for webhooks (create, update). Sends Jamf's `ComputerAdded` webhook (`[webhooks]`, unsigned) to JSON subscriptions; XML subscriptions and Basic auth are not carried. `subset` until a per-instance schema, a sandbox round trip and goldens exist. |
|
|
84
84
|
| apple-business-manager | docs-derived, wave 3 (full-parity pass) | base; generated from the complete pinned Apple Business API 2.4 DocC JSON corpus (329 pages, per-page sha256 in provenance.json). 24 entities / 281 recursive fields / 28 closed enums / 2 read tools: every documented resource type (OrgDevice, AppleCareCoverage, MdmDevice, MdmDeviceDetail, MdmServer, OrgDeviceActivity, User, UserGroup, OrganizationalUnit, Blueprint, Configuration, App, Package, AuditEvent with all eventData payloads) plus one linkage entity per documented relationship. Vendor `attributes` nesting is preserved; nested `enrolledUserId` and user-group `ouId` relationships are enforced, `roleOuList[].ouId` is not (array traversal); `productFamily` stays open because the shared hr/apple test fixture inserts `MAC`/`IPAD` against Apple's documented `Mac`/`iPad`. `connector.toml` declares all 56 documented routes (OAuth2 client credentials, cursor paging) answered by `api/handlers.py` in Apple's JSON:API envelope with `fields[type]`, `include`, `filter[...]`; `scenarios/default` seeds 69 synthetic rows across every entity. No OpenAPI exists, so `connector conform` is not applicable; the six `DELETE .../relationships/*` routes answer 400 because the world API drops DELETE bodies. `subset`: no sandbox, no live evidence, no goldens. |
|
|
85
85
|
| netsuite | docs-derived, wave 3 (expanded) | tenant-shaped skeleton from the pinned 2026.1 REST API Browser (28 chunks, sha256 in provenance.json; 2023.2 archive as cross-check) plus Oracle record-service, filtering, paging, upsert, error and OAuth docs: 22 standard records as 23 entities / 325 `$defs` / 11,385 recursive fields / 171 relationships / 3 tools / 144 `connector.toml` operations (list, create, get, PATCH, upsert `eid:`, delete per record and 12 modelled-to-modelled `!transform` routes; nsError envelope, `q` filter grammar, `limit`/`offset` paging, bearer required). **Describe-on-bind is required** for role/account-specific records, custom fields, lists, segments, enums, and nullability. Vendor nesting is preserved; `salesOrder-itemElement` is also projected as `netsuite_sales_order_lines` (`order_id`, `line`). Single-target references become restrict relationships; five `one of` references the brief requires (`entity`/`customer` on sales orders, invoices, credit memos, payments; line `item`) are narrowed to customers/items and listed in scope.toml; the other 237 and all collection-item paths stay unenforced. `externalId` uniqueness follows the `eid:` address; the brief's business numbers (`entityId`, `itemId`, `tranId`, `acctNumber`, subsidiary `name`) are declared as the world's contract, not as vendor-schema facts. Default scenario: 97 synthetic rows across all 23 entities. No `vendor-openapi.json`: the Browser is HTML and the OpenAPI 3.0 metadata is per account, so `conform` is not applicable. `suiteql` is not shipped. `subset`: no account metadata overlay, round trip, or goldens. |
|
|
86
86
|
| microsoft-teams | authored schema-only base | [Usage, artifacts, scope, and pinned evidence](../../../documentation/features/microsoft-teams-schema.md); no tools or live integration |
|
|
@@ -75,8 +75,8 @@ registration, a platform builder, live ingestion, tools, or a registry framework
|
|
|
75
75
|
| `gateway worlds schema import PATH --from <kind> --spec <url\|path> [--scope scope.toml]` | not implemented; author the contract and provenance manually |
|
|
76
76
|
| `gateway worlds schema parity PATH --surface <tools-list.json> \| --connection <id>` (advisory report) | not implemented |
|
|
77
77
|
| `gateway worlds playground <connector>` | not implemented |
|
|
78
|
-
| Platform upload of a JSON Schema, OpenAPI, or DDL as a new connector | not implemented as a UI upload; the platform agent
|
|
79
|
-
| Platform agent record ingestion
|
|
78
|
+
| Platform upload of a JSON Schema, OpenAPI, or DDL as a new connector | not implemented as a UI upload; the platform agent authors the tree in its sandbox and runs `gateway worlds create <slug> --from ./dir` through `run_gateway_cli`, the same door as the CLI (2026-10-10) |
|
|
79
|
+
| Platform agent record ingestion | the CLI's own `data import <slug>`, `pull`, `push` and `describe` through `run_gateway_cli`; see `documentation/features/agent.md` |
|
|
80
80
|
| SDK/public and platform publication | validates assembled files and actual stored archive bytes through the trusted compiler/materializer, including READY/dedup/ref paths |
|
|
81
81
|
| Connectors Slack world creation | durable structured capture → shared Python mapper → immutable publication; explicit synthetic mode |
|
|
82
82
|
| Worker schema tests/workbench | shared validation and isolated E2B author execution; missing isolation is non-green |
|
|
@@ -143,7 +143,7 @@ deliverable can finish with synthetic fixtures and explicitly skipped live valid
|
|
|
143
143
|
Tool handlers (`tools/*.py`) reach the world's rows through `from gateway_env import store`. It has
|
|
144
144
|
exactly these methods; `gateway worlds schema check .` refuses any other `store.<name>` at file:line
|
|
145
145
|
with this list, and a hosted call into such a handler answers 400 `{error: "handler", detail, handler}`
|
|
146
|
-
(an `AttributeError`/`TypeError`/`NameError` is the author's bug; anything else a handler raises is a
|
|
146
|
+
(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
|
|
147
147
|
500 `{error: "engine", detail, handler}`; never a bare exception string). A route's handler answers the
|
|
148
148
|
same way on every door, and an answer JSON cannot carry (a `datetime`, a set, NaN) is its 400; a route
|
|
149
149
|
answering bytes names its `Content-Type` (a vendor's `404 text/plain`), and the bytes go out as sent.
|
|
@@ -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
|
-
- [ ]
|
|
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.
|
|
@@ -194,10 +194,11 @@ No `upsert`: `get`, then `insert` or `update`. Read-only SQL: `gateway_env.db.on
|
|
|
194
194
|
## Runtime authoring boundary
|
|
195
195
|
|
|
196
196
|
When adding a bridge command to `schema/platform.py`, mirror it as a typed wrapper in
|
|
197
|
-
`worldSchemaRuntime.ts` (`compileWorldFiles` / `
|
|
198
|
-
in, `{entries,
|
|
199
|
-
`tests/environment/test_schema_platform.py`, and let
|
|
200
|
-
the subprocess
|
|
197
|
+
`worldSchemaRuntime.ts` (`compileWorldFiles` / `importWorldData` are the pattern: file map
|
|
198
|
+
in, `{entries, ...}` out, errors as `SchemaBridgeError`), cover it in
|
|
199
|
+
`tests/environment/test_schema_platform.py`, and let a service call the wrapper, never
|
|
200
|
+
the subprocess; the public `/api/public/worlds/runtime` route reaches only the commands in
|
|
201
|
+
`WORLD_RUNTIME_COMMANDS`. The bridge needs Python ≥ 3.12 (`tomllib`, and the store's sqlite `setconfig`); set `GATEWAY_SCHEMA_PYTHON`
|
|
201
202
|
when the default interpreter is older.
|
|
202
203
|
|
|
203
204
|
Use `worldSchemaRuntime.ts` for platform validation and `schema.platform` for
|
|
@@ -264,7 +265,6 @@ Python SDK as package data so an agent in any repository can install it.
|
|
|
264
265
|
Revalidated 2026-09-07 while integrating `ba89fe16` with `015d6b25`:
|
|
265
266
|
`schema/scaffold.py`, `schema/platform.py`, `tests/environment/test_schema_scaffold.py`,
|
|
266
267
|
`worldSchemaPublication.ts`, `worldSchemaRuntime.ts`, `environmentBundleTester.ts`,
|
|
267
|
-
`environmentBuildWorkbench.ts`, `environmentSchemaSandbox.ts`,
|
|
268
268
|
`NativeSlackService.ts`, and `deploy/benchmark-runner/engines/{session_server,schema_session}.py`.
|
|
269
269
|
Full source paths and runtime boundaries are listed in [world-schema.md](../../../documentation/features/world-schema.md).
|
|
270
270
|
These source checks do not imply live-provider validation or executed fidelity scores.
|
|
@@ -357,21 +357,17 @@ redacted pages back into `captures/`.
|
|
|
357
357
|
|
|
358
358
|
### From the platform agent (no checkout)
|
|
359
359
|
|
|
360
|
-
The console agent
|
|
361
|
-
`
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
(
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
refused before anything is queued. `run_gateway_cli` runs the TypeScript `gateway worlds …` CLI
|
|
372
|
-
(the same flags as this page) staged into the sandbox, local-only (paths under `/workspace`,
|
|
373
|
-
no `--host`/`--remote`/`workspace:<slug>`, platform env stripped, pinned to its local runtime),
|
|
374
|
-
so publishing always goes through the tools above. To parallelise several connectors, `spawn_subagent` with a brief
|
|
360
|
+
The console agent runs the CLI on this page through `run_gateway_cli` in its sandbox: write
|
|
361
|
+
`connector.toml` + `schema/` under `./acme` → `connector validate ./acme`, `connector conform ./acme --openapi ./spec.json`,
|
|
362
|
+
`schema check ./acme`, `test ./acme` → `create acme --from ./acme` (billed: the session's
|
|
363
|
+
`provisionWorlds` or `confirm: true`) → `start_connector_capture({ containerId, op, args, params })` →
|
|
364
|
+
`get_connector_capture({ …, downloadTo })` → `connector ingest ./acme` → `push ./acme`, then
|
|
365
|
+
`edit close acme`. `connector publish ./acme` makes it a workspace connector (`hub:write` and
|
|
366
|
+
`allowConnectorWrites`, else `confirm: true`). A `./dir` runs in the sandbox; a slug reaches the
|
|
367
|
+
platform as the user through a key minted for that one call, valid only on the routes that verb calls and
|
|
368
|
+
deleted when the call ends; `--host` and key flags are refused. `list_world_secrets` shows the
|
|
369
|
+
env var names the world holds, never values; a `connector.toml` with an inline credential is
|
|
370
|
+
refused before anything is queued. To parallelise several connectors, `spawn_subagent` with a brief
|
|
375
371
|
naming only the tools that child needs (`allowSubagents` on the session).
|
|
376
372
|
|
|
377
373
|
### From the CLI sandbox (no checkout, no Python)
|
|
@@ -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
|
|
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
|
|
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
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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" #
|
|
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
|
-
(
|
|
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
|
|
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;
|
|
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
|
|
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
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
`
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
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.
|
package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md
CHANGED
|
@@ -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
|
-
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
`
|
|
10
|
-
|
|
11
|
-
- `bench push`
|
|
12
|
-
on the way up
|
|
13
|
-
|
|
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
|
|
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 `
|
|
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"]`.
|