@withgateway/sdk 0.3.1 → 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 +4 -3
- package/dist/cli.js +2880 -2032
- package/dist/cli.js.map +1 -1
- package/dist/cli.mjs +2982 -2135
- 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 +180 -41
- package/dist/files/index.js.map +1 -1
- package/dist/files/index.mjs +172 -35
- package/dist/files/index.mjs.map +1 -1
- package/dist/{index-CBqbB_0J.d.ts → index-DUHmS74p.d.ts} +1 -1
- package/dist/{index-D-AMnAMa.d.mts → index-mJhG3vZU.d.mts} +1 -1
- package/dist/index.d.mts +4 -4
- package/dist/index.d.ts +4 -4
- package/dist/index.js +1309 -540
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +1287 -532
- 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 +177 -38
- package/dist/traces/index.js.map +1 -1
- package/dist/traces/index.mjs +169 -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 +69 -13
- package/dist/tracing/index.js.map +1 -1
- package/dist/tracing/index.mjs +69 -13
- package/dist/tracing/index.mjs.map +1 -1
- package/dist/worlds/index.d.mts +249 -120
- package/dist/worlds/index.d.ts +249 -120
- package/dist/worlds/index.js +1240 -484
- package/dist/worlds/index.js.map +1 -1
- package/dist/worlds/index.mjs +1231 -476
- 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 -514
- 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/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 +123 -171
- 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 +19 -11
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +29 -3
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +14 -14
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +12 -12
- 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 +19 -11
- package/skills/connector-schema-authoring/connector-worlds.md +13 -4
- package/skills/connector-schema-authoring/world-schema.md +103 -51
- package/skills/world-data-ingestion/ROWS.md +29 -3
- package/skills/world-data-ingestion/SKILL.md +14 -14
- package/skills/worlds-getting-started/SKILL.md +12 -12
- 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) |
|
|
@@ -104,9 +104,9 @@ deliverable can finish with synthetic fixtures and explicitly skipped live valid
|
|
|
104
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`.
|
|
105
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.
|
|
106
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.
|
|
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 nested key or relationship field is a JSON Pointer, `/owner/user_id`, never `owner.user_id`; the compiler's refusal says so.
|
|
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
|
|
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 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).
|
|
110
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.
|
|
111
111
|
|
|
112
112
|
### 2. Tenant overlay (required for tenant-shaped, optional for mixed, absent for base)
|
|
@@ -133,7 +133,8 @@ deliverable can finish with synthetic fixtures and explicitly skipped live valid
|
|
|
133
133
|
### 5. Tools (only if the world ships tools)
|
|
134
134
|
|
|
135
135
|
- [ ] Every tool in `x-gateway.tools` has exactly one handler in `tools/*.py` (the loader refuses a mismatch); generated defaults are fine.
|
|
136
|
-
- [ ]
|
|
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.
|
|
137
138
|
- [ ] Handlers never read `benchmark_runtime_context` or `benchmark_conversation_events`.
|
|
138
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).
|
|
139
140
|
|
|
@@ -143,7 +144,9 @@ Tool handlers (`tools/*.py`) reach the world's rows through `from gateway_env im
|
|
|
143
144
|
exactly these methods; `gateway worlds schema check .` refuses any other `store.<name>` at file:line
|
|
144
145
|
with this list, and a hosted call into such a handler answers 400 `{error: "handler", detail, handler}`
|
|
145
146
|
(an `AttributeError`/`TypeError`/`NameError` is the author's bug; anything else a handler raises is a
|
|
146
|
-
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.
|
|
147
150
|
|
|
148
151
|
- `get(entity: str, key: dict) -> dict | None` — one row by primary key, or `None`.
|
|
149
152
|
- `list(entity: str) -> list[dict]` — every row, ordered by key.
|
|
@@ -235,7 +238,7 @@ Full procedure: `.llm_artifacts/plans/connector-implementation-orchestration.md`
|
|
|
235
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).
|
|
236
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.
|
|
237
240
|
- Writing a nested field as `owner.user_id` in `unique` or `relationships`. Nested paths are JSON Pointers: `/owner/user_id`.
|
|
238
|
-
- 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.
|
|
239
242
|
|
|
240
243
|
## Where this skill is discoverable
|
|
241
244
|
|
|
@@ -389,7 +392,10 @@ them:
|
|
|
389
392
|
- `[api] envelope = "results"` wraps rows as `{"results": [...], "hits": N, "cursor": ""}`
|
|
390
393
|
(empty means a bare array); `hits_key = ""` leaves the count out and
|
|
391
394
|
`cursor_absent_when_done = true` (world-wide, or per route under `[operations.api]`)
|
|
392
|
-
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`.
|
|
393
399
|
- `unauthorized` / `not_found` / `invalid` are JSON strings replayed on 401 / 404 / 400, so
|
|
394
400
|
the vendor's own error bodies come back; `""` (or `'null'`) means no body at all. A route
|
|
395
401
|
whose missing row the vendor answers its own way sets `not_found` and `not_found_status`
|
|
@@ -405,8 +411,10 @@ them:
|
|
|
405
411
|
credential for it, the way it does for a bearer of the session token.
|
|
406
412
|
|
|
407
413
|
`gateway worlds serve PATH --port 8080 [--api-key K]` runs it locally; the runner's admin
|
|
408
|
-
endpoints (`/
|
|
409
|
-
|
|
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
|
|
410
418
|
`connector.toml` it packages the api-kind bundle the platform hosts on the way (root
|
|
411
419
|
legacy-shaped on purpose, since the api runner refuses a schema bundle there; `server/`
|
|
412
420
|
needs nothing installed). Open a session with `--surface api` and hand the client that
|
|
@@ -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:
|
|
@@ -270,8 +274,7 @@ level}]}`; text before the JSON is skipped; `input`/`output` decoded as JSON or
|
|
|
270
274
|
|
|
271
275
|
A `gateway worlds session export` line (`{seq, kind, tool, args, result, error, completedAt}`)
|
|
272
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
|
|
273
|
-
silently dropped. `captureToolCalls` (TS) / `capture_tool_calls` (Python) write the same
|
|
274
|
-
record at the source.
|
|
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,8 +383,7 @@ 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
|
|
@@ -393,13 +395,11 @@ curl -H "Authorization: Bearer $API_TOKEN" "$API_URL/<route>" # read it b
|
|
|
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
|
|
|
@@ -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,7 +181,7 @@ 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
|
|
|
@@ -314,7 +314,7 @@ 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
|
|
@@ -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,7 +391,7 @@ 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
|
|
|
@@ -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`,
|
|
@@ -17,6 +17,7 @@ Reference for `worlds-getting-started`: every CLI step and its MCP twin, then ho
|
|
|
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
19
|
| `worlds data import` | `import_world_data` |
|
|
20
|
+
| `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) |
|
|
20
21
|
| `worlds session open [-t\|--task-id\|--task-file]` (none: exploratory) / `status` / `call` / `close` / `list` / `pin` | none on the public MCP server — CLI or REST only (`/api/public/world-sessions[/{id}[/calls]]`; the open answers `idleExpiresAt` + `pinned`) |
|
|
21
22
|
| `worlds session seed` | `seed_world_session` |
|
|
22
23
|
| `worlds session export` | `export_world_session` |
|
|
@@ -37,7 +38,7 @@ Reference for `worlds-getting-started`: every CLI step and its MCP twin, then ho
|
|
|
37
38
|
| `bench diff` / `propose` | `env_diff`, `env_propose` (proposals are the legacy PR-style door; edit sessions below are the version-control loop) |
|
|
38
39
|
| `worlds\|bench edit status\|list\|close\|discard\|rollback <slug>` | `list_world_edits({ slug, status?, limit? })`, `close_world_edit({ slug, sessionId?, force?, message? })`, `discard_world_edit`, `rollback_world_edit({ slug, sessionId, force?, message? })` (`GET /api/public/worlds/{slug}/edits`, `POST …/edits/close\|discard\|rollback`). After a world's first version every push, sandbox commit, data import, agent `env_commit` and UI save lands on the credential's open edit session — a private `edit/<id>` branch only that credential reads as `main` (`describe`, `pull`, `log`, `session open`, `sandbox open`); the write's JSON carries `editSessionId` + a hint. `close`, or 60 minutes without an edit, seals the session: the shared `main` moves to its tip (every version stays in `log`; the session is the rollback unit); a `main` that moved meanwhile is rebased when the paths differ, else the session parks as `conflict` (`close --force` takes its content). `rollback` restores source + data snapshot from before a sealed session as a new sealed session (`--force` when later sessions would be undone too). UI: world › History › Edit sessions |
|
|
39
40
|
| `worlds task edit status\|close\|rollback <task>` (task id, spec file with `worlds`, or `task up` manifest) | `get_task_edit({ task })`, `close_task_edit({ task, requireAll?, force?, message? })`, `rollback_task_edit({ task, groupId, force?, message? })` (`POST /api/public/world-task-edits/status\|close\|rollback`). The same edit sessions across every world a task names: `status` shows each world's unsealed edits (open and `parked` in conflict) and what closing would do (`fast-forward`, `rebase`, `conflict`) — your own `task up` opens them at your tip (`private: true`), everyone else still gets shared `main`; `close` seals every world in ONE transaction (a conflict, a missing world, a ref other than `main` or a parked session anywhere seals nothing, and the 409 names every world's problem; worlds with no edit are skipped unless `--require-all`), and the sessions share a `groupId`; `rollback --group` restores every world together to the `main` the group replaced, refused when anything reached a world's `main` after the group (a later session or a write outside sessions) unless `--force` |
|
|
40
|
-
| `worlds\|bench sandbox open\|status\|read\|write\|exec\|check\|commit\|close` | `open_world_sandbox`, `get_world_sandbox`, `read_world_sandbox_file`, `write_world_sandbox_file` (base64), `exec_in_world_sandbox`, `check_world_sandbox`, `commit_world_sandbox`, `close_world_sandbox({ sandboxId, force? })` (`/api/public/benchmark-containers/sandboxes[/{id}[/file\|exec\|check\|commit]]`; `close` with uncommitted work is a 409 `sandbox_uncommitted` naming the paths, nothing closed, unless `force: true` / `--force`; a sandbox whose machine was replaced gets its tree back (latest snapshot, or the base) and the next verb answers 409 `sandbox_recreated` once — look at the tree, redo lost edits, retry; 503 `sandbox_restore_failed` means retry; 409 `sandbox_tree_missing` means the world root was deleted, so close and reopen; the source tree only — no data snapshot, nothing on the caller's disk; `commit` lands on the recorded base; `commit --rebase` sends `rebase: true` and replays onto a branch head that moved, a 409 naming each conflicting path). `open` reports `cli: {version, digest}` — the platform's own `gateway` CLI and a `sqlite3` are on PATH inside `exec`, so `gateway worlds schema entity add\|verifier add\|task add\|compile\|check .`, `gateway worlds data import\|show\|query .`, `gateway worlds test .`, `gateway worlds serve . --port 8080 & sleep 2; gateway worlds call http://localhost:8080 <tool> …` (one `exec`; a served world lives only as long as that command) and `sqlite3 db/state.sqlite "…"` run on the working copy; remote verbs (push, run, session open) stop in the sandbox by design — `check`/`commit` from your machine. `cli: null` + `warnings[]` means the image cannot host the runtime (python3 < 3.12 or node < 18); plain shell still runs |
|
|
41
|
+
| `worlds\|bench sandbox open\|status\|read\|write\|exec\|check\|commit\|close` | `open_world_sandbox`, `get_world_sandbox`, `read_world_sandbox_file`, `write_world_sandbox_file` (base64), `exec_in_world_sandbox`, `check_world_sandbox`, `commit_world_sandbox`, `close_world_sandbox({ sandboxId, force? })` (`/api/public/benchmark-containers/sandboxes[/{id}[/file\|exec\|check\|commit]]`; `close` with uncommitted work is a 409 `sandbox_uncommitted` naming the paths, nothing closed, unless `force: true` / `--force`; a sandbox whose machine was replaced gets its tree back (latest snapshot, or the base) and the next verb answers 409 `sandbox_recreated` once — look at the tree, redo lost edits, retry; 503 `sandbox_restore_failed` means retry; 409 `sandbox_tree_missing` means the world root was deleted, so close and reopen; the source tree only — no data snapshot, nothing on the caller's disk; `commit` lands on the recorded base; `commit --rebase` sends `rebase: true` and replays onto a branch head that moved, a 409 naming each conflicting path). `open` reports `cli: {version, digest}` — the platform's own `gateway` CLI and a `sqlite3` are on PATH inside `exec`, so `gateway worlds schema entity add\|verifier add\|task add\|compile\|check .`, `gateway worlds data import\|show\|query\|sql .`, `gateway worlds test .`, `gateway worlds serve . --port 8080 & sleep 2; gateway worlds call http://localhost:8080 <tool> …` (one `exec`; a served world lives only as long as that command) and `sqlite3 db/state.sqlite "…"` run on the working copy; remote verbs (push, run, session open) stop in the sandbox by design — `check`/`commit` from your machine. `cli: null` + `warnings[]` means the image cannot host the runtime (python3 < 3.12 or node < 18); plain shell still runs |
|
|
41
42
|
| `worlds\|bench sandbox open --new <slug> --from custom\|<template>` | `open_world_sandbox({ new, from })` (same route, body `{new, from}`; a world that does not exist yet — `baseVersionId`/`containerId`/`baseContentHash` null, `branch: main`, `pendingSlug`; `custom` = the `schema init` scaffold, else a shipped template (`GET /api/public/worlds/templates`; unknown → 400 naming the list); taken slug → 409 `world_exists`, never renamed; `check_world_sandbox` runs the first commit's gate; the first `commit_world_sandbox` creates the world on `main` through the `worlds create --from <dir>` door, later commits land on the new base; the same staged CLI runs on the scaffold) |
|
|
42
43
|
| `worlds skill <name>` / `worlds connector skill` | `get_connector_authoring_skill`, `guide` |
|
|
43
44
|
| `worlds connector capture --remote` / poll + download | `start_connector_capture`, `get_connector_capture` (platform agent only) |
|
|
@@ -53,7 +54,7 @@ before it makes a request.
|
|
|
53
54
|
| `sandbox exec --timeout`, `exec_in_world_sandbox timeoutMs` | default 60 s, at most 600 s | refused, not clamped |
|
|
54
55
|
| Sandbox tree at `check`/`commit`, `bench push` unpacked | 128 MB of source, 2000 files | refused, naming the limit, before a byte is read; move data to `worlds data import`, delete scratch files or list them in `.gatewayignore` |
|
|
55
56
|
| Sandbox tree at `check`/`commit`: credential-shaped files (`.env`, `*.pem`, `id_rsa`, `credentials.json`…; `.env.example` stays), symlinks, sockets/devices | held back, never in the version | listed under `ignored`, each named in `warnings` (path only); use `bench secrets set` for a key the world needs |
|
|
56
|
-
| `worlds data query` / `data show` on a stored version | none beyond the version's own caps | the platform opens the version's tree and snapshot in a prepared directory it owns; no size travels through the request |
|
|
57
|
+
| `worlds data query` / `data sql` / `data show` on a stored version | none beyond the version's own caps | the platform opens the version's tree and snapshot in a prepared directory it owns; no size travels through the request |
|
|
57
58
|
| `bench push` / `worlds create --from` compressed bundle | 64 MB (16 MB from the browser) | refused, naming the limit |
|
|
58
59
|
| A single manifest / metadata file in a bundle | 1 MB | refused |
|
|
59
60
|
| `sandbox write` HTTP body | 1 MB (framework cap; only reachable by a body no schema would accept) | 413 |
|
package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md
CHANGED
|
@@ -28,3 +28,18 @@ The things that bite once and never again, moved out of `SKILL.md` to keep it un
|
|
|
28
28
|
anything is provisioned — the same preflight a run dispatch applies; set the secret, then open.
|
|
29
29
|
- `gateway secret set NAME` is an upsert: the same name again rotates the value and answers
|
|
30
30
|
`updated: true`; `bench secrets set` does the same for a benchmark's environment.
|
|
31
|
+
- Imported data survives every edit that cannot touch a stored row. After `gateway worlds data import
|
|
32
|
+
<slug>` the world's tree carries `db/snapshot.json` (the hosted snapshot) and not the rows; in
|
|
33
|
+
`worlds sandbox open <slug>@main`, adding a tool, a handler, a route, a test or a documentation
|
|
34
|
+
file then `schema compile .` and `schema check .` pass and the commit keeps the snapshot, no
|
|
35
|
+
re-import, and `gateway bench fork <slug>` takes the data with it. Adding an entity or a field
|
|
36
|
+
that is not required (or another `domain_version`) carries the data too: `sandbox check` says
|
|
37
|
+
the commit migrates the snapshot, and `sandbox commit` migrates it and re-pins the tree.
|
|
38
|
+
Removing, retyping or requiring a field, or changing a key, a relationship or a description, is
|
|
39
|
+
refused, naming what changed: keep it as it was, or remove `db/snapshot.json` and import every
|
|
40
|
+
row again. `check` reports
|
|
41
|
+
the handlers `not_run` there, since a session needs the hosted rows; `gateway worlds session open
|
|
42
|
+
<slug>` runs them, so a handler that cannot be imported (a syntax error, a missing module) passes
|
|
43
|
+
`check` and is first refused at that open: open a session on the version after a handler edit.
|
|
44
|
+
Compile from a fresh `sandbox open` rather than copying in artifacts compiled
|
|
45
|
+
elsewhere: the pin proves its data's domain from the `schema/lock.json` it started with.
|