@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
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: worlds-getting-started
|
|
3
|
-
description: Starter guide for building worlds and environments on the platform, end to end, for an agent (Claude Code, Cursor, Codex). Use when starting a world from scratch, building a world or environment, mocking a vendor, importing a Swagger or OpenAPI spec into a world (schema init --from-openapi), choosing between
|
|
3
|
+
description: Starter guide for building worlds and environments on the platform, end to end, for an agent (Claude Code, Cursor, Codex). Use when starting a world from scratch, building a world or environment, mocking a vendor, importing a Swagger or OpenAPI spec into a world (schema init --from-openapi), choosing between an official template, a workspace connector, an OpenAPI document, a vendor API capture or a custom contract, provisioning worlds for tenants in one call (worlds create), publishing with bench push, opening a session, reading every request a world received (worlds requests), checks over those requests (journal checks on gateway_requests, calls, verify.py, SQL verifiers; task try before you save, task regrade of past runs), running and grading, or iterating with pull, fork, diff and edit sessions (worlds edit status/close/rollback: version control without PRs). Every CLI step names its MCP twin (list_connectors, publish_connector, create_world, init_world_from_connector, env_write_file, env_commit, import_world_data, run_evaluation and the rest) and where the result shows in the UI.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Worlds: getting started
|
|
@@ -55,7 +55,7 @@ first, then `guide({ topic: "connectors" })` for the connector loop and `guide({
|
|
|
55
55
|
`schema init` writes: `schema/world.json` (the contract), `gateway-env.toml` with `[schema]`,
|
|
56
56
|
and on top of it, optional, `tools/handlers.py` (tools, the `list_messages` style) and
|
|
57
57
|
`connector.toml` + `api/handlers.py` (the vendor's HTTP routes) with a `[ui]` section for the
|
|
58
|
-
page over those routes (every
|
|
58
|
+
page over those routes (every official template declares one; `schema compile` generates
|
|
59
59
|
`ui/static` from the contract, `gateway worlds schema ui init ./x` declares it for a world of
|
|
60
60
|
your own, `[ui] generated = false` keeps a hand-written page — the UI-twin templates such as
|
|
61
61
|
notion, servicenow and zendesk ship a built twin under `ui/static` that way). It is stored as it is, and
|
|
@@ -75,7 +75,7 @@ browser; the tools are always there). Everything else is derived or retired (own
|
|
|
75
75
|
|
|
76
76
|
| You have | Path | First command |
|
|
77
77
|
| --- | --- | --- |
|
|
78
|
-
| A vendor
|
|
78
|
+
| A vendor with an official template (`gateway worlds schema templates`: github, slack, salesforce, jira, linear, workday, netsuite, microsoft-teams, google-drive, google-calendar, jamf, kandji, apple-business-manager, …; fetched from the platform, so log in first) | official template | `gateway worlds schema init ./x --connector github` |
|
|
79
79
|
| A connector someone in your org (or any org) already published | workspace connector | `gateway worlds connector list --hub` then `schema init ./x --connector workspace:<slug>` |
|
|
80
80
|
| A Swagger 2.0 / OpenAPI 3.x document (JSON or YAML; a file, `drive:<path>` or a URL) | OpenAPI import | `gateway worlds schema init ./x --from-openapi petstore.yaml` — entities + routes from the spec, plan printed first; §2 "From an OpenAPI spec" |
|
|
81
81
|
| A vendor API with a dev key and no template | vendor API capture | `schema init ./x --connector custom`, write `connector.toml`, capture, ingest (`documentation/features/connector-worlds.md`) |
|
|
@@ -188,7 +188,7 @@ MCP: `validate_connector_template({ files, slug? })` compiles without writing; a
|
|
|
188
188
|
## 4. Data
|
|
189
189
|
|
|
190
190
|
```bash
|
|
191
|
-
gateway worlds describe ./x
|
|
191
|
+
gateway worlds describe ./x [--entity e] [--json] # entities, keys, row counts, [redact] per field; --json: the shape catalog
|
|
192
192
|
gateway worlds data show ./x # kind + entity counts
|
|
193
193
|
gateway worlds data query ./x users --where email=jo@acme.test --resolve # the rows you mean; plaintext into a hashed field
|
|
194
194
|
gateway worlds data import ./x rows.json # rows file: {entity: [rows]} | JSONL | .csv/.tsv --entity (cells cast by the schema; --delimiter)
|
|
@@ -204,7 +204,7 @@ gateway worlds data ingest ./x calls.jsonl --map ingest.toml # or a
|
|
|
204
204
|
shape-preserved (`[preserve]`), rounded, or dropped (`[drop]`, never on disk). A hashed field is still looked up by
|
|
205
205
|
its plaintext: the world's `[redact]` policy fixes the stored form (`sha256:` of `<slug>:<value>`), and the CLI, the
|
|
206
206
|
SDK (`storedForms` in `@withgateway/sdk/worlds`) and the served handlers all compute it from that one rule. A dropped
|
|
207
|
-
field is a documented miss, not an error.
|
|
207
|
+
field is a documented miss, not an error. Tags are capture's forms: other writes land as written (`--json` has the legend). `--json` also carries the **shape catalog** (enums at any depth, JSON shapes, custom fields, ids, sequences, each route's answer shape; MCP `describe_world`): `references/shape-catalog.md`.
|
|
208
208
|
|
|
209
209
|
Rows file contract, modes, upsert and refusals: `world-data-ingestion`. Captures: pace with `[capture] requests_per_minute`;
|
|
210
210
|
a vendor that allow-lists IPs is captured with `--remote` after `gateway bench secrets set --env x --key VENDOR_API_KEY`.
|
|
@@ -231,7 +231,7 @@ makes the world under a PAT session; under an API key it returns the initialized
|
|
|
231
231
|
For a world you provision rather than iterate on (a tenant's Slack, one per customer):
|
|
232
232
|
|
|
233
233
|
```bash
|
|
234
|
-
gateway worlds create acme-slack --from slack --rows rows.json --name "Acme Slack" #
|
|
234
|
+
gateway worlds create acme-slack --from slack --rows rows.json --name "Acme Slack" # official template + their rows
|
|
235
235
|
gateway worlds create acme-crm --from workspace:acme-crm --overlay ./overlay --json # hub connector + your edits
|
|
236
236
|
gateway worlds create acme-custom --from ./x # a directory, any kind
|
|
237
237
|
gateway worlds create acme-drive --from-connection google_drive # the connector's template filled from an active connection (id or slug); `--from <template>` picks the template
|
|
@@ -246,7 +246,7 @@ version, attributed to the key (`apikey:<id>`), owned by nobody. 409 when the sl
|
|
|
246
246
|
project. `--layout api-bundle` (body `layout`) packages the tree as its api bundle instead —
|
|
247
247
|
deprecated, and the answer's `deprecations` says so. A legacy tools bundle, a Harbor tree or a
|
|
248
248
|
verifiers package is a 400 `world_kind_retired`. `--from-connection` binds an active connection
|
|
249
|
-
(
|
|
249
|
+
(WorldHub page) shared with the key's project — a personal one serves its owner alone (MCP as
|
|
250
250
|
that user); an inactive connection or a template that does not read the connector is refused,
|
|
251
251
|
nothing created. Refresh later with `gateway worlds data pull <slug> --connection …`.
|
|
252
252
|
|
|
@@ -256,7 +256,7 @@ is the same request and answer; a PAT session reaches its own personal connectio
|
|
|
256
256
|
|
|
257
257
|
### Migrate a stored world: `worlds migrate`
|
|
258
258
|
|
|
259
|
-
The platform's connector worlds (the ones the
|
|
259
|
+
The platform's connector worlds (the ones the WorldHub page lists — containers created from
|
|
260
260
|
a template) that were stored as api bundles become schema trees again:
|
|
261
261
|
|
|
262
262
|
```bash
|
|
@@ -321,7 +321,7 @@ gateway worlds session state <SESSION_ID> # every entity's row
|
|
|
321
321
|
gateway worlds session reset <SESSION_ID> # back to the snapshot (+ the task's seed); `session restart <SESSION_ID> [--version <pin>]` does it on what its pin (x@ref; unpinned = newest you may read) points to NOW, same id, URLs + token, running or closed; a grade then reads only the requests after its session.restart ledger entry
|
|
322
322
|
gateway worlds session grade <SESSION_ID> [--timeout S] # {reward, rewards, raw}; exploratory → {reward: null, reason: "no grader"}
|
|
323
323
|
gateway worlds session export <SESSION_ID> --out calls.jsonl [--requests] # the platform's ledger; --requests adds the session's entries from the world's request ledger (kind "request": via, status, sizes; bodies by result.requestId), live or closed
|
|
324
|
-
gateway worlds requests x [--session <SESSION_ID>] [--via api|ui|tool|webhook] [--status 4xx] [--since 2026-10-05] [--json] # every request the world received (every session, version and door), newest first, kept for its life; reading records nothing; `requests show x <REQUEST_ID> [--out f]` adds headers + bodies, `session requests <SESSION_ID>` lists one session's (exit 3: its engine records no requests, only World Host sessions do)
|
|
324
|
+
gateway worlds requests x [--session <SESSION_ID>] [--via api|ui|tool|webhook|page] [--status 4xx] [--since 2026-10-05] [--json] # every request the world received (every session, version and door), newest first, kept for its life; reading records nothing; `requests show x <REQUEST_ID> [--out f]` adds headers + bodies, `session requests <SESSION_ID>` lists one session's (exit 3: its engine records no requests, only World Host sessions do)
|
|
325
325
|
gateway worlds data ingest x calls.jsonl --transform shape.py # the calls back in as rows, shaped by your code or --map ingest.toml (world-data-ingestion §2c)
|
|
326
326
|
gateway worlds session close <SESSION_ID> # a closed session reopens by id, same URLs + token, from its last checkpoint: gateway worlds session reopen <SESSION_ID>
|
|
327
327
|
```
|
|
@@ -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
|
|
@@ -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).
|
|
@@ -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` |
|
|
@@ -1,102 +0,0 @@
|
|
|
1
|
-
declare const PLATFORM_TIMEOUT_ENV = "GATEWAY_TIMEOUT_MS";
|
|
2
|
-
/** How long one platform request may go unanswered before it is abandoned; `GATEWAY_TIMEOUT_MS` overrides it. */
|
|
3
|
-
declare const PLATFORM_TIMEOUT_DEFAULT_MS = 120000;
|
|
4
|
-
type PlatformEndpoint = {
|
|
5
|
-
host: string;
|
|
6
|
-
publicKey: string;
|
|
7
|
-
secretKey: string;
|
|
8
|
-
};
|
|
9
|
-
type PlatformMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
|
|
10
|
-
type PlatformReply = {
|
|
11
|
-
status: number;
|
|
12
|
-
ok: boolean;
|
|
13
|
-
text: string;
|
|
14
|
-
};
|
|
15
|
-
/** The request budget in force: `GATEWAY_TIMEOUT_MS` when set, else the default. */
|
|
16
|
-
declare function platformTimeoutMs(env?: NodeJS.ProcessEnv): number;
|
|
17
|
-
/** Why a request got no answer, from the socket-level error undici hides under `fetch failed`. */
|
|
18
|
-
declare class TransportCause {
|
|
19
|
-
readonly reason: string;
|
|
20
|
-
readonly detail: string | null;
|
|
21
|
-
readonly next: string;
|
|
22
|
-
private constructor();
|
|
23
|
-
static timeout(timeoutMs: number): TransportCause;
|
|
24
|
-
static of(error: unknown): TransportCause;
|
|
25
|
-
describe(): string;
|
|
26
|
-
}
|
|
27
|
-
/** A platform request that never got an answer: one line naming the request, the host, the cause and the next step. */
|
|
28
|
-
declare class UnreachableError extends Error {
|
|
29
|
-
readonly host: string;
|
|
30
|
-
readonly method: string;
|
|
31
|
-
readonly route: string;
|
|
32
|
-
readonly failure: TransportCause;
|
|
33
|
-
constructor(host: string, method: string, route: string, failure: TransportCause);
|
|
34
|
-
}
|
|
35
|
-
/**
|
|
36
|
-
* Another attempt after a gateway 5xx (502, 503, 504) or no answer at all, for a request whose repeat is harmless: a
|
|
37
|
-
* keyed filing step, which the platform answers with the first filing. Every other request gets one attempt (`NONE`).
|
|
38
|
-
*/
|
|
39
|
-
declare class RetryPolicy {
|
|
40
|
-
readonly delaysMs: readonly number[];
|
|
41
|
-
private readonly wait;
|
|
42
|
-
readonly budgetMs: number;
|
|
43
|
-
private readonly now;
|
|
44
|
-
static readonly NONE: RetryPolicy;
|
|
45
|
-
/** A platform restart or a short edge outage: no wait starts that would end past five minutes, so a step ends
|
|
46
|
-
* within the budget plus one request timeout. */
|
|
47
|
-
static readonly FILING: RetryPolicy;
|
|
48
|
-
static readonly TRANSIENT_STATUSES: ReadonlySet<number>;
|
|
49
|
-
constructor(delaysMs: readonly number[], wait?: (ms: number) => Promise<void>, budgetMs?: number, now?: () => number);
|
|
50
|
-
run(attempt: () => Promise<PlatformReply>): Promise<PlatformReply>;
|
|
51
|
-
}
|
|
52
|
-
/** The one door every CLI and SDK request to the platform goes through: Basic auth with the project key, a per-request timeout, and a transport failure turned into an `UnreachableError`. */
|
|
53
|
-
declare class PlatformTransport {
|
|
54
|
-
private readonly endpoint;
|
|
55
|
-
private readonly timeoutMs;
|
|
56
|
-
constructor(endpoint: PlatformEndpoint, timeoutMs?: number);
|
|
57
|
-
/** A request that legitimately takes longer (a sandbox exec, a world create) waits its own budget; every other one waits the default. */
|
|
58
|
-
budget(ownMs?: number): number;
|
|
59
|
-
send(method: PlatformMethod, route: string, body?: unknown, opts?: {
|
|
60
|
-
timeoutMs?: number;
|
|
61
|
-
retry?: RetryPolicy;
|
|
62
|
-
}): Promise<PlatformReply>;
|
|
63
|
-
private once;
|
|
64
|
-
}
|
|
65
|
-
|
|
66
|
-
declare const MAX_MEDIA_BYTES: number;
|
|
67
|
-
type MediaField = "input" | "output" | "metadata";
|
|
68
|
-
declare class MediaUploadError extends Error {
|
|
69
|
-
readonly status?: number | undefined;
|
|
70
|
-
constructor(message: string, status?: number | undefined);
|
|
71
|
-
}
|
|
72
|
-
declare class MediaReference {
|
|
73
|
-
readonly mediaId: string;
|
|
74
|
-
readonly contentType: string;
|
|
75
|
-
constructor(mediaId: string, contentType: string);
|
|
76
|
-
toString(): string;
|
|
77
|
-
}
|
|
78
|
-
type PutBytes = (url: string, data: Buffer, headers: Record<string, string>) => Promise<{
|
|
79
|
-
status: number;
|
|
80
|
-
error: string | null;
|
|
81
|
-
}>;
|
|
82
|
-
/** Uploads media for one project (the key pair's). */
|
|
83
|
-
declare class MediaUploader {
|
|
84
|
-
private readonly transport;
|
|
85
|
-
private readonly put;
|
|
86
|
-
maxBytes: number;
|
|
87
|
-
constructor(transport: PlatformTransport, put?: PutBytes, maxBytes?: number);
|
|
88
|
-
/** The uploader for `GATEWAY_HOST` / `GATEWAY_PUBLIC_KEY` /
|
|
89
|
-
* `GATEWAY_SECRET_KEY` only; null when any is unset, so a run traced with a saved login uploads none. */
|
|
90
|
-
static fromEnv(env?: NodeJS.ProcessEnv): MediaUploader | null;
|
|
91
|
-
/** Store `data` linked to the trace (and observation) and return its reference. */
|
|
92
|
-
upload(data: Buffer, link: {
|
|
93
|
-
contentType: string;
|
|
94
|
-
traceId: string;
|
|
95
|
-
observationId: string | null;
|
|
96
|
-
field: MediaField;
|
|
97
|
-
}): Promise<MediaReference>;
|
|
98
|
-
private store;
|
|
99
|
-
private send;
|
|
100
|
-
}
|
|
101
|
-
|
|
102
|
-
export { MAX_MEDIA_BYTES as M, PLATFORM_TIMEOUT_DEFAULT_MS as P, RetryPolicy as R, TransportCause as T, UnreachableError as U, PLATFORM_TIMEOUT_ENV as a, type PlatformEndpoint as b, type PlatformMethod as c, type PlatformReply as d, PlatformTransport as e, type MediaField as f, MediaReference as g, MediaUploadError as h, MediaUploader as i, platformTimeoutMs as p };
|
package/dist/media-BIApiPzS.d.ts
DELETED
|
@@ -1,102 +0,0 @@
|
|
|
1
|
-
declare const PLATFORM_TIMEOUT_ENV = "GATEWAY_TIMEOUT_MS";
|
|
2
|
-
/** How long one platform request may go unanswered before it is abandoned; `GATEWAY_TIMEOUT_MS` overrides it. */
|
|
3
|
-
declare const PLATFORM_TIMEOUT_DEFAULT_MS = 120000;
|
|
4
|
-
type PlatformEndpoint = {
|
|
5
|
-
host: string;
|
|
6
|
-
publicKey: string;
|
|
7
|
-
secretKey: string;
|
|
8
|
-
};
|
|
9
|
-
type PlatformMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
|
|
10
|
-
type PlatformReply = {
|
|
11
|
-
status: number;
|
|
12
|
-
ok: boolean;
|
|
13
|
-
text: string;
|
|
14
|
-
};
|
|
15
|
-
/** The request budget in force: `GATEWAY_TIMEOUT_MS` when set, else the default. */
|
|
16
|
-
declare function platformTimeoutMs(env?: NodeJS.ProcessEnv): number;
|
|
17
|
-
/** Why a request got no answer, from the socket-level error undici hides under `fetch failed`. */
|
|
18
|
-
declare class TransportCause {
|
|
19
|
-
readonly reason: string;
|
|
20
|
-
readonly detail: string | null;
|
|
21
|
-
readonly next: string;
|
|
22
|
-
private constructor();
|
|
23
|
-
static timeout(timeoutMs: number): TransportCause;
|
|
24
|
-
static of(error: unknown): TransportCause;
|
|
25
|
-
describe(): string;
|
|
26
|
-
}
|
|
27
|
-
/** A platform request that never got an answer: one line naming the request, the host, the cause and the next step. */
|
|
28
|
-
declare class UnreachableError extends Error {
|
|
29
|
-
readonly host: string;
|
|
30
|
-
readonly method: string;
|
|
31
|
-
readonly route: string;
|
|
32
|
-
readonly failure: TransportCause;
|
|
33
|
-
constructor(host: string, method: string, route: string, failure: TransportCause);
|
|
34
|
-
}
|
|
35
|
-
/**
|
|
36
|
-
* Another attempt after a gateway 5xx (502, 503, 504) or no answer at all, for a request whose repeat is harmless: a
|
|
37
|
-
* keyed filing step, which the platform answers with the first filing. Every other request gets one attempt (`NONE`).
|
|
38
|
-
*/
|
|
39
|
-
declare class RetryPolicy {
|
|
40
|
-
readonly delaysMs: readonly number[];
|
|
41
|
-
private readonly wait;
|
|
42
|
-
readonly budgetMs: number;
|
|
43
|
-
private readonly now;
|
|
44
|
-
static readonly NONE: RetryPolicy;
|
|
45
|
-
/** A platform restart or a short edge outage: no wait starts that would end past five minutes, so a step ends
|
|
46
|
-
* within the budget plus one request timeout. */
|
|
47
|
-
static readonly FILING: RetryPolicy;
|
|
48
|
-
static readonly TRANSIENT_STATUSES: ReadonlySet<number>;
|
|
49
|
-
constructor(delaysMs: readonly number[], wait?: (ms: number) => Promise<void>, budgetMs?: number, now?: () => number);
|
|
50
|
-
run(attempt: () => Promise<PlatformReply>): Promise<PlatformReply>;
|
|
51
|
-
}
|
|
52
|
-
/** The one door every CLI and SDK request to the platform goes through: Basic auth with the project key, a per-request timeout, and a transport failure turned into an `UnreachableError`. */
|
|
53
|
-
declare class PlatformTransport {
|
|
54
|
-
private readonly endpoint;
|
|
55
|
-
private readonly timeoutMs;
|
|
56
|
-
constructor(endpoint: PlatformEndpoint, timeoutMs?: number);
|
|
57
|
-
/** A request that legitimately takes longer (a sandbox exec, a world create) waits its own budget; every other one waits the default. */
|
|
58
|
-
budget(ownMs?: number): number;
|
|
59
|
-
send(method: PlatformMethod, route: string, body?: unknown, opts?: {
|
|
60
|
-
timeoutMs?: number;
|
|
61
|
-
retry?: RetryPolicy;
|
|
62
|
-
}): Promise<PlatformReply>;
|
|
63
|
-
private once;
|
|
64
|
-
}
|
|
65
|
-
|
|
66
|
-
declare const MAX_MEDIA_BYTES: number;
|
|
67
|
-
type MediaField = "input" | "output" | "metadata";
|
|
68
|
-
declare class MediaUploadError extends Error {
|
|
69
|
-
readonly status?: number | undefined;
|
|
70
|
-
constructor(message: string, status?: number | undefined);
|
|
71
|
-
}
|
|
72
|
-
declare class MediaReference {
|
|
73
|
-
readonly mediaId: string;
|
|
74
|
-
readonly contentType: string;
|
|
75
|
-
constructor(mediaId: string, contentType: string);
|
|
76
|
-
toString(): string;
|
|
77
|
-
}
|
|
78
|
-
type PutBytes = (url: string, data: Buffer, headers: Record<string, string>) => Promise<{
|
|
79
|
-
status: number;
|
|
80
|
-
error: string | null;
|
|
81
|
-
}>;
|
|
82
|
-
/** Uploads media for one project (the key pair's). */
|
|
83
|
-
declare class MediaUploader {
|
|
84
|
-
private readonly transport;
|
|
85
|
-
private readonly put;
|
|
86
|
-
maxBytes: number;
|
|
87
|
-
constructor(transport: PlatformTransport, put?: PutBytes, maxBytes?: number);
|
|
88
|
-
/** The uploader for `GATEWAY_HOST` / `GATEWAY_PUBLIC_KEY` /
|
|
89
|
-
* `GATEWAY_SECRET_KEY` only; null when any is unset, so a run traced with a saved login uploads none. */
|
|
90
|
-
static fromEnv(env?: NodeJS.ProcessEnv): MediaUploader | null;
|
|
91
|
-
/** Store `data` linked to the trace (and observation) and return its reference. */
|
|
92
|
-
upload(data: Buffer, link: {
|
|
93
|
-
contentType: string;
|
|
94
|
-
traceId: string;
|
|
95
|
-
observationId: string | null;
|
|
96
|
-
field: MediaField;
|
|
97
|
-
}): Promise<MediaReference>;
|
|
98
|
-
private store;
|
|
99
|
-
private send;
|
|
100
|
-
}
|
|
101
|
-
|
|
102
|
-
export { MAX_MEDIA_BYTES as M, PLATFORM_TIMEOUT_DEFAULT_MS as P, RetryPolicy as R, TransportCause as T, UnreachableError as U, PLATFORM_TIMEOUT_ENV as a, type PlatformEndpoint as b, type PlatformMethod as c, type PlatformReply as d, PlatformTransport as e, type MediaField as f, MediaReference as g, MediaUploadError as h, MediaUploader as i, platformTimeoutMs as p };
|