@withgateway/sdk 0.3.0 → 0.3.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/README.md +6 -1
- package/dist/cli.js +3971 -2338
- package/dist/cli.js.map +1 -1
- package/dist/cli.mjs +3950 -2318
- package/dist/cli.mjs.map +1 -1
- package/dist/files/index.d.mts +1 -1
- package/dist/files/index.d.ts +1 -1
- package/dist/files/index.js +214 -41
- package/dist/files/index.js.map +1 -1
- package/dist/files/index.mjs +206 -35
- package/dist/files/index.mjs.map +1 -1
- package/dist/{index-DAb-FCMg.d.ts → index-DUHmS74p.d.ts} +3 -13
- package/dist/{index-D6oi1TWE.d.mts → index-mJhG3vZU.d.mts} +3 -13
- package/dist/index.d.mts +4 -4
- package/dist/index.d.ts +4 -4
- package/dist/index.js +1456 -564
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +1433 -557
- package/dist/index.mjs.map +1 -1
- package/dist/{media-CbcAfQvd.d.mts → media-BIApiPzS.d.mts} +21 -2
- package/dist/{media-CbcAfQvd.d.ts → media-BIApiPzS.d.ts} +21 -2
- package/dist/traces/index.d.mts +1 -1
- package/dist/traces/index.d.ts +1 -1
- package/dist/traces/index.js +211 -38
- package/dist/traces/index.js.map +1 -1
- package/dist/traces/index.mjs +203 -32
- package/dist/traces/index.mjs.map +1 -1
- package/dist/tracing/index.d.mts +2 -2
- package/dist/tracing/index.d.ts +2 -2
- package/dist/tracing/index.js +96 -21
- package/dist/tracing/index.js.map +1 -1
- package/dist/tracing/index.mjs +96 -21
- package/dist/tracing/index.mjs.map +1 -1
- package/dist/worlds/index.d.mts +300 -123
- package/dist/worlds/index.d.ts +300 -123
- package/dist/worlds/index.js +1385 -508
- package/dist/worlds/index.js.map +1 -1
- package/dist/worlds/index.mjs +1377 -501
- package/dist/worlds/index.mjs.map +1 -1
- package/package.json +1 -1
- package/runtime/gatewaysdk/environment/_bundle.py +2 -27
- package/runtime/gatewaysdk/environment/_materialize.py +49 -69
- package/runtime/gatewaysdk/environment/_world.py +122 -197
- package/runtime/gatewaysdk/environment/backing.py +137 -0
- package/runtime/gatewaysdk/environment/core.py +1 -1
- package/runtime/gatewaysdk/environment/legacy_sqlite.py +301 -0
- package/runtime/gatewaysdk/environment/reward_keys.py +25 -0
- package/runtime/gatewaysdk/environment/runtime.py +8 -13
- package/runtime/gatewaysdk/environment/schema/__init__.py +4 -4
- package/runtime/gatewaysdk/environment/schema/admin_routes.py +86 -0
- package/runtime/gatewaysdk/environment/schema/api.py +266 -515
- package/runtime/gatewaysdk/environment/schema/batch.py +42 -37
- package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +17 -5
- package/runtime/gatewaysdk/environment/schema/call_log.py +291 -0
- package/runtime/gatewaysdk/environment/schema/call_redaction.py +344 -0
- package/runtime/gatewaysdk/environment/schema/cast.py +31 -4
- package/runtime/gatewaysdk/environment/schema/compiler.py +334 -158
- package/runtime/gatewaysdk/environment/schema/conform.py +8 -12
- package/runtime/gatewaysdk/environment/schema/connector.py +27 -62
- package/runtime/gatewaysdk/environment/schema/data.py +50 -207
- package/runtime/gatewaysdk/environment/schema/database/__init__.py +24 -0
- package/runtime/gatewaysdk/environment/schema/database/audit.py +121 -0
- package/runtime/gatewaysdk/environment/schema/database/base.py +995 -0
- package/runtime/gatewaysdk/environment/schema/database/budget.py +33 -0
- package/runtime/gatewaysdk/environment/schema/database/connections.py +101 -0
- package/runtime/gatewaysdk/environment/schema/database/engines.py +8 -0
- package/runtime/gatewaysdk/environment/schema/database/guard.py +208 -0
- package/runtime/gatewaysdk/environment/schema/database/ingest.py +154 -0
- package/runtime/gatewaysdk/environment/schema/database/matching.py +58 -0
- package/runtime/gatewaysdk/environment/schema/database/provenance.py +30 -0
- package/runtime/gatewaysdk/environment/schema/database/rows.py +53 -0
- package/runtime/gatewaysdk/environment/schema/database/runtime_rows.py +39 -0
- package/runtime/gatewaysdk/environment/schema/database/sqlite.py +367 -0
- package/runtime/gatewaysdk/environment/schema/domain_migration.py +236 -0
- package/runtime/gatewaysdk/environment/schema/envelope.py +169 -0
- package/runtime/gatewaysdk/environment/schema/extract.py +6 -13
- package/runtime/gatewaysdk/environment/schema/grading.py +45 -30
- package/runtime/gatewaysdk/environment/schema/handler_errors.py +142 -12
- package/runtime/gatewaysdk/environment/schema/host.py +158 -250
- package/runtime/gatewaysdk/environment/schema/lanes.py +53 -0
- package/runtime/gatewaysdk/environment/schema/local.py +44 -71
- package/runtime/gatewaysdk/environment/schema/mapping.py +5 -25
- package/runtime/gatewaysdk/environment/schema/openapi_import.py +112 -73
- package/runtime/gatewaysdk/environment/schema/openapi_paging.py +147 -0
- package/runtime/gatewaysdk/environment/schema/openapi_payloads.py +288 -0
- package/runtime/gatewaysdk/environment/schema/openapi_routes.py +97 -102
- package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +113 -30
- package/runtime/gatewaysdk/environment/schema/platform.py +124 -178
- package/runtime/gatewaysdk/environment/schema/platform_import.py +2 -3
- package/runtime/gatewaysdk/environment/schema/platform_query.py +61 -5
- package/runtime/gatewaysdk/environment/schema/primary_key.py +61 -0
- package/runtime/gatewaysdk/environment/schema/proof.py +19 -12
- package/runtime/gatewaysdk/environment/schema/runtime.py +77 -160
- package/runtime/gatewaysdk/environment/schema/served_names.py +58 -0
- package/runtime/gatewaysdk/environment/schema/session_files.py +166 -0
- package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +2 -2
- package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +22 -14
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +29 -3
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +16 -16
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +18 -18
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +3 -2
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +15 -0
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/openapi-import.md +50 -21
- package/runtime/gatewaysdk/environment/schema/slack.py +4 -8
- package/runtime/gatewaysdk/environment/schema/snapshot.py +385 -129
- package/runtime/gatewaysdk/environment/schema/store_contract.py +8 -14
- package/runtime/gatewaysdk/environment/schema/tasks.py +140 -55
- package/runtime/gatewaysdk/environment/schema/tools_world.py +110 -87
- package/runtime/gatewaysdk/environment/schema/ui.py +24 -5
- package/runtime/gatewaysdk/environment/schema/ui_static/app.js +100 -130
- package/runtime/gatewaysdk/environment/schema/ui_static/index.html +1 -8
- package/runtime/gatewaysdk/environment/schema/validation.py +166 -40
- package/runtime/gatewaysdk/environment/schema/workers.py +142 -57
- package/runtime/gatewaysdk/environment/schema/world_sql.py +81 -0
- package/runtime/gatewaysdk/environment/schema/world_tests.py +71 -39
- package/runtime/gatewaysdk/environment/score.py +57 -0
- package/runtime/gatewaysdk/environment/secret_values.py +36 -0
- package/runtime/gatewaysdk/environment/world.py +42 -3
- package/runtime/gatewaysdk/environment/world_session_contract.py +32 -5
- package/skills/benchmarks-getting-started/SKILL.md +2 -2
- package/skills/connector-schema-authoring/SKILL.md +22 -14
- package/skills/connector-schema-authoring/connector-worlds.md +26 -10
- package/skills/connector-schema-authoring/world-schema.md +111 -51
- package/skills/world-data-ingestion/ROWS.md +29 -3
- package/skills/world-data-ingestion/SKILL.md +16 -16
- package/skills/worlds-getting-started/SKILL.md +18 -18
- package/skills/worlds-getting-started/references/cli-mcp-map.md +3 -2
- package/skills/worlds-getting-started/references/gotchas.md +15 -0
- package/skills/worlds-getting-started/references/openapi-import.md +50 -21
- package/runtime/gatewaysdk/environment/schema/store.py +0 -1013
|
@@ -0,0 +1,166 @@
|
|
|
1
|
+
"""The files a session's store opens without auditing every row again.
|
|
2
|
+
|
|
3
|
+
A version's :class:`ProvenTemplate` is the file every session of the version
|
|
4
|
+
starts from. Its rows are proven once, when the host caches the version; an
|
|
5
|
+
open or a reset clones it and the store runs only its contract and DDL check.
|
|
6
|
+
A :class:`SessionExport` is a checkpoint a session continues from: its bytes
|
|
7
|
+
must hash to the sha256 the platform recorded when the host exported it, and
|
|
8
|
+
it carries the session's call log beside the rows.
|
|
9
|
+
"""
|
|
10
|
+
|
|
11
|
+
from __future__ import annotations
|
|
12
|
+
|
|
13
|
+
import json
|
|
14
|
+
import os
|
|
15
|
+
import uuid
|
|
16
|
+
from pathlib import Path
|
|
17
|
+
from typing import NamedTuple
|
|
18
|
+
|
|
19
|
+
from .._materialize import materialize_template
|
|
20
|
+
from .compiler import Contract
|
|
21
|
+
from .database import WorldDatabase
|
|
22
|
+
from .snapshot import contract_hash, file_sha256, runtime_version
|
|
23
|
+
from .validation import fail
|
|
24
|
+
|
|
25
|
+
_PROVEN = object()
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
def refuse_digest_mismatch(path: Path, sha256: str) -> None:
|
|
29
|
+
"""Refuse a session export whose bytes do not hash to the sha256 recorded for them."""
|
|
30
|
+
actual = file_sha256(path)
|
|
31
|
+
if actual != sha256.lower():
|
|
32
|
+
fail("host", f"session export checksum mismatch: expected {sha256}, got {actual}")
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
class ProvenTemplate:
|
|
36
|
+
"""The file every session of a version starts from, its rows proven once.
|
|
37
|
+
|
|
38
|
+
When the host caches a version the template is built through the store (every
|
|
39
|
+
row audited as it was written), copied from the snapshot the host fetched and
|
|
40
|
+
verified against the sha256 the platform recorded, or copied from the tree's own
|
|
41
|
+
``db/state.sqlite`` and audited in full there and then: a sidecar the tree wrote
|
|
42
|
+
is its author's claim, not a proof. The proof beside the file names its sha256,
|
|
43
|
+
the contract and the runtime, so a later build (a restart, the version's worker)
|
|
44
|
+
trusts the same bytes without a second audit, and builds any other bytes afresh.
|
|
45
|
+
What it names is fixed once :meth:`prove` returns."""
|
|
46
|
+
|
|
47
|
+
__slots__ = ("_path", "_contract")
|
|
48
|
+
|
|
49
|
+
def __init__(self, path: Path, contract: Contract, proof: object) -> None:
|
|
50
|
+
if proof is not _PROVEN:
|
|
51
|
+
raise TypeError("a ProvenTemplate comes from ProvenTemplate.prove")
|
|
52
|
+
self._path = Path(path)
|
|
53
|
+
self._contract = contract
|
|
54
|
+
|
|
55
|
+
@property
|
|
56
|
+
def path(self) -> Path:
|
|
57
|
+
return self._path
|
|
58
|
+
|
|
59
|
+
@property
|
|
60
|
+
def contract(self) -> Contract:
|
|
61
|
+
return self._contract
|
|
62
|
+
|
|
63
|
+
@staticmethod
|
|
64
|
+
def required(template: object) -> ProvenTemplate:
|
|
65
|
+
"""``template`` itself, refused unless :meth:`prove` made it."""
|
|
66
|
+
if not isinstance(template, ProvenTemplate):
|
|
67
|
+
raise TypeError("a world opens unaudited only on a ProvenTemplate (ProvenTemplate.prove)")
|
|
68
|
+
return template
|
|
69
|
+
|
|
70
|
+
@classmethod
|
|
71
|
+
def prove(cls, bundle: Path, path: Path, contract: Contract, *, fetched: bool) -> ProvenTemplate:
|
|
72
|
+
"""The version's template at ``path``. ``fetched`` says the tree's snapshot is
|
|
73
|
+
the platform's, downloaded and verified against its recorded sha256 just now."""
|
|
74
|
+
template = cls(path, contract, _PROVEN)
|
|
75
|
+
if not template._recorded():
|
|
76
|
+
template._build(bundle, fetched=fetched)
|
|
77
|
+
return template
|
|
78
|
+
|
|
79
|
+
@property
|
|
80
|
+
def proof_path(self) -> Path:
|
|
81
|
+
return self.path.with_name(f"{self.path.name}.proof.json")
|
|
82
|
+
|
|
83
|
+
def _proof(self) -> dict[str, str]:
|
|
84
|
+
return {
|
|
85
|
+
"sha256": file_sha256(self.path),
|
|
86
|
+
"contractHash": contract_hash(self.contract),
|
|
87
|
+
"runtime": runtime_version(),
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
def _recorded(self) -> bool:
|
|
91
|
+
try:
|
|
92
|
+
recorded = json.loads(self.proof_path.read_text(encoding="utf-8"))
|
|
93
|
+
except (OSError, ValueError):
|
|
94
|
+
return False
|
|
95
|
+
return self.path.is_file() and recorded == self._proof()
|
|
96
|
+
|
|
97
|
+
def _build(self, bundle: Path, *, fetched: bool) -> None:
|
|
98
|
+
staging = self.path.with_name(f".{self.path.name}.{uuid.uuid4().hex}")
|
|
99
|
+
try:
|
|
100
|
+
copied = materialize_template(bundle, staging, require_sql=True) is not None
|
|
101
|
+
if copied and not fetched:
|
|
102
|
+
WorldDatabase.open(staging, self.contract).close()
|
|
103
|
+
os.replace(staging, self.path)
|
|
104
|
+
finally:
|
|
105
|
+
staging.unlink(missing_ok=True)
|
|
106
|
+
record = self.proof_path.with_name(f".{self.proof_path.name}.{uuid.uuid4().hex}")
|
|
107
|
+
record.write_text(json.dumps(self._proof(), sort_keys=True) + "\n", encoding="utf-8")
|
|
108
|
+
os.replace(record, self.proof_path)
|
|
109
|
+
|
|
110
|
+
|
|
111
|
+
class ExportFile(NamedTuple):
|
|
112
|
+
"""A session export on this host's disk and the sha256 the platform recorded for it."""
|
|
113
|
+
|
|
114
|
+
path: Path
|
|
115
|
+
sha256: str
|
|
116
|
+
|
|
117
|
+
def for_worker(self) -> dict[str, str]:
|
|
118
|
+
return {"path": str(self.path), "sha256": self.sha256}
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
_VERIFIED = object()
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
class SessionExport:
|
|
125
|
+
"""A checkpoint the host continues a session from, verified where it is opened.
|
|
126
|
+
|
|
127
|
+
The bytes hash to the sha256 the platform recorded when the host exported them,
|
|
128
|
+
so they are the store's own copy, every row audited as it committed, and the
|
|
129
|
+
session opens on them without a second row audit. :meth:`verified` is the only
|
|
130
|
+
way to get one. The call log rides in the file as ``_gateway_calls``, a table the
|
|
131
|
+
store never opens: :meth:`carry_calls` writes it into a fresh export, and
|
|
132
|
+
:meth:`verified` reads it back and drops it before the store sees the file. What
|
|
133
|
+
it names is fixed once :meth:`verified` returns."""
|
|
134
|
+
|
|
135
|
+
__slots__ = ("_path", "_calls")
|
|
136
|
+
|
|
137
|
+
def __init__(self, path: Path, calls: list[dict], proof: object) -> None:
|
|
138
|
+
if proof is not _VERIFIED:
|
|
139
|
+
raise TypeError("a SessionExport comes from SessionExport.verified")
|
|
140
|
+
self._path = Path(path)
|
|
141
|
+
self._calls = tuple(calls)
|
|
142
|
+
|
|
143
|
+
@property
|
|
144
|
+
def path(self) -> Path:
|
|
145
|
+
return self._path
|
|
146
|
+
|
|
147
|
+
@property
|
|
148
|
+
def calls(self) -> list[dict]:
|
|
149
|
+
return list(self._calls)
|
|
150
|
+
|
|
151
|
+
@staticmethod
|
|
152
|
+
def required(export: object) -> SessionExport:
|
|
153
|
+
"""``export`` itself, refused unless :meth:`verified` made it."""
|
|
154
|
+
if not isinstance(export, SessionExport):
|
|
155
|
+
raise TypeError("a session resumes only from a SessionExport (SessionExport.verified)")
|
|
156
|
+
return export
|
|
157
|
+
|
|
158
|
+
@classmethod
|
|
159
|
+
def verified(cls, export: ExportFile, engine: type[WorldDatabase]) -> SessionExport:
|
|
160
|
+
refuse_digest_mismatch(export.path, export.sha256)
|
|
161
|
+
calls = [json.loads(entry) for entry in engine.take_entries(export.path)]
|
|
162
|
+
return cls(export.path, calls, _VERIFIED)
|
|
163
|
+
|
|
164
|
+
@staticmethod
|
|
165
|
+
def carry_calls(path: Path, calls: list[dict], engine: type[WorldDatabase]) -> None:
|
|
166
|
+
engine.carry_entries(path, [json.dumps(call, sort_keys=True) for call in calls])
|
|
@@ -407,8 +407,8 @@ reward: 0 {"ticket_closed":0}
|
|
|
407
407
|
reward is for the untouched world; an agent's rollout is what `benchmarks run` grades. Drive one by hand: …
|
|
408
408
|
```
|
|
409
409
|
|
|
410
|
-
A verifier that cannot run — bad SQL, a missing entity — prints `FAIL verifier 'x': …` with
|
|
411
|
-
words and exits 1; that is what the dry run is for. A reward of 1.0 here means the verifier passes
|
|
410
|
+
A verifier that cannot run — bad SQL, a missing entity — prints `FAIL verifier 'x': …` with the database
|
|
411
|
+
engine's words and exits 1; that is what the dry run is for. A reward of 1.0 here means the verifier passes
|
|
412
412
|
before any agent acts: rewrite it. Without the bundled runtime (no python3 >= 3.12) the four steps
|
|
413
413
|
print and the run is marked not executed, exit 0.
|
|
414
414
|
|
|
@@ -41,7 +41,7 @@ registration, a platform builder, live ingestion, tools, or a registry framework
|
|
|
41
41
|
## The rules that never bend
|
|
42
42
|
|
|
43
43
|
- **The schema is the deliverable.** A world with a faithful model and no tools is complete. Tools are added when wanted, by whoever wants them.
|
|
44
|
-
- **Every write goes through the schema.** Handlers use `gateway_env.store`; ingestion uses `store.apply_batch` or `store.ingest`; nothing else writes. Out-of-contract writes are rejected with the reason.
|
|
44
|
+
- **Every write goes through the schema.** Handlers use `gateway_env.store`; ingestion uses `store.apply_batch` or `store.ingest`; nothing else writes. Out-of-contract writes are rejected with the reason (one known gap: never name an ingest session's `TEMP` staging table after a world table; see `world-schema.md`, Raw ingestion).
|
|
45
45
|
- **Check the right boundary.** Compile/check validate compiled artifacts; materialization and store operations validate persisted data. Publication checks actual bundle bytes, handler declarations and initial state through the trusted runtime. Fidelity evidence and Environment Actions remain advisory.
|
|
46
46
|
- **Fidelity shape is decided by the vendor, not by a house rule.** A **base** connector is prebaked once (Slack). A **tenant-shaped** connector's model is mostly customer-defined, so describe at bind time is required (Salesforce, NetSuite, Workday). A **mixed** connector is a base plus an optional overlay (Okta, Entra, Google, LDAP, Jamf).
|
|
47
47
|
- **Surface parity is advisory.** If the world declares it mirrors an MCP surface, produce the parity report and show it. Never block on it, never shrink or bend the model to satisfy it.
|
|
@@ -55,7 +55,7 @@ registration, a platform builder, live ingestion, tools, or a registry framework
|
|
|
55
55
|
| Command or path | Status |
|
|
56
56
|
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
57
57
|
| `gateway worlds schema init PATH --connector <slug> [--name NAME] [--with-example-tool]` | exists (#219); `--connector custom` is the blank starting point for an arbitrary connector: its `$id` is derived from `--name` (`urn:gateway:connector:<name>`), it ships the `records` entity and a starter verifier but no tools unless `--with-example-tool` asks for the `list_records`/`get_record`/`create_record` example, and it writes no `data/records.json` (Brex retrospective, 2026-09-14) |
|
|
58
|
-
| `gateway worlds schema init PATH --from-openapi SOURCE [--plan-only] [--include GLOB\|TAG]… [--exclude GLOB\|TAG]…` | exists (2026-09-22); imports a Swagger 2.0 / OpenAPI 3.x document (JSON or YAML; a local path, `drive:<path>` read platform-side, or an http(s) URL) into `schema/world.json` + `connector.toml` + `schema/provenance.json`:
|
|
58
|
+
| `gateway worlds schema init PATH --from-openapi SOURCE [--plan-only] [--include GLOB\|TAG]… [--exclude GLOB\|TAG]…` | exists (2026-09-22); imports a Swagger 2.0 / OpenAPI 3.x document (JSON or YAML; a local path, `drive:<path>` read platform-side, or an http(s) URL) into `schema/world.json` + `connector.toml` + `schema/provenance.json`: the item schemas the selected operations' responses carry, read through the vendor's envelope, become entities (never the wrappers; keyed by a declared id, else the field the read route looks a row up by, nested as a JSON Pointer when it sits inside the row), every path+method a route that answers in the vendor's envelope (`envelope = "message.items"` + `wrapper`) and pages as the document says (passthrough when the response is not an entity), the plan is printed first and `--plan-only` writes nothing; a YAML document needs PyYAML in the Python that runs the runtime and is refused naming the fix without it; refusals (no `paths`, unknown `$ref`, cyclic entity root, undeclared path parameter) carry a JSON pointer. Rules: `worlds-getting-started` → `references/openapi-import.md` |
|
|
59
59
|
| `gateway worlds connector validate\|capture\|ingest PATH` | exists; a `connector.toml` in the world describes base URL, auth scheme, pacing, redaction and operations; `capture` records paced, redacted pages (errors included) under `captures/` with the secret never written; `ingest` seeds `data/initial.json` through the contract in a scratch copy first; `ingest --dry-run [--report refusals.jsonl]` lists every violation of every capture (the `data import --report` records plus `capture`), exit 2, nothing written |
|
|
60
60
|
| `gateway worlds schema reconcile PATH --from captures [--write]` | exists (runtime, offline CLI and `gateway worlds schema reconcile`); the contract against the captured rows: relaxes `required` for fields absent in captures, adds undocumented keys as optional properties typed from the values, drops formats the captured values fail; a report of every change, `schema/world.json` rewritten and recompiled only with `--write` |
|
|
61
61
|
| `gateway worlds connector conform PATH --openapi vendor.yaml` | exists; serves the world in-process, calls every declared operation with arguments from its own seed, and checks status + body against the vendor's OpenAPI response schemas; non-zero exit on any mismatch. Run it before calling a world 1:1; its FAIL list is the work list (unseeded entities → 404s, creates the contract rejects → 4xx, honest 501s). Reads OpenAPI 3.0 `nullable`, reference cycles and `discriminator` unions; `[operations.api] sample_headers` / `sample_body` shape a request the route demands (`Idempotency-Key`, a body) |
|
|
@@ -64,7 +64,8 @@ registration, a platform builder, live ingestion, tools, or a registry framework
|
|
|
64
64
|
| `gateway worlds schema compile \| check \| describe PATH` | exists (#216); `compile` also writes `ui/static` (index.html, app.js, contract.json) when connector.toml declares `[ui]` (every shipped template does): the page over the routes an agent drives with `--surface ui,browser`; `[ui] generated = false` keeps a hand-written page |
|
|
65
65
|
| `gateway worlds schema ui init PATH` | exists (TS CLI + `python -m … ui-init`); declares `[ui]` in connector.toml when missing (before the first `[[operations]]`) and compiles, which generates the page; refuses a world with no connector.toml (a page shows routes). `worlds serve` serves it on its own port at `/` (and at `/__ui/`) and answers its `api_path` for the pin; `generated = false` + any frontend built to static files into `ui/static` is served the same way |
|
|
66
66
|
| `gateway worlds schema entity add PATH NAME --ref D \| --fields "a:string,b:integer?" \| --schema JSON --key F [--unique F,F] [--relationship F->entity]` | exists (TS CLI, local); declares one entity in `schema/world.json` without hand-editing the document: keeps `$defs`, package metadata and other entities byte-for-byte in meaning, refuses duplicate names, non-required or non-string/integer keys, unknown `$defs` and undeclared relationship targets, and writes nothing on refusal |
|
|
67
|
-
| `gateway worlds
|
|
67
|
+
| `gateway worlds schema entity remove PATH NAME` | exists (TS CLI, local); takes one entity out of `schema/world.json` with the `$defs` only it used; refused (exit 2, nothing written) while a `connector.toml` operation, a `verifiers/*.sql`, rows in `data/initial.json`, a `[dependencies.<alias>.entities]` map or another entity's relationship uses it, each named; keeps at least one entity and re-points the untouched `state_present.sql` placeholder |
|
|
68
|
+
| `gateway worlds connector route add PATH NAME --path /v1/x/{id} [-X POST] [--param q] [--entity E] [--results r] [--action create] [--filter id=id] [--body f=p] [--handler fn]` | exists (TS CLI, local); appends one `[[operations]]` (+ `[operations.api]`) to `connector.toml` leaving existing bytes untouched; validates name, method, path, entity against `schema/world.json`, filter keys against `{args}`/params, and the handler/action pairing; a new `connector.toml` starts with `[auth] scheme = "bearer"` (the hosted session token) and `--action handler --handler fn` writes a 501 stub into `api/handlers.py` unless `fn` is defined |
|
|
68
69
|
| `gateway worlds connector publish DIR [--slug S] [-m MSG] [--tag T] [--workspace-visible] [--project-scope]` | exists; saves a template directory, or the world it was authored in, as a workspace connector (Context Hub `connector` repo, org-owned, versioned); the platform compiles the template before accepting it and answers 400 with the reason; a re-publish is a new commit and paths no longer present are removed; `data/`, `captures/`, `db/` and generated files stay behind |
|
|
69
70
|
| `gateway worlds connector list [--hub] [--query Q]` / `pull SLUG [--out DIR] [--version V]` / `clone SLUG-OR-ID [--name N] [--slug S]` | exists; `list` shows this org's connectors (vendor, auth, entities, operations), `--hub` adds every connector another org published; `pull` writes the template files; `clone` copies a published connector into this org with provenance — a live reference is never made, so the publisher's later edits need a re-clone |
|
|
70
71
|
| `gateway worlds schema init PATH --connector workspace:<slug>` | exists; initializes from the platform's copy through `init_bundle_from_files` (needs `GATEWAY_*` keys); the offline `python -m gatewaysdk.environment.schema init` refuses `workspace:` and names this command |
|
|
@@ -103,9 +104,9 @@ deliverable can finish with synthetic fixtures and explicitly skipped live valid
|
|
|
103
104
|
- [ ] Author `schema/world.json` and reusable sibling definitions from pinned vendor sources, following the type-mapping notes in [CONNECTORS.md](CONNECTORS.md). `gateway worlds schema entity add` declares an entity with its key, uniques and relationships in one command so the declaration shape is never wrong; hand-author only the payload definitions (`--schema` or `$defs`). Record source URLs, versions/retrieval dates, and hashes of the actual retrieved bytes in `schema/provenance.json`.
|
|
104
105
|
- [ ] Entities have the vendor's keys, relationships, enums, and nullability, and follow [CONVENTIONS.md](CONVENTIONS.md): one reserved prefix per template, plural snake_case names, vendor casing on fields, shared `base.json` primitives. Reserved prefixes and the `payload` name are avoided.
|
|
105
106
|
- [ ] Enforce supported required fields, types, enums, key uniqueness, and reference integrity. Document vendor rules the dialect cannot express, normalization choices, and constraints the future mapper must enforce; structural validation is not vendor behavior.
|
|
106
|
-
- [ ] Real vendor documents compile as they come (Brex retrospective, 2026-09-14): `format: int64`/`double` on numbers is ignored, not refused (string formats are still validated); a schema-valued `additionalProperties` types a map (`Record<string, string>`); a type nested in itself (`ExpandableExpense` holding an `ExpandableExpense`) compiles, with the nested occurrence validated as its bare type and stored as JSON, never projected to a column. A nested key or relationship field is a JSON Pointer, `/owner/user_id`, never `owner.user_id`; the compiler's refusal says so.
|
|
107
|
-
- [ ] Every property verifier SQL will name has a column: scalars and compositions whose non-null branches are scalar (`anyOf [{$ref Status}, {type: null}]`, the nullable-enum shape) project; a composition that may hold an object or array stays JSON-only. A verifier that names a column the contract never projected fails the grade with
|
|
108
|
-
- [ ] `gateway worlds schema compile PATH` then `check PATH` pass. Never edit generated files; SDK templates contain authored inputs and generate bundle artifacts at `init` time. Changing the root `$id` after `init` is fine: `compile` re-stamps an empty `data/initial.json` onto the new domain; a journal that holds rows is refused with the fix named (re-import its rows, or restore the schema it was written against).
|
|
107
|
+
- [ ] Real vendor documents compile as they come (Brex retrospective, 2026-09-14): `format: int64`/`double` on numbers is ignored, not refused (string formats are still validated); a schema-valued `additionalProperties` types a map (`Record<string, string>`); a type nested in itself (`ExpandableExpense` holding an `ExpandableExpense`) compiles, with the nested occurrence validated as its bare type and stored as JSON, never projected to a column. A contract whose inlined files would pass the 4 MB publication cap (Google Docs' recursive body) compiles each object/array definition once under `$defs` and references it instead; nothing to do in the template. A nested key or relationship field is a JSON Pointer, `/owner/user_id`, never `owner.user_id`; the compiler's refusal says so. A primary key may be nested too (`/protocolSection/identificationModule/nctId`) when every object on its path is required and non-null; lookups (`get`, `update`, `delete`) then pass it flat under the pointer itself. Field names keep the vendor's hyphens (`reference-count`); dots and slashes never belong to a name. A verifier's SQL double-quotes such a column (`"reference-count"`): unquoted, SQLite reads a subtraction.
|
|
108
|
+
- [ ] Every property verifier SQL will name has a column: scalars and compositions whose non-null branches are scalar (`anyOf [{$ref Status}, {type: null}]`, the nullable-enum shape) project; a composition that may hold an object or array stays JSON-only. A verifier that names a column the contract never projected fails the grade with the database engine's message and the statement; it never scores 0 quietly (double-quoted unknown names no longer fall back to string literals).
|
|
109
|
+
- [ ] `gateway worlds schema compile PATH` then `check PATH` pass. Never edit generated files; SDK templates contain authored inputs and generate bundle artifacts at `init` time. Changing the root `$id` after `init` is fine: `compile` re-stamps an empty `data/initial.json` onto the new domain; a journal that holds rows follows a change that only adds to its domain (a new entity, a new field that is not required) and is refused otherwise, with the fix named (re-import its rows, or restore the schema it was written against).
|
|
109
110
|
- [ ] Shared templates and committed fixtures hold synthetic data only. Tenant captures stay in their owning project; initial batches and refresh journals retain explicit capture/synthetic provenance.
|
|
110
111
|
|
|
111
112
|
### 2. Tenant overlay (required for tenant-shaped, optional for mixed, absent for base)
|
|
@@ -132,7 +133,8 @@ deliverable can finish with synthetic fixtures and explicitly skipped live valid
|
|
|
132
133
|
### 5. Tools (only if the world ships tools)
|
|
133
134
|
|
|
134
135
|
- [ ] Every tool in `x-gateway.tools` has exactly one handler in `tools/*.py` (the loader refuses a mismatch); generated defaults are fine.
|
|
135
|
-
- [ ]
|
|
136
|
+
- [ ] Routes are never tools. A call by a route's name is refused (`not_a_tool`, naming the session's api URL), and a task's `tools` lists declared tools only. A tool may share an operation's name: a call by that name runs the tool, and the route answers only over HTTP at its path.
|
|
137
|
+
- [ ] Handler reads use `gateway_env.store.get` / `list`; writes use `insert` / `update` / `delete`. Read-only SQL uses `gateway_env.db.one/all`; raw SQL writes are denied. The host's `WorldDatabase.query` is not exposed by the handler store proxy.
|
|
136
138
|
- [ ] Handlers never read `benchmark_runtime_context` or `benchmark_conversation_events`.
|
|
137
139
|
- [ ] A user attaching custom tools to this world needs nothing from this checklist beyond the store API; document any conventions the model expects (key formats, enum values).
|
|
138
140
|
|
|
@@ -142,7 +144,9 @@ Tool handlers (`tools/*.py`) reach the world's rows through `from gateway_env im
|
|
|
142
144
|
exactly these methods; `gateway worlds schema check .` refuses any other `store.<name>` at file:line
|
|
143
145
|
with this list, and a hosted call into such a handler answers 400 `{error: "handler", detail, handler}`
|
|
144
146
|
(an `AttributeError`/`TypeError`/`NameError` is the author's bug; anything else a handler raises is a
|
|
145
|
-
500 `{error: "engine", detail, handler}`; never a bare exception string).
|
|
147
|
+
500 `{error: "engine", detail, handler}`; never a bare exception string). A route's handler answers the
|
|
148
|
+
same way on every door, and an answer JSON cannot carry (a `datetime`, a set, NaN) is its 400; a route
|
|
149
|
+
answering bytes names its `Content-Type` (a vendor's `404 text/plain`), and the bytes go out as sent.
|
|
146
150
|
|
|
147
151
|
- `get(entity: str, key: dict) -> dict | None` — one row by primary key, or `None`.
|
|
148
152
|
- `list(entity: str) -> list[dict]` — every row, ordered by key.
|
|
@@ -234,7 +238,7 @@ Full procedure: `.llm_artifacts/plans/connector-implementation-orchestration.md`
|
|
|
234
238
|
- Treating descriptive resources as schema authority. `init` preserves flat supporting `.json`, `.md` and `.toml` files; only referenced schemas become compiler inputs. Slack capability defaults expand into self-contained entries; see [world-schema.md](../../../documentation/features/world-schema.md#connector-templates-and-init).
|
|
235
239
|
- Converting Slack message timestamps to floats or RFC3339. Preserve exact `(workspace_id, channel_id, ts)` keys; see the [Slack model guide](../../../gatewaysdk/sdk/src/gatewaysdk/environment/schema/connectors/slack/MODEL.md) for normalization and limits.
|
|
236
240
|
- Writing a nested field as `owner.user_id` in `unique` or `relationships`. Nested paths are JSON Pointers: `/owner/user_id`.
|
|
237
|
-
- Reading a verifier's 0 as "the agent failed". If the SQL names a column that does not exist the grade is now an error carrying
|
|
241
|
+
- Reading a verifier's 0 as "the agent failed". If the SQL names a column that does not exist the grade is now an error carrying the database engine's message; an older world that still scores 0 on every task has verifier SQL naming an unprojected property — recompile, the nullable-enum shape projects now.
|
|
238
242
|
|
|
239
243
|
## Where this skill is discoverable
|
|
240
244
|
|
|
@@ -388,7 +392,10 @@ them:
|
|
|
388
392
|
- `[api] envelope = "results"` wraps rows as `{"results": [...], "hits": N, "cursor": ""}`
|
|
389
393
|
(empty means a bare array); `hits_key = ""` leaves the count out and
|
|
390
394
|
`cursor_absent_when_done = true` (world-wide, or per route under `[operations.api]`)
|
|
391
|
-
leaves the cursor key out of the last page — Brex's `{items, next_cursor?}`.
|
|
395
|
+
leaves the cursor key out of the last page — Brex's `{items, next_cursor?}`. A dotted
|
|
396
|
+
`envelope = "message.items"` nests the page (`{message: {items, total-results, next-cursor}}`),
|
|
397
|
+
and `[operations.api] wrapper = '{"status": "ok", "message-type": "work-list"}'` lays it onto
|
|
398
|
+
the rest of the vendor's envelope; a single row is wrapped only by its route's own `envelope`.
|
|
392
399
|
- `unauthorized` / `not_found` / `invalid` are JSON strings replayed on 401 / 404 / 400, so
|
|
393
400
|
the vendor's own error bodies come back; `""` (or `'null'`) means no body at all. A route
|
|
394
401
|
whose missing row the vendor answers its own way sets `not_found` and `not_found_status`
|
|
@@ -404,10 +411,11 @@ them:
|
|
|
404
411
|
credential for it, the way it does for a bearer of the session token.
|
|
405
412
|
|
|
406
413
|
`gateway worlds serve PATH --port 8080 [--api-key K]` runs it locally; the runner's admin
|
|
407
|
-
endpoints (`/
|
|
408
|
-
|
|
414
|
+
endpoints (`/__world/seed`, `/__world/reset`, `/__world/state`) sit beside the vendor routes
|
|
415
|
+
and answer only the run's `X-World-Admin-Token` (`gateway worlds test` hands a world's pytest
|
|
416
|
+
files theirs as `WORLD_ADMIN_TOKEN`; by hand, use `/__session/*`); `/healthz` answers everyone,
|
|
417
|
+
and a World Host session's doors answer none of the others. `gateway bench push PATH` publishes the world: for a world carrying
|
|
409
418
|
`connector.toml` it packages the api-kind bundle the platform hosts on the way (root
|
|
410
419
|
legacy-shaped on purpose, since the api runner refuses a schema bundle there; `server/`
|
|
411
420
|
needs nothing installed). Open a session with `--surface api` and hand the client that
|
|
412
|
-
URL; the vendor's auth scheme applies
|
|
413
|
-
otherwise any non-empty one).
|
|
421
|
+
URL; the vendor's auth scheme applies, with the session's own api token as the credential.
|
|
@@ -292,9 +292,10 @@ A schema world's validated database is kept, not rebuilt. `gateway worlds schema
|
|
|
292
292
|
builds `db/state.sqlite` (the default snapshot: `data/initial.json` applied through the
|
|
293
293
|
contract) and `scenarios/<name>/state.sqlite` (the default with the scenario's overlays),
|
|
294
294
|
each with a `state.json` sidecar `{contractHash, batchDigest, entityCounts, builtAt,
|
|
295
|
-
runtime, fileSha256}`; the same
|
|
296
|
-
and a data batch the contract refuses leaves no
|
|
297
|
-
|
|
295
|
+
runtime, fileSha256}`; a snapshot that already holds the same data is never rebuilt,
|
|
296
|
+
`schema check` verifies the sidecars, and a data batch the contract refuses leaves no
|
|
297
|
+
snapshot behind. `gateway worlds serve` and
|
|
298
|
+
the api bundle open the snapshot (copy + `WorldDatabase.open`, no row replay) and reset by
|
|
298
299
|
copying it again; without one the JSON is replayed as before. A hosted pod gets
|
|
299
300
|
`WORLD_SNAPSHOT_URL` (presigned GET, `.gz` or `Content-Encoding: gzip` is gunzipped),
|
|
300
301
|
`WORLD_SNAPSHOT_SHA256` and `WORLD_SNAPSHOT_DIGEST`; the server downloads, verifies, writes
|
|
@@ -303,3 +304,28 @@ reports `"snapshot": {batchDigest, contractHash}` (or null) and `/__world/seed`
|
|
|
303
304
|
overlay form `{"base": digest, "rows": {...}, "mode": append|replace}` beside the legacy
|
|
304
305
|
whole-state body. Snapshot files are build outputs: gitignore `db/state.sqlite`,
|
|
305
306
|
`db/state.json`, `scenarios/*/state.*`.
|
|
307
|
+
|
|
308
|
+
**Which edits keep a snapshot.** Rows are bound to the domain they were stored under, not to
|
|
309
|
+
the whole contract: adding a tool, editing a handler, a route, a test, a documentation file or
|
|
310
|
+
the package version keeps every snapshot (local, hosted, pinned), with no re-import. A change
|
|
311
|
+
that only adds to the domain (a new entity, a new field that is not required, another
|
|
312
|
+
`domain_version`) carries the rows: compile migrates the snapshots the tree holds and keeps the
|
|
313
|
+
pin with the stored domain's `lock` and `entities`, `sandbox check` says the commit migrates the
|
|
314
|
+
hosted snapshot, and `sandbox commit` migrates it and re-pins the tree (a CLI push of such a
|
|
315
|
+
change is refused, naming the sandbox). Any other change to an entity, a field (its description
|
|
316
|
+
or title too), a key or a relationship refuses it, naming each change:
|
|
317
|
+
|
|
318
|
+
```text
|
|
319
|
+
snapshot_pinned at /db/snapshot.json: The rows here were stored under the previous domain, and
|
|
320
|
+
this change requires field users.age. Stored rows carry over only when a change adds to their
|
|
321
|
+
domain (a new entity, a new field that is not required, or another domain_version): ...
|
|
322
|
+
```
|
|
323
|
+
|
|
324
|
+
Then keep those as they were, or remove `db/snapshot.json` and import every row again. A tree
|
|
325
|
+
pinned to a hosted snapshot (`db/snapshot.json`, what a data import publishes) compiles and checks
|
|
326
|
+
without the snapshot itself, as in a sandbox: compile keeps the pin, never rebuilds state from
|
|
327
|
+
the data files, and records in the pin (`lock`) the contract the snapshot was built under, which
|
|
328
|
+
is how the platform proves the next edit still fits it. If `schema/lock.json` was replaced by
|
|
329
|
+
artifacts compiled elsewhere before that, compile says the domain cannot be proven: restore
|
|
330
|
+
`schema/lock.json` from the version you started from and compile again. A `[redact]` change is
|
|
331
|
+
not part of it: the store never applies the policy; capture and `--redact apply` do.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: world-data-ingestion
|
|
3
|
-
description: Put rows into a world from any agent. Use when uploading data to a world, seeding a world, importing rows (a few or millions), adding records to a schema world or mock-tools world, pulling a connector's data through an active connection (`gateway worlds data pull --connection`), seeding a live session, exporting a session's calls, turning a vendor export or a real run into world data, turning an agent's real tool calls, a trace's TOOL observations or a saved ClickHouse result into rows (`gateway worlds data calls pull`, then `data ingest --transform` with your own code or `--map ingest.toml`, `captureToolCalls`), or asking why a served world starts from a snapshot. Covers the rows file contract (JSON object, JSONL, --entity), the tool-call record contract, the transform contract, the `ingest.toml` grammar and `map init`, append vs replace, primary-key upsert, `gateway worlds describe`, `gateway worlds data show|import|pull|check|extract|calls pull|ingest|status|batches|publish`, chunked resumable uploads, refusal reports, data snapshots (`db/state.sqlite`, `WORLD_SNAPSHOT_*`), `gateway worlds session seed|export`, the MCP twins import_world_data / pull_world_data / seed_world_session / export_world_session, the refusals, and the definition of done.
|
|
3
|
+
description: Put rows into a world from any agent. Use when uploading data to a world, seeding a world, importing rows (a few or millions), adding records to a schema world or mock-tools world, pulling a connector's data through an active connection (`gateway worlds data pull --connection`), seeding a live session, exporting a session's calls, turning a vendor export or a real run into world data, turning an agent's real tool calls, a trace's TOOL observations or a saved ClickHouse result into rows (`gateway worlds data calls pull`, then `data ingest --transform` with your own code or `--map ingest.toml`, `captureToolCalls`), or asking why a served world starts from a snapshot. Covers the rows file contract (JSON object, JSONL, --entity), the tool-call record contract, the transform contract, the `ingest.toml` grammar and `map init`, append vs replace, primary-key upsert, `gateway worlds describe`, `gateway worlds data show|import|sql|pull|check|extract|calls pull|ingest|status|batches|publish`, chunked resumable uploads, refusal reports, data snapshots (`db/state.sqlite`, `WORLD_SNAPSHOT_*`), `gateway worlds session seed|export`, the MCP twins import_world_data / pull_world_data / sql_world_data / seed_world_session / export_world_session, the refusals, and the definition of done.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# World data ingestion
|
|
@@ -71,8 +71,7 @@ Rules:
|
|
|
71
71
|
(`--atomic`, the default); `--per-chunk` keeps the good chunks of a large upload and lists
|
|
72
72
|
the refused ones.
|
|
73
73
|
- Inside one batch, two rows with the same key merge by `--merge`: `upsert` (default, the
|
|
74
|
-
later row replaces the earlier) or `fill` (the first row wins, later rows only add fields
|
|
75
|
-
it lacks).
|
|
74
|
+
later row replaces the earlier) or `fill` (the first row wins, later rows only add fields it lacks).
|
|
76
75
|
|
|
77
76
|
## Decision table by world kind
|
|
78
77
|
|
|
@@ -95,7 +94,7 @@ Every CLI step has its MCP twin on the next line. `<WORLD>` is a local world dir
|
|
|
95
94
|
platform world slug (the CLI pulls it to a temp dir, imports, and pushes a new version unless
|
|
96
95
|
`--no-push`). Auth and host: `GATEWAY_HOST`, `GATEWAY_PUBLIC_KEY`, `GATEWAY_SECRET_KEY`, or
|
|
97
96
|
`gateway auth login`. Third place: a CLI sandbox (`worlds sandbox open <slug>@main`) has `gateway` + `sqlite3` on PATH, so
|
|
98
|
-
`sandbox exec <id> 'gateway worlds data import . rows.json'` (`show`, `query`) runs on the uncommitted copy with nothing local; `check` then `commit` lands it. Same refusals as a directory (exit 2).
|
|
97
|
+
`sandbox exec <id> 'gateway worlds data import . rows.json'` (`show`, `query`, `sql`) runs on the uncommitted copy with nothing local; `check` then `commit` lands it. Same refusals as a directory (exit 2).
|
|
99
98
|
The sandbox holds **no platform credentials, by design**: never write keys into its tree (`.gateway-env`, `*.env` are held out of every
|
|
100
99
|
commit, with a warning); bulk rows reach the platform world through `worlds sandbox import <id> <path>` from where the keys are (2d).
|
|
101
100
|
|
|
@@ -108,8 +107,13 @@ gateway worlds data show <WORLD> # {world, kind, entity_count
|
|
|
108
107
|
gateway worlds data show <WORLD> --entity users # the rows of one entity
|
|
109
108
|
gateway worlds data query <WORLD> users --where plan=pro --limit 50 # the rows you mean; a repeated --where key is IN
|
|
110
109
|
gateway worlds data query <WORLD> users --where email=jo@acme.test --resolve # plaintext into a hashed field
|
|
110
|
+
gateway worlds data sql <WORLD> 'SELECT id, name FROM users LIMIT 5' # read-only SQL, any engine
|
|
111
111
|
```
|
|
112
112
|
|
|
113
|
+
`data sql` runs ONE read-only statement (joins, `GROUP BY`, counts) over a schema world's entity tables,
|
|
114
|
+
whatever its database engine: a write, `ATTACH`, `PRAGMA` or a second statement is refused; at most 1000 rows
|
|
115
|
+
(`--limit`). MCP twin: `sql_world_data({ slug, sql, limit? })`. A db/schema.sql world is a SQLite file: `sqlite3`.
|
|
116
|
+
|
|
113
117
|
`data query --resolve` turns each `--where` value into the form the store holds under the
|
|
114
118
|
`[redact]` policy before matching, and prints `resolved <field> -> <form>`; a dropped field
|
|
115
119
|
resolves to nothing, so zero rows there is the policy, not a missing import. MCP twin:
|
|
@@ -269,9 +273,8 @@ level}]}`; text before the JSON is skipped; `input`/`output` decoded as JSON or
|
|
|
269
273
|
```
|
|
270
274
|
|
|
271
275
|
A `gateway worlds session export` line (`{seq, kind, tool, args, result, error, completedAt}`)
|
|
272
|
-
is accepted as it is: `kind != "call"` and a failed call are skipped and counted, never
|
|
273
|
-
silently dropped. `captureToolCalls` (TS) / `capture_tool_calls` (Python) write the same
|
|
274
|
-
record at the source.
|
|
276
|
+
is accepted as it is: `kind != "call"` (a grade, or a `--requests` line of kind `request`) and a failed call are skipped and counted, never
|
|
277
|
+
silently dropped. `captureToolCalls` (TS) / `capture_tool_calls` (Python) write the same record at the source.
|
|
275
278
|
|
|
276
279
|
**2. Transform.** `--transform <script>`: a `.py` file, or `.ts`/`.mjs`/`.js` for node, that
|
|
277
280
|
exports `transform(records) -> {entity: [rows]}` (node: `transform` or the default export),
|
|
@@ -380,26 +383,23 @@ state}` to poll with `data status`. A new-world sandbox commits once first. MCP:
|
|
|
380
383
|
|
|
381
384
|
### 3. Verify on a live session
|
|
382
385
|
|
|
383
|
-
Open a session, seed it, hit it. Live seeding does not change the world's version; it
|
|
384
|
-
changes this session only.
|
|
386
|
+
Open a session, seed it, hit it. Live seeding does not change the world's version; it changes this session only.
|
|
385
387
|
|
|
386
388
|
```bash
|
|
387
389
|
gateway worlds session open <slug> -t <scenario> --surface api # prints sessionId and api.url
|
|
388
390
|
gateway worlds session seed <SESSION_ID> rows.json # kind:"seed" call, waits for the result
|
|
389
391
|
gateway worlds session seed <SESSION_ID> rows.json --redact refuse # same, refusing plaintext in a redacted field (apply hashes it first)
|
|
390
392
|
gateway worlds session seed <SESSION_ID> rows.json --mode replace # swap the named entities
|
|
391
|
-
curl -H
|
|
393
|
+
curl -H "Authorization: Bearer $API_TOKEN" "$API_URL/<route>" # read it back (api.token from session open)
|
|
392
394
|
```
|
|
393
395
|
|
|
394
396
|
Prints `{sessionId, mode, result}`. MCP: `seed_world_session({ sessionId, rows, mode? })` waits
|
|
395
397
|
up to 60 seconds for the engine and otherwise returns a `callId` to poll. Same caps as the
|
|
396
|
-
import. Public API: `POST /api/public/world-sessions/{sessionId}/calls` with
|
|
397
|
-
`{ kind: "seed", rows, mode }`.
|
|
398
|
+
import. Public API: `POST /api/public/world-sessions/{sessionId}/calls` with `{ kind: "seed", rows, mode }`.
|
|
398
399
|
|
|
399
400
|
The tools surface is open by default; `--surface api` adds the vendor's HTTP routes. A fresh
|
|
400
401
|
version's first session takes about fifteen minutes to come up (`PROVISIONING`, 503 on the
|
|
401
|
-
URL); that is a cold pod, not a fault. Pass `--no-wait` and poll
|
|
402
|
-
`gateway worlds session status <SESSION_ID>`.
|
|
402
|
+
URL); that is a cold pod, not a fault. Pass `--no-wait` and poll `gateway worlds session status <SESSION_ID>`.
|
|
403
403
|
|
|
404
404
|
Which kinds can seed live: schema worlds (the store applies the batch through the contract),
|
|
405
405
|
api worlds (the runner merges the rows into the whole state and posts it to the world's seed
|
|
@@ -478,8 +478,8 @@ Sanitize before importing: hash or drop personal fields the world's `[redact]` p
|
|
|
478
478
|
|
|
479
479
|
## Data snapshots
|
|
480
480
|
|
|
481
|
-
Why a served world starts in under a second (`db/state.sqlite`, `WORLD_SNAPSHOT_*`,
|
|
482
|
-
|
|
481
|
+
Why a served world starts in under a second (`db/state.sqlite`, `WORLD_SNAPSHOT_*`, `/__world/seed`), and why a tool,
|
|
482
|
+
handler or route edit keeps the imported data while an entity, field or key edit does not: [ROWS.md — Data snapshots](ROWS.md#data-snapshots).
|
|
483
483
|
|
|
484
484
|
## Definition of done
|
|
485
485
|
|
|
@@ -134,7 +134,7 @@ gateway worlds connector route add ./x create_account -X POST --path /v1/account
|
|
|
134
134
|
|
|
135
135
|
Each refuses (and writes nothing) on a duplicate name, an undeclared entity or `$defs` reference, a key that is not a
|
|
136
136
|
required string/integer field, or a filter on an unknown argument. A create route mints its single-field primary key (`uuid` for strings, `int` for integers) unless `--body` maps it;
|
|
137
|
-
`--generate field=uuid|int|now` and `--default field=value` fill the rest. A custom world's first `route add` creates `connector.toml
|
|
137
|
+
`--generate field=uuid|int|now` and `--default field=value` fill the rest. A custom world's first `route add` creates `connector.toml` with `[auth] scheme = "bearer"` (a hosted session's api token; `worlds serve` answers 401 without one); `--action handler --handler fn` writes a 501 stub `fn(ctx, args, query, body)` into `api/handlers.py` unless it is defined. The custom scaffold's example entity is `records`: `gateway worlds schema entity remove ./x records` once yours are declared (refused, naming each reference, while a route, verifier, row, dependency map or relationship uses it). `schema init` prints `kind: "schema"`, `api` and the `next` commands in order (custom: entity add → entity remove records → route add → task add → compile → check → import → serve → `worlds create`).
|
|
138
138
|
Manifest `kind` is `schema` (older trees: `mock-tools`). Handlers: `def name(ctx, args, query, body)`; `ctx` reads and writes the store and keeps the clock.
|
|
139
139
|
|
|
140
140
|
### From an OpenAPI spec (Swagger 2.0, OpenAPI 3.x)
|
|
@@ -168,7 +168,7 @@ with this list, and a hosted call into such a handler answers 400 `{error: "hand
|
|
|
168
168
|
- `lineage(entity: str, key: dict) -> list[dict]` — the batches that wrote the row at `key`, oldest first.
|
|
169
169
|
- `counts() -> dict[str, int]` — rows per entity, `{entity: count}`.
|
|
170
170
|
|
|
171
|
-
No `upsert`: `get`, then `insert` or `update`. Read-only SQL: `gateway_env.db.one/all`; raw SQL writes are refused. The scaffolded `tools/handlers.py` docstring carries the same table.
|
|
171
|
+
No `upsert`: `get`, then `insert` or `update`. Read-only SQL: `gateway_env.db.one/all`; raw SQL writes are refused. The scaffolded `tools/handlers.py` docstring carries the same table. Every tool call and every route call (handler routes too) is one transaction: one that raises, breaks the contract or answers 4xx/5xx keeps no writes or `ctx.emit` events and is still logged with its status. A route's handler answers like a tool's on every door, an answer JSON cannot carry (a `datetime`, a set, NaN) is its 400, and a route answering bytes (a `404 text/plain`) comes back through `call` as `{status, body}` with the body as text.
|
|
172
172
|
|
|
173
173
|
## 3. Check
|
|
174
174
|
|
|
@@ -181,14 +181,14 @@ gateway worlds serve ./x --port 8080 # answers the vendor
|
|
|
181
181
|
```
|
|
182
182
|
|
|
183
183
|
`check` validates the compiled bundle; `conform` drives every declared route against the
|
|
184
|
-
vendor's document and exits non-zero on a mismatch. Its FAIL list is the work list.
|
|
184
|
+
vendor's document and exits non-zero on a mismatch. Its FAIL list is the work list. Routes are never tools: an agent reaches a world's routes over HTTP (the api url and token `session open --surface api` prints, or `worlds serve` and a request to `http://127.0.0.1:<port>/<path>`), and gets a tool only where `x-gateway.tools` declares one with a handler. A call by a route's name is refused (`not_a_tool`, naming the api URL). A task's `tools` lists declared tools only, and a task that lists any closes the session's routes (403 `route_not_allowed`). An api bundle serves no tools, so the benchmark runner refuses to run one: `gateway worlds migrate <slug> --apply` turns it into a schema world.
|
|
185
185
|
|
|
186
186
|
MCP: `validate_connector_template({ files, slug? })` compiles without writing; answers `{ valid, reason? }`.
|
|
187
187
|
|
|
188
188
|
## 4. Data
|
|
189
189
|
|
|
190
190
|
```bash
|
|
191
|
-
gateway worlds describe ./x # entities, keys, relationships, row counts, [redact] per field
|
|
191
|
+
gateway worlds describe ./x # entities, keys, relationships, row counts, enum values, [redact] per field
|
|
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)
|
|
@@ -314,14 +314,14 @@ gateway worlds session open x -t default # prints {sessionId,
|
|
|
314
314
|
gateway worlds session open x -t default --surface api # asks for api.url explicitly: the vendor's routes, hosted (400 on a tree with no connector.toml)
|
|
315
315
|
gateway worlds session open x -t default --surface ui,browser # + ui.entry (the page, token once then cookie) and browser.wsUrl (a pool Chromium); 400 without [ui] or without a pool; --browser-tier standard (spot, may be reclaimed; the SDK repairs + reconnects, raises BrowserReconnected on a lost click/type) | premium (on-demand), default: the org's setting
|
|
316
316
|
gateway worlds session browse <SESSION_ID> [--path /#/accounts] [--screenshot p.png] # open the page in the browser surface; prints url, title, text
|
|
317
|
-
gateway worlds session open x [--no-wait]
|
|
317
|
+
gateway worlds session open x [--no-wait|--timeout S] # EXPLORATORY: no task, no grader (task.source "none"); waits up to S seconds (600) for ready, --no-wait not at all
|
|
318
318
|
gateway worlds session open x --task-file task.json --surface api # the session's own task (below)
|
|
319
319
|
gateway worlds session status <SESSION_ID> # poll until ready
|
|
320
320
|
gateway worlds session seed <SESSION_ID> rows.json # rows into this session only
|
|
321
321
|
gateway worlds session state <SESSION_ID> # every entity's rows, the dump a grader reads
|
|
322
322
|
gateway worlds session reset <SESSION_ID> # back to the snapshot (+ the task's seed)
|
|
323
323
|
gateway worlds session grade <SESSION_ID> [--timeout S] # {reward, rewards, raw}; exploratory → {reward: null, reason: "no grader"}
|
|
324
|
-
gateway worlds session export <SESSION_ID> --out calls.jsonl
|
|
324
|
+
gateway worlds session export <SESSION_ID> --out calls.jsonl [--requests] # the platform's ledger; --requests (live session, one state call) adds the world's own request log, kind "request" with via
|
|
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
|
```
|
|
@@ -344,7 +344,7 @@ verifiers) is refused `world_kind_retired`; one on an api bundle opens and lists
|
|
|
344
344
|
`instruction` is what the agent is told; `seed` (`{mode?, rows}`, the live-seed contract) is laid on the clone and re-applied by `reset`;
|
|
345
345
|
`grader` is `assertions` (`entity`, `where`, `exists|absent|count|all|any`, `field op value`; each check's `id` becomes a `rewards` key;
|
|
346
346
|
`entity: "calls"` reads the call log — `operation`, `args`, `selectors`, `status`, `rows`, `found`, and `via`: `ui` from the page's `api_path`,
|
|
347
|
-
`api` from the api origin, `tool`
|
|
347
|
+
`api` from the api origin, `tool` for a declared tool's call; a credential-named or secret-shaped field reads `[redacted]`; `rows`/`found` are null where the answer declares no rows, a request too large to keep names what it lacks in `withheld`, and a check grades whenever the calls it can read decide it, ungraded only where those could change the result), `{kind: "python", source, timeoutSeconds?}` (a `verify.py` body; it reads the state as JSON on stdin — `{"<entity>": {"<primary key>": row}, "calls": [...], "report": "<the agent's report>"}`, a verifier's entities as `<alias>.<entity>` — and prints ONE flat JSON object as the last line of stdout, `reward` plus a number from 0 to 1 per check — `true`/`false` read as 1/0, `null` or a string as ungraded, no `reward` leaves the task ungraded, and a nested object or array (a `rewards` map included), a number outside 0..1 or NaN/Infinity fails the grade by key and value; it must exit 0 within `timeoutSeconds`, default and most 30, or the grade fails with the reason) or `{kind: "rubric", rubric, criteria?, model?}`
|
|
348
348
|
(an LLM judge over end state + call log, graded on the platform: `grade` answers pending until
|
|
349
349
|
the worker finalizes it); `tools: [names]` narrows the operations the session may call to
|
|
350
350
|
exactly those (a name the world does not serve is a 400); `metadata` rides the session. At most one of
|
|
@@ -352,7 +352,7 @@ exactly those (a name the world does not serve is a 400); `metadata` rides the s
|
|
|
352
352
|
`task` block is `{source: "inline", name, hash, metadata}`. SDK: `openSession(slug, { task: spec })` / `openSession(slug)` (TS), `open_session(slug, spec)` / `open_session(slug)` (Python);
|
|
353
353
|
`runSessions` / `run_sessions` take a mixed list of names and specs. Over several worlds, `worlds: {alias: {slug, …}}` opens one session per alias
|
|
354
354
|
(`task up|grade|export|down`, `open_task`/`openTask`); a question spanning them is a `verifiers[]` entry (`name`, `scope`, assertions|python over
|
|
355
|
-
`<alias>.<entity>` / `<alias>.calls`), graded on the platform only, rewards `x.<name
|
|
355
|
+
`<alias>.<entity>` / `<alias>.calls`), graded on the platform only, rewards `x.<name>`, so no world is aliased `x` (worlds/sessions.mdx).
|
|
356
356
|
|
|
357
357
|
**A stored task.** The same spec kept as a project resource, versioned by content, so many
|
|
358
358
|
sessions open it by id and grades attribute to the task and its version:
|
|
@@ -391,15 +391,15 @@ gateway bench dispatch <RUN_CONFIG_ID> # each stored task
|
|
|
391
391
|
The first session on a freshly pushed version takes about fifteen minutes: the pod is
|
|
392
392
|
scheduled and the runner sidecar pulled; the session reads `PROVISIONING` and the api URL
|
|
393
393
|
answers 503. That is a cold start, not a fault, until about twenty minutes have passed.
|
|
394
|
-
`session open` prints `session <id> opening — gateway worlds session status <id>` on stderr at once, then waits
|
|
394
|
+
`session open` prints `session <id> opening — gateway worlds session status <id>` on stderr at once while the World Host opens the session, then waits for ready up to `--timeout` seconds (600): a failed open exits 1 naming the reason and code (`browser_capacity` and `host_unavailable` are worth retrying), and a wait that runs out prints `ready: false`, exits 1 and leaves it opening; on a cold version use `--no-wait` and poll. A call on a session still opening waits up to 30 s, then 409 `session_starting`. `open` and
|
|
395
395
|
`status` print `idleExpiresAt` (null once pinned) + `pinned`; `status` warns under 5 minutes. A call
|
|
396
396
|
body over 4mb is refused client-side: `{status: "error", code: "payload_too_large"}`, exit 2.
|
|
397
397
|
|
|
398
|
-
The world's API honours the vendor's auth scheme
|
|
399
|
-
|
|
398
|
+
The world's API honours the vendor's auth scheme and accepts the session's own api token (bearer or
|
|
399
|
+
the vendor's header); `worlds serve` accepts the `--api-key` pin (default `conform`).
|
|
400
400
|
|
|
401
401
|
MCP: `seed_world_session`, `export_world_session`, `save_world_session_task`; open/call/close are CLI or REST only.
|
|
402
|
-
Find what you opened: `gateway worlds session list` / `sandbox list`; `session pin <id>` stops the reaper.
|
|
402
|
+
Find what you opened: `gateway worlds session list` (every state; the live ones are `--state RUNNING` and `--state IDLE`) / `sandbox list`; `session pin <id>` stops the reaper.
|
|
403
403
|
|
|
404
404
|
## Test the world (not the agent)
|
|
405
405
|
|
|
@@ -412,10 +412,10 @@ gateway worlds test my-world # the same suite on the platform,
|
|
|
412
412
|
gateway bench tests my-world # every run the platform kept (push, CLI, API)
|
|
413
413
|
```
|
|
414
414
|
|
|
415
|
-
A case: `{"name": "...", "request": {"method": "GET", "path": "/v1/accounts", "
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
415
|
+
A case: `{"name": "...", "request": {"method": "GET", "path": "/v1/accounts"}, "expect": {"status": 200}}`.
|
|
416
|
+
A `test_*.py` gets `WORLD_URL`, `WORLD_API_KEY` and, with `[ui]`, `WORLD_UI_URL` (the page on its own origin; the
|
|
417
|
+
platform's runner has no browser, so check the page over HTTP there). `[actions]` `on_push = ["tests"]` in
|
|
418
|
+
`gateway-env.toml` runs the suite on each push (Tests tab); `POST/GET /api/public/worlds/{slug}/tests`; `documentation/features/world-tests.md`.
|
|
419
419
|
|
|
420
420
|
## Act on a world as an outside agent (local)
|
|
421
421
|
|
|
@@ -438,7 +438,7 @@ its `api.url` takes the session's bearer): act on it by id, `gateway worlds call
|
|
|
438
438
|
## 7. Run and grade
|
|
439
439
|
|
|
440
440
|
```bash
|
|
441
|
-
gateway worlds run x -a agent.mjs --all # TS CLI: agent
|
|
441
|
+
gateway worlds run x -a agent.mjs --all # TS CLI: agent.mjs[#export] (the default export unless #name) async (session, task) => void, every task; -t <task> for one; x is a slug[@ref] or a pushed dir
|
|
442
442
|
gateway worlds run x -a agent.py:agent # Python CLI: agent callable module:function; --path ./x runs a local dir, --no-file grades without filing
|
|
443
443
|
gateway worlds ci ./x -a agent.mjs --min-score 0.8 # push the working tree, run, gate (CI); --run-config <file> instead of -a; Python: --path ./x -a agent.py:agent
|
|
444
444
|
gateway environment run x -m <provider/model> -k 3 # hosted runner, one job per model; -k is 1–64
|
|
@@ -474,7 +474,7 @@ gateway worlds sandbox import <id> data/trips.csv --entity trip # rows a sandbo
|
|
|
474
474
|
```
|
|
475
475
|
|
|
476
476
|
The sandbox carries the platform's `gateway` CLI and `sqlite3` on PATH: `exec` runs `worlds
|
|
477
|
-
schema|data|test|serve|call …` on the working copy with nothing on your machine. `open` prints
|
|
477
|
+
schema|data|test|serve|call …` on the working copy with nothing on your machine; on a world whose data is a hosted snapshot, a tool, handler or route edit compiles and keeps that data, an entity or key edit is refused (`references/gotchas.md`). `open` prints
|
|
478
478
|
`cli: {version, digest}`, or `cli: null` plus the reason under `warnings`. Remote verbs (`push`, `run`,
|
|
479
479
|
`session open`) stop inside the sandbox by design: it holds no platform credential, and never write one
|
|
480
480
|
into its tree — `check`/`commit` hold back scratch, credential-shaped files (`.env`, `.gateway-env`, `*.env`,
|