@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
@@ -1,61 +1,31 @@
1
- """THE NUMBERS AND WORDS A WORLD SESSION PROMISES — the Python twin.
2
-
3
- Stdlib only, and inside ``gatewaysdk.environment`` because that package is
4
- what gets vendored on its own — the web/worker images ship
5
- ``/opt/gateway-schema/gatewaysdk/environment``, ``installSandboxRuntime``
6
- copies it into agent sandboxes and api bundles stage it beside
7
- ``server/main.py`` — so the World Host's grader, the SDK client
8
- (:mod:`gatewaysdk.world_sessions`) and the CLI all read this one module.
9
-
10
- The TypeScript source of truth is
11
- ``gateway/packages/shared/src/server/services/worldSessionContract.ts``;
12
- both are pinned to ``conformance/world-sessions.json`` by a test on each
13
- side, so the route, the World Host and the two CLIs cannot drift apart.
14
- """
1
+ """Stdlib only, inside ``gatewaysdk.environment``: that package is vendored alone into images, sandboxes and bundles."""
15
2
 
16
3
  from __future__ import annotations
17
4
 
18
5
  from datetime import datetime, timezone
19
6
 
20
- #: The largest body ``POST world-sessions/{id}/calls`` accepts. The CLI
21
- #: measures the serialized body against the byte count and refuses before
22
- #: sending; the label is what help and the refusal name.
23
7
  CALL_BODY_LIMIT_BYTES = 4 * 1024 * 1024
24
8
  CALL_BODY_LIMIT_LABEL = "4mb"
25
9
 
26
- #: ``session status`` warns once an unpinned session has less than this left.
27
10
  IDLE_WARNING_MINUTES = 5
28
11
 
29
- #: The most entries one page of the world request ledger holds, as the platform lists it
30
- #: and as a World Host drains a session's outbox.
31
12
  REQUEST_LOG_PAGE_MAX = 200
32
13
 
33
- #: How much of each body the request ledger keeps: the first this many bytes of its text.
34
14
  REQUEST_BODY_CAPTURE_BYTES = 64 * 1024
35
15
 
36
- #: What a World Host's heartbeat names to say it serves open sessions; the platform places an
37
- #: open session only on a host that does.
38
16
  OPEN_DOOR_FEATURE = "open-door"
39
17
 
40
- #: The code a session the World Host did not serve answers its request ledger read with.
18
+ WORLD_STATES_FEATURE = "world-states"
19
+
41
20
  REQUESTS_NOT_RECORDED = "requests_not_recorded"
42
21
 
43
- #: The task an exploratory session runs on when the caller names none, and
44
- #: the ``task.source`` the platform reports for it.
45
22
  EXPLORATORY_TASK: dict[str, str] = {"instruction": "exploratory session"}
46
23
  EXPLORATORY_TASK_SOURCE = "none"
47
24
 
48
- #: What a session that has no grader answers ``grade`` with, beside
49
- #: ``reward: null``.
50
25
  NO_GRADER_REASON = "no grader"
51
26
 
52
- #: Where a world's server and its runner find the token for the runner's
53
- #: ``/__world/*`` routes: set by the platform on a session pod's two
54
- #: containers, by the Batch runner on a world it boots.
55
27
  ADMIN_TOKEN_ENV = "WORLD_ADMIN_TOKEN"
56
28
 
57
- #: The code and words of a call by a route's name: a world's routes answer
58
- #: over its HTTP api, never through the tool door.
59
29
  NOT_A_TOOL = "not_a_tool"
60
30
  ROUTE_NOT_A_TOOL = "'{name}' is a route of this world, not a tool; call it over the session's api URL"
61
31
 
@@ -64,7 +34,10 @@ def route_not_a_tool(name: str) -> str:
64
34
  return ROUTE_NOT_A_TOOL.format(name=name)
65
35
 
66
36
 
