@withgateway/sdk 0.3.0 → 0.3.1
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 +5 -1
- package/dist/cli.js +1497 -712
- package/dist/cli.js.map +1 -1
- package/dist/cli.mjs +1500 -715
- package/dist/cli.mjs.map +1 -1
- package/dist/files/index.js +34 -0
- package/dist/files/index.js.map +1 -1
- package/dist/files/index.mjs +34 -0
- package/dist/files/index.mjs.map +1 -1
- package/dist/{index-DAb-FCMg.d.ts → index-CBqbB_0J.d.ts} +2 -12
- package/dist/{index-D6oi1TWE.d.mts → index-D-AMnAMa.d.mts} +2 -12
- package/dist/index.d.mts +3 -3
- package/dist/index.d.ts +3 -3
- package/dist/index.js +173 -50
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +171 -50
- package/dist/index.mjs.map +1 -1
- package/dist/traces/index.js +34 -0
- package/dist/traces/index.js.map +1 -1
- package/dist/traces/index.mjs +34 -0
- package/dist/traces/index.mjs.map +1 -1
- package/dist/tracing/index.d.mts +1 -1
- package/dist/tracing/index.d.ts +1 -1
- package/dist/tracing/index.js +39 -20
- package/dist/tracing/index.js.map +1 -1
- package/dist/tracing/index.mjs +39 -20
- package/dist/tracing/index.mjs.map +1 -1
- package/dist/worlds/index.d.mts +66 -18
- package/dist/worlds/index.d.ts +66 -18
- package/dist/worlds/index.js +171 -50
- package/dist/worlds/index.js.map +1 -1
- package/dist/worlds/index.mjs +171 -50
- package/dist/worlds/index.mjs.map +1 -1
- package/package.json +1 -1
- package/runtime/gatewaysdk/environment/schema/api.py +7 -8
- package/runtime/gatewaysdk/environment/schema/cast.py +31 -4
- package/runtime/gatewaysdk/environment/schema/platform.py +1 -7
- package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +3 -3
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +2 -2
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +6 -6
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +1 -1
- package/skills/connector-schema-authoring/SKILL.md +3 -3
- package/skills/connector-schema-authoring/connector-worlds.md +12 -5
- package/skills/connector-schema-authoring/world-schema.md +8 -0
- package/skills/world-data-ingestion/SKILL.md +2 -2
- package/skills/worlds-getting-started/SKILL.md +6 -6
- package/skills/worlds-getting-started/references/cli-mcp-map.md +1 -1
package/package.json
CHANGED
|
@@ -927,6 +927,11 @@ class Router:
|
|
|
927
927
|
return presented in self.tokens
|
|
928
928
|
return key is None or presented == key
|
|
929
929
|
|
|
930
|
+
def without_credential(self, query_all: dict) -> dict:
|
|
931
|
+
"""The query as the call log keeps it: a query-auth world's key is never recorded."""
|
|
932
|
+
credential = self.spec.auth_name if self.spec.scheme == "query" else None
|
|
933
|
+
return {k: v for k, v in query_all.items() if k != credential}
|
|
934
|
+
|
|
930
935
|
|
|
931
936
|
class ApiContext:
|
|
932
937
|
"""What a world's handler gets: the store, the clock, and the vendor's shapes."""
|
|
@@ -1565,8 +1570,6 @@ class WorldApp:
|
|
|
1565
1570
|
) -> Response:
|
|
1566
1571
|
settings, router = self.settings, self.router
|
|
1567
1572
|
path = self._strip(url.path)
|
|
1568
|
-
# Every value of a repeated key is kept; ``query`` hands routes the first, the way
|
|
1569
|
-
# they always read it, and ``ctx.query_all`` hands handlers and filters the rest.
|
|
1570
1573
|
query_all = {k: list(v) for k, v in urllib.parse.parse_qs(url.query).items()}
|
|
1571
1574
|
query = {k: v[0] for k, v in query_all.items()}
|
|
1572
1575
|
if not router.authorized(headers, query, self.key):
|
|
@@ -1584,7 +1587,8 @@ class WorldApp:
|
|
|
1584
1587
|
started = time.monotonic()
|
|
1585
1588
|
status, answer, extra = self._answer_route(op, operation, args, query, query_all, body, headers, url, default_host)
|
|
1586
1589
|
elapsed = time.monotonic() - started
|
|
1587
|
-
|
|
1590
|
+
logged_query = router.without_credential(query_all)
|
|
1591
|
+
self.calls.record(operation, method, path, args, logged_query, body, status, answer, elapsed, via)
|
|
1588
1592
|
return status, answer, extra
|
|
1589
1593
|
|
|
1590
1594
|
def _answer_route(self, op, operation, args, query, query_all, body, headers, url, default_host) -> Response:
|
|
@@ -1596,8 +1600,6 @@ class WorldApp:
|
|
|
1596
1600
|
ctx.query_all = query_all
|
|
1597
1601
|
try:
|
|
1598
1602
|
if BEFORE in handlers:
|
|
1599
|
-
# The world's gate: quotas, allow-lists, key states — whatever the vendor
|
|
1600
|
-
# checks before any route, declarative ones included.
|
|
1601
1603
|
verdict = _normalize(handlers[BEFORE](ctx, args, query, body), None)
|
|
1602
1604
|
if verdict is not None:
|
|
1603
1605
|
return verdict
|
|
@@ -1691,7 +1693,6 @@ def send_response(
|
|
|
1691
1693
|
return
|
|
1692
1694
|
headers = dict(extra or {})
|
|
1693
1695
|
if isinstance(body, bytes):
|
|
1694
|
-
# As the handler shaped them, under the Content-Type it named (checked in _normalize).
|
|
1695
1696
|
payload = body
|
|
1696
1697
|
else:
|
|
1697
1698
|
payload = json.dumps(body, ensure_ascii=False).encode("utf-8")
|
|
@@ -1840,8 +1841,6 @@ def openapi_document(spec: Spec, contract_id: str, settings: ApiSettings | None
|
|
|
1840
1841
|
):
|
|
1841
1842
|
entry["requestBody"] = {"content": {"application/json": {"schema": {"type": "object"}}}}
|
|
1842
1843
|
if len(operation.methods) > 1:
|
|
1843
|
-
# One OpenAPI operation, listed under the verb a capture sends; the
|
|
1844
|
-
# others the served route also answers are named here.
|
|
1845
1844
|
entry["x-gateway-methods"] = list(operation.methods)
|
|
1846
1845
|
methods = paths.setdefault(operation.path, {})
|
|
1847
1846
|
method = operation.method.lower()
|
|
@@ -36,11 +36,19 @@ _MISSING = object()
|
|
|
36
36
|
@dataclass(frozen=True)
|
|
37
37
|
class FieldType:
|
|
38
38
|
"""One field as ``gateway worlds describe`` reports it: ``type`` is the JSON Schema
|
|
39
|
-
type word(s) joined by ``" | "``, a ``$ref`` name, or None when the schema says nothing
|
|
39
|
+
type word(s) joined by ``" | "``, a ``$ref`` name, or None when the schema says nothing;
|
|
40
|
+
``enum`` the values the schema allows, when it lists them."""
|
|
40
41
|
|
|
41
42
|
name: str
|
|
42
43
|
type: str | None
|
|
43
44
|
required: bool
|
|
45
|
+
enum: tuple | None = None
|
|
46
|
+
|
|
47
|
+
def describe(self) -> dict:
|
|
48
|
+
described: dict = {"name": self.name, "type": self.type, "required": self.required}
|
|
49
|
+
if self.enum is not None:
|
|
50
|
+
described["enum"] = list(self.enum)
|
|
51
|
+
return described
|
|
44
52
|
|
|
45
53
|
|
|
46
54
|
def _article(kind: str) -> str:
|
|
@@ -160,7 +168,7 @@ class RowCaster:
|
|
|
160
168
|
return row
|
|
161
169
|
|
|
162
170
|
|
|
163
|
-
#:
|
|
171
|
+
#: The untyped reader: every cell as its text, or None for an empty cell.
|
|
164
172
|
TEXT_CASTER = RowCaster([])
|
|
165
173
|
|
|
166
174
|
EntityCasters = Callable[[str], "RowCaster | None"]
|
|
@@ -178,7 +186,6 @@ def _definition(world: dict, entity: Any) -> dict:
|
|
|
178
186
|
if isinstance(ref, str) and ref.startswith("#/$defs/"):
|
|
179
187
|
definition = (world.get("$defs") or {}).get(ref[len("#/$defs/") :])
|
|
180
188
|
return definition if isinstance(definition, dict) else {}
|
|
181
|
-
# An inline payload (`schema entity add --schema '{…}'`) declares its fields right here.
|
|
182
189
|
if isinstance(schema, dict) and isinstance(schema.get("properties"), dict):
|
|
183
190
|
return schema
|
|
184
191
|
return {}
|
|
@@ -196,19 +203,39 @@ def _field_type(field_schema: Any) -> str | None:
|
|
|
196
203
|
return kind if isinstance(kind, str) else None
|
|
197
204
|
|
|
198
205
|
|
|
206
|
+
def _field_enum(field_schema: Any, defs: dict) -> tuple | None:
|
|
207
|
+
if not isinstance(field_schema, dict):
|
|
208
|
+
return None
|
|
209
|
+
branches = field_schema.get("anyOf") or field_schema.get("oneOf")
|
|
210
|
+
if isinstance(branches, list):
|
|
211
|
+
return _branches_enum(branches, defs)
|
|
212
|
+
ref = field_schema.get("$ref")
|
|
213
|
+
target = defs.get(ref[len("#/$defs/") :]) if isinstance(ref, str) and ref.startswith("#/$defs/") else field_schema
|
|
214
|
+
values = target.get("enum") if isinstance(target, dict) else None
|
|
215
|
+
return tuple(values) if isinstance(values, list) else None
|
|
216
|
+
|
|
217
|
+
|
|
218
|
+
def _branches_enum(branches: list, defs: dict) -> tuple | None:
|
|
219
|
+
"""A nullable enum (``anyOf: [{$ref: Enum}, {type: null}]``) allows the enum's values and null."""
|
|
220
|
+
values = [value for branch in branches for value in (_field_enum(branch, defs) or ())]
|
|
221
|
+
nullable = any(isinstance(branch, dict) and branch.get("type") == "null" for branch in branches)
|
|
222
|
+
return tuple(values) + ((None,) if nullable else ()) if values else None
|
|
223
|
+
|
|
224
|
+
|
|
199
225
|
def world_fields(world: dict) -> dict[str, list[FieldType]]:
|
|
200
226
|
"""Every entity's fields as a world.json document declares them (the ``$defs`` entry its
|
|
201
227
|
``schema.$ref`` names, or an inline ``properties``), sorted by entity name — the field
|
|
202
228
|
list ``gateway worlds describe`` reports and a CSV import casts by."""
|
|
203
229
|
gateway = world.get("x-gateway") if isinstance(world, dict) else None
|
|
204
230
|
entities = (gateway.get("entities") or {}) if isinstance(gateway, dict) else {}
|
|
231
|
+
defs = world.get("$defs") or {}
|
|
205
232
|
fields: dict[str, list[FieldType]] = {}
|
|
206
233
|
for name, entity in sorted(entities.items()):
|
|
207
234
|
definition = _definition(world, entity)
|
|
208
235
|
required = set(definition.get("required") or [])
|
|
209
236
|
properties = definition.get("properties") or {}
|
|
210
237
|
fields[name] = [
|
|
211
|
-
FieldType(field_name, _field_type(field_schema), field_name in required)
|
|
238
|
+
FieldType(field_name, _field_type(field_schema), field_name in required, _field_enum(field_schema, defs))
|
|
212
239
|
for field_name, field_schema in properties.items()
|
|
213
240
|
]
|
|
214
241
|
return fields
|
|
@@ -21,7 +21,6 @@ import shutil
|
|
|
21
21
|
import sys
|
|
22
22
|
import tarfile
|
|
23
23
|
import tempfile
|
|
24
|
-
from dataclasses import asdict
|
|
25
24
|
from pathlib import Path, PurePosixPath
|
|
26
25
|
from typing import TYPE_CHECKING, Any
|
|
27
26
|
|
|
@@ -719,7 +718,7 @@ def _template_summary(files: dict[str, bytes]) -> dict:
|
|
|
719
718
|
"primaryKey": list(entity.get("primary_key") or []) if isinstance(entity, dict) else [],
|
|
720
719
|
"unique": list(entity.get("unique") or []) if isinstance(entity, dict) else [],
|
|
721
720
|
"relationships": list(entity.get("relationships") or []) if isinstance(entity, dict) else [],
|
|
722
|
-
"fields": [
|
|
721
|
+
"fields": [field.describe() for field in fields_by_entity.get(name, [])],
|
|
723
722
|
}
|
|
724
723
|
)
|
|
725
724
|
_annotate_redaction(entities, policy)
|
|
@@ -929,9 +928,6 @@ def _ingest_calls(request: dict) -> dict:
|
|
|
929
928
|
return answer
|
|
930
929
|
|
|
931
930
|
|
|
932
|
-
# ---------------------------------------------------------------- batches
|
|
933
|
-
|
|
934
|
-
|
|
935
931
|
def _workdir(request: dict) -> Path:
|
|
936
932
|
"""The absolute directory the caller prepared; every path in the request is under it."""
|
|
937
933
|
workdir = request.get("workdir")
|
|
@@ -1502,8 +1498,6 @@ def execute(request: dict) -> dict:
|
|
|
1502
1498
|
)
|
|
1503
1499
|
extra["batch"] = append_batch(world, batch, source=source)
|
|
1504
1500
|
if request["command"] == "init-template":
|
|
1505
|
-
# The platform's "create world" for every connector template: the same
|
|
1506
|
-
# init + compile the CLI runs, on a fresh empty tree, with nothing seeded.
|
|
1507
1501
|
from .scaffold import init_bundle
|
|
1508
1502
|
|
|
1509
1503
|
connector = request.get("connector")
|
|
@@ -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 |
|
|
@@ -409,5 +410,4 @@ vendor routes. `gateway bench push PATH` publishes the world: for a world carryi
|
|
|
409
410
|
`connector.toml` it packages the api-kind bundle the platform hosts on the way (root
|
|
410
411
|
legacy-shaped on purpose, since the api runner refuses a schema bundle there; `server/`
|
|
411
412
|
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).
|
|
413
|
+
URL; the vendor's auth scheme applies, with the session's own api token as the credential.
|
|
@@ -269,7 +269,7 @@ level}]}`; text before the JSON is skipped; `input`/`output` decoded as JSON or
|
|
|
269
269
|
```
|
|
270
270
|
|
|
271
271
|
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
|
|
272
|
+
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
273
|
silently dropped. `captureToolCalls` (TS) / `capture_tool_calls` (Python) write the same
|
|
274
274
|
record at the source.
|
|
275
275
|
|
|
@@ -388,7 +388,7 @@ gateway worlds session open <slug> -t <scenario> --surface api # prints s
|
|
|
388
388
|
gateway worlds session seed <SESSION_ID> rows.json # kind:"seed" call, waits for the result
|
|
389
389
|
gateway worlds session seed <SESSION_ID> rows.json --redact refuse # same, refusing plaintext in a redacted field (apply hashes it first)
|
|
390
390
|
gateway worlds session seed <SESSION_ID> rows.json --mode replace # swap the named entities
|
|
391
|
-
curl -H
|
|
391
|
+
curl -H "Authorization: Bearer $API_TOKEN" "$API_URL/<route>" # read it back (api.token from session open)
|
|
392
392
|
```
|
|
393
393
|
|
|
394
394
|
Prints `{sessionId, mode, result}`. MCP: `seed_world_session({ sessionId, rows, mode? })` waits
|
|
@@ -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)
|
|
@@ -188,7 +188,7 @@ MCP: `validate_connector_template({ files, slug? })` compiles without writing; a
|
|
|
188
188
|
## 4. Data
|
|
189
189
|
|
|
190
190
|
```bash
|
|
191
|
-
gateway worlds describe ./x # 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)
|
|
@@ -321,7 +321,7 @@ gateway worlds session seed <SESSION_ID> rows.json # rows into this ses
|
|
|
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
|
```
|
|
@@ -395,11 +395,11 @@ answers 503. That is a cold start, not a fault, until about twenty minutes have
|
|
|
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
|
|
|
@@ -37,7 +37,7 @@ Reference for `worlds-getting-started`: every CLI step and its MCP twin, then ho
|
|
|
37
37
|
| `bench diff` / `propose` | `env_diff`, `env_propose` (proposals are the legacy PR-style door; edit sessions below are the version-control loop) |
|
|
38
38
|
| `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
39
|
| `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`; 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 |
|
|
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
41
|
| `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
42
|
| `worlds skill <name>` / `worlds connector skill` | `get_connector_authoring_skill`, `guide` |
|
|
43
43
|
| `worlds connector capture --remote` / poll + download | `start_connector_capture`, `get_connector_capture` (platform agent only) |
|
|
@@ -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 |
|
|
@@ -409,5 +410,4 @@ vendor routes. `gateway bench push PATH` publishes the world: for a world carryi
|
|
|
409
410
|
`connector.toml` it packages the api-kind bundle the platform hosts on the way (root
|
|
410
411
|
legacy-shaped on purpose, since the api runner refuses a schema bundle there; `server/`
|
|
411
412
|
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).
|
|
413
|
+
URL; the vendor's auth scheme applies, with the session's own api token as the credential.
|
|
@@ -84,8 +84,9 @@ reads `PROVISIONING` and the URL answers 503; that is a cold start, not a fault,
|
|
|
84
84
|
about twenty minutes have passed. `session open` waits ten minutes by default, so on a cold
|
|
85
85
|
version pass `--no-wait` and poll `gateway worlds session status <sessionId>` until `ready`.
|
|
86
86
|
|
|
87
|
-
The world's API honours the vendor's auth scheme:
|
|
88
|
-
|
|
87
|
+
The world's API honours the vendor's auth scheme: a hosted session accepts its own api token (as a
|
|
88
|
+
bearer or in the vendor's header), `worlds serve` the credential `--api-key` pins (default `conform`),
|
|
89
|
+
and `WORLD_API_KEY` applies only to a legacy api bundle. Anything else answers 401 with the body configured under
|
|
89
90
|
`[api].unauthorized` (`""` or `'null'` for a bare status with no body, the way some vendors answer).
|
|
90
91
|
|
|
91
92
|
**Data.** Captures are one way in. Any agent can put rows into the world without knowing its
|
|
@@ -128,7 +129,13 @@ least one `[[operations]]` entry.
|
|
|
128
129
|
|
|
129
130
|
`gateway worlds connector route add <world> <name>` appends one `[[operations]]` block to
|
|
130
131
|
`connector.toml` without touching the bytes already there (comments and formatting survive;
|
|
131
|
-
the TOML is parsed only to validate).
|
|
132
|
+
the TOML is parsed only to validate). A world's first route creates `connector.toml` with
|
|
133
|
+
`[auth] scheme = "bearer"` and `secret_env = "<SLUG>_API_KEY"`: the api token a hosted session
|
|
134
|
+
hands the agent is a bearer, and `worlds serve` answers 401 without one and accepts the bearer
|
|
135
|
+
`--api-key` pins (default `conform`). `--action handler --handler fn` writes a stub
|
|
136
|
+
`def fn(ctx, args, query, body)` answering 501 into `api/handlers.py` unless `fn` is already
|
|
137
|
+
defined there; the output's `handler: {file, function, written}` says which. Flags map onto
|
|
138
|
+
the spec's keys:
|
|
132
139
|
|
|
133
140
|
| Flag | Key |
|
|
134
141
|
| ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------- |
|
|
@@ -175,8 +182,8 @@ does all of that from the same `connector.toml`:
|
|
|
175
182
|
(function allow-list, quota, blocked IP) hold on plain reads and writes as much as on handlers;
|
|
176
183
|
handlers and the gate may answer with headers too (`SpyCloud-Error`, `Retry-After`).
|
|
177
184
|
- An oauth2 world answers the vendor's token route before any authorization, so a client that
|
|
178
|
-
performs the grant first works unchanged;
|
|
179
|
-
|
|
185
|
+
performs the grant first works unchanged; a hosted session checks the client secret against its
|
|
186
|
+
own api token, `worlds serve` against the `--api-key` pin.
|
|
180
187
|
|
|
181
188
|
The handlers ship inside the api bundle beside the world, so the hosted container runs them
|
|
182
189
|
with nothing installed. The abstraction is the platform's; the handlers are the customer's.
|
|
@@ -140,6 +140,14 @@ string/integer fields, unknown `$defs`, and any file that is not a `gateway-worl
|
|
|
140
140
|
document; a refusal leaves the file untouched. Source:
|
|
141
141
|
`gatewaysdk/sdk-ts/src/cli/runtime/scaffold.ts`.
|
|
142
142
|
|
|
143
|
+
`gateway worlds schema entity remove ./x records` takes one entity out again, with the `$defs`
|
|
144
|
+
only it used (the custom scaffold's example `records` entity once yours are declared). It is
|
|
145
|
+
refused, naming each reference and writing nothing, while a `connector.toml` operation answers
|
|
146
|
+
from it, a `verifiers/*.sql` reads it, `data/initial.json` holds rows of it, a
|
|
147
|
+
`[dependencies.<alias>.entities]` map names it or another entity relates to it; the world keeps
|
|
148
|
+
at least one entity, and the untouched `state_present.sql` placeholder is re-pointed at one that
|
|
149
|
+
stays. Source: `gatewaysdk/sdk-ts/src/cli/runtime/scaffoldEntityRemove.ts`.
|
|
150
|
+
|
|
143
151
|
## Supported payload language
|
|
144
152
|
|
|
145
153
|
| Construct | `gateway-world/1` semantics |
|
|
@@ -269,7 +269,7 @@ level}]}`; text before the JSON is skipped; `input`/`output` decoded as JSON or
|
|
|
269
269
|
```
|
|
270
270
|
|
|
271
271
|
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
|
|
272
|
+
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
273
|
silently dropped. `captureToolCalls` (TS) / `capture_tool_calls` (Python) write the same
|
|
274
274
|
record at the source.
|
|
275
275
|
|
|
@@ -388,7 +388,7 @@ gateway worlds session open <slug> -t <scenario> --surface api # prints s
|
|
|
388
388
|
gateway worlds session seed <SESSION_ID> rows.json # kind:"seed" call, waits for the result
|
|
389
389
|
gateway worlds session seed <SESSION_ID> rows.json --redact refuse # same, refusing plaintext in a redacted field (apply hashes it first)
|
|
390
390
|
gateway worlds session seed <SESSION_ID> rows.json --mode replace # swap the named entities
|
|
391
|
-
curl -H
|
|
391
|
+
curl -H "Authorization: Bearer $API_TOKEN" "$API_URL/<route>" # read it back (api.token from session open)
|
|
392
392
|
```
|
|
393
393
|
|
|
394
394
|
Prints `{sessionId, mode, result}`. MCP: `seed_world_session({ sessionId, rows, mode? })` waits
|
|
@@ -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)
|
|
@@ -188,7 +188,7 @@ MCP: `validate_connector_template({ files, slug? })` compiles without writing; a
|
|
|
188
188
|
## 4. Data
|
|
189
189
|
|
|
190
190
|
```bash
|
|
191
|
-
gateway worlds describe ./x # 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)
|
|
@@ -321,7 +321,7 @@ gateway worlds session seed <SESSION_ID> rows.json # rows into this ses
|
|
|
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
|
```
|
|
@@ -395,11 +395,11 @@ answers 503. That is a cold start, not a fault, until about twenty minutes have
|
|
|
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
|
|
|
@@ -37,7 +37,7 @@ Reference for `worlds-getting-started`: every CLI step and its MCP twin, then ho
|
|
|
37
37
|
| `bench diff` / `propose` | `env_diff`, `env_propose` (proposals are the legacy PR-style door; edit sessions below are the version-control loop) |
|
|
38
38
|
| `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
39
|
| `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`; 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 |
|
|
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
41
|
| `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
42
|
| `worlds skill <name>` / `worlds connector skill` | `get_connector_authoring_skill`, `guide` |
|
|
43
43
|
| `worlds connector capture --remote` / poll + download | `start_connector_capture`, `get_connector_capture` (platform agent only) |
|