@withgateway/sdk 0.4.0 → 0.6.0

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 (94) hide show
  1. package/dist/cli.js +1128 -783
  2. package/dist/cli.js.map +1 -1
  3. package/dist/cli.mjs +1130 -785
  4. package/dist/cli.mjs.map +1 -1
  5. package/dist/files/index.js +47 -18
  6. package/dist/files/index.js.map +1 -1
  7. package/dist/files/index.mjs +47 -18
  8. package/dist/files/index.mjs.map +1 -1
  9. package/dist/{index-mJhG3vZU.d.mts → index-Di9nNqOY.d.mts} +26 -3
  10. package/dist/{index-DUHmS74p.d.ts → index-LA-PMRJT.d.ts} +26 -3
  11. package/dist/index.d.mts +3 -3
  12. package/dist/index.d.ts +3 -3
  13. package/dist/index.js +179 -43
  14. package/dist/index.js.map +1 -1
  15. package/dist/index.mjs +176 -43
  16. package/dist/index.mjs.map +1 -1
  17. package/dist/replay/index.d.mts +1 -1
  18. package/dist/replay/index.d.ts +1 -1
  19. package/dist/replay/index.js.map +1 -1
  20. package/dist/replay/index.mjs.map +1 -1
  21. package/dist/traces/index.js +47 -18
  22. package/dist/traces/index.js.map +1 -1
  23. package/dist/traces/index.mjs +47 -18
  24. package/dist/traces/index.mjs.map +1 -1
  25. package/dist/tracing/index.d.mts +1 -1
  26. package/dist/tracing/index.d.ts +1 -1
  27. package/dist/tracing/index.js +1 -1
  28. package/dist/tracing/index.js.map +1 -1
  29. package/dist/tracing/index.mjs +1 -1
  30. package/dist/tracing/index.mjs.map +1 -1
  31. package/dist/worlds/index.d.mts +184 -85
  32. package/dist/worlds/index.d.ts +184 -85
  33. package/dist/worlds/index.js +176 -43
  34. package/dist/worlds/index.js.map +1 -1
  35. package/dist/worlds/index.mjs +176 -43
  36. package/dist/worlds/index.mjs.map +1 -1
  37. package/package.json +1 -1
  38. package/runtime/gatewaysdk/environment/_bundle.py +4 -6
  39. package/runtime/gatewaysdk/environment/_world.py +24 -1
  40. package/runtime/gatewaysdk/environment/runtime.py +45 -2
  41. package/runtime/gatewaysdk/environment/schema/api.py +24 -3
  42. package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +1 -0
  43. package/runtime/gatewaysdk/environment/schema/call_capture.py +13 -1
  44. package/runtime/gatewaysdk/environment/schema/call_log.py +46 -0
  45. package/runtime/gatewaysdk/environment/schema/call_redaction.py +6 -0
  46. package/runtime/gatewaysdk/environment/schema/compiler.py +4 -1
  47. package/runtime/gatewaysdk/environment/schema/conform.py +32 -8
  48. package/runtime/gatewaysdk/environment/schema/connector.py +5 -0
  49. package/runtime/gatewaysdk/environment/schema/connectors/custom/handlers.py +2 -1
  50. package/runtime/gatewaysdk/environment/schema/connectors/github/api/handlers.py +217 -58
  51. package/runtime/gatewaysdk/environment/schema/connectors/github/connector.toml +9 -19
  52. package/runtime/gatewaysdk/environment/schema/connectors/github/scenarios/default/seed/github_webhooks.json +10 -2
  53. package/runtime/gatewaysdk/environment/schema/connectors/github/tests/webhooks.json +47 -0
  54. package/runtime/gatewaysdk/environment/schema/connectors/github/world.json +21 -0
  55. package/runtime/gatewaysdk/environment/schema/connectors/jamf/api/handlers.py +185 -18
  56. package/runtime/gatewaysdk/environment/schema/connectors/jamf/connector.toml +29 -14
  57. package/runtime/gatewaysdk/environment/schema/connectors/jamf/provenance.json +43 -12
  58. package/runtime/gatewaysdk/environment/schema/connectors/jamf/scenarios/default/seed/jamf_webhooks.json +2 -2
  59. package/runtime/gatewaysdk/environment/schema/connectors/jamf/scope.toml +4 -17
  60. package/runtime/gatewaysdk/environment/schema/connectors/jamf/tests/webhooks.json +107 -0
  61. package/runtime/gatewaysdk/environment/schema/connectors/jamf/vendor-openapi.json +1 -1
  62. package/runtime/gatewaysdk/environment/schema/connectors/linear/api/handlers.py +85 -1
  63. package/runtime/gatewaysdk/environment/schema/connectors/linear/connector.toml +19 -31
  64. package/runtime/gatewaysdk/environment/schema/connectors/linear/provenance.json +18 -8
  65. package/runtime/gatewaysdk/environment/schema/connectors/linear/scenarios/default/seed/webhooks.json +19 -3
  66. package/runtime/gatewaysdk/environment/schema/connectors/linear/tests/test_webhooks.py +71 -0
  67. package/runtime/gatewaysdk/environment/schema/database/guard.py +2 -1
  68. package/runtime/gatewaysdk/environment/schema/handler_errors.py +27 -1
  69. package/runtime/gatewaysdk/environment/schema/journal.py +4 -3
  70. package/runtime/gatewaysdk/environment/schema/local.py +1 -0
  71. package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +20 -5
  72. package/runtime/gatewaysdk/environment/schema/platform.py +16 -219
  73. package/runtime/gatewaysdk/environment/schema/runtime.py +7 -0
  74. package/runtime/gatewaysdk/environment/schema/scaffold.py +2 -1
  75. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/CONNECTORS.md +3 -3
  76. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +19 -22
  77. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +7 -9
  78. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +3 -3
  79. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +14 -11
  80. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +36 -5
  81. package/runtime/gatewaysdk/environment/schema/snapshot.py +2 -2
  82. package/runtime/gatewaysdk/environment/schema/tools_world.py +19 -0
  83. package/runtime/gatewaysdk/environment/schema/verbs.py +6 -0
  84. package/runtime/gatewaysdk/environment/schema/webhooks.py +687 -0
  85. package/runtime/gatewaysdk/environment/schema/world_host.py +20 -3
  86. package/runtime/gatewaysdk/environment/schema/world_tests.py +74 -0
  87. package/skills/connector-schema-authoring/CONNECTORS.md +3 -3
  88. package/skills/connector-schema-authoring/SKILL.md +19 -22
  89. package/skills/connector-schema-authoring/connector-worlds.md +153 -11
  90. package/skills/connector-schema-authoring/world-schema.md +7 -6
  91. package/skills/world-data-ingestion/SKILL.md +7 -9
  92. package/skills/worlds-getting-started/SKILL.md +3 -3
  93. package/skills/worlds-getting-started/references/cli-mcp-map.md +14 -11
  94. package/skills/worlds-getting-started/references/gotchas.md +36 -5