67
- #: Why the benchmark runner's agent refuses an api bundle: it serves no tools.
37
+ BUNDLE_RUN_REFUSAL = (
38
+ "A world bundle runs nothing on its own: its member worlds run, opened together as one bundle session. "
39
+ "Run or open a member world."
40
+ )
68
41
  API_BUNDLE_RUN_REFUSAL = (
69
42
  "an api bundle serves no tools: its routes answer over its HTTP api and are never an agent's tools, so "
70
43
  "the benchmark runner's agent has nothing to call. Migrate it to a schema world (`gateway worlds migrate "
@@ -326,7 +326,7 @@ fields and the reward signature against the verifiers version you install.
326
326
 
327
327
  ```bash
328
328
  gateway benchmarks init ./crm-bench # custom contract: example entity, three tools, one verifier, one task
329
- gateway benchmarks init ./slack-bench --connector slack # a shipped template: the vendor's entities, routes and tools
329
+ gateway benchmarks init ./slack-bench --connector slack # an official template (needs a login): the vendor's entities, routes and tools
330
330
  gateway benchmarks init ./x --task onboard --prompt "Create an account for Acme." --model openai/gpt-5-mini -k 3
331
331
  ```
332
332
 
@@ -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 served. `subset` until a per-instance schema, a sandbox round trip and goldens exist. |
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's `create_custom_world` takes an authored `gateway-world/1` document, inline files, a sandbox tree or `--connector`-style `template` and publishes it through the trusted `compile` bridge (2026-09-09) |
79
- | Platform agent record ingestion (`ingest_records_to_world` → `platform.py apply-batch`, `ingest_to_world` file writes with recompile, `describe_world_schema`, `load_world_to_sandbox`) | exists; schema-gated, `batchId` idempotent, one immutable READY version per call, project-scoped; see `documentation/features/agent.md` |
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
- - [ ] SDK-shipped: commit authored files under `gatewaysdk/sdk/src/gatewaysdk/environment/schema/connectors/<slug>/`; `list_templates()` and `test_schema_scaffold.py` cover the slug and preserve its authored dependencies/provenance during initialization. Schema-only templates declare an empty tools map and have no operation handlers.
177
+ - [ ] Official: an official editor pushes the template tree into the official organization (`gateway worlds create <slug> --from <dir>` with `GATEWAY_TOKEN` + `GATEWAY_PROJECT_ID`, then publish it), and every reader serves it from that world's head (`gateway worlds schema templates`, `schema init --connector <slug>`, `worlds create --from <slug>`). Authored trees still sit under `gatewaysdk/sdk/src/gatewaysdk/environment/schema/connectors/<slug>/` until O4 moves them out; `tests/test_official_template_world.py` pins that a world built from the files is byte-identical to the old directory init. Schema-only templates declare an empty tools map and have no operation handlers.
178
178
  - [ ] Platform integration, if separately in scope: map an existing source kind in `schemaWorldTemplates.ts` so "Build from connector" offers it. Do not register a native provider or invent a source kind for an SDK-only schema milestone.
179
179
  - [ ] Treat `connectionMode` as the primary authentication path, not the only setup path. A managed connector may retain `remoteMcpPreset` as a fallback; render that action from the preset's presence. For native source connectors such as Slack, the source-backed Link action is the managed authentication path because native-provider dispatch intentionally precedes Merge.
180
180
  - [ ] User-added templates can use `--connector custom` and SDK publication. Generic schema upload and shared/project registry infrastructure remain unimplemented.
@@ -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` / `applyWorldBatch` are the pattern: file map
198
- in, `{entries, report, ...}` out, errors as `SchemaBridgeError`), cover it in
199
- `tests/environment/test_schema_platform.py`, and let the agent tool call the wrapper, never
200
- the subprocess. The bridge needs Python ≥ 3.12 (`tomllib`, and the store's sqlite `setconfig`); set `GATEWAY_SCHEMA_PYTHON`
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 has this loop as tools, all discoverable with `search_tools`:
361
- `get_connector_authoring_skill` (this file) → write `connector.toml` + `schema/` in the
362
- sandbox → `run_gateway_cli({ command: "connector validate" | "connector conform" | "schema check", args: [...] })`
363
- → `validate_connector_template({ files })` → `publish_connector({ slug, files, parentCommit? })`
364
- (needs `hub:write` and the session's `allowConnectorWrites`, else `confirm: true`; a moved
365
- head is refused by `parentCommit`, re-read with `get_connector`) → `init_world_from_connector`
366
- (the platform builds the world as its hosted api bundle; `worldSlug` sets the exact slug, else the
367
- name gets an 8-hex tail; poll `get_world_request` until READY, then `open_world_session` with the
368
- api surface serves the vendor's routes — no pull-and-push step) → `start_connector_capture({ containerId, op, args, params })` → `get_connector_capture({ …, downloadTo })`
369
- → `run_gateway_cli connector ingest` → `ingest_to_world`. `list_world_secrets` shows the env
370
- var names the world holds, never values; a `connector.toml` with an inline credential is
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)
@@ -40,9 +40,9 @@ layout: opt-in on create (`layout: "api-bundle"` / `--layout api-bundle`, the an
40
40
  `deprecations: [{code: "api-bundle-layout", …}]`), still served as an api session for the worlds
41
41
  that already use it, and every platform reader still resolves it through `schemaWorldPrefix` /
42
42
  `schemaWorldFiles` (`packages/shared/src/domain/worldSchema.ts`, the twin of the runtime's
43
- `world_root`). `gateway bench push` in the TypeScript CLI still packages a `connector.toml` tree on
44
- the way up (`isConnectorWorld` in `bench.ts`), as does `publishWorldTree` (the agent's
45
- `create_custom_world`); those are the remaining packaging sites. `gateway worlds migrate <slug>`
43
+ `world_root`). Nothing packages a `connector.toml` tree on the way up any more: `gateway bench push`
44
+ and `gateway worlds push` push the tree as it is (`versionVerbs.ts`), and `publishWorldTree`
45
+ (`worldPublicationService.ts`, now behind the world fixture seeder only) commits it as given. `gateway worlds migrate <slug>`
46
46
  (`POST /api/public/worlds/{slug}/migrate`, MCP `migrate_world`; `planWorldMigration` in
47
47
  `packages/shared/src/domain/worldMigration.ts`) restores a stored bundle to its tree — the source is
48
48
  inside the bundle under `server/world/`; the bundle's own scenarios are carried, its derived files
@@ -254,6 +254,7 @@ least one `[[operations]]` entry.
254
254
  | `[[operations]]` | `name`, `method`, `path`, `params`, `entity`, `results` | `path` may carry `{args}`; a `params` name keeps the vendor's spelling, dots included (`query.bibliographic`, `filter.overallStatus`), and may end in `[]` (`expand[]`, `status[]`) for a key the vendor repeats, which capture then sends repeated and the served route filters on any value of; `results` is the dotted path to the row array (empty when the body is the row). An operation without `entity` never seeds and answers 501 `not_modelled`. Routes are never tools: an agent calls them over HTTP (the api url and token `session open --surface api` prints), and a tool exists only where `x-gateway.tools` declares one with a handler. An `entity` (or an `explode` target) that `schema/world.json` does not declare is refused by `connector validate`, `schema compile`, `schema check` and the platform's describe (`gateway worlds describe`, local or platform) alike — `operation X lands on entity Y, which schema/world.json does not declare (declared: …)` at `/operations/<i>/entity` — and nothing is written; hand-edited TOML meets the same gate `route add` applies. |
255
255
  | `[operations.ingest]` | `drop`, `explode`, `carry_args` | `drop` removes vendor fields the entity does not carry; each `[[operations.ingest.explode]]` (`field`, `entity`, `carry`, `take`) turns a nested array into child rows; `carry_args = { account_id = "id" }` stamps the capture's path argument or query parameter onto every row before projection (a statement only knows its account from the URL it was fetched under). `connector ingest --dry-run [--report FILE]` lists every violation of every capture and writes nothing. |
256
256
  | `[operations.api]` | `filter`, `match`, `action`, `status`, `single`, `envelope`, `wrapper`, `page`, `body`, `defaults`, `generate`, `handler`, `sample`, `sample_headers`, `sample_body`, `not_found`, `not_found_status`, `cursor_absent_when_done` | `filter` maps a path argument or declared query parameter to the row field it selects on (case-insensitive, any depth; an absent parameter does not narrow, one sent more than once matches rows carrying any of its values); `match = { name = "contains" }` switches an argument from equality to substring or `prefix`, and a list field matches when any element does. `action` is `read` (default), `create`, `update`, `delete` or `handler`: writes persist through the contract, `body` maps row fields (dotted for nested) to request-body paths, `defaults` fixes constants, `generate` fills `uuid`, `int` or `now`; `update` and `delete` find their row through `filter` and answer the vendor's 404 otherwise; they, and a `single` read with a path argument, refuse (`finds its row by nothing`, 400) when neither `filter` nor a path argument naming a field selects a row, rather than act on some row; a singleton served under a scoped path answers through `action = "handler"`. `status` is the 2xx the vendor answers (201 for create, 204 for delete by default), `single` returns the row itself instead of an envelope, `envelope` and `page` override the world-wide setting per route. A dotted `envelope` nests the answer the way the vendor does (`message.items` answers `{message: {items, total-results, next-cursor}}`), and a single row is wrapped only by its own route's `envelope` (`message` answers `{message: row}`). `wrapper` is the rest of the vendor's envelope as a JSON object string (`'{"status": "ok", "message-type": "work-list"}'`), the answer laid onto it key by key; `schema init --from-openapi` writes it from the document. `handler` names a function `def name(ctx, args, query, body)` in the handlers module that returns a body, `(status, body)` or `(status, body, headers)`; `ctx` reads and writes the store (`rows`, `get`, `find`, `insert`, `update`, `delete`), keeps time (`now`, `elapsed`, `ladder` for status machines, frozen by `GATEWAY_WORLD_CLOCK`), mints ids (`uuid`) and shapes answers (`envelope`, `not_found`, `invalid`) and sees the request's `headers` and `query_all` (every value of every parameter, `{"expand[]": ["a", "b"]}`; the `query` argument keeps the first value only). `not_found` / `not_found_status` answer this route's missing row the vendor's own way (a 403 with its own message for one resource) and fall back to `[api]`; `cursor_absent_when_done` overrides `[api]` for this route. `sample = { ip = "203.0.113.5" }` gives the conformance run a value a validating route accepts when no seeded row can supply one; `sample_headers = { "Idempotency-Key" = "conform-1" }` and `sample_body = { reason = "conform" }` give it the headers and body a route demands (read by `connector conform` only; the served API never sends requests). |
257
+ | `[webhooks]` | `subscriptions`, `url`, `events`, `secret`, `enabled`, `scope`, `signing`, `signature_header` | Where the world's webhook subscriptions live and how the vendor signs what it sends (see Webhooks below). `subscriptions` names the entity agents register endpoints in through the vendor's own routes; `url`, `events`, `secret`, `enabled` and each `scope` value name its fields (checked against the contract at compile). `signing` is `svix`, `github`, `linear`, `stripe`, `hmac-sha256` (with `signature_header`) or `none`. |
257
258
 
258
259
  ### Scaffolding a route
259
260
 
@@ -319,6 +320,143 @@ does all of that from the same `connector.toml`:
319
320
  The handlers ship inside the api bundle beside the world, so the hosted container runs them
320
321
  with nothing installed. The abstraction is the platform's; the handlers are the customer's.
321
322
 
323
+ ## Webhooks
324
+
325
+ A vendor that notifies (AgentMail's `message.received`, GitHub's `push`) declares where its
326
+ subscriptions live, and a handler sends:
327
+
328
+ ```toml
329
+ [webhooks]
330
+ subscriptions = "webhooks" # the entity POST /v0/webhooks writes
331
+ url = "url"
332
+ events = "event_types" # absent or empty: every event
333
+ secret = "secret"
334
+ enabled = "enabled" # absent: on; false: off
335
+ scope = { inbox_id = "inbox_ids" } # a scoped event reaches a row whose list holds it, or is empty
336
+ signing = "svix"
337
+ ```
338
+
339
+ ```python
340
+ def send_message(ctx, args, query, body):
341
+ ...
342
+ ctx.deliver("message.sent", {"type": "event", "event_type": "message.sent", "message": message},
343
+ scope={"inbox_id": args["inbox_id"]})
344
+ ```
345
+
346
+ A tool sends the same way with `from gateway_env import webhooks` and `webhooks.deliver(...)`.
347
+ The GitHub (`ping`, `issues`, `issue_comment`, `pull_request`, `push`), Linear (`Issue`, `Comment`)
348
+ and Jamf (`ComputerAdded`) templates send from their routes; their agent tools write the same rows
349
+ and send nothing, so an agent that must be notified works through the routes.
350
+ Each subscription that is enabled, wants the event and holds its scope gets one delivery: the
351
+ body as JSON, signed with that subscription's secret the vendor's way (`svix-id`,
352
+ `svix-timestamp`, `svix-signature`; GitHub's `X-Hub-Signature-256`; Linear's bare hex `linear-signature`;
353
+ Stripe's `stripe-signature: t=…,v1=…` over `timestamp.body`; `sha256=` under a named
354
+ header). `deliver` answers the delivery ids. A delivery is kept only when the call that sent it
355
+ commits: a call that answers 4xx/5xx, breaks the contract or raises sends nothing, like its
356
+ writes.
357
+
358
+ On a World Host session every delivery lands in the world's request ledger with `via`
359
+ `webhook`: the event type as `operation`, the receiver's URL without its userinfo or query as
360
+ `path` (a segment carrying a credential `[redacted]`), the body, and status `0` until a receiver
361
+ answers. Of the headers the ledger keeps `content-type`, `svix-id`, `svix-timestamp`,
362
+ `x-github-event` and `x-github-delivery`; the signature is `[redacted]`.
363
+
364
+ Bounds: at most 100 deliveries per event (a subscription past the bound is skipped and logged),
365
+ 500 per call, and 256 KB per body. The body is frozen as JSON when `deliver` is called: what the
366
+ ledger keeps and a receiver gets is what was signed, whatever the handler does to its object after.
367
+ A handler that calls `deliver` wrongly (no `[webhooks]`, an empty event type, a scope key the table
368
+ does not declare, a body JSON cannot carry such as `NaN`, a body too large, a call past 500) gets
369
+ its own `400 handler` answer. A subscription whose secret the scheme cannot sign with, or whose
370
+ URL no receiver could be at (not http(s), no host, a port that does not parse), is skipped, never
371
+ the agent's refusal.
372
+ `gateway worlds requests <slug> --via webhook` lists them, and a check reads them like any
373
+ request: `{entity: "gateway_requests", where: {via: "webhook", operation: "message.received"}}`. A grader's `calls` never holds them: it is what the agent called.
374
+ ### Seeing and receiving them
375
+
376
+ - `gateway worlds session webhooks <id>` lists the subscriptions the session's world holds (url
377
+ without its userinfo or query, events, scope, on or off, how many deliveries each was sent since
378
+ the session's feed began; never a secret; the first 200). The session page shows the same as its
379
+ Webhooks section.
380
+ - `gateway worlds session listen <id> --forward-to http://localhost:3000/webhooks` forwards every
381
+ delivery to a receiver on your machine, each with its signed headers and exact body, so the
382
+ receiver verifies it with the secret the world returned when the webhook was registered. The
383
+ receiver's status (or `0` and why it never answered) goes back to the world's request ledger, once
384
+ per delivery. Only deliveries sent from now are forwarded unless `--replay` (a Svix receiver refuses
385
+ a delivery older than about 5 minutes). `--once` forwards every delivery the session holds and
386
+ exits; without it a failed poll is retried with backoff until Ctrl-C, except a session that ended, is
387
+ another project's or another engine's, which stops it with exit 1 (a session starting or being
388
+ recovered is retried).
389
+ - In the ledger a delivery's entry has the event type as `operation` and its id in
390
+ `query.delivery`; a receiver's answer is recorded under `<event type>.answer` with
391
+ `query.answer` naming the delivery. So `{entity: "gateway_requests", where: {via: "webhook",
392
+ operation: "message.received"}}` counts deliveries whether or not anyone was listening, and
393
+ `operation: "message.received.answer"` counts what receivers answered.
394
+ - The routes: `GET /api/public/world-sessions/{id}/webhooks?after&epoch&tail&limit` (read key:
395
+ subscriptions and which event went to which subscription and when; no signed header, payload or
396
+ URL) and `POST` the same with `{after, epoch, tail, limit, answers, subscriptions}` (secret key:
397
+ deliveries whole, the receivers' answers kept first). A session another project holds is 404; one
398
+ that is not running 409. A session on another engine answers 409 `webhooks_not_served`.
399
+ - The World Host keeps each session's last 500 deliveries, at most 8 MiB, whole for this; a page is at
400
+ most 100 deliveries and 4 MiB. The feed is in memory: a session that starts again (a restart, a move)
401
+ starts a fresh feed under a new `epoch`, and a poll naming the old one is read from the fresh feed's
402
+ start with `reset: true`; a page says how many deliveries left the feed unread (`missed`). The
403
+ ledger keeps every delivery. A delivered body is the body as signed when the handler sent it.
404
+
405
+ ### Pushing them to receivers on the internet
406
+
407
+ A project can have the platform deliver its worlds' webhooks itself: **Settings → General → World
408
+ webhooks → Send webhooks to their receivers** (off by default; a project admin or owner turns it on;
409
+ the change is in the audit log). While it is on, a worker job every 5 seconds reads each running World
410
+ Host session of the project, posts every new delivery to its subscription's URL with its signed headers
411
+ and exact body, and hands the receiver's answer back to the world's request ledger (`<event>.answer`,
412
+ the receiver's status or `0` and why). A session opened while push is on is pushed from its first
413
+ delivery; one that was already running when push was turned on starts at its feed's head, so turning
414
+ push on never replays what was sent before.
415
+
416
+ Only https on port 443 is pushed to. Every URL passes the platform's SSRF guard and the host is resolved
417
+ once: every address must be public (private, loopback, link-local, metadata, CGNAT, reserved, NAT64,
418
+ 6to4 and IPv6-local ranges are refused; an operator's `LANGFUSE_WEBHOOK_WHITELISTED_IPS` and
419
+ `_IP_SEGMENTS` also let a world's subscriptions reach the addresses they name, while
420
+ `_WHITELISTED_HOST` only skips the URL check: a listed host that resolves to a refused address is still
421
+ refused), and the connection goes to the address that was checked, so a DNS answer that changes
422
+ afterwards is never used. The world's `host` and connection headers are not forwarded. No redirect is
423
+ followed, an answer outside HTTP's 100–599 is recorded as `0` and why, a receiver has 10 seconds in all, its DNS included (however slowly it answers), and its
424
+ answer is read to 64 KB and dropped.
425
+
426
+ At most once per delivery: the relay moves its place past a delivery before sending it, so a failure
427
+ is recorded with its reason and never retried. Each session is sent by one lease holder at a time, and a
428
+ holder whose lease ran out can neither move the session's place nor send again, so two workers never
429
+ send one delivery twice. A session gets 20 seconds of sending per tick; the rest waits for the next.
430
+ One tick pushes at most 200 sessions: the share is split evenly between opted-in projects, a project
431
+ with fewer live sessions than its share passing the rest on, and each project's share starts after the
432
+ last session its previous share ended on (kept in Redis, whatever a tick's length, sessions opening and
433
+ closing between ticks included), so every live session is reached within about `ceil(live / share)`
434
+ ticks; when more are live than one tick takes, the worker
435
+ logs an error. Ticks repeat every 5 seconds, one at a time on each worker replica (replicas may overlap; the
436
+ per-session lease keeps them apart), and the project's setting is read again as each session's lease
437
+ is taken, so turning push off stops every session not already sending; a tick lasts as long as its slowest
438
+ sessions (16 in parallel, each up to 10 seconds to poll and 20 of sending), so a delivery usually
439
+ leaves within seconds and, under full load, within minutes. Turning push off and on again starts every
440
+ session that already existed at its feed's head: nothing a world sent while push was off is pushed
441
+ (saving the setting unchanged moves nothing). The first time the relay writes a session's place is recorded on
442
+ the session, so a session whose place in Redis is lost (a day without a tick, a Redis failover) starts
443
+ again at its feed's head, logged at error, and is never sent its feed a second time; deliveries in that
444
+ gap are not pushed. Answers to a session's last deliveries are lost if
445
+ the session closes before the next tick (the deliveries stay in the ledger at status 0). There is no
446
+ platform-wide off switch beyond each project's own. Every enabled subscription row receives, including rows a seed or
447
+ an import put there. `session listen` and push can run together; the first answer to a delivery is
448
+ the one kept.
449
+
450
+ A world can send a registered webhook somewhere else without touching the world:
451
+ **World settings → Webhook destinations**, or the pencil on a subscription in the session's Webhooks
452
+ section, maps a registered URL (its scheme, host, port and path; never its query or userinfo) to a
453
+ destination (`world_webhook_destinations`, `WorldWebhookDestinations`, project admins and owners,
454
+ audit-logged). The push relay sends every delivery whose subscription registered that URL, in every
455
+ session of the world, to the destination instead, signed as before; the subscription row, what the
456
+ agent reads back and the ledger's `path` stay the registered URL. A destination passes the same checks
457
+ as a push (https on 443, no credentials, the platform's URL guard) when it is saved and again at every
458
+ send. At most 100 per world; `session listen` is unaffected (it sends to its own `--forward-to`).
459
+
322
460
  ## Capturing from the platform
323
461
 
324
462
  A vendor that allow-lists a caller's IP (SpyCloud) cannot be captured from a laptop. The same
@@ -349,11 +487,14 @@ author `connector.toml` + `schema/` in the sandbox → `run_gateway_cli connecto
349
487
  (`environments:write`; the key comes from the world's Secrets tab — `list_world_secrets` shows
350
488
  names only, and a `connector.toml` that inlines a credential is refused) → `get_connector_capture`
351
489
  (status, redacted file metadata, and once complete a copy of the pages into
352
- `<sandbox dir>/captures/`) → `run_gateway_cli connector ingest` → `ingest_to_world`. The
353
- sandbox never holds the vendor key or a platform credential: capture runs server-side exactly as
354
- the `--remote` path above, and the CLI wrapper runs the same TypeScript `gateway` CLI this page
355
- documents (`node /tmp/gateway-cli/cli.js worlds …`, staged from the web image's build) pinned to
356
- its local runtime, with `GATEWAY_*`/`LANGFUSE_*` stripped and `--host`/`--remote` refused. Details in
490
+ `<sandbox dir>/captures/`) → `run_gateway_cli connector ingest ./dir` → `run_gateway_cli push ./dir`
491
+ (the world checked out with `pull <slug> --dir ./dir`). The sandbox never holds the vendor key:
492
+ capture runs server-side exactly as the `--remote` path above. The CLI wrapper runs the same
493
+ TypeScript `gateway` CLI this page documents (`node /tmp/gateway-cli/cli.js worlds …`, staged
494
+ from the web image's build) pinned to its local runtime. A command on `./dir` runs with
495
+ `GATEWAY_*`/`LANGFUSE_*` stripped; a command on a slug reaches the platform as the user through a
496
+ project key minted for that one call (valid only on the routes that verb calls, deleted when the call
497
+ ends); `--host` and key flags are refused. Details in
357
498
  [agent.md](agent.md#platform-actions-worlds-tasks-rollouts-connectors-ingestion-self-schedules).
358
499
 
359
500
  ## Conformance and scenarios
@@ -477,8 +618,8 @@ gateway worlds connector skill --install . # the authoring skill + agen
477
618
  - **Compile before accept.** Every push is run through the schema runtime on the platform
478
619
  (`validateConnectorTemplate`); a template that does not make a world is refused with a 400
479
620
  carrying the reason and nothing is committed. The digest is `template_digest`, the same
480
- algorithm an installed template pins with, so a workspace connector and an identical installed
481
- template pin identically.
621
+ algorithm an official template pins with (over its official world head's files), so a workspace
622
+ connector and an identical official template pin identically.
482
623
  - **Re-publishing is a commit.** A second publish to the same slug pulls the head, sends
483
624
  `parent_commit`, and deletes paths no longer in the directory, so the connector always equals
484
625
  the directory. `--workspace-visible` makes it visible to the whole workspace rather than the
@@ -491,10 +632,11 @@ gateway worlds connector skill --install . # the authoring skill + agen
491
632
  unless it is cloned again.
492
633
  - **Initializing from the platform's copy.** `--connector workspace:<slug>` pulls the head commit
493
634
  and calls `init_bundle_from_files`, the same path the platform's `init-template-files` bridge
494
- uses; the manifest records `connector = "<slug>"`. Logged out (or under the agent's
495
- local-only `run_gateway_cli`), `gateway worlds schema init --connector workspace:<slug>` refuses
635
+ uses; the manifest records `connector = "<slug>"`. Logged out,
636
+ `gateway worlds schema init --connector workspace:<slug>` refuses
496
637
  and names `gateway auth login`; the offline `python -m gatewaysdk.environment.schema init`
497
- refuses it the same way.
638
+ refuses it the same way. The agent's `run_gateway_cli` refuses it before running and names
639
+ `connector pull <slug> --out ./dir` instead.
498
640
  - **The agent CTA.** `gateway worlds connector skill` prints the `connector-schema-authoring`
499
641
  skill; `--install DIR` writes SKILL.md, CONVENTIONS.md and CONNECTORS.md plus the
500
642
  `connector-template-author` agent under `DIR/.claude/`, where Claude Code, Cursor and Codex