@withgateway/sdk 0.6.0 → 0.9.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/agents/index.d.mts +581 -0
- package/dist/agents/index.d.ts +581 -0
- package/dist/agents/index.js +1473 -0
- package/dist/agents/index.js.map +1 -0
- package/dist/agents/index.mjs +1424 -0
- package/dist/agents/index.mjs.map +1 -0
- package/dist/apiError-DHpfbmdx.d.mts +17 -0
- package/dist/apiError-DHpfbmdx.d.ts +17 -0
- package/dist/cli.js +11611 -6845
- package/dist/cli.js.map +1 -1
- package/dist/cli.mjs +10090 -5325
- package/dist/cli.mjs.map +1 -1
- package/dist/files/index.d.mts +3 -1
- package/dist/files/index.d.ts +3 -1
- package/dist/files/index.js +371 -102
- package/dist/files/index.js.map +1 -1
- package/dist/files/index.mjs +371 -102
- package/dist/files/index.mjs.map +1 -1
- package/dist/hooks/index.js +346 -136
- package/dist/hooks/index.js.map +1 -1
- package/dist/hooks/index.mjs +346 -136
- package/dist/hooks/index.mjs.map +1 -1
- package/dist/{index-LA-PMRJT.d.ts → index-DIN14Lhg.d.ts} +1 -1
- package/dist/{index-Di9nNqOY.d.mts → index-DuB-eQ0Z.d.mts} +1 -1
- package/dist/index.d.mts +7 -4
- package/dist/index.d.ts +7 -4
- package/dist/index.js +3177 -748
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +2987 -590
- package/dist/index.mjs.map +1 -1
- package/dist/media-CQUC7TkS.d.mts +39 -0
- package/dist/media-DQnBloaX.d.ts +39 -0
- package/dist/traces/index.d.mts +3 -1
- package/dist/traces/index.d.ts +3 -1
- package/dist/traces/index.js +371 -102
- package/dist/traces/index.js.map +1 -1
- package/dist/traces/index.mjs +371 -102
- package/dist/traces/index.mjs.map +1 -1
- package/dist/tracing/index.d.mts +3 -2
- package/dist/tracing/index.d.ts +3 -2
- package/dist/tracing/index.js +257 -16
- package/dist/tracing/index.js.map +1 -1
- package/dist/tracing/index.mjs +257 -16
- package/dist/tracing/index.mjs.map +1 -1
- package/dist/transport-CpRe7zgd.d.mts +123 -0
- package/dist/transport-CpRe7zgd.d.ts +123 -0
- package/dist/worlds/index.d.mts +1986 -1746
- package/dist/worlds/index.d.ts +1986 -1746
- package/dist/worlds/index.js +1470 -290
- package/dist/worlds/index.js.map +1 -1
- package/dist/worlds/index.mjs +1465 -286
- package/dist/worlds/index.mjs.map +1 -1
- package/package.json +6 -1
- package/runtime/gatewaysdk/environment/bundle_manifest.py +531 -0
- package/runtime/gatewaysdk/environment/factory_documents.py +670 -0
- package/runtime/gatewaysdk/environment/factory_rules.py +973 -0
- package/runtime/gatewaysdk/environment/factory_shapes.py +253 -0
- package/runtime/gatewaysdk/environment/factory_spine.py +1155 -0
- package/runtime/gatewaysdk/environment/factory_spine_shapes.py +480 -0
- package/runtime/gatewaysdk/environment/schema/__main__.py +2 -2
- package/runtime/gatewaysdk/environment/schema/_slack_fidelity.py +8 -23
- package/runtime/gatewaysdk/environment/schema/admission.py +61 -59
- package/runtime/gatewaysdk/environment/schema/api.py +3 -4
- package/runtime/gatewaysdk/environment/schema/assertions.py +7 -1
- package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +1 -0
- package/runtime/gatewaysdk/environment/schema/call_log.py +20 -0
- package/runtime/gatewaysdk/environment/schema/cast.py +133 -67
- package/runtime/gatewaysdk/environment/schema/compiler.py +16 -17
- package/runtime/gatewaysdk/environment/schema/database/base.py +2 -2
- package/runtime/gatewaysdk/environment/schema/handler_errors.py +58 -4
- package/runtime/gatewaysdk/environment/schema/host.py +94 -12
- package/runtime/gatewaysdk/environment/schema/host_browser.py +48 -0
- package/runtime/gatewaysdk/environment/schema/host_control.py +35 -2
- package/runtime/gatewaysdk/environment/schema/host_handoff.py +4 -1
- package/runtime/gatewaysdk/environment/schema/host_loops.py +27 -4
- package/runtime/gatewaysdk/environment/schema/host_metrics.py +69 -0
- package/runtime/gatewaysdk/environment/schema/host_requests.py +35 -0
- package/runtime/gatewaysdk/environment/schema/host_session.py +20 -2
- package/runtime/gatewaysdk/environment/schema/host_surfaces.py +6 -0
- package/runtime/gatewaysdk/environment/schema/host_versions.py +100 -19
- package/runtime/gatewaysdk/environment/schema/host_workers.py +172 -50
- package/runtime/gatewaysdk/environment/schema/ingest.py +12 -3
- package/runtime/gatewaysdk/environment/schema/journal.py +7 -2
- package/runtime/gatewaysdk/environment/schema/local.py +32 -7
- package/runtime/gatewaysdk/environment/schema/mapping.py +1 -1
- package/runtime/gatewaysdk/environment/schema/measured_tests.py +187 -0
- package/runtime/gatewaysdk/environment/schema/page_checks.py +123 -0
- package/runtime/gatewaysdk/environment/schema/platform.py +80 -270
- package/runtime/gatewaysdk/environment/schema/platform_query.py +4 -3
- package/runtime/gatewaysdk/environment/schema/platform_templates.py +420 -0
- package/runtime/gatewaysdk/environment/schema/process_memory.py +76 -0
- package/runtime/gatewaysdk/environment/schema/redaction.py +13 -0
- package/runtime/gatewaysdk/environment/schema/request_ledger.py +4 -1
- package/runtime/gatewaysdk/environment/schema/run_parameters.py +25 -0
- package/runtime/gatewaysdk/environment/schema/runtime.py +57 -5
- package/runtime/gatewaysdk/environment/schema/scaffold.py +386 -219
- package/runtime/gatewaysdk/environment/schema/session_files.py +13 -2
- package/runtime/gatewaysdk/environment/schema/shape_catalog.py +493 -0
- package/runtime/gatewaysdk/environment/schema/shape_declarations.py +219 -0
- package/runtime/gatewaysdk/environment/schema/skill.py +1 -0
- package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +1 -1
- package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +2 -2
- package/runtime/gatewaysdk/environment/schema/skills/factory-orchestrator/SKILL.md +147 -0
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +5 -1
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +8 -6
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +9 -9
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +33 -2
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +6 -6
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +17 -2
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/new-world-sandbox.md +1 -1
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/shape-catalog.md +59 -0
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/ui-map.md +3 -2
- package/runtime/gatewaysdk/environment/schema/slack.py +55 -10
- package/runtime/gatewaysdk/environment/schema/snapshot.py +28 -2
- package/runtime/gatewaysdk/environment/schema/tasks.py +25 -2
- package/runtime/gatewaysdk/environment/schema/template_record.py +131 -0
- package/runtime/gatewaysdk/environment/schema/tools_world.py +7 -5
- package/runtime/gatewaysdk/environment/schema/ui.py +54 -33
- package/runtime/gatewaysdk/environment/schema/ui_interactions.py +419 -0
- package/runtime/gatewaysdk/environment/schema/ui_recorder.js +895 -0
- package/runtime/gatewaysdk/environment/schema/ui_replay.py +366 -0
- package/runtime/gatewaysdk/environment/schema/ui_replay_record.LICENSE +25 -0
- package/runtime/gatewaysdk/environment/schema/ui_replay_record.js +109 -0
- package/runtime/gatewaysdk/environment/schema/validation.py +24 -1
- package/runtime/gatewaysdk/environment/schema/worker.py +12 -5
- package/runtime/gatewaysdk/environment/schema/worker_key.py +38 -0
- package/runtime/gatewaysdk/environment/schema/worker_peaks.py +38 -0
- package/runtime/gatewaysdk/environment/schema/worker_watch.py +50 -0
- package/runtime/gatewaysdk/environment/schema/workers.py +245 -69
- package/runtime/gatewaysdk/environment/schema/world_host.py +96 -73
- package/runtime/gatewaysdk/environment/schema/world_tests.py +3 -1
- package/runtime/gatewaysdk/environment/secret_values.py +1 -1
- package/runtime/gatewaysdk/environment/world.py +34 -43
- package/runtime/gatewaysdk/environment/world_session_contract.py +7 -34
- package/skills/benchmarks-getting-started/SKILL.md +1 -1
- package/skills/connector-schema-authoring/SKILL.md +2 -2
- package/skills/connector-schema-authoring/connector-worlds.md +3 -2
- package/skills/connector-schema-authoring/world-schema.md +36 -23
- package/skills/factory-orchestrator/SKILL.md +147 -0
- package/skills/world-data-ingestion/ROWS.md +5 -1
- package/skills/world-data-ingestion/SKILL.md +8 -6
- package/skills/worlds-getting-started/SKILL.md +9 -9
- package/skills/worlds-getting-started/references/cli-mcp-map.md +33 -2
- package/skills/worlds-getting-started/references/gotchas.md +6 -6
- package/skills/worlds-getting-started/references/journal-checks.md +17 -2
- package/skills/worlds-getting-started/references/new-world-sandbox.md +1 -1
- package/skills/worlds-getting-started/references/shape-catalog.md +59 -0
- package/skills/worlds-getting-started/references/ui-map.md +3 -2
- package/dist/media-BIApiPzS.d.mts +0 -102
- package/dist/media-BIApiPzS.d.ts +0 -102
|
@@ -16,12 +16,18 @@ Reference for `worlds-getting-started`: every CLI step and its MCP twin, then ho
|
|
|
16
16
|
| `worlds create <slug> --from … [--overlay] [--rows] [--batch] [--layout]` | `create_world` |
|
|
17
17
|
| `worlds migrate <slug> [--apply] [--force]` / `--all` | `migrate_world` |
|
|
18
18
|
| `bench push` | `env_write_file` + `env_commit`, or `create_environment_version` (one file) |
|
|
19
|
-
| `worlds data import` | `import_world_data` |
|
|
19
|
+
| `worlds data import [--state <name>]` | `import_world_data` (`worldState`: the rows land in that world state; main's data and versions do not move; the bulk lane is `request_data_upload` with `worldState`, refused with `publish: "later"`) |
|
|
20
|
+
| `worlds describe <world> [--entity <e>] [--json]` | `describe_world({ slug, ref?, entity? })` (`GET /api/public/worlds/{slug}?ref=&entity=`): entities with keys, row counts and each field's `[redact]` form, plus `catalog` (enumerations, JSON columns, custom fields, ids, sequences, the redaction legend, answer shapes per route; `references/shape-catalog.md`); an unknown entity is refused naming the entities |
|
|
20
21
|
| `worlds data sql <world> '<sql>' [--limit] [--scenario] [--json]` | `sql_world_data` (`POST /api/public/worlds/{slug}/data/sql`; ONE read-only statement over a schema world's rows, whatever its engine; a write, `ATTACH`, `PRAGMA` or a second statement is refused; at most 1000 rows. A db/schema.sql world is a SQLite file: `sqlite3` in a sandbox) |
|
|
22
|
+
| `worlds state list <world>` | `list_world_states({ slug })` (`GET /api/public/worlds/{slug}/states`): the world's states by name, each with its `bindings` and `dataSnapshotId` (null = the state opens on the version's own data). A world state is a named starting point: data plus knob values, opened on any version |
|
|
23
|
+
| `worlds state show <world> <name> [--ref <ref>]` | `get_world_state({ slug, name, ref? })` (`GET …/states/{name}?ref=`): how the state opens on that version (`opens`: `source` `version`\|`state`\|`carried`, `snapshot`, `bindings`, `fingerprint`), or why it does not (`refusal.code`: `state_knobs`, `state_not_carried`, `state_carrying`, `state_data_not_dispatched`); a world with no READY version answers `versionId`, `opens` and `refusal` null |
|
|
24
|
+
| `worlds state create <world> <name> [--description <text>] [--param <k=v>]… [--from-snapshot <id> \| --from-state <name>]` | `create_world_state({ slug, name, description?, bindings?, fromSnapshot?, fromState? })` (`POST …/states`, secret key, 201): answers what `show` answers on main, and a `refusal` there still means the state exists (the CLI prints it as `warning:` and exits 0); a taken name is 409 `state_exists`, both sources 400 |
|
|
25
|
+
| `worlds state delete <world> <name>` | `delete_world_state({ slug, name })` (`DELETE …/states/{name}`): `{ state, deleted: true, runCount }` |
|
|
26
|
+
| `worlds state pull <world> <name> [--ref <ref>] [--out <dir>] [--force]` | `pull_world_state({ slug, name, ref? })` (`GET …/states/{name}/pull`): `opens` plus `download` `{url, expiresAt}`, a signed GET (1 h) of the gzipped SQLite snapshot, null when the state opens on the version's own tree files; the MCP twin hands back the URL, the CLI downloads it into `state.json` + `state.sqlite` and checks the un-gzipped file against `opens.snapshot.sha256` |
|
|
21
27
|
| `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
28
|
| `worlds session seed` | `seed_world_session` |
|
|
23
29
|
| `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 |
|
|
30
|
+
| `worlds requests [list] <slug> [--session <id>] [--version <ref>] [--via api\|ui\|tool\|webhook\|page] [--operation <name>] [--status 200\|2xx\|4xx\|5xx] [--since <time>] [--until <time>] [--limit N] [--cursor <c>] [--json]` | `list_world_requests({ slug, sessionId?, versionId?, via?, operation?, status?, since?, until?, cursor?, limit? })` (`GET /api/public/worlds/{slug}/requests`): every request the world received, from every session, version and door (`via` api, ui, tool, webhook, page), newest first, a page of at most 200 with `nextCursor`; metadata only (method, path, query, status, rows, found, duration, each body's size and `truncated`). The world keeps them for its life under the project's retention setting, and reading records nothing in any session's ledger. `--since`/`--until` take an ISO 8601 date or time (no zone is UTC); a bad filter is exit 2 before any request. UI: the world's Requests view, the session page's activity feed |
|
|
25
31
|
| `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
32
|
| `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
33
|
| `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 |
|
|
@@ -48,6 +54,31 @@ Reference for `worlds-getting-started`: every CLI step and its MCP twin, then ho
|
|
|
48
54
|
| `worlds skill <name>` / `worlds connector skill` | `get_connector_authoring_skill`, `guide` |
|
|
49
55
|
| `worlds connector capture --remote` / poll + download | `start_connector_capture`, `get_connector_capture` (platform agent only) |
|
|
50
56
|
|
|
57
|
+
## Agents that build worlds (the agent SDK)
|
|
58
|
+
|
|
59
|
+
An agent (instructions, a model, the tool servers it may use: `sandbox`, `drive`, `web`, `docs`) runs on the
|
|
60
|
+
platform as your project key, in a thread per input; it builds worlds through the same CLI (`run_gateway_cli`) and
|
|
61
|
+
asks you through `ask_user`. Create it once and edit it live: every edit is a tracked version, live unless
|
|
62
|
+
`--no-deploy`, and a run keeps the version it was sent on. A key, not a personal token, drives all of these.
|
|
63
|
+
|
|
64
|
+
| CLI | MCP |
|
|
65
|
+
| --- | --- |
|
|
66
|
+
| `agents create <name> --instructions <text> [--model] [--effort] [--max-turns] [--tool <server[:tool,…]>]…` | `create_agent({ name, instructions, model?, effort?, maxTurns?, tools? })` |
|
|
67
|
+
| `agents update <name> [--instructions\|--model\|--effort\|--clear-effort\|--max-turns] [--from] [--no-deploy]`, `agents tools attach <name> <server[:tool,…]>…`, `agents tools detach <name> <server>…` | `edit_agent({ name, set?, attach?, detach?, from?, deploy? })` |
|
|
68
|
+
| `agents versions <name>` | `list_agent_versions({ name })` |
|
|
69
|
+
| `agents rollback <name> <versionId> [--force]` | `rollback_agent({ name, versionId, from?, force? })` |
|
|
70
|
+
| `agents push <file.mjs[#export]\|file.py[:attr]\|file.json> [--deploy]` | `push_agent_definition({ definition, deploy? })` |
|
|
71
|
+
| `agents deploy <name> <versionId> [--force]` | `deploy_agent_definition({ agent, versionId, force? })` |
|
|
72
|
+
| `threads create --agent <name> [--autonomy provisionWorlds=true …]` | `create_agent_thread({ agent, title?, autonomy? })` |
|
|
73
|
+
| `threads send <thread> <input> [--watch]`, `agents run <name> <input>` | `send_agent_message({ threadId, input, version? })` |
|
|
74
|
+
| `threads watch <thread> [--run] [--after <cursor>]` (exit 4: it waits for a person) | `get_agent_run({ threadId, runId, waitSeconds? })` |
|
|
75
|
+
| `threads resolve <thread> --action <id> --answer <text>` | `answer_agent_run({ threadId, runId, actionId, answer })` |
|
|
76
|
+
| `threads cancel <thread> [--run]` | `cancel_agent_run({ threadId, runId })` |
|
|
77
|
+
|
|
78
|
+
SDKs: `@withgateway/sdk` (`Gateway`, `tools`; `gateway.agents.create(...)` returns a live `Agent` with `update`,
|
|
79
|
+
`tools.attach|detach`, `versions`, `rollback`, `run`; `defineAgent` + `agents.push` for CI) and `gatewaysdk.agents`
|
|
80
|
+
(the same in snake_case).
|
|
81
|
+
|
|
51
82
|
## Size and time limits (one source: `packages/shared/src/world/limits.ts`)
|
|
52
83
|
|
|
53
84
|
Every door enforces the same number and names it in the refusal; the CLI checks the file
|
package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md
CHANGED
|
@@ -2,12 +2,12 @@
|
|
|
2
2
|
|
|
3
3
|
The things that bite once and never again, moved out of `SKILL.md` to keep it under 500 lines.
|
|
4
4
|
|
|
5
|
-
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
`
|
|
10
|
-
|
|
5
|
+
- Connector templates live on the platform as official worlds: `schema init ./x --connector salesforce`
|
|
6
|
+
fetches the template's current version (`GET /api/public/worlds/templates/salesforce`) and needs a login
|
|
7
|
+
(`gateway auth login` or the `GATEWAY_*` keys); without one it exits 2 and says so, and `schema templates`
|
|
8
|
+
lists `custom` alone with a note. Only `--connector custom` scaffolds offline. The platform agent's
|
|
9
|
+
`run_gateway_cli` has no platform credentials: open a sandbox from the template instead
|
|
10
|
+
(`sandbox open --new <slug> --from salesforce`). No `python3 >= 3.12`? The platform's runtime builds it.
|
|
11
11
|
- `bench push` and `worlds create --from ./x` store the tree as it is; nothing is repackaged into
|
|
12
12
|
an api-kind bundle on the way up. `worlds migrate` turns a bundle pushed before that back into
|
|
13
13
|
the tree. Either way, edit the schema world, not a bundle.
|
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
# Journal checks: verifiers over the requests a session's world received
|
|
2
2
|
|
|
3
3
|
A World Host session records every request its world receives, through every door: the api origin,
|
|
4
|
-
the page's `api_path` (ui) and a declared tool's call
|
|
4
|
+
the page's `api_path` (ui) and a declared tool's call; and, on a UI world, every interaction on its
|
|
5
|
+
page (page). Before a grade the platform waits until the
|
|
5
6
|
host has stored every request it holds for the session (the flush barrier), reads them back and
|
|
6
7
|
hands the grader those requests with whether they are all of them. Three ways to check them, one
|
|
7
8
|
implementation underneath: a declarative check, a `verify.py`, a SQL verifier.
|
|
@@ -26,7 +27,21 @@ as `not recorded`, whatever the grader accepts.
|
|
|
26
27
|
"contentType": "application/json" } }
|
|
27
28
|
```
|
|
28
29
|
|
|
29
|
-
- `via` is `api`, `ui` or `
|
|
30
|
+
- `via` is `api`, `ui`, `tool`, `webhook` or `page`; a tool call has no `method` or `path`.
|
|
31
|
+
- `page` is a UI world's page:
|
|
32
|
+
- **Operations:** `ui.click`, `ui.dblclick`, `ui.contextmenu`, `ui.hover`, `ui.change`, `ui.submit`, `ui.key`, `ui.copy`, `ui.cut`, `ui.paste`, `ui.drag`, `ui.drop`, `ui.file`, `ui.scroll`, `ui.visibility`, `ui.open` and `ui.navigate`. Each has no `method` and the page as its `path`.
|
|
33
|
+
- **The body:** `request.body` (`args` in `calls`) holds the `target`:
|
|
34
|
+
- `name`, `role`, `id`, `testid`, `selector`, `xpath`;
|
|
35
|
+
- `checked`, `expanded`, `pressed`, `selected`, `disabled`;
|
|
36
|
+
- `group` and `options` (a radio's legend and every option, a select's every option);
|
|
37
|
+
- `within` (the enclosing dialog or region) and `context` (the text of its row or card).
|
|
38
|
+
|
|
39
|
+
It also holds the `value`, a `point`, `files`, a drop's `source`, and the page load's `load` and `seq`; `load` and `seq` are in the entry's `query` too, so a journal read without bodies still shows a gap.
|
|
40
|
+
- **Who sees page rows:** only a check that names the page (`via: page`, a `ui.*` operation, or an `args.target.*` / `request.body.target.*` path). Every other check reads what it read before. SQL and python graders see page rows in `gateway_requests` and filter on `via`; before reading them, require one `ui.recording` row and no `ui.unrecorded` row (the host's notes, path `/`, one per UI session: a row count or a `path = '/'` match includes them).
|
|
41
|
+
- **When a check is ungraded:** if the grade has no journal (a cross-world `<alias>.calls` check, or a grade off the platform), if the journal does not show every life of the session recorded its pages (no `ui.recording`, which a World Host with the recorder writes when it first opens a UI session, or a `ui.unrecorded`, which a restore writes when the export it restores came from a host from before the recorder), if pages were served and none reported (a page that never ran the recorder), or if a page load's numbered interactions have a gap (a report lost). A check that names the page on a world with no ui is refused when the session opens.
|
|
42
|
+
- **What is recorded:** clicks and keys count only when trusted; an agent's `el.click()` by script is not a click. A value set by script still counts as a `ui.change`.
|
|
43
|
+
- **Trust:** an interaction is what the page reported. The session's token holder can send one without a browser.
|
|
44
|
+
- **Example** (picked High out of Low, Normal and High): `{"entity": "calls", "where": {"via": "page", "operation": "ui.change", "args.target.group": "Priority", "args.target.name": "High", "args.value": "true"}}`
|
|
30
45
|
- A JSON body reads as JSON, any other as text. Bodies are what the ledger stored: redacted when
|
|
31
46
|
captured, the first 64 KB (`truncated: true` past that). A request past the grade's budget (2,000
|
|
32
47
|
bodies, 8 MiB) carries `withheld: ["request.headers", "request.body", "response.body"]`.
|
|
@@ -19,7 +19,7 @@ What `open` does and does not do:
|
|
|
19
19
|
- The slug goes through the one world slug validator and must be free in the project. A taken
|
|
20
20
|
slug is a 409 `world_exists`; the sandbox never renames it (pick another slug).
|
|
21
21
|
- `--from custom` seeds the working tree with exactly what `gateway worlds schema init <slug>`
|
|
22
|
-
writes; `--from <template>` with
|
|
22
|
+
writes; `--from <template>` with an official template (`gateway worlds schema templates`,
|
|
23
23
|
`GET /api/public/worlds/templates`). An unknown template is a 400 that names the list.
|
|
24
24
|
- No world, container or version is created at open. `open`/`status` say so:
|
|
25
25
|
`containerId: null`, `baseVersionId: null`, `baseContentHash: null`, `branch: "main"`,
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
# The shape catalog
|
|
2
|
+
|
|
3
|
+
Reference for `worlds-getting-started`: what `gateway worlds describe <world> --json` carries under
|
|
4
|
+
`catalog`, where each part comes from, and how a world declares what nothing else says.
|
|
5
|
+
|
|
6
|
+
```bash
|
|
7
|
+
gateway worlds describe x --json # the whole catalog (a platform world: GET /api/public/worlds/x)
|
|
8
|
+
gateway worlds describe x --entity tickets --json # one entity's fields and catalog entries; answers stay whole (?entity=tickets)
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
MCP: `describe_world({ slug, ref?, entity? })` answers the same document. An entity the world does not
|
|
12
|
+
declare is refused naming the ones it does.
|
|
13
|
+
|
|
14
|
+
## What it holds
|
|
15
|
+
|
|
16
|
+
| Key | What | Read from |
|
|
17
|
+
| --- | --- | --- |
|
|
18
|
+
| `enumerations` | `{entity, pointer, values, labels?}`: the values a field allows, at any depth (`/events/*/kind`); a union that also admits other values lists none | JSON Schema `enum`, `const`, `oneOf`/`anyOf` of `const` (a `title` is the label) |
|
|
19
|
+
| `columns`, `types` | `{entity, field, schema}` for every JSON field; the definitions they reach, keyed `<file>.<Name>` (`world.Event`, `types.Link`) | the entity's schema as the compiler resolves it, sibling `schema/*.json` files included, annotations left out |
|
|
20
|
+
| `customFields` | `{entity, field, definitions, key, where, pairs?, add}`: a JSON field's keys are rows of `definitions`; `add` is the row that defines one more | `custom_fields` on the entity |
|
|
21
|
+
| `ids` | `{entity, pointer, target: {entity, key, where}}` or `{entity, pointer, values: [{id, label}]}` | `ids` on the entity (top-level foreign keys stay `entities[].relationships`) |
|
|
22
|
+
| `sequences` | `{entity, field, scope, start, source, operations}`: dense numbers, one counter per `scope` value | `sequences` on the entity; `[operations.api] generate = { f = "int" }` |
|
|
23
|
+
| `redaction` | `legend` for `[hash]` `[preserve]` `[round]` `[drop]`, and `writes`: capture stores these forms, an import, seed or upload only with `--redact apply`, every other write (a factory write too) as written | `[redact]` |
|
|
24
|
+
| `answers` | per route: `records`, `id`, `fields`, `count`, `total`, `cursor`, `cursorParam`, `declared` (JSON pointers, `""` the root) | the route's `[api]` envelope, `hits_key`, `cursor_key`, paging and the entity's key; `[operations.answer]` |
|
|
25
|
+
|
|
26
|
+
A write that fills a JSON field writes the shape under `columns`; a key under `customFields` needs its
|
|
27
|
+
definitions row first (`add` names it); an id under `ids` must be one of the target's rows or values.
|
|
28
|
+
|
|
29
|
+
`catalog` is `null` when describe could not read it: the entities still list, and a local describe adds
|
|
30
|
+
`catalogRefused` with the refusal (for a built world, a `[ui] static` without its `index.html`, say).
|
|
31
|
+
|
|
32
|
+
## Declaring what nothing else says
|
|
33
|
+
|
|
34
|
+
In `schema/world.json`, on the entity (all optional; none changes stored rows):
|
|
35
|
+
|
|
36
|
+
```json
|
|
37
|
+
"custom_fields": [{"field": "properties", "definitions": "acme_fields", "key": "name", "where": {"object_type": "tickets"}}],
|
|
38
|
+
"ids": [{"pointer": "/links/*/type_id", "values": [{"id": 1, "label": "parent"}, {"id": 2, "label": "duplicate"}]}],
|
|
39
|
+
"sequences": [{"field": "number", "scope": ["queue_id"], "start": 100}]
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
`pairs: {"id": "id", "value": "value"}` says the field is an array of id/value items instead of an
|
|
43
|
+
object. In `connector.toml`, under an `[[operations]]` entry whose answer the route settings cannot
|
|
44
|
+
describe (a handler's own shape):
|
|
45
|
+
|
|
46
|
+
```toml
|
|
47
|
+
[operations.answer]
|
|
48
|
+
records = "/results"
|
|
49
|
+
id = "ticket_id"
|
|
50
|
+
fields = ["status"]
|
|
51
|
+
count = "/count"
|
|
52
|
+
total = "/meta/total"
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
`gateway worlds schema compile` and `check` refuse a declaration naming a field or entity the world
|
|
56
|
+
does not have, a sequence on a non-integer field, an id with both `entity` and `values`, a pointer
|
|
57
|
+
that is not a JSON Pointer, or a scoped sequence (or one with its own `start`) on a field a route
|
|
58
|
+
generates as `int`, which the world numbers across the whole entity from 1 (`catalog` / `spec` codes,
|
|
59
|
+
with the location).
|
package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/ui-map.md
CHANGED
|
@@ -5,8 +5,9 @@ is the world's container.
|
|
|
5
5
|
|
|
6
6
|
| Thing | Where |
|
|
7
7
|
| --- | --- |
|
|
8
|
-
|
|
|
9
|
-
| One connector: Overview (verdict + schema), API (served routes, tools), Worlds (built from it, Cancel/Retry) | `/project/{projectId}/
|
|
8
|
+
| Public worlds of every organization, then connectors, shipped and workspace, with Create world / Clone; New connector | WorldHub `/project/{projectId}/worldhub` (`/connectors` redirects) |
|
|
9
|
+
| One connector: Overview (verdict + schema), API (served routes, tools), Worlds (built from it, Cancel/Retry), UI | `/project/{projectId}/worldhub/{slug}` |
|
|
10
|
+
| A public world as another organization sees it: Overview (schema of `main`), API, History (code changes only) | `/project/{projectId}/worldhub/worlds/{containerId}` |
|
|
10
11
|
| A world: tabs Overview, Scenarios, Schema, Results, Evals, History | `/project/{projectId}/world?env={containerId}&tab=<tab>` |
|
|
11
12
|
| Schema tab: entities, tool schemas, the pin back to the connector, and the Redaction tile (per-field hash / preserve / round / drop, salt = connector slug) | `...&tab=schema` |
|
|
12
13
|
| Overview: provenance (type, "Created from <connector> <version>", author), then Relationships — Links picture, Uses (pin → resolved version, entity mappings with transform chains), Used by; unresolved pins shown, never omitted | `...&tab=overview` |
|
|
@@ -11,16 +11,19 @@ import hashlib
|
|
|
11
11
|
from pathlib import Path
|
|
12
12
|
import shutil
|
|
13
13
|
import tempfile
|
|
14
|
+
from typing import Mapping
|
|
14
15
|
|
|
15
16
|
from .compiler import Contract, check_bundle
|
|
16
|
-
from .scaffold import
|
|
17
|
+
from .scaffold import TemplateWorld
|
|
18
|
+
from .template_record import TemplateRecord
|
|
17
19
|
from .database import WorldDatabase
|
|
18
20
|
from .validation import encoded, fail, read_json
|
|
19
|
-
from ._slack_fidelity import fidelity_report, load_capabilities
|
|
21
|
+
from ._slack_fidelity import fidelity_report, load_capabilities
|
|
20
22
|
from ._slack_scenario import write_scenario
|
|
21
23
|
|
|
22
24
|
FORMAT = "gateway-slack-evidence/1"
|
|
23
25
|
MAPPING = {"id": "slack-evidence", "version": "1"}
|
|
26
|
+
PUBLISHED_CAPABILITIES = "schema/capabilities.json"
|
|
24
27
|
|
|
25
28
|
|
|
26
29
|
def _merge(old, patch):
|
|
@@ -657,12 +660,21 @@ def synthetic_slack_evidence() -> dict:
|
|
|
657
660
|
}
|
|
658
661
|
|
|
659
662
|
|
|
660
|
-
def build_slack_bundle(
|
|
661
|
-
|
|
663
|
+
def build_slack_bundle(
|
|
664
|
+
destination: str | Path,
|
|
665
|
+
*,
|
|
666
|
+
template: Mapping[str, bytes],
|
|
667
|
+
evidence: dict | None = None,
|
|
668
|
+
name: str | None = None,
|
|
669
|
+
) -> Contract:
|
|
670
|
+
"""Create a populated executable Slack bundle in a new/empty directory from the
|
|
671
|
+
official Slack world's files (the world the platform serves for the Slack template)."""
|
|
662
672
|
evidence = synthetic_slack_evidence() if evidence is None else evidence
|
|
663
673
|
workspace, principal = _envelope(evidence)
|
|
664
674
|
destination = Path(destination)
|
|
665
|
-
|
|
675
|
+
official = TemplateWorld(template, location="/template")
|
|
676
|
+
contract = official.write(destination, name=name or "slack-world")
|
|
677
|
+
capabilities = load_capabilities(official.files, PUBLISHED_CAPABILITIES)
|
|
666
678
|
try:
|
|
667
679
|
diagnostics = {}
|
|
668
680
|
batch = map_slack_evidence(evidence, contract, diagnostics=diagnostics)
|
|
@@ -677,22 +689,43 @@ def build_slack_bundle(destination: str | Path, *, evidence: dict | None = None,
|
|
|
677
689
|
encoded({"workspace_id": workspace["id"], "user_id": principal["user_id"]})
|
|
678
690
|
)
|
|
679
691
|
(destination / "fidelity.json").write_bytes(
|
|
680
|
-
encoded(
|
|
692
|
+
encoded(
|
|
693
|
+
fidelity_report(
|
|
694
|
+
contract,
|
|
695
|
+
evidence,
|
|
696
|
+
batch,
|
|
697
|
+
diagnostics,
|
|
698
|
+
mapping=MAPPING,
|
|
699
|
+
capabilities=capabilities,
|
|
700
|
+
template_digest=official.digest,
|
|
701
|
+
)
|
|
702
|
+
)
|
|
681
703
|
)
|
|
682
|
-
(destination / "capabilities.json").write_bytes(encoded(
|
|
704
|
+
(destination / "capabilities.json").write_bytes(encoded(capabilities))
|
|
683
705
|
write_scenario(destination, evidence, batch, entities=contract.entities)
|
|
684
706
|
(destination / "slack-imports.json").write_bytes(
|
|
685
707
|
encoded({batch["id"]: hashlib.sha256(encoded(evidence)).hexdigest()})
|
|
686
708
|
)
|
|
687
709
|
check_bundle(destination)
|
|
710
|
+
TemplateRecord.of_world(destination, connector=official.record.connector, digest=official.digest).write(
|
|
711
|
+
destination
|
|
712
|
+
)
|
|
688
713
|
return contract
|
|
689
714
|
except BaseException:
|
|
690
715
|
shutil.rmtree(destination)
|
|
691
716
|
raise
|
|
692
717
|
|
|
693
718
|
|
|
694
|
-
def refresh_slack_bundle(
|
|
719
|
+
def refresh_slack_bundle(
|
|
720
|
+
destination: str | Path,
|
|
721
|
+
evidence: dict | None = None,
|
|
722
|
+
*,
|
|
723
|
+
template: Mapping[str, bytes],
|
|
724
|
+
batch_id: str | None = None,
|
|
725
|
+
) -> dict:
|
|
695
726
|
"""Validate then append one refresh batch; preserve original batch and lineage.
|
|
727
|
+
``template`` is the official Slack world's files: a world built from another template
|
|
728
|
+
version is refused.
|
|
696
729
|
|
|
697
730
|
Call this only on an isolated copy while constructing a new immutable version.
|
|
698
731
|
The publisher owns expected-parent CAS and immutable version promotion.
|
|
@@ -705,7 +738,9 @@ def refresh_slack_bundle(destination: str | Path, evidence: dict | None = None,
|
|
|
705
738
|
fail("slack_evidence", "Refresh cannot change the bound workspace or principal", "/evidence/principal")
|
|
706
739
|
contract = check_bundle(destination)
|
|
707
740
|
previous_report = read_json(destination / "fidelity.json")
|
|
708
|
-
|
|
741
|
+
official = TemplateWorld(template, location="/template")
|
|
742
|
+
official.record.verify(official.files, "/template")
|
|
743
|
+
if previous_report.get("template_digest") != official.digest:
|
|
709
744
|
fail(
|
|
710
745
|
"slack_template_mismatch",
|
|
711
746
|
"Refresh requires the original template package; create a new world with the current template",
|
|
@@ -747,7 +782,17 @@ def refresh_slack_bundle(destination: str | Path, evidence: dict | None = None,
|
|
|
747
782
|
imports[batch_id] = digest
|
|
748
783
|
(destination / "slack-imports.json").write_bytes(encoded(imports))
|
|
749
784
|
(destination / "fidelity.json").write_bytes(
|
|
750
|
-
encoded(
|
|
785
|
+
encoded(
|
|
786
|
+
fidelity_report(
|
|
787
|
+
contract,
|
|
788
|
+
evidence,
|
|
789
|
+
batch,
|
|
790
|
+
diagnostics,
|
|
791
|
+
mapping=MAPPING,
|
|
792
|
+
capabilities=load_capabilities(official.files, PUBLISHED_CAPABILITIES),
|
|
793
|
+
template_digest=official.digest,
|
|
794
|
+
)
|
|
795
|
+
)
|
|
751
796
|
)
|
|
752
797
|
write_scenario(destination, evidence, state, entities=contract.entities)
|
|
753
798
|
return result
|
|
@@ -66,6 +66,7 @@ from .domain_migration import DomainMigration
|
|
|
66
66
|
from .validation import ContractError, canonical, fail, read_json
|
|
67
67
|
|
|
68
68
|
SIDECAR = "state.json"
|
|
69
|
+
SNAPSHOT_OUTPUTS = frozenset({*(engine.snapshot_name for engine in WorldDatabase.engines()), SIDECAR})
|
|
69
70
|
PIN = "snapshot.json"
|
|
70
71
|
DEFAULT_DIR = "db"
|
|
71
72
|
SCENARIOS = "scenarios"
|
|
@@ -406,9 +407,29 @@ def scenario_dirs(world: str | Path) -> dict[str, Path]:
|
|
|
406
407
|
return out
|
|
407
408
|
|
|
408
409
|
|
|
409
|
-
|
|
410
|
+
SCENARIO_GRADERS = "checks"
|
|
411
|
+
|
|
412
|
+
|
|
413
|
+
def scenario_seed_dir(scenario: Path) -> Path:
|
|
414
|
+
"""Where a scenario's rows live: a directory inside the scenario, neither the scenario itself
|
|
415
|
+
(its built snapshot sits there) nor its graders, so a copy that keeps a scenario's code and
|
|
416
|
+
drops its data can tell the two apart by path."""
|
|
410
417
|
table = tomllib.loads((scenario / "scenario.toml").read_text(encoding="utf-8"))
|
|
411
|
-
|
|
418
|
+
name = str(table.get("seed") or "seed")
|
|
419
|
+
root = scenario.resolve()
|
|
420
|
+
seed_dir = (scenario / name).resolve()
|
|
421
|
+
inside = seed_dir != root and seed_dir.is_relative_to(root)
|
|
422
|
+
if not inside or seed_dir.is_relative_to(root / SCENARIO_GRADERS):
|
|
423
|
+
fail(
|
|
424
|
+
"scenario",
|
|
425
|
+
f"{scenario.name}/scenario.toml seed {name!r} must name a directory inside the scenario, not the scenario itself or {SCENARIO_GRADERS}/",
|
|
426
|
+
f"/{SCENARIOS}/{scenario.name}",
|
|
427
|
+
)
|
|
428
|
+
return seed_dir
|
|
429
|
+
|
|
430
|
+
|
|
431
|
+
def scenario_seed_files(scenario: Path) -> list[Path]:
|
|
432
|
+
seed_dir = scenario_seed_dir(scenario)
|
|
412
433
|
return sorted(seed_dir.glob("*.json")) if seed_dir.is_dir() else []
|
|
413
434
|
|
|
414
435
|
|
|
@@ -527,6 +548,11 @@ def verify(snapshot: Path, contract: Contract, remedy: str = REBUILD_REMEDY) ->
|
|
|
527
548
|
return sidecar
|
|
528
549
|
|
|
529
550
|
|
|
551
|
+
def is_snapshot_output(path: str) -> bool:
|
|
552
|
+
"""A built snapshot or its sidecar: an output of a tree, never a source. Twin of ``isWorldSnapshotOutput``."""
|
|
553
|
+
return path.rsplit("/", 1)[-1] in SNAPSHOT_OUTPUTS
|
|
554
|
+
|
|
555
|
+
|
|
530
556
|
def snapshot_name(contract: Contract) -> str:
|
|
531
557
|
"""The file name the contract's engine writes a snapshot to."""
|
|
532
558
|
return WorldDatabase.for_contract(contract).snapshot_name
|
|
@@ -76,12 +76,14 @@ class TaskSpec:
|
|
|
76
76
|
def allows_tool(self, tool: str) -> bool:
|
|
77
77
|
return self.tools is None or tool in self.tools
|
|
78
78
|
|
|
79
|
+
def grader_checks(self) -> list[dict]:
|
|
80
|
+
return list(self.grader["checks"]) if self.grader is not None and self.grader["kind"] == "assertions" else []
|
|
81
|
+
|
|
79
82
|
def entities(self) -> list[str]:
|
|
80
83
|
named: list[str] = []
|
|
81
84
|
if self.seed is not None:
|
|
82
85
|
named.extend(self.seed["rows"])
|
|
83
|
-
|
|
84
|
-
named.extend(check["entity"] for check in self.grader["checks"])
|
|
86
|
+
named.extend(check["entity"] for check in self.grader_checks())
|
|
85
87
|
# A session task is named for its alias: only checks under it name this world's entities.
|
|
86
88
|
own = f"{self.name}."
|
|
87
89
|
for verifier in self.verifiers:
|
|
@@ -96,6 +98,27 @@ JOURNAL = "gateway_requests"
|
|
|
96
98
|
JOURNAL_META = "gateway_journal"
|
|
97
99
|
RESERVED_STATE_KEYS = frozenset({CALL_LOG, "snapshot", JOURNAL})
|
|
98
100
|
DOOR_FIELD = "via"
|
|
101
|
+
PAGE_DOOR = "page"
|
|
102
|
+
PAGE_SERVED = "ui.served"
|
|
103
|
+
PAGE_RECORDING = "ui.recording"
|
|
104
|
+
PAGE_UNRECORDED_LIFE = "ui.unrecorded"
|
|
105
|
+
PAGE_NOTES = frozenset({PAGE_SERVED, PAGE_RECORDING, PAGE_UNRECORDED_LIFE})
|
|
106
|
+
PAGE_UNJOURNALED = (
|
|
107
|
+
"a check on the page's interactions is decided from the session's journal, which shows whether its pages "
|
|
108
|
+
"were recorded; this grade has none (a cross-world check, or a grade off the platform): ungraded"
|
|
109
|
+
)
|
|
110
|
+
PAGE_UNRECORDED = (
|
|
111
|
+
"no World Host noted that it recorded every part of this session's pages (a host from before the page "
|
|
112
|
+
"recorder served some of them), so a check on the page's interactions cannot be decided: ungraded"
|
|
113
|
+
)
|
|
114
|
+
PAGE_UNHEARD = (
|
|
115
|
+
"the session served its ui's pages but no page reported an interaction (a page that never ran the "
|
|
116
|
+
"recorder), so a check on the page's interactions cannot be decided: ungraded"
|
|
117
|
+
)
|
|
118
|
+
PAGE_GAP = (
|
|
119
|
+
"the page numbered {missing} interactions it never reported (a report lost on the way), so a check "
|
|
120
|
+
"on the page's interactions cannot be decided: ungraded"
|
|
121
|
+
)
|
|
99
122
|
WITHHELD_FIELD = "withheld"
|
|
100
123
|
ROW_FIELDS = ("found", "rows")
|
|
101
124
|
ORDER_KEYS = ("before", "after")
|
|
@@ -0,0 +1,131 @@
|
|
|
1
|
+
"""``schema/template.json``: the template a world was built from, the template's digest, the compiler outputs the
|
|
2
|
+
build produced, and the sha256 of every other file the built world holds. A reader trusts the digest only while the
|
|
3
|
+
world still holds exactly those files (twin: ``TemplateRecord`` in gateway/packages/shared/src/world/templateRecord.ts;
|
|
4
|
+
the outputs a record may name are pinned by conformance/template-record.json)."""
|
|
5
|
+
|
|
6
|
+
from __future__ import annotations
|
|
7
|
+
|
|
8
|
+
import hashlib
|
|
9
|
+
import json
|
|
10
|
+
from dataclasses import dataclass
|
|
11
|
+
from pathlib import Path, PurePosixPath
|
|
12
|
+
from typing import Any, Mapping
|
|
13
|
+
|
|
14
|
+
from ..world import WorldTree
|
|
15
|
+
from .compiler import GENERATED, LOCK
|
|
16
|
+
from .snapshot import is_snapshot_output
|
|
17
|
+
from .ui import GENERATED_FILES, is_generated, read_ui_declaration
|
|
18
|
+
from .validation import fail, tree_path
|
|
19
|
+
|
|
20
|
+
RECORD = "schema/template.json"
|
|
21
|
+
COMPILED_OUTPUTS = (*GENERATED, LOCK)
|
|
22
|
+
_SHA256 = frozenset("0123456789abcdef")
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
def is_template_output(path: str) -> bool:
|
|
26
|
+
return path in COMPILED_OUTPUTS or PurePosixPath(path).name in GENERATED_FILES
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
@dataclass(frozen=True)
|
|
30
|
+
class TemplateRecord:
|
|
31
|
+
connector: str
|
|
32
|
+
digest: str
|
|
33
|
+
outputs: tuple[str, ...]
|
|
34
|
+
sources: Mapping[str, str]
|
|
35
|
+
|
|
36
|
+
@classmethod
|
|
37
|
+
def of_world(cls, root: Path, *, connector: str, digest: str) -> "TemplateRecord":
|
|
38
|
+
outputs = tuple(sorted(_compiled_outputs(root)))
|
|
39
|
+
sources = {
|
|
40
|
+
path: hashlib.sha256((root / path).read_bytes()).hexdigest()
|
|
41
|
+
for path in WorldTree.from_dir(root).hashed_paths()
|
|
42
|
+
if _covered(path, outputs)
|
|
43
|
+
}
|
|
44
|
+
return cls(connector, digest, outputs, sources)
|
|
45
|
+
|
|
46
|
+
@classmethod
|
|
47
|
+
def parse(cls, files: Mapping[str, bytes], location: str) -> "TemplateRecord":
|
|
48
|
+
where = f"{location}/{RECORD}"
|
|
49
|
+
try:
|
|
50
|
+
raw = json.loads(files[RECORD].decode("utf-8")) if RECORD in files else None
|
|
51
|
+
except (UnicodeDecodeError, ValueError):
|
|
52
|
+
raw = None
|
|
53
|
+
if not isinstance(raw, dict):
|
|
54
|
+
fail("template", f"The world carries no readable {RECORD}", where)
|
|
55
|
+
return cls(
|
|
56
|
+
_text(raw.get("connector"), "connector", where),
|
|
57
|
+
_sha256(raw.get("digest"), "digest", where),
|
|
58
|
+
_outputs(raw.get("outputs"), where),
|
|
59
|
+
_sources(raw.get("sources"), where),
|
|
60
|
+
)
|
|
61
|
+
|
|
62
|
+
def verify(self, files: Mapping[str, bytes], location: str) -> None:
|
|
63
|
+
"""Refuse a world that no longer holds, byte for byte, every file it was built with: an edit in place."""
|
|
64
|
+
held = {path for path in files if _covered(path, self.outputs)}
|
|
65
|
+
changed = sorted(
|
|
66
|
+
path
|
|
67
|
+
for path in held | set(self.sources)
|
|
68
|
+
if path not in held
|
|
69
|
+
or path not in self.sources
|
|
70
|
+
or hashlib.sha256(files[path]).hexdigest() != self.sources[path]
|
|
71
|
+
)
|
|
72
|
+
if changed:
|
|
73
|
+
fail(
|
|
74
|
+
"template",
|
|
75
|
+
f"The world no longer holds the files it was built with from its template ({', '.join(changed[:5])}); "
|
|
76
|
+
"rebuild it from its template",
|
|
77
|
+
location,
|
|
78
|
+
)
|
|
79
|
+
|
|
80
|
+
def write(self, root: Path) -> None:
|
|
81
|
+
document = {
|
|
82
|
+
"connector": self.connector,
|
|
83
|
+
"digest": self.digest,
|
|
84
|
+
"outputs": list(self.outputs),
|
|
85
|
+
"sources": dict(sorted(self.sources.items())),
|
|
86
|
+
}
|
|
87
|
+
(root / RECORD).write_bytes((json.dumps(document, indent=2) + "\n").encode("utf-8"))
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
def _covered(path: str, outputs: tuple[str, ...]) -> bool:
|
|
91
|
+
return path != RECORD and path not in outputs and not is_snapshot_output(path)
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
def _compiled_outputs(root: Path) -> list[str]:
|
|
95
|
+
outputs = [path for path in COMPILED_OUTPUTS if (root / path).is_file()]
|
|
96
|
+
ui = read_ui_declaration(root)
|
|
97
|
+
static = PurePosixPath(ui.static).as_posix() if ui is not None else None
|
|
98
|
+
if static is None or ui.generated is not True or not is_generated(root / static / "index.html"):
|
|
99
|
+
return outputs
|
|
100
|
+
return [*outputs, *(f"{static}/{name}" for name in GENERATED_FILES if (root / static / name).is_file())]
|
|
101
|
+
|
|
102
|
+
|
|
103
|
+
def _text(value: Any, field: str, where: str) -> str:
|
|
104
|
+
if not isinstance(value, str) or not value:
|
|
105
|
+
fail("template", f"{RECORD} names no {field}", where)
|
|
106
|
+
return value
|
|
107
|
+
|
|
108
|
+
|
|
109
|
+
def _sha256(value: Any, field: str, where: str) -> str:
|
|
110
|
+
if not isinstance(value, str) or len(value) != 64 or not set(value) <= _SHA256:
|
|
111
|
+
fail("template", f"{RECORD} {field} is not a sha256 hex digest", where)
|
|
112
|
+
return value
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
def _outputs(value: Any, where: str) -> tuple[str, ...]:
|
|
116
|
+
if not isinstance(value, list) or not all(isinstance(path, str) for path in value):
|
|
117
|
+
fail("template", f"{RECORD} names no outputs list", where)
|
|
118
|
+
for path in value:
|
|
119
|
+
tree_path(path, where)
|
|
120
|
+
if not is_template_output(path):
|
|
121
|
+
fail("template", f"{RECORD} names {path} as an output; only compiler outputs are", where)
|
|
122
|
+
return tuple(value)
|
|
123
|
+
|
|
124
|
+
|
|
125
|
+
def _sources(value: Any, where: str) -> dict[str, str]:
|
|
126
|
+
if not isinstance(value, dict) or not value:
|
|
127
|
+
fail("template", f"{RECORD} names no source files", where)
|
|
128
|
+
for path, digest in value.items():
|
|
129
|
+
tree_path(path, where)
|
|
130
|
+
_sha256(digest, f"source {path}", where)
|
|
131
|
+
return dict(value)
|
|
@@ -208,7 +208,7 @@ def _scenario_task(name: str, scenario: Path) -> ToolsTask:
|
|
|
208
208
|
table = tomllib.loads((scenario / "scenario.toml").read_text(encoding="utf-8"))
|
|
209
209
|
instruction = scenario / "instruction.md"
|
|
210
210
|
prompt = instruction.read_text(encoding="utf-8") if instruction.is_file() else str(table.get("instruction") or "")
|
|
211
|
-
verify = scenario /
|
|
211
|
+
verify = scenario / snapshots.SCENARIO_GRADERS / "verify.py"
|
|
212
212
|
return ToolsTask(
|
|
213
213
|
id=name,
|
|
214
214
|
prompt=prompt.strip() or f"Drive the world into the state the scenario '{name}' checks.",
|
|
@@ -262,8 +262,8 @@ def load_tasks(bundle: Path, manifest: _bundle.EnvManifest, verifiers: list[str]
|
|
|
262
262
|
def load_tools_version(
|
|
263
263
|
bundle: Path,
|
|
264
264
|
template: Path,
|
|
265
|
-
snapshot: dict[str, str] | None,
|
|
266
265
|
*,
|
|
266
|
+
fetched: bool,
|
|
267
267
|
run_handlers: bool,
|
|
268
268
|
) -> ToolsVersion:
|
|
269
269
|
if not is_tools_bundle(bundle):
|
|
@@ -278,15 +278,13 @@ def load_tools_version(
|
|
|
278
278
|
"`gateway worlds schema init` starts one that does",
|
|
279
279
|
)
|
|
280
280
|
contract = check_bundle(bundle)
|
|
281
|
-
if snapshot:
|
|
282
|
-
snapshots.fetch(bundle, contract, snapshot["url"], snapshot["sha256"], snapshot["digest"])
|
|
283
281
|
# connector.toml is read as the api runtime reads it, so an unservable route is refused at cache time.
|
|
284
282
|
spec = settings = None
|
|
285
283
|
if (bundle / SPEC).is_file():
|
|
286
284
|
spec = load_spec(bundle)
|
|
287
285
|
settings = load_api_settings(bundle, spec)
|
|
288
286
|
read_fields = RouteBindings.served(spec, settings, contract)
|
|
289
|
-
proven = ProvenTemplate.prove(bundle, template, contract, fetched=
|
|
287
|
+
proven = ProvenTemplate.prove(bundle, template, contract, fetched=fetched, read_fields=read_fields)
|
|
290
288
|
verifiers = verifier_names(bundle)
|
|
291
289
|
if REWARD in verifiers:
|
|
292
290
|
fail("host", f"verifier name '{REWARD}' is reserved for the scalar grade")
|
|
@@ -351,6 +349,7 @@ class ToolsWorld:
|
|
|
351
349
|
allowed: frozenset[str] | None = None,
|
|
352
350
|
dependencies: dict[str, DependencyWorld] | None = None,
|
|
353
351
|
calls: CallLog | None = None,
|
|
352
|
+
parameters: dict[str, str] | None = None,
|
|
354
353
|
) -> None:
|
|
355
354
|
if version.handlers is None:
|
|
356
355
|
fail("host", "a mock-tools session runs world-authored handlers; only a version worker opens one")
|
|
@@ -361,6 +360,7 @@ class ToolsWorld:
|
|
|
361
360
|
self.task = self._task_of(version, task)
|
|
362
361
|
self.allowed = allowed
|
|
363
362
|
self.calls = calls
|
|
363
|
+
self.parameters = dict(parameters or {})
|
|
364
364
|
self.dependencies = dict(dependencies or {})
|
|
365
365
|
self.served = served_with_dependencies(version, self.dependencies)
|
|
366
366
|
self._task_seed = seed
|
|
@@ -429,6 +429,8 @@ class ToolsWorld:
|
|
|
429
429
|
scenario_id = str(self.task.metadata.get("scenario_id") or self.task.id)
|
|
430
430
|
for world in (self.world, *self.worlds.values()):
|
|
431
431
|
world.set_task_context(scenario_id)
|
|
432
|
+
if self.parameters:
|
|
433
|
+
self.world.set_run_parameters(self.parameters)
|
|
432
434
|
self._attach()
|
|
433
435
|
|
|
434
436
|
def _attach(self) -> None:
|