@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.
- package/dist/cli.js +1128 -783
- package/dist/cli.js.map +1 -1
- package/dist/cli.mjs +1130 -785
- package/dist/cli.mjs.map +1 -1
- package/dist/files/index.js +47 -18
- package/dist/files/index.js.map +1 -1
- package/dist/files/index.mjs +47 -18
- package/dist/files/index.mjs.map +1 -1
- package/dist/{index-mJhG3vZU.d.mts → index-Di9nNqOY.d.mts} +26 -3
- package/dist/{index-DUHmS74p.d.ts → index-LA-PMRJT.d.ts} +26 -3
- package/dist/index.d.mts +3 -3
- package/dist/index.d.ts +3 -3
- package/dist/index.js +179 -43
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +176 -43
- package/dist/index.mjs.map +1 -1
- package/dist/replay/index.d.mts +1 -1
- package/dist/replay/index.d.ts +1 -1
- package/dist/replay/index.js.map +1 -1
- package/dist/replay/index.mjs.map +1 -1
- package/dist/traces/index.js +47 -18
- package/dist/traces/index.js.map +1 -1
- package/dist/traces/index.mjs +47 -18
- package/dist/traces/index.mjs.map +1 -1
- package/dist/tracing/index.d.mts +1 -1
- package/dist/tracing/index.d.ts +1 -1
- package/dist/tracing/index.js +1 -1
- package/dist/tracing/index.js.map +1 -1
- package/dist/tracing/index.mjs +1 -1
- package/dist/tracing/index.mjs.map +1 -1
- package/dist/worlds/index.d.mts +184 -85
- package/dist/worlds/index.d.ts +184 -85
- package/dist/worlds/index.js +176 -43
- package/dist/worlds/index.js.map +1 -1
- package/dist/worlds/index.mjs +176 -43
- package/dist/worlds/index.mjs.map +1 -1
- package/package.json +1 -1
- package/runtime/gatewaysdk/environment/_bundle.py +4 -6
- package/runtime/gatewaysdk/environment/_world.py +24 -1
- package/runtime/gatewaysdk/environment/runtime.py +45 -2
- package/runtime/gatewaysdk/environment/schema/api.py +24 -3
- package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +1 -0
- package/runtime/gatewaysdk/environment/schema/call_capture.py +13 -1
- package/runtime/gatewaysdk/environment/schema/call_log.py +46 -0
- package/runtime/gatewaysdk/environment/schema/call_redaction.py +6 -0
- package/runtime/gatewaysdk/environment/schema/compiler.py +4 -1
- package/runtime/gatewaysdk/environment/schema/conform.py +32 -8
- package/runtime/gatewaysdk/environment/schema/connector.py +5 -0
- package/runtime/gatewaysdk/environment/schema/connectors/custom/handlers.py +2 -1
- package/runtime/gatewaysdk/environment/schema/connectors/github/api/handlers.py +217 -58
- package/runtime/gatewaysdk/environment/schema/connectors/github/connector.toml +9 -19
- package/runtime/gatewaysdk/environment/schema/connectors/github/scenarios/default/seed/github_webhooks.json +10 -2
- package/runtime/gatewaysdk/environment/schema/connectors/github/tests/webhooks.json +47 -0
- package/runtime/gatewaysdk/environment/schema/connectors/github/world.json +21 -0
- package/runtime/gatewaysdk/environment/schema/connectors/jamf/api/handlers.py +185 -18
- package/runtime/gatewaysdk/environment/schema/connectors/jamf/connector.toml +29 -14
- package/runtime/gatewaysdk/environment/schema/connectors/jamf/provenance.json +43 -12
- package/runtime/gatewaysdk/environment/schema/connectors/jamf/scenarios/default/seed/jamf_webhooks.json +2 -2
- package/runtime/gatewaysdk/environment/schema/connectors/jamf/scope.toml +4 -17
- package/runtime/gatewaysdk/environment/schema/connectors/jamf/tests/webhooks.json +107 -0
- package/runtime/gatewaysdk/environment/schema/connectors/jamf/vendor-openapi.json +1 -1
- package/runtime/gatewaysdk/environment/schema/connectors/linear/api/handlers.py +85 -1
- package/runtime/gatewaysdk/environment/schema/connectors/linear/connector.toml +19 -31
- package/runtime/gatewaysdk/environment/schema/connectors/linear/provenance.json +18 -8
- package/runtime/gatewaysdk/environment/schema/connectors/linear/scenarios/default/seed/webhooks.json +19 -3
- package/runtime/gatewaysdk/environment/schema/connectors/linear/tests/test_webhooks.py +71 -0
- package/runtime/gatewaysdk/environment/schema/database/guard.py +2 -1
- package/runtime/gatewaysdk/environment/schema/handler_errors.py +27 -1
- package/runtime/gatewaysdk/environment/schema/journal.py +4 -3
- package/runtime/gatewaysdk/environment/schema/local.py +1 -0
- package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +20 -5
- package/runtime/gatewaysdk/environment/schema/platform.py +16 -219
- package/runtime/gatewaysdk/environment/schema/runtime.py +7 -0
- package/runtime/gatewaysdk/environment/schema/scaffold.py +2 -1
- package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/CONNECTORS.md +3 -3
- package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +19 -22
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +7 -9
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +3 -3
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +14 -11
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +36 -5
- package/runtime/gatewaysdk/environment/schema/snapshot.py +2 -2
- package/runtime/gatewaysdk/environment/schema/tools_world.py +19 -0
- package/runtime/gatewaysdk/environment/schema/verbs.py +6 -0
- package/runtime/gatewaysdk/environment/schema/webhooks.py +687 -0
- package/runtime/gatewaysdk/environment/schema/world_host.py +20 -3
- package/runtime/gatewaysdk/environment/schema/world_tests.py +74 -0
- package/skills/connector-schema-authoring/CONNECTORS.md +3 -3
- package/skills/connector-schema-authoring/SKILL.md +19 -22
- package/skills/connector-schema-authoring/connector-worlds.md +153 -11
- package/skills/connector-schema-authoring/world-schema.md +7 -6
- package/skills/world-data-ingestion/SKILL.md +7 -9
- package/skills/worlds-getting-started/SKILL.md +3 -3
- package/skills/worlds-getting-started/references/cli-mcp-map.md +14 -11
- package/skills/worlds-getting-started/references/gotchas.md +36 -5
|
@@ -75,8 +75,8 @@ registration, a platform builder, live ingestion, tools, or a registry framework
|
|
|
75
75
|
| `gateway worlds schema import PATH --from <kind> --spec <url\|path> [--scope scope.toml]` | not implemented; author the contract and provenance manually |
|
|
76
76
|
| `gateway worlds schema parity PATH --surface <tools-list.json> \| --connection <id>` (advisory report) | not implemented |
|
|
77
77
|
| `gateway worlds playground <connector>` | not implemented |
|
|
78
|
-
| Platform upload of a JSON Schema, OpenAPI, or DDL as a new connector | not implemented as a UI upload; the platform agent
|
|
79
|
-
| Platform agent record ingestion
|
|
78
|
+
| Platform upload of a JSON Schema, OpenAPI, or DDL as a new connector | not implemented as a UI upload; the platform agent authors the tree in its sandbox and runs `gateway worlds create <slug> --from ./dir` through `run_gateway_cli`, the same door as the CLI (2026-10-10) |
|
|
79
|
+
| Platform agent record ingestion | the CLI's own `data import <slug>`, `pull`, `push` and `describe` through `run_gateway_cli`; see `documentation/features/agent.md` |
|
|
80
80
|
| SDK/public and platform publication | validates assembled files and actual stored archive bytes through the trusted compiler/materializer, including READY/dedup/ref paths |
|
|
81
81
|
| Connectors Slack world creation | durable structured capture → shared Python mapper → immutable publication; explicit synthetic mode |
|
|
82
82
|
| Worker schema tests/workbench | shared validation and isolated E2B author execution; missing isolation is non-green |
|
|
@@ -143,7 +143,7 @@ deliverable can finish with synthetic fixtures and explicitly skipped live valid
|
|
|
143
143
|
Tool handlers (`tools/*.py`) reach the world's rows through `from gateway_env import store`. It has
|
|
144
144
|
exactly these methods; `gateway worlds schema check .` refuses any other `store.<name>` at file:line
|
|
145
145
|
with this list, and a hosted call into such a handler answers 400 `{error: "handler", detail, handler}`
|
|
146
|
-
(an `AttributeError`/`TypeError`/`NameError` is the author's bug; anything else a handler raises is a
|
|
146
|
+
(an `AttributeError`/`TypeError`/`NameError` is the author's bug; `raise Refusal(404, body)` (imported from `gateway_env` at module top) answers that 4xx and body; anything else a handler raises is a
|
|
147
147
|
500 `{error: "engine", detail, handler}`; never a bare exception string). A route's handler answers the
|
|
148
148
|
same way on every door, and an answer JSON cannot carry (a `datetime`, a set, NaN) is its 400; a route
|
|
149
149
|
answering bytes names its `Content-Type` (a vendor's `404 text/plain`), and the bytes go out as sent.
|
|
@@ -194,10 +194,11 @@ No `upsert`: `get`, then `insert` or `update`. Read-only SQL: `gateway_env.db.on
|
|
|
194
194
|
## Runtime authoring boundary
|
|
195
195
|
|
|
196
196
|
When adding a bridge command to `schema/platform.py`, mirror it as a typed wrapper in
|
|
197
|
-
`worldSchemaRuntime.ts` (`compileWorldFiles` / `
|
|
198
|
-
in, `{entries,
|
|
199
|
-
`tests/environment/test_schema_platform.py`, and let
|
|
200
|
-
the subprocess
|
|
197
|
+
`worldSchemaRuntime.ts` (`compileWorldFiles` / `importWorldData` are the pattern: file map
|
|
198
|
+
in, `{entries, ...}` out, errors as `SchemaBridgeError`), cover it in
|
|
199
|
+
`tests/environment/test_schema_platform.py`, and let a service call the wrapper, never
|
|
200
|
+
the subprocess; the public `/api/public/worlds/runtime` route reaches only the commands in
|
|
201
|
+
`WORLD_RUNTIME_COMMANDS`. The bridge needs Python ≥ 3.12 (`tomllib`, and the store's sqlite `setconfig`); set `GATEWAY_SCHEMA_PYTHON`
|
|
201
202
|
when the default interpreter is older.
|
|
202
203
|
|
|
203
204
|
Use `worldSchemaRuntime.ts` for platform validation and `schema.platform` for
|
|
@@ -357,21 +358,17 @@ redacted pages back into `captures/`.
|
|
|
357
358
|
|
|
358
359
|
### From the platform agent (no checkout)
|
|
359
360
|
|
|
360
|
-
The console agent
|
|
361
|
-
`
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
(
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
refused before anything is queued. `run_gateway_cli` runs the TypeScript `gateway worlds …` CLI
|
|
372
|
-
(the same flags as this page) staged into the sandbox, local-only (paths under `/workspace`,
|
|
373
|
-
no `--host`/`--remote`/`workspace:<slug>`, platform env stripped, pinned to its local runtime),
|
|
374
|
-
so publishing always goes through the tools above. To parallelise several connectors, `spawn_subagent` with a brief
|
|
361
|
+
The console agent runs the CLI on this page through `run_gateway_cli` in its sandbox: write
|
|
362
|
+
`connector.toml` + `schema/` under `./acme` → `connector validate ./acme`, `connector conform ./acme --openapi ./spec.json`,
|
|
363
|
+
`schema check ./acme`, `test ./acme` → `create acme --from ./acme` (billed: the session's
|
|
364
|
+
`provisionWorlds` or `confirm: true`) → `start_connector_capture({ containerId, op, args, params })` →
|
|
365
|
+
`get_connector_capture({ …, downloadTo })` → `connector ingest ./acme` → `push ./acme`, then
|
|
366
|
+
`edit close acme`. `connector publish ./acme` makes it a workspace connector (`hub:write` and
|
|
367
|
+
`allowConnectorWrites`, else `confirm: true`). A `./dir` runs in the sandbox; a slug reaches the
|
|
368
|
+
platform as the user through a key minted for that one call, valid only on the routes that verb calls and
|
|
369
|
+
deleted when the call ends; `--host` and key flags are refused. `list_world_secrets` shows the
|
|
370
|
+
env var names the world holds, never values; a `connector.toml` with an inline credential is
|
|
371
|
+
refused before anything is queued. To parallelise several connectors, `spawn_subagent` with a brief
|
|
375
372
|
naming only the tools that child needs (`allowSubagents` on the session).
|
|
376
373
|
|
|
377
374
|
### From the CLI sandbox (no checkout, no Python)
|
|
@@ -109,7 +109,7 @@ gateway worlds data query <WORLD> users --where email=jo@acme.test --resolve #
|
|
|
109
109
|
gateway worlds data sql <WORLD> 'SELECT id, name FROM users LIMIT 5' # read-only SQL, any engine
|
|
110
110
|
```
|
|
111
111
|
|
|
112
|
-
`data sql` runs ONE read-only statement (joins, `GROUP BY`, counts) over a schema world's entity tables,
|
|
112
|
+
`data sql` runs ONE read-only statement (joins, `GROUP BY`, counts) over a schema world's entity tables (and `json_each` / `json_tree` over their JSON),
|
|
113
113
|
whatever its database engine: a write, `ATTACH`, `PRAGMA` or a second statement is refused; at most 1000 rows
|
|
114
114
|
(`--limit`). MCP twin: `sql_world_data({ slug, sql, limit? })`. A db/schema.sql world is a SQLite file: `sqlite3`.
|
|
115
115
|
|
|
@@ -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
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
slugs); land the result with `ingest_to_world`. Capture pages are not rows: `get_connector_capture(downloadTo)` →
|
|
229
|
-
`run_gateway_cli connector ingest` → `ingest_to_world`.
|
|
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
|
|
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
|
|
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;
|
|
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
|
|
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
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
`
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
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.
|
package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md
CHANGED
|
@@ -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
|
|
8
|
-
|
|
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`
|
|
12
|
-
on the way up
|
|
13
|
-
|
|
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.
|
|
@@ -37,7 +37,7 @@ the **pin** (:class:`SnapshotPin`): the hosted snapshot's ``batchDigest`` (and s
|
|
|
37
37
|
fields), which replaces the data files as the default batch. The tree's ``data/*.json``
|
|
38
38
|
then no longer describes the world's data — only that snapshot does — so a pinned tree
|
|
39
39
|
is never rebuilt from, nor served from, its data files; the platform hands the file
|
|
40
|
-
down (``
|
|
40
|
+
down (``gateway worlds sandbox open``, the pod's ``WORLD_SNAPSHOT_*``). Where the file is not
|
|
41
41
|
handed down (a sandbox), the pin itself proves which domain the hosted rows were stored
|
|
42
42
|
under, so the contract still compiles and checks.
|
|
43
43
|
|
|
@@ -330,7 +330,7 @@ class SnapshotStore:
|
|
|
330
330
|
"""How a refusal of a pinned snapshot neither the tree nor this store holds ends."""
|
|
331
331
|
if self.root is None:
|
|
332
332
|
return (
|
|
333
|
-
": run the world on the platform (`gateway worlds session open <slug>`,
|
|
333
|
+
": run the world on the platform (`gateway worlds session open <slug>`, `gateway worlds sandbox open <slug>`), "
|
|
334
334
|
f"which serves that snapshot, or remove {DEFAULT_DIR}/{PIN} to rebuild from the data files"
|
|
335
335
|
)
|
|
336
336
|
return (
|
|
@@ -391,6 +391,12 @@ class ToolsWorld:
|
|
|
391
391
|
|
|
392
392
|
@staticmethod
|
|
393
393
|
def _open_world(version: ToolsVersion, directory: Path) -> World:
|
|
394
|
+
world = ToolsWorld._new_world(version, directory)
|
|
395
|
+
world.serve_webhooks(version.spec.webhooks if version.spec is not None else None)
|
|
396
|
+
return world
|
|
397
|
+
|
|
398
|
+
@staticmethod
|
|
399
|
+
def _new_world(version: ToolsVersion, directory: Path) -> World:
|
|
394
400
|
host = _EnvHost(version, directory)
|
|
395
401
|
# _EnvHost is what a World reads of an Environment.
|
|
396
402
|
return World(host, world_id=SESSION_WORLD, template=version.template) # type: ignore[arg-type]
|
|
@@ -463,6 +469,7 @@ class ToolsWorld:
|
|
|
463
469
|
status, body = self._run(world, local, args)
|
|
464
470
|
finally:
|
|
465
471
|
self._log(tool, args, status, body, time.monotonic() - started)
|
|
472
|
+
self._log_webhooks(world)
|
|
466
473
|
return {"status": status, "body": body}
|
|
467
474
|
|
|
468
475
|
def _admitted(self, tool: str) -> tuple[World, str]:
|
|
@@ -487,6 +494,11 @@ class ToolsWorld:
|
|
|
487
494
|
if self.calls is not None:
|
|
488
495
|
self.calls.record_tool(tool, args, status, body, elapsed_s)
|
|
489
496
|
|
|
497
|
+
def _log_webhooks(self, world: World) -> None:
|
|
498
|
+
delivered = world.webhooks.take()
|
|
499
|
+
if self.calls is not None:
|
|
500
|
+
self.calls.record_webhooks(delivered)
|
|
501
|
+
|
|
490
502
|
def grade(self, journal: WorldJournal | None = None) -> dict:
|
|
491
503
|
"""``reward`` is null when no verifier answered a number, never 0; a dependency's verifier that reads the
|
|
492
504
|
journal fails closed, as the journal is the root world's."""
|
|
@@ -639,6 +651,13 @@ class ToolsWorldState(WorldState):
|
|
|
639
651
|
def store(self, value) -> None: # WorldState.close assigns None; the world owns it.
|
|
640
652
|
return None
|
|
641
653
|
|
|
654
|
+
@property
|
|
655
|
+
def webhooks(self): # type: ignore[override]
|
|
656
|
+
return self._tools.world.webhooks
|
|
657
|
+
|
|
658
|
+
def serve_webhooks(self, webhooks) -> None:
|
|
659
|
+
return None
|
|
660
|
+
|
|
642
661
|
def reset(self, *, initial: bool = True) -> None:
|
|
643
662
|
self._tools.reset()
|
|
644
663
|
self._clear_events()
|
|
@@ -11,6 +11,7 @@ from ..world_session_contract import REQUEST_LOG_PAGE_MAX
|
|
|
11
11
|
from .redaction import parse_mode
|
|
12
12
|
from .request_ledger import OUTBOX_CURSOR
|
|
13
13
|
from .validation import ContractError, fail
|
|
14
|
+
from .webhooks import WebhookPoll
|
|
14
15
|
|
|
15
16
|
|
|
16
17
|
@dataclass(frozen=True)
|
|
@@ -97,6 +98,10 @@ def read_requests(body: dict) -> dict[str, Any]:
|
|
|
97
98
|
return {"cursor": cursor, "limit": limit}
|
|
98
99
|
|
|
99
100
|
|
|
101
|
+
def read_webhooks(body: dict) -> dict[str, Any]:
|
|
102
|
+
return {"poll": WebhookPoll.parse(body)}
|
|
103
|
+
|
|
104
|
+
|
|
100
105
|
SESSION_VERBS: tuple[SessionVerb, ...] = (
|
|
101
106
|
SessionVerb("GET", "tools", read_nothing),
|
|
102
107
|
SessionVerb("GET", "task", read_nothing),
|
|
@@ -104,6 +109,7 @@ SESSION_VERBS: tuple[SessionVerb, ...] = (
|
|
|
104
109
|
SessionVerb("GET", "evidence", read_nothing),
|
|
105
110
|
SessionVerb("POST", "requests", read_requests, hosted=True),
|
|
106
111
|
SessionVerb("POST", "flush", read_nothing, hosted=True),
|
|
112
|
+
SessionVerb("POST", "webhooks", read_webhooks),
|
|
107
113
|
SessionVerb("POST", "grade", read_grade),
|
|
108
114
|
SessionVerb("POST", "reset", read_nothing),
|
|
109
115
|
SessionVerb("POST", "seed", read_seed),
|