@@ -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
 
@@ -220,13 +220,11 @@ policy (`drop`, `hash` as `sha256:<hex>` of `<slug>:<value>`, `preserve` as a sa
220
220
  same-character-class hash for identifiers, `round`) unless `--no-redact`. Output is tagged
221
221
  JSONL; the summary `{"read", "rows", "unknownFields", "redacted"}` is on stderr.
222
222
 
223
- Platform agent (console): the same `import_world_data`, plus `sandboxPath` for a rows file
224
- already in the sandbox (any ROWS form above; `entity` for bare arrays/JSONL) instead of
225
- `rows` — build the file with code, then import; do not paste 4 MiB through `rows`.
226
- `run_gateway_cli({ command: "data show" | "data check" | "data import" | "data extract", args: ["/workspace/<world>", ...] })`
227
- is the local-directory form for a world you `load_world_to_sandbox`ed (same flags as above, no remote
228
- slugs); land the result with `ingest_to_world`. Capture pages are not rows: `get_connector_capture(downloadTo)` →
229
- `run_gateway_cli connector ingest` → `ingest_to_world`.
223
+ Platform agent (console): the same CLI, through `run_gateway_cli` in its sandbox. Build the rows
224
+ file with code, then `run_gateway_cli({ command: "data import", args: ["<slug>", "./rows.jsonl", "--dry-run"] })`
225
+ and again without `--dry-run`; a slug reaches the platform as the user, a `./dir` stays in the
226
+ sandbox. Capture pages are not rows: `get_connector_capture(downloadTo)` →
227
+ `run_gateway_cli connector ingest ./<world>` → `push ./<world>`.
230
228
 
231
229
  ### 2c. Turn tool calls into rows: pull, transform, ingest
232
230
 
