@withgateway/sdk 0.3.3 → 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/README.md +4 -3
- package/dist/cli.js +3005 -1401
- package/dist/cli.js.map +1 -1
- package/dist/cli.mjs +2996 -1392
- package/dist/cli.mjs.map +1 -1
- package/dist/files/index.js +128 -37
- package/dist/files/index.js.map +1 -1
- package/dist/files/index.mjs +126 -35
- package/dist/files/index.mjs.map +1 -1
- package/dist/hooks/index.d.mts +1 -1
- package/dist/hooks/index.d.ts +1 -1
- package/dist/hooks/index.js +124 -11
- package/dist/hooks/index.js.map +1 -1
- package/dist/hooks/index.mjs +124 -11
- package/dist/hooks/index.mjs.map +1 -1
- package/dist/{index-C3UzD0G3.d.mts → index-CDPQBsU5.d.mts} +19 -3
- package/dist/{index-C3UzD0G3.d.ts → index-CDPQBsU5.d.ts} +19 -3
- 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 +4 -4
- package/dist/index.d.ts +4 -4
- package/dist/index.js +1078 -260
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +1040 -251
- 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 +125 -34
- package/dist/traces/index.js.map +1 -1
- package/dist/traces/index.mjs +123 -32
- 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 +7 -1
- package/dist/tracing/index.js.map +1 -1
- package/dist/tracing/index.mjs +7 -1
- package/dist/tracing/index.mjs.map +1 -1
- package/dist/worlds/index.d.mts +819 -438
- package/dist/worlds/index.d.ts +819 -438
- package/dist/worlds/index.js +912 -236
- package/dist/worlds/index.js.map +1 -1
- package/dist/worlds/index.mjs +908 -232
- 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/_materialize.py +5 -25
- package/runtime/gatewaysdk/environment/_world.py +82 -66
- package/runtime/gatewaysdk/environment/backing.py +20 -24
- package/runtime/gatewaysdk/environment/core.py +1 -16
- package/runtime/gatewaysdk/environment/legacy_sqlite.py +14 -27
- package/runtime/gatewaysdk/environment/runtime.py +45 -2
- package/runtime/gatewaysdk/environment/schema/admission.py +174 -0
- package/runtime/gatewaysdk/environment/schema/api.py +198 -474
- package/runtime/gatewaysdk/environment/schema/assertions.py +458 -0
- package/runtime/gatewaysdk/environment/schema/batch.py +3 -3
- package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +1 -0
- package/runtime/gatewaysdk/environment/schema/cache_layout.py +5 -0
- package/runtime/gatewaysdk/environment/schema/call_capture.py +321 -0
- package/runtime/gatewaysdk/environment/schema/call_log.py +276 -18
- package/runtime/gatewaysdk/environment/schema/call_redaction.py +207 -19
- package/runtime/gatewaysdk/environment/schema/cast.py +15 -35
- package/runtime/gatewaysdk/environment/schema/compiler.py +4 -1
- package/runtime/gatewaysdk/environment/schema/conform.py +38 -35
- package/runtime/gatewaysdk/environment/schema/connector.py +94 -152
- package/runtime/gatewaysdk/environment/schema/connectors/confluence/connector.toml +1 -12
- 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 +10 -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/connectors/servicenow/connector.toml +2 -5
- package/runtime/gatewaysdk/environment/schema/cors.py +54 -0
- package/runtime/gatewaysdk/environment/schema/credentials.py +313 -8
- package/runtime/gatewaysdk/environment/schema/data.py +14 -13
- package/runtime/gatewaysdk/environment/schema/database/base.py +106 -165
- package/runtime/gatewaysdk/environment/schema/database/guard.py +45 -37
- package/runtime/gatewaysdk/environment/schema/database/reads.py +169 -0
- package/runtime/gatewaysdk/environment/schema/database/sqlite.py +57 -31
- package/runtime/gatewaysdk/environment/schema/declared_routes.py +210 -0
- package/runtime/gatewaysdk/environment/schema/door.py +899 -0
- package/runtime/gatewaysdk/environment/schema/envelope.py +86 -28
- package/runtime/gatewaysdk/environment/schema/grading.py +58 -86
- package/runtime/gatewaysdk/environment/schema/handler_errors.py +52 -5
- package/runtime/gatewaysdk/environment/schema/host.py +229 -1695
- package/runtime/gatewaysdk/environment/schema/host_control.py +144 -0
- package/runtime/gatewaysdk/environment/schema/host_handoff.py +370 -0
- package/runtime/gatewaysdk/environment/schema/host_loops.py +97 -0
- package/runtime/gatewaysdk/environment/schema/host_owners.py +121 -0
- package/runtime/gatewaysdk/environment/schema/host_proxy.py +111 -0
- package/runtime/gatewaysdk/environment/schema/host_requests.py +6 -0
- package/runtime/gatewaysdk/environment/schema/host_session.py +126 -0
- package/runtime/gatewaysdk/environment/schema/host_surfaces.py +79 -21
- package/runtime/gatewaysdk/environment/schema/host_transfers.py +127 -0
- package/runtime/gatewaysdk/environment/schema/host_versions.py +242 -0
- package/runtime/gatewaysdk/environment/schema/host_workers.py +577 -0
- package/runtime/gatewaysdk/environment/schema/journal.py +438 -0
- package/runtime/gatewaysdk/environment/schema/ledger_spill.py +828 -0
- package/runtime/gatewaysdk/environment/schema/local.py +32 -116
- package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +20 -5
- package/runtime/gatewaysdk/environment/schema/platform.py +29 -234
- package/runtime/gatewaysdk/environment/schema/request_body.py +238 -0
- package/runtime/gatewaysdk/environment/schema/request_ledger.py +958 -0
- package/runtime/gatewaysdk/environment/schema/route_bindings.py +25 -3
- package/runtime/gatewaysdk/environment/schema/route_miss.py +54 -0
- package/runtime/gatewaysdk/environment/schema/runtime.py +136 -176
- package/runtime/gatewaysdk/environment/schema/scaffold.py +2 -1
- package/runtime/gatewaysdk/environment/schema/session_files.py +133 -24
- package/runtime/gatewaysdk/environment/schema/session_move.py +275 -0
- package/runtime/gatewaysdk/environment/schema/skills/agents/connector-template-author.md +5 -1
- package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +8 -9
- package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/CONNECTORS.md +3 -3
- package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +50 -28
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +12 -8
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +20 -22
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +25 -25
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +24 -16
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +71 -7
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +182 -0
- package/runtime/gatewaysdk/environment/schema/snapshot.py +150 -30
- package/runtime/gatewaysdk/environment/schema/spill_files.py +228 -0
- package/runtime/gatewaysdk/environment/schema/tasks.py +229 -323
- package/runtime/gatewaysdk/environment/schema/tools_world.py +103 -203
- package/runtime/gatewaysdk/environment/schema/validation.py +69 -1
- package/runtime/gatewaysdk/environment/schema/verbs.py +38 -36
- package/runtime/gatewaysdk/environment/schema/webhooks.py +687 -0
- package/runtime/gatewaysdk/environment/schema/worker.py +6 -4
- package/runtime/gatewaysdk/environment/schema/workers.py +203 -39
- package/runtime/gatewaysdk/environment/schema/world_host.py +970 -0
- package/runtime/gatewaysdk/environment/schema/world_tests.py +83 -11
- package/runtime/gatewaysdk/environment/world.py +1 -1
- package/runtime/gatewaysdk/environment/world_session_contract.py +14 -0
- package/skills/agents/connector-template-author.md +5 -1
- package/skills/benchmarks-getting-started/SKILL.md +8 -9
- package/skills/connector-schema-authoring/CONNECTORS.md +3 -3
- package/skills/connector-schema-authoring/SKILL.md +50 -28
- package/skills/connector-schema-authoring/connector-worlds.md +282 -18
- package/skills/connector-schema-authoring/world-schema.md +7 -6
- package/skills/world-data-ingestion/ROWS.md +12 -8
- package/skills/world-data-ingestion/SKILL.md +20 -22
- package/skills/worlds-getting-started/SKILL.md +25 -25
- package/skills/worlds-getting-started/references/cli-mcp-map.md +24 -16
- package/skills/worlds-getting-started/references/gotchas.md +71 -7
- package/skills/worlds-getting-started/references/journal-checks.md +182 -0
|
@@ -21,13 +21,18 @@ 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\|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
|
+
| `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
|
+
| `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 |
|
|
24
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`) |
|
|
25
|
-
| `worlds
|
|
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) |
|
|
30
|
+
| `worlds data calls pull` / `worlds data ingest [--transform\|--map]` | — (no MCP twin yet; the platform agent runs it through `run_gateway_cli`) |
|
|
26
31
|
| `files upload <local>... [--to]` | `request_file_upload` + `confirm_file_upload` (`upload_file` for ≤25 MB inline) |
|
|
27
32
|
| `files list [path]` / `files get <path>` / `files download\|cat <path>` | `list_files` / `get_file` (a presigned URL; the CLI streams it) |
|
|
28
33
|
| `files delete` / `files move` / `files mkdir` | `delete_file` / `move_file` / `create_folder` |
|
|
29
|
-
| `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
|
|
30
|
-
| `worlds sandbox import <id> <path-in-sandbox> [--entity] [--mode]` | `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) |
|
|
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) |
|
|
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) |
|
|
31
36
|
| `files connectors list\|sync <id>` | `list_file_connectors` / `sync_file_connector` (`GET\|POST /api/public/files/connectors[/sync]`) |
|
|
32
37
|
| `traces list\|get\|export [--observations]` | `get_trace`, `get_observations` (`GET /api/public/traces[/{id}]`, `/observations`) |
|
|
33
38
|
| `traces sessions list\|get [--io]` | `get_session` (`GET /api/public/sessions[/{id}?includeIO=true]`) |
|
|
@@ -36,9 +41,9 @@ Reference for `worlds-getting-started`: every CLI step and its MCP twin, then ho
|
|
|
36
41
|
| `environment run` / `worlds run` | `run_evaluation` |
|
|
37
42
|
| `environment link-task-set` / `create-task` | `create_task_set`, `create_task`, `link_task_set` |
|
|
38
43
|
| `bench diff` / `propose` | `env_diff`, `env_propose` (proposals are the legacy PR-style door; edit sessions below are the version-control loop) |
|
|
39
|
-
| `worlds\|bench edit status\|list\|close\|discard\|rollback <slug>` | `list_world_edits({ slug, status?, limit? })`, `close_world_edit({ slug, sessionId?, force?, message? })`, `discard_world_edit`, `rollback_world_edit({ slug, sessionId, force?, message? })` (`GET /api/public/worlds/{slug}/edits`, `POST …/edits/close\|discard\|rollback`). After a world's first version every push, sandbox commit, data import, agent `env_commit` and UI save lands on the credential's open edit session — a private `edit/<id>` branch only that credential reads
|
|
40
|
-
| `worlds task edit status\|close\|rollback <task>` (task id, spec file with `worlds`, or `task up` manifest) | `get_task_edit({ task })`, `close_task_edit({ task, requireAll?, force?, message? })`, `rollback_task_edit({ task, groupId, force?, message? })` (`POST /api/public/world-task-edits/status\|close\|rollback`). The same edit sessions across every world a task names: `status` shows each world's unsealed edits (open and `parked` in conflict) and what closing would do (`fast-forward`, `rebase`, `conflict`) —
|
|
41
|
-
| `worlds\|bench sandbox open\|status\|read\|write\|exec\|check\|commit\|close` | `open_world_sandbox`, `get_world_sandbox`, `read_world_sandbox_file`, `write_world_sandbox_file` (base64), `exec_in_world_sandbox`, `check_world_sandbox`, `commit_world_sandbox`, `close_world_sandbox({ sandboxId, force? })` (`/api/public/benchmark-containers/sandboxes[/{id}[/file\|exec\|check\|commit]]`; `close` with uncommitted work is a 409 `sandbox_uncommitted` naming the paths, nothing closed, unless `force: true` / `--force`; a sandbox whose machine was replaced gets its tree back (latest snapshot, or the base) and the next verb answers 409 `sandbox_recreated` once — look at the tree, redo lost edits, retry; 503 `sandbox_restore_failed` means retry; 409 `sandbox_tree_missing` means the world root was deleted, so close and reopen; the source tree only — no data snapshot, nothing on the caller's disk; `commit` lands on the recorded base; `commit --rebase` sends `rebase: true` and replays onto a branch head that moved, a 409 naming each conflicting path). `open` reports `cli: {version, digest}` — the platform's own `gateway` CLI and a `sqlite3` are on PATH inside `exec`, so `gateway worlds schema entity add\|verifier add\|task add\|compile\|check .`, `gateway worlds data import\|show\|query\|sql .`, `gateway worlds test .`, `gateway worlds serve . --port 8080 & sleep 2; gateway worlds call http://localhost:8080 <tool> …` (one `exec`; a served world lives only as long as that command) and `sqlite3 db/state.sqlite "…"` run on the working copy; remote verbs (push, run, session open) stop in the sandbox by design — `check`/`commit` from your machine. `cli: null` + `warnings[]` means the image cannot host the runtime (python3 < 3.12 or node < 18); plain shell still runs |
|
|
44
|
+
| `worlds\|bench edit status\|list\|close\|discard\|rollback <slug>` | `list_world_edits({ slug, status?, limit? })`, `close_world_edit({ slug, sessionId?, force?, message? })`, `discard_world_edit`, `rollback_world_edit({ slug, sessionId, force?, message? })` (`GET /api/public/worlds/{slug}/edits`, `POST …/edits/close\|discard\|rollback`). After a world's first version every push, sandbox commit, data import, agent `env_commit` and UI save lands on the credential's open edit session — a private `edit/<id>` branch only that credential's unpinned reads see (no `@ref`, no version: `describe`, `pull`, `log`, `session open`, `sandbox open`, `test`); `slug@main`/`@latest`, an exact version pin, every run, task and stored pin resolve to sealed versions only (an unsealed version id answers only its own author); the write's JSON carries `editSessionId` + a hint. `close`, or 60 minutes without an edit, seals the session: the shared `main` moves to its tip (every version stays in `log`; the session is the rollback unit); a `main` that moved meanwhile is rebased when the paths differ, else the session parks as `conflict` (`close --force` takes its content). `rollback` restores source + data snapshot from before a sealed session as a new sealed session (`--force` when later sessions would be undone too). UI: world › History › Edit sessions |
|
|
45
|
+
| `worlds task edit status\|close\|rollback <task>` (task id, spec file with `worlds`, or `task up` manifest) | `get_task_edit({ task })`, `close_task_edit({ task, requireAll?, force?, message? })`, `rollback_task_edit({ task, groupId, force?, message? })` (`POST /api/public/world-task-edits/status\|close\|rollback`). The same edit sessions across every world a task names: `status` shows each world's unsealed edits (open and `parked` in conflict) and what closing would do (`fast-forward`, `rebase`, `conflict`) — every `task up`, run config and schedule, yours included, keeps the sealed `main` until the close; `close` seals every world in ONE transaction (a conflict, a missing world, a ref other than `main` or a parked session anywhere seals nothing, and the 409 names every world's problem; worlds with no edit are skipped unless `--require-all`), and the sessions share a `groupId`; `rollback --group` restores every world together to the `main` the group replaced, refused when anything reached a world's `main` after the group (a later session or a write outside sessions) unless `--force` |
|
|
46
|
+
| `worlds\|bench sandbox open\|status\|read\|write\|exec\|check\|commit\|close` | `open_world_sandbox`, `get_world_sandbox`, `read_world_sandbox_file`, `write_world_sandbox_file` (base64), `exec_in_world_sandbox`, `check_world_sandbox`, `commit_world_sandbox`, `close_world_sandbox({ sandboxId, force? })` (`/api/public/benchmark-containers/sandboxes[/{id}[/file\|exec\|check\|commit]]`; `close` with uncommitted work is a 409 `sandbox_uncommitted` naming the paths, nothing closed, unless `force: true` / `--force`; a sandbox whose machine was replaced gets its tree back (latest snapshot, or the base) and the next verb answers 409 `sandbox_recreated` once — look at the tree, redo lost edits, retry; 503 `sandbox_restore_failed` means retry; 503 `sandbox_unresponsive` / `sandbox_unavailable` / `sandbox_replacing` mean nothing changed: call again after `retryAfterSeconds` (a sandbox silent for 5 minutes is then replaced from its latest snapshot and answers 409 `sandbox_recreated`); 409 `sandbox_tree_missing` means the world root was deleted, so close and reopen; the source tree only — no data snapshot, nothing on the caller's disk; `commit` lands on the recorded base; `commit --rebase` sends `rebase: true` and replays onto a branch head that moved, a 409 naming each conflicting path). `open` reports `cli: {version, digest}` — the platform's own `gateway` CLI and a `sqlite3` are on PATH inside `exec`, so `gateway worlds schema entity add\|verifier add\|task add\|compile\|check .`, `gateway worlds data import\|show\|query\|sql .`, `gateway worlds test .`, `gateway worlds serve . --port 8080 & sleep 2; gateway worlds call http://localhost:8080 <tool> …` (one `exec`; a served world lives only as long as that command) and `sqlite3 db/state.sqlite "…"` run on the working copy; remote verbs (push, run, session open) stop in the sandbox by design — `check`/`commit` from your machine. `cli: null` + `warnings[]` means the image cannot host the runtime (python3 < 3.12 or node < 18); plain shell still runs |
|
|
42
47
|
| `worlds\|bench sandbox open --new <slug> --from custom\|<template>` | `open_world_sandbox({ new, from })` (same route, body `{new, from}`; a world that does not exist yet — `baseVersionId`/`containerId`/`baseContentHash` null, `branch: main`, `pendingSlug`; `custom` = the `schema init` scaffold, else a shipped template (`GET /api/public/worlds/templates`; unknown → 400 naming the list); taken slug → 409 `world_exists`, never renamed; `check_world_sandbox` runs the first commit's gate; the first `commit_world_sandbox` creates the world on `main` through the `worlds create --from <dir>` door, later commits land on the new base; the same staged CLI runs on the scaffold) |
|
|
43
48
|
| `worlds skill <name>` / `worlds connector skill` | `get_connector_authoring_skill`, `guide` |
|
|
44
49
|
| `worlds connector capture --remote` / poll + download | `start_connector_capture`, `get_connector_capture` (platform agent only) |
|
|
@@ -50,8 +55,9 @@ before it makes a request.
|
|
|
50
55
|
|
|
51
56
|
| Door | Limit | Over it |
|
|
52
57
|
|---|---|---|
|
|
53
|
-
| `sandbox write
|
|
54
|
-
| `
|
|
58
|
+
| `sandbox write` | 256 MB per file (past 4 MB the CLIs send it in parts, checked by size and SHA-256 before it lands); `--from <dir>` writes every file under it but `.git/`, `.gateway/` and scratch (`node_modules/`, `__pycache__/`, `*.pyc`, ...), and says what it skipped | refused before any request, naming the limit; generate bigger data in the sandbox (`sandbox exec`) and load it with `sandbox import` |
|
|
59
|
+
| `write_world_sandbox_file`, `env_write_file`, `propose_task_fix` | 256 KB per call | refused, naming the limit; a bigger file → `sandbox write`; rows → `worlds data import <slug> <file>`; the whole tree → `bench push` |
|
|
60
|
+
| `sandbox exec --timeout`, `exec_in_world_sandbox timeoutMs` | default 60 s, at most 600 s | refused, not clamped; a start gets the sandbox ready, then waits for the command until 40 s have passed in all, and a command not done by then answers `running` with an `execId` (the CLIs wait again by themselves; `exec_in_world_sandbox` takes `execId` to wait); a timeout returns what it printed; a start whose getting ready took over 45 s is a 409 `sandbox_exec_deferred` with nothing started, its `warnings` saying what getting ready found (the CLIs start again and print them; what getting ready did is kept, a snapshot lay that failed too, so the next start is quick); a job whose runner died is a 409 `sandbox_exec_lost`, and a runner the sandbox cannot prepare a 503 `sandbox_exec_start_failed` (nothing started) |
|
|
55
61
|
| Sandbox tree at `check`/`commit`, `bench push` unpacked | 128 MB of source, 2000 files | refused, naming the limit, before a byte is read; move data to `worlds data import`, delete scratch files or list them in `.gatewayignore` |
|
|
56
62
|
| Sandbox tree at `check`/`commit`: credential-shaped files (`.env`, `*.pem`, `id_rsa`, `credentials.json`…; `.env.example` stays), symlinks, sockets/devices | held back, never in the version | listed under `ignored`, each named in `warnings` (path only); use `bench secrets set` for a key the world needs |
|
|
57
63
|
| `worlds data query` / `data sql` / `data show` on a stored version | none beyond the version's own caps | the platform opens the version's tree and snapshot in a prepared directory it owns; no size travels through the request |
|
|
@@ -61,11 +67,13 @@ before it makes a request.
|
|
|
61
67
|
|
|
62
68
|
## The platform agent
|
|
63
69
|
|
|
64
|
-
The platform (console) agent
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
`
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
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,16 +4,19 @@ 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.
|
|
17
|
+
- A `[dependencies]` pin never resolves to an open edit, yours included: `@main` is the sealed
|
|
18
|
+
`main`, and a hash, semver or version id must name a sealed version. Seal the linked world's
|
|
19
|
+
edit (`gateway worlds edit close <slug>`) before you push the world that links it.
|
|
17
20
|
- Sharing is publish + clone, never a live reference; later edits reach a clone only on re-clone.
|
|
18
21
|
- Never commit `captures/`; never merge a customer's world as an SDK template.
|
|
19
22
|
- A seed (scenario overlay or runner admin endpoint) is the whole state, not an increment.
|
|
@@ -21,20 +24,53 @@ The things that bite once and never again, moved out of `SKILL.md` to keep it un
|
|
|
21
24
|
- A platform request that never gets an answer fails in one line: the request, the host, the cause
|
|
22
25
|
(`connection refused`, `DNS lookup failed`, `timed out after 120s`) and the next step, exit 1. Each
|
|
23
26
|
request waits `GATEWAY_TIMEOUT_MS` (default 120000); polls (session ready, grades) are many short
|
|
24
|
-
requests, so a long wait is never cut by it
|
|
27
|
+
requests, so a long wait is never cut by it; a sandbox `exec` waits in 40 s requests until its
|
|
28
|
+
command ends, and other sandbox requests (and MCP tool calls through either proxy) wait 290 s,
|
|
29
|
+
under Node's 300 s fetch limit, on both twins. An edge answer that is not the platform's JSON (an
|
|
30
|
+
HTML 502/503/504 from a load balancer) is named, never printed.
|
|
31
|
+
- A version that holds dot or root files and was committed, by any door but a directory push, before
|
|
32
|
+
the platform hashed every stored file carries a content hash over its archive files only. Deleting
|
|
33
|
+
its only dot or root file (a `.gatewayignore`, say) and changing nothing else is refused, naming the
|
|
34
|
+
version and the files: commit the deletion with another change, or put the file back. An unchanged
|
|
35
|
+
tree on such a version commits the same files under the new hash, and `check` and `commit` say so,
|
|
36
|
+
unless those files are ones a sandbox never commits (scratch such as `__pycache__/`, or `.env`):
|
|
37
|
+
then an untouched sandbox is refused until it carries another change.
|
|
25
38
|
|
|
26
39
|
- A world that declares an environment secret (`environment_secret_name` in `release/manifest.json`, or `${NAME:?}` in a task's `docker-compose.yaml`) is refused at `session open`
|
|
27
40
|
with 400 `missing_env_secrets` naming `gateway bench secrets set --env <slug> --key <NAME>` before
|
|
28
41
|
anything is provisioned — the same preflight a run dispatch applies; set the secret, then open.
|
|
29
42
|
- `gateway secret set NAME` is an upsert: the same name again rotates the value and answers
|
|
30
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.
|
|
31
47
|
- Imported data survives every edit that cannot touch a stored row. After `gateway worlds data import
|
|
32
48
|
<slug>` the world's tree carries `db/snapshot.json` (the hosted snapshot) and not the rows; in
|
|
33
49
|
`worlds sandbox open <slug>@main`, adding a tool, a handler, a route, a test or a documentation
|
|
34
50
|
file then `schema compile .` and `schema check .` pass and the commit keeps the snapshot, no
|
|
35
51
|
re-import, and `gateway bench fork <slug>` takes the data with it. Adding an entity or a field
|
|
36
52
|
that is not required (or another `domain_version`) carries the data too: `sandbox check` says
|
|
37
|
-
the commit migrates the snapshot, and `sandbox commit` migrates it and re-pins the tree
|
|
53
|
+
the commit migrates the snapshot, and `sandbox commit` migrates it as a job and re-pins the tree:
|
|
54
|
+
the CLI follows the batch (each phase on stderr, up to `--wait` seconds) and prints the new
|
|
55
|
+
version, or exits 1 naming the refusal (`storage`, `timeout`, `checkout_cap`, `refused`,
|
|
56
|
+
`base_moved`); MCP `commit_world_sandbox` answers `{batchId}` to poll with `get_data_batch` when the
|
|
57
|
+
job outlasts its wait. While the batch runs, `commit` and `import` are refused
|
|
58
|
+
(`sandbox_commit_pending`); once it lands a sandbox used in the last 15 minutes takes the version
|
|
59
|
+
at once when none of the files it rewrites changed since the commit, else its next `commit`,
|
|
60
|
+
`import` or `exec` takes it and says what it found (`commit` and `import` say it on a refusal
|
|
61
|
+
too; `close` takes it silently), and `sandbox check` shows it first without writing anything. A `sandbox import` stands the sandbox on the data version it published, so
|
|
62
|
+
the next commit needs no `--rebase`; when another door moved `main`, `sandbox check` says
|
|
63
|
+
`baseMoved` and `--rebase` carries the edit and the imported rows onto the tip. A `--rebase` whose
|
|
64
|
+
base sits on an edit session still open, still closing, or stopped in conflict is
|
|
65
|
+
refused (`rebase_unrelated`) naming the session and what to do: close an open one (`edit close
|
|
66
|
+
<slug> --session <id>`), wait for one that is closing, and land one in conflict over `main`
|
|
67
|
+
(`edit close <slug> --session <id> --force`) or drop it (`edit discard <slug> --session <id>`);
|
|
68
|
+
then `--rebase` again. `worlds push` from a pulled tree keeps the snapshot for the edits that cannot touch a row, and refuses a domain
|
|
69
|
+
change, naming the sandbox: make that one there. No file is
|
|
70
|
+
deleted by hand: compile drops the `db/state.*` the tree's own data files built, which the pin
|
|
71
|
+
replaces, and check never refuses them. In the sandbox `data show|sql`, `worlds test` and
|
|
72
|
+
`worlds call` read the hosted rows, which the platform lays beside the tree (never in it) before
|
|
73
|
+
each `exec`, after taking a batch that landed; `exec`'s warnings say when it could not.
|
|
38
74
|
Removing, retyping or requiring a field, or changing a key, a relationship or a description, is
|
|
39
75
|
refused, naming what changed: keep it as it was, or remove `db/snapshot.json` and import every
|
|
40
76
|
row again. `check` reports
|
|
@@ -43,3 +79,31 @@ The things that bite once and never again, moved out of `SKILL.md` to keep it un
|
|
|
43
79
|
`check` and is first refused at that open: open a session on the version after a handler edit.
|
|
44
80
|
Compile from a fresh `sandbox open` rather than copying in artifacts compiled
|
|
45
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.
|
|
@@ -0,0 +1,182 @@
|
|
|
1
|
+
# Journal checks: verifiers over the requests a session's world received
|
|
2
|
+
|
|
3
|
+
A World Host session records every request its world receives, through every door: the api origin,
|
|
4
|
+
the page's `api_path` (ui) and a declared tool's call. Before a grade the platform waits until the
|
|
5
|
+
host has stored every request it holds for the session (the flush barrier), reads them back and
|
|
6
|
+
hands the grader those requests with whether they are all of them. Three ways to check them, one
|
|
7
|
+
implementation underneath: a declarative check, a `verify.py`, a SQL verifier.
|
|
8
|
+
|
|
9
|
+
Only the World Host records requests. A stored task whose checks read them is refused at validation
|
|
10
|
+
and at dispatch on any other engine, a run config included (`checks on the session's journal
|
|
11
|
+
(gateway_requests, calls, a python grader that reads it) need the World Host`). A local `worlds serve`
|
|
12
|
+
session reads `calls` from its own call log; there and in `benchmarks dry-run` the rest fails closed
|
|
13
|
+
as `not recorded`, whatever the grader accepts.
|
|
14
|
+
|
|
15
|
+
## What a grader reads
|
|
16
|
+
|
|
17
|
+
`gateway_requests`, one row per request, oldest first:
|
|
18
|
+
|
|
19
|
+
```json
|
|
20
|
+
{ "seq": 2, "id": "0a1b…", "at": "2026-10-05T12:00:01.000Z", "durationMs": 12.5,
|
|
21
|
+
"via": "api", "operation": "create_record", "method": "POST", "path": "/records",
|
|
22
|
+
"query": { "dry_run": "false" }, "rows": 1, "found": true,
|
|
23
|
+
"request": { "headers": { "content-type": "application/json" }, "body": { "name": "Acme" },
|
|
24
|
+
"bodyBytes": 16, "truncated": false, "contentType": "application/json" },
|
|
25
|
+
"response": { "status": 201, "body": { "id": "rec_1" }, "bodyBytes": 15, "truncated": false,
|
|
26
|
+
"contentType": "application/json" } }
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
- `via` is `api`, `ui` or `tool`; a tool call has no `method` or `path`.
|
|
30
|
+
- A JSON body reads as JSON, any other as text. Bodies are what the ledger stored: redacted when
|
|
31
|
+
captured, the first 64 KB (`truncated: true` past that). A request past the grade's budget (2,000
|
|
32
|
+
bodies, 8 MiB) carries `withheld: ["request.headers", "request.body", "response.body"]`.
|
|
33
|
+
- `gateway_journal` is the summary: `{ "complete": true, "reason": null, "requests": 4, "withheld": 0 }`.
|
|
34
|
+
`complete` is false when the host shed bodies or lost requests, did not answer the barrier, the
|
|
35
|
+
platform refused some, the session was reopened from a checkpoint or recovered after its worker or
|
|
36
|
+
host stopped, fewer requests remain than a past grade read, or the session holds more than 20,000;
|
|
37
|
+
`reason` says which. `withheld` counts the requests whose bodies the grade's budget left out.
|
|
38
|
+
- What a session's world was asked, to write a check against: `gateway worlds session requests
|
|
39
|
+
<SESSION_ID> --json` (MCP `list_world_requests`), or the `asked:` lines `task try` prints.
|
|
40
|
+
|
|
41
|
+
## 1. Declarative checks (`assertions`)
|
|
42
|
+
|
|
43
|
+
```json
|
|
44
|
+
{ "kind": "assertions", "checks": [
|
|
45
|
+
{ "id": "created", "entity": "gateway_requests",
|
|
46
|
+
"where": { "operation": "create_record", "response.status": 201 } },
|
|
47
|
+
{ "id": "no_deletes", "entity": "gateway_requests", "where": { "method": "DELETE" }, "assert": "absent" },
|
|
48
|
+
{ "id": "one_create", "entity": "gateway_requests", "where": { "operation": "create_record" },
|
|
49
|
+
"assert": "count", "count": { "eq": 1 } },
|
|
50
|
+
{ "id": "looked_first", "entity": "gateway_requests", "where": { "operation": "get_record" },
|
|
51
|
+
"before": { "operation": "update_record" } },
|
|
52
|
+
{ "id": "named_acme", "entity": "gateway_requests", "where": { "operation": "create_record" },
|
|
53
|
+
"assert": "all", "field": "request.body.name", "value": "Acme" }
|
|
54
|
+
] }
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
- `where`, `field`, `before` and `after` name `seq`, `id`, `at`, `durationMs`, `via`, `operation`,
|
|
58
|
+
`method`, `path`, `rows`, `found`, `request.body`, `request.bodyBytes`, `request.truncated`,
|
|
59
|
+
`request.contentType`, `response.status`, `response.body`, `response.bodyBytes`,
|
|
60
|
+
`response.truncated`, `response.contentType`, or a path under `query.`, `request.headers.`,
|
|
61
|
+
`request.body.`, `response.body.`. Anything else is refused with the field it meant:
|
|
62
|
+
`gateway_requests has no field response.stauts; did you mean response.status?`.
|
|
63
|
+
- `before: {…}` keeps the requests before the first one it matches (all of them when none does);
|
|
64
|
+
`after: {…}` keeps the requests after the first one it matches (none when none does). They go on
|
|
65
|
+
`gateway_requests` and `calls` checks only.
|
|
66
|
+
- `entity: "calls"` on a World Host session is the call log's view of the same requests: every
|
|
67
|
+
door, tool calls included, with no bound (`operation`, `args`, `query`, `body`, `selectors`,
|
|
68
|
+
`via`, `status`, `rows`, `found`). A request no route took and a tool call the door refused stay
|
|
69
|
+
in `gateway_requests` only.
|
|
70
|
+
|
|
71
|
+
## 2. A `verify.py` that reads the journal
|
|
72
|
+
|
|
73
|
+
```json
|
|
74
|
+
{ "kind": "python", "readsJournal": true, "source": "<verify.py below>" }
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
```python
|
|
78
|
+
import json, sys
|
|
79
|
+
|
|
80
|
+
state = json.load(sys.stdin)
|
|
81
|
+
creates = [r for r in state["gateway_requests"]
|
|
82
|
+
if r["operation"] == "create_record" and r["response"]["status"] == 201]
|
|
83
|
+
print(json.dumps({"reward": 1 if len(creates) == 1 else 0, "one_create": len(creates) == 1}))
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
Only a grader that declares `readsJournal: true` gets `gateway_requests` and `gateway_journal` on
|
|
87
|
+
stdin, beside the rows, `calls` and `report`. On an incomplete journal, or one whose bodies were
|
|
88
|
+
withheld, it scores 0 with the reason unless it also declares `acceptsIncompleteJournal: true`; then
|
|
89
|
+
it runs and reads `state["gateway_journal"]` itself (a body cut at 64 KB says `truncated: true`).
|
|
90
|
+
With no journal recorded at all it scores 0 either way.
|
|
91
|
+
|
|
92
|
+
## 3. A SQL verifier (`verifiers/<name>.sql`, a `[[tasks]]` world)
|
|
93
|
+
|
|
94
|
+
```sql
|
|
95
|
+
SELECT CASE WHEN COUNT(*) = 0 THEN 1.0 ELSE 0.0 END
|
|
96
|
+
FROM gateway_requests WHERE method = 'DELETE';
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
```sql
|
|
100
|
+
SELECT CASE WHEN COUNT(*) = 1 THEN 1.0 ELSE 0.0 END
|
|
101
|
+
FROM gateway_requests
|
|
102
|
+
WHERE operation = 'create_record' AND status = 201
|
|
103
|
+
AND json_extract(request_body, '$.name') = 'Acme';
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
`gateway_requests` columns: `seq, id, at, duration_ms, via, operation, method, path, query, status,
|
|
107
|
+
rows, found, request_headers, request_body, request_body_bytes, request_truncated,
|
|
108
|
+
request_content_type, response_body, response_body_bytes, response_truncated,
|
|
109
|
+
response_content_type, withheld` (query, headers and bodies are the stored text: read them with
|
|
110
|
+
`json_extract`). `gateway_journal(complete, reason, requests, withheld)`. A verifier that reads
|
|
111
|
+
either on an incomplete journal, or reads a body column while a body was withheld or cut at 64 KB,
|
|
112
|
+
scores 0, and the grade names why under `reasons`, unless `gateway-env.toml` lets it (a read counts
|
|
113
|
+
however the statement reaches the table, joins included):
|
|
114
|
+
|
|
115
|
+
```toml
|
|
116
|
+
[verifiers.created_at_least_once]
|
|
117
|
+
accepts_incomplete_journal = true
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
Let only a check that a missing request can only make fail accept an incomplete journal: `COUNT(*) >
|
|
121
|
+
0`, not `= 0` or `= 1`, which pass on a journal that lost a request they count. No flag grades a
|
|
122
|
+
journal never recorded, nor a linked world's verifier that reads one: the session's journal is the
|
|
123
|
+
root world's.
|
|
124
|
+
|
|
125
|
+
An entity may not be named `gateway_…` (the compiler refuses it), so the names never collide.
|
|
126
|
+
|
|
127
|
+
## Fail closed
|
|
128
|
+
|
|
129
|
+
A check the stored requests do not decide fails and says why:
|
|
130
|
+
|
|
131
|
+
```
|
|
132
|
+
FAIL no_deletes — journal incomplete (the World Host lost 2 requests): the 4 requests it holds do not decide this check
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
A check they do decide still grades: `created` passes on an incomplete journal that holds the
|
|
136
|
+
request. Every World Host grade but a rubric's takes the barrier and records how complete the
|
|
137
|
+
journal was, so a later `try` or `regrade` of the session knows. A `calls` check on `args`, `body`
|
|
138
|
+
or `selectors` has the bodies fetched for it; one on `operation` or `status` alone does not need
|
|
139
|
+
them.
|
|
140
|
+
|
|
141
|
+
## Try, save, regrade
|
|
142
|
+
|
|
143
|
+
```bash
|
|
144
|
+
gateway worlds task try task.json --session <SESSION_ID> # a spec not saved yet; files nothing
|
|
145
|
+
gateway worlds task try <TASK_ID> --session <SESSION_ID> --version 3 --json
|
|
146
|
+
gateway worlds task update <TASK_ID> --spec task.json # save: the next version
|
|
147
|
+
gateway worlds task validate <TASK_ID>
|
|
148
|
+
gateway worlds task regrade <TASK_ID> # the task's latest run, whole, by the current version
|
|
149
|
+
gateway worlds task regrade <TASK_ID> --run <EVALUATION_ID> --version 3
|
|
150
|
+
gateway worlds task regrade <TASK_ID> --all-runs --limit 20
|
|
151
|
+
gateway worlds task regrade <TASK_ID> --session <SESSION_ID> # one rollout; its run then shows the versions it mixes
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
```
|
|
155
|
+
try the spec on session ses_01: graded live
|
|
156
|
+
journal: 4 requests, incomplete (the World Host lost 2 requests)
|
|
157
|
+
PASS created — matched #2 api POST create_record 201 (+1 more)
|
|
158
|
+
FAIL no_deletes — journal incomplete (the World Host lost 2 requests): the 4 requests it holds do not decide this check
|
|
159
|
+
reward 0.5
|
|
160
|
+
asked:
|
|
161
|
+
1x api GET list_records 200 /records
|
|
162
|
+
2x api POST create_record 201 /records
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
`try` grades a live session in place, and a closed one on an ephemeral copy restored from the
|
|
166
|
+
checkpoint its last grade took, over the requests that grade read. A session no grade checkpointed
|
|
167
|
+
refuses checks over rows; checks over `gateway_requests` and `calls` still run. A check on an entity
|
|
168
|
+
the session's world does not define is refused, as an open refuses it.
|
|
169
|
+
|
|
170
|
+
`regrade` grades each rollout's session the way `try` does and replaces the rollout's grade in
|
|
171
|
+
place: the grade it held moves to `info.grades`, `info.verifierVersion` names the version that
|
|
172
|
+
graded it, and the run's metrics and label (`verifier v3`, or `verifiers v2, v3` for a mixed run)
|
|
173
|
+
follow. A release gate reads the new rewards on its next read. Exit 1 when nothing was regraded, a
|
|
174
|
+
rollout kept its grade (already graded by that version, so a rerun adds no history; no checkpoint
|
|
175
|
+
for a check over rows) or a rollout was regraded to no score (`--json` holds its reasons). A run or
|
|
176
|
+
session that is not the task's is refused. A task over several worlds is not regraded, and `try` on
|
|
177
|
+
one of its sessions grades that world's own grader, not the cross-world verifiers.
|
|
178
|
+
|
|
179
|
+
| CLI | MCP | REST | SDK |
|
|
180
|
+
| --- | --- | --- | --- |
|
|
181
|
+
| `worlds task try` | `try_world_task({ sessionId, taskId \| spec, version? })` (MEMBER and above: it runs your verify.py) | `POST /api/public/world-tasks/try` | `new TaskGrades(opts).try(sessionId, target)` / `TaskGrades().try_task(session_id, task_id=… \| spec=…)` |
|
|
182
|
+
| `worlds task regrade` | `regrade_world_task({ taskId, version?, runs?, allRuns?, sessions?, limit? })` | `POST /api/public/world-tasks/{taskId}/regrade` | `.regrade(taskId, scope)` / `.regrade(task_id, …)` |
|