@@ -362,7 +360,7 @@ operations route by name; `captureToolCalls(tools, sink)` records the calls). Py
362
360
  redact="off", dry_run=False)` and `ingest_tool_calls`; `capture_tool_calls`. Bridge:
363
361
  `ingest-calls {files, records, map?, redact?, dry_run?, mode?}` → the report + `projected`
364
362
  rows (+ `files` when the tree changed); transforms never run in the bridge. No MCP twin yet;
365
- the console agent has `run_gateway_cli data ingest` on a sandboxed directory.
363
+ the console agent runs the same `data ingest` through `run_gateway_cli`.
366
364
 
367
365
  ### 2d. Rows generated or downloaded inside a sandbox
368
366
 
@@ -155,7 +155,7 @@ environment; land them with `env_commit({ containerId, changeReason })` (one ver
155
155
  Tool handlers (`tools/*.py`) reach the world's rows through `from gateway_env import store`. It has
156
156
  exactly these methods; `gateway worlds schema check .` refuses any other `store.<name>` at file:line
157
157
  with this list, and a hosted call into such a handler answers 400 `{error: "handler", detail, handler}`
158
- (an `AttributeError`/`TypeError`/`NameError` is the author's bug; anything else a handler raises is a
158
+ (an `AttributeError`/`TypeError`/`NameError` is the author's bug; `raise Refusal(404, body)` (imported from `gateway_env` at module top) answers that 4xx and body; anything else a handler raises is a
159
159
  500 `{error: "engine", detail, handler}`; never a bare exception string).
160
160
 
161
161
  - `get(entity: str, key: dict) -> dict | None` — one row by primary key, or `None`.
@@ -192,7 +192,7 @@ gateway worlds describe ./x # entities, keys, re
192
192
  gateway worlds data show ./x # kind + entity counts
193
193
  gateway worlds data query ./x users --where email=jo@acme.test --resolve # the rows you mean; plaintext into a hashed field
194
194
  gateway worlds data import ./x rows.json # rows file: {entity: [rows]} | JSONL | .csv/.tsv --entity (cells cast by the schema; --delimiter)
195
- gateway files fetch https://example.test/rows.csv --to imports/rows.csv --header "Authorization: Bearer {{secret:API_KEY}}" # the platform fetches; the secret never leaves it
195
+ gateway files fetch https://example.test/rows.csv --to imports/rows.csv --header "Authorization: Bearer {{secret:API_KEY}}" # the platform fetches; the secret goes only to origins it lists (gateway secret origins API_KEY https://example.test)
196
196
  gateway worlds connector capture ./x --op <name> --arg k=v # from the real vendor, redacted
197
197
  gateway worlds connector ingest ./x # captures -> data/initial.json; `--dry-run --report` checks only, nothing written
198
198
  gateway worlds data calls pull calls.jsonl --from traces --session <id> # an agent's real calls, raw; prints records per tool + result shapes
@@ -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] [--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
  ```
@@ -21,16 +21,17 @@ Reference for `worlds-getting-started`: every CLI step and its MCP twin, then ho
21
21
  | `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
22
  | `worlds session seed` | `seed_world_session` |
23
23
  | `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 |
24
+ | `worlds requests [list] <slug> [--session <id>] [--version <ref>] [--via api\|ui\|tool\|webhook] [--operation <name>] [--status 200\|2xx\|4xx\|5xx] [--since <time>] [--until <time>] [--limit N] [--cursor <c>] [--json]` | `list_world_requests({ slug, sessionId?, versionId?, via?, operation?, status?, since?, until?, cursor?, limit? })` (`GET /api/public/worlds/{slug}/requests`): every request the world received, from every session, version and door (`via` api, ui, tool, webhook), newest first, a page of at most 200 with `nextCursor`; metadata only (method, path, query, status, rows, found, duration, each body's size and `truncated`). The world keeps them for its life under the project's retention setting, and reading records nothing in any session's ledger. `--since`/`--until` take an ISO 8601 date or time (no zone is UTC); a bad filter is exit 2 before any request. UI: the world's Requests view, the session page's activity feed |
25
25
  | `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
26
  | `worlds session requests <sessionId>` (the list's filters but `--session`/`--version`) | `list_world_requests({ slug, sessionId })` (the CLI reads `GET /api/public/world-sessions/{id}/requests`, the world's list for one session; both MCP tools call the platform's `WorldRequestLedger` directly). A session whose engine is not the World Host records no requests: the route answers 409 `requests_not_recorded`, the CLI prints its one line and exits 3, and `session export --requests` notes the same line on stderr and writes the call log. `worlds requests <slug> --session <id>` and `list_world_requests({ slug, sessionId })` answer such a session the same way: 409, exit 3, the tool's error naming the engine |
27
+ | `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
28
  | `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
29
  | `worlds session restart <id> [--version <pin>]` | `restart_world_session` (`POST /api/public/world-sessions/{id}/restart` `{version?}`: a running or closed session's world started over on its pin's current version, or `version`, which becomes the pin, under the same id, URLs and token; base data plus the task's seed. The route and the CLI answer what `status` answers plus `restart: {previousVersionId, versionId, pin, boundarySeq, boundaryAt}`; the MCP tool answers the `restart` block with `sessionId`. A request the old world received has an `at` before `boundaryAt`, and a grade reads only those after it. 409 `session_not_restartable` / `session_version_unavailable` / `session_reopen_in_progress` / `no_open_door`; 503 when the new world did not open) |
29
- | `worlds data calls pull` / `worlds data ingest [--transform\|--map]` | — (no MCP twin yet; `run_gateway_cli data ingest` on a sandboxed directory) |
30
+ | `worlds data calls pull` / `worlds data ingest [--transform\|--map]` | — (no MCP twin yet; the platform agent runs it through `run_gateway_cli`) |
30
31
  | `files upload <local>... [--to]` | `request_file_upload` + `confirm_file_upload` (`upload_file` for ≤25 MB inline) |
31
32
  | `files list [path]` / `files get <path>` / `files download\|cat <path>` | `list_files` / `get_file` (a presigned URL; the CLI streams it) |
32
33
  | `files delete` / `files move` / `files mkdir` | `delete_file` / `move_file` / `create_folder` |
33
- | `files fetch <url> --to <path> [--header "Name: value"]...` | `download_url_to_drive` (`POST /api/public/files/fetch`; the platform fetches, nothing passes through the caller's machine; a header value may name a project secret as `{{secret:NAME}}`, expanded on the platform and never returned; `--local` fetches from the caller's machine instead, without secrets) |
34
+ | `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
35
  | `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
36
  | `files connectors list\|sync <id>` | `list_file_connectors` / `sync_file_connector` (`GET\|POST /api/public/files/connectors[/sync]`) |
36
37
  | `traces list\|get\|export [--observations]` | `get_trace`, `get_observations` (`GET /api/public/traces[/{id}]`, `/observations`) |
@@ -66,11 +67,13 @@ before it makes a request.
66
67
 
67
68
  ## The platform agent
68
69
 
69
- The platform (console) agent has every MCP tool in this table as an agent tool of the
70
- same name, plus `run_gateway_cli` for the *local* CLI rows (`schema init|templates|compile|check|describe|api-bundle`,
71
- `connector validate|conform|ingest|skill`, `data show|import|check|extract`, `skill`) inside its sandbox
72
- — structured `{ command, args }` with this CLI's exact flags (the TypeScript `gateway`, run as
73
- `node /tmp/gateway-cli/cli.js worlds …`), paths under `/workspace`, no remote flags, no platform
74
- credentials — and `spawn_subagent` / `wait_for_subagent` to hand one world or connector
75
- each to a tool-restricted child. Everything that writes to the platform goes through the
76
- MCP-twin tools, gated by capabilities and the session's autonomy settings.
70
+ The platform (console) agent edits worlds with this CLI, through `run_gateway_cli` in its
71
+ sandbox: structured `{ command, args }` with the CLI's exact flags (the TypeScript `gateway`,
72
+ run as `node /tmp/gateway-cli/cli.js worlds …`), paths under `/workspace`. A `./dir` runs in
73
+ the sandbox; a slug (`list`, `describe`, `create`, `pull`, `push`, `data …`, `test`, `session …`,
74
+ `requests …`, `edit …`, `connector list|pull|publish|clone`) reaches the platform as the user,
75
+ through a key minted for that one call, valid only on the routes that verb calls and deleted
76
+ when the call ends. A read verb needs read access, a write verb world-write access; `create`
77
+ and `session open` also need the session's `provisionWorlds` (or `confirm: true`),
78
+ `connector publish|clone` its `allowConnectorWrites`. `spawn_subagent` / `wait_for_subagent` hand one world or connector each to a
79
+ tool-restricted child.
@@ -4,13 +4,13 @@ The things that bite once and never again, moved out of `SKILL.md` to keep it un
4
4
 
5
5
  - A shipped template (`schema init ./x --connector salesforce`) scaffolds offline through the
6
6
  bundled runtime: no host, no keys, no config file read. Only `--connector workspace:<slug>`
7
- needs the platform — without `gateway auth login` or the `GATEWAY_*` keys (the agent's
8
- local-only `run_gateway_cli` included) `schema init` refuses it and names `--host`,
7
+ needs the platform — without `gateway auth login` or the `GATEWAY_*` keys (the platform
8
+ agent's `run_gateway_cli` included: its local commands carry no key) `schema init` refuses it and names `--host`,
9
9
  `GATEWAY_HOST` and the login command. No `python3 >= 3.12`? A shipped template scaffolds
10
10
  on the platform instead, so there it does need a host.
11
- - `bench push` (the TS CLI) on a world with `connector.toml` still packages an api-kind bundle
12
- on the way up; `worlds create --from ./x` stores the tree as it is, and `worlds migrate`
13
- turns a pushed bundle back into the tree. Either way, edit the schema world, not the bundle.
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.