@withgateway/sdk 0.6.0 → 0.9.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/dist/agents/index.d.mts +573 -0
- package/dist/agents/index.d.ts +573 -0
- package/dist/agents/index.js +1443 -0
- package/dist/agents/index.js.map +1 -0
- package/dist/agents/index.mjs +1394 -0
- package/dist/agents/index.mjs.map +1 -0
- package/dist/apiError-DHpfbmdx.d.mts +17 -0
- package/dist/apiError-DHpfbmdx.d.ts +17 -0
- package/dist/cli.js +5019 -1599
- package/dist/cli.js.map +1 -1
- package/dist/cli.mjs +5003 -1584
- package/dist/cli.mjs.map +1 -1
- package/dist/files/index.d.mts +3 -1
- package/dist/files/index.d.ts +3 -1
- package/dist/files/index.js +371 -102
- package/dist/files/index.js.map +1 -1
- package/dist/files/index.mjs +371 -102
- package/dist/files/index.mjs.map +1 -1
- package/dist/hooks/index.js +346 -136
- package/dist/hooks/index.js.map +1 -1
- package/dist/hooks/index.mjs +346 -136
- package/dist/hooks/index.mjs.map +1 -1
- package/dist/{index-LA-PMRJT.d.ts → index-DIN14Lhg.d.ts} +1 -1
- package/dist/{index-Di9nNqOY.d.mts → index-DuB-eQ0Z.d.mts} +1 -1
- package/dist/index.d.mts +7 -4
- package/dist/index.d.ts +7 -4
- package/dist/index.js +2689 -401
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +2650 -394
- package/dist/index.mjs.map +1 -1
- package/dist/media-CQUC7TkS.d.mts +39 -0
- package/dist/media-DQnBloaX.d.ts +39 -0
- package/dist/traces/index.d.mts +3 -1
- package/dist/traces/index.d.ts +3 -1
- package/dist/traces/index.js +371 -102
- package/dist/traces/index.js.map +1 -1
- package/dist/traces/index.mjs +371 -102
- package/dist/traces/index.mjs.map +1 -1
- package/dist/tracing/index.d.mts +3 -2
- package/dist/tracing/index.d.ts +3 -2
- package/dist/tracing/index.js +257 -16
- package/dist/tracing/index.js.map +1 -1
- package/dist/tracing/index.mjs +257 -16
- package/dist/tracing/index.mjs.map +1 -1
- package/dist/transport-CpRe7zgd.d.mts +123 -0
- package/dist/transport-CpRe7zgd.d.ts +123 -0
- package/dist/worlds/index.d.mts +1983 -1745
- package/dist/worlds/index.d.ts +1983 -1745
- package/dist/worlds/index.js +1295 -226
- package/dist/worlds/index.js.map +1 -1
- package/dist/worlds/index.mjs +1290 -222
- package/dist/worlds/index.mjs.map +1 -1
- package/package.json +6 -1
- package/runtime/gatewaysdk/environment/bundle_manifest.py +243 -0
- package/runtime/gatewaysdk/environment/schema/__main__.py +2 -2
- package/runtime/gatewaysdk/environment/schema/_slack_fidelity.py +8 -23
- package/runtime/gatewaysdk/environment/schema/api.py +3 -4
- package/runtime/gatewaysdk/environment/schema/assertions.py +7 -1
- package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +1 -0
- package/runtime/gatewaysdk/environment/schema/call_log.py +20 -0
- package/runtime/gatewaysdk/environment/schema/database/base.py +2 -2
- package/runtime/gatewaysdk/environment/schema/host.py +74 -11
- package/runtime/gatewaysdk/environment/schema/host_browser.py +48 -0
- package/runtime/gatewaysdk/environment/schema/host_control.py +33 -2
- package/runtime/gatewaysdk/environment/schema/host_handoff.py +4 -1
- package/runtime/gatewaysdk/environment/schema/host_requests.py +14 -0
- package/runtime/gatewaysdk/environment/schema/host_session.py +13 -2
- package/runtime/gatewaysdk/environment/schema/host_surfaces.py +6 -0
- package/runtime/gatewaysdk/environment/schema/host_versions.py +96 -19
- package/runtime/gatewaysdk/environment/schema/journal.py +7 -2
- package/runtime/gatewaysdk/environment/schema/local.py +32 -7
- package/runtime/gatewaysdk/environment/schema/page_checks.py +123 -0
- package/runtime/gatewaysdk/environment/schema/platform.py +23 -267
- package/runtime/gatewaysdk/environment/schema/platform_templates.py +332 -0
- package/runtime/gatewaysdk/environment/schema/request_ledger.py +4 -1
- package/runtime/gatewaysdk/environment/schema/run_parameters.py +25 -0
- package/runtime/gatewaysdk/environment/schema/runtime.py +43 -5
- package/runtime/gatewaysdk/environment/schema/scaffold.py +367 -217
- package/runtime/gatewaysdk/environment/schema/session_files.py +13 -2
- package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +1 -1
- package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +1 -2
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +4 -2
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +7 -7
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +32 -2
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +6 -6
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +17 -2
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/new-world-sandbox.md +1 -1
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/ui-map.md +3 -2
- package/runtime/gatewaysdk/environment/schema/slack.py +55 -10
- package/runtime/gatewaysdk/environment/schema/snapshot.py +28 -2
- package/runtime/gatewaysdk/environment/schema/tasks.py +25 -2
- package/runtime/gatewaysdk/environment/schema/template_record.py +131 -0
- package/runtime/gatewaysdk/environment/schema/tools_world.py +7 -5
- package/runtime/gatewaysdk/environment/schema/ui.py +54 -33
- package/runtime/gatewaysdk/environment/schema/ui_interactions.py +419 -0
- package/runtime/gatewaysdk/environment/schema/ui_recorder.js +895 -0
- package/runtime/gatewaysdk/environment/schema/ui_replay.py +366 -0
- package/runtime/gatewaysdk/environment/schema/ui_replay_record.LICENSE +25 -0
- package/runtime/gatewaysdk/environment/schema/ui_replay_record.js +109 -0
- package/runtime/gatewaysdk/environment/schema/validation.py +10 -1
- package/runtime/gatewaysdk/environment/schema/worker.py +5 -1
- package/runtime/gatewaysdk/environment/schema/workers.py +8 -1
- package/runtime/gatewaysdk/environment/schema/world_host.py +44 -15
- package/runtime/gatewaysdk/environment/secret_values.py +1 -1
- package/runtime/gatewaysdk/environment/world.py +34 -43
- package/runtime/gatewaysdk/environment/world_session_contract.py +7 -34
- package/skills/benchmarks-getting-started/SKILL.md +1 -1
- package/skills/connector-schema-authoring/SKILL.md +1 -2
- package/skills/connector-schema-authoring/connector-worlds.md +2 -2
- package/skills/connector-schema-authoring/world-schema.md +29 -23
- package/skills/world-data-ingestion/SKILL.md +4 -2
- package/skills/worlds-getting-started/SKILL.md +7 -7
- package/skills/worlds-getting-started/references/cli-mcp-map.md +32 -2
- package/skills/worlds-getting-started/references/gotchas.md +6 -6
- package/skills/worlds-getting-started/references/journal-checks.md +17 -2
- package/skills/worlds-getting-started/references/new-world-sandbox.md +1 -1
- package/skills/worlds-getting-started/references/ui-map.md +3 -2
- package/dist/media-BIApiPzS.d.mts +0 -102
- package/dist/media-BIApiPzS.d.ts +0 -102
|
@@ -1,17 +1,4 @@
|
|
|
1
|
-
"""
|
|
2
|
-
|
|
3
|
-
``World.from_tree`` is the one Python detector: the local runtime
|
|
4
|
-
(``_bundle.detect_kind``), the data commands (``data.world_kind``), the hub
|
|
5
|
-
client (``harbor_adapter.detect_env_kind``), the benchmark runner
|
|
6
|
-
(``engines/hub_bundle.detect_env_kind``), the platform bridge
|
|
7
|
-
(``platform.world_root``) and the World Host (``host_versions.world_tree``) all read
|
|
8
|
-
their answer from here. The TypeScript twin is
|
|
9
|
-
``packages/shared/src/world/`` (``WorldTree`` + ``World.fromTree``); the
|
|
10
|
-
corpus under ``conformance/worlds/`` pins both to the same answers.
|
|
11
|
-
|
|
12
|
-
Stdlib only: the benchmark runner vendors this subpackage without the SDK's
|
|
13
|
-
dependencies.
|
|
14
|
-
"""
|
|
1
|
+
"""Stdlib only: the benchmark runner vendors this subpackage without the SDK's dependencies."""
|
|
15
2
|
|
|
16
3
|
from __future__ import annotations
|
|
17
4
|
|
|
@@ -26,15 +13,14 @@ from typing import ClassVar
|
|
|
26
13
|
|
|
27
14
|
from ._toml import tomllib
|
|
28
15
|
from .errors import WorldStartError
|
|
29
|
-
from .
|
|
16
|
+
from .bundle_manifest import BUNDLE_MANIFEST
|
|
17
|
+
from .world_session_contract import API_BUNDLE_RUN_REFUSAL, BUNDLE_RUN_REFUSAL
|
|
30
18
|
|
|
31
19
|
try: # optional: only consulted when a tree ships a root .gitignore
|
|
32
20
|
from gitignore_parser import parse_gitignore
|
|
33
21
|
except ImportError: # pragma: no cover - the runner and the sandbox vendor this module alone
|
|
34
22
|
parse_gitignore = None # type: ignore[assignment]
|
|
35
23
|
|
|
36
|
-
# Twin of packages/shared/src/world/markers.ts.
|
|
37
|
-
|
|
38
24
|
WORLD_MANIFEST = "gateway-env.toml"
|
|
39
25
|
API_BUNDLE_MANIFEST = "gateway-api-world.toml"
|
|
40
26
|
BUNDLED_WORLD_PREFIX = "server/world/"
|
|
@@ -52,21 +38,16 @@ KIND_API = "api"
|
|
|
52
38
|
KIND_HARBOR = "harbor"
|
|
53
39
|
KIND_VERIFIERS = "verifiers"
|
|
54
40
|
KIND_VERIFIERS_V1 = "verifiers-v1"
|
|
41
|
+
KIND_BUNDLE = "bundle"
|
|
55
42
|
|
|
56
43
|
_SKIPPED_DIRS = frozenset({"dist", "build", "outputs", "__pycache__", "node_modules"})
|
|
57
|
-
# A root Gateway marker widens the hashed root
|
|
58
|
-
|
|
59
|
-
# connector.toml, a benchmark's config and fixtures) at the root.
|
|
60
|
-
_BROAD_ROOT_MARKERS = frozenset({WORLD_MANIFEST, API_BUNDLE_MANIFEST, BENCHMARK_CONFIG})
|
|
44
|
+
# A root Gateway marker widens the hashed root to every ordinary root file: those kinds keep executable contract there.
|
|
45
|
+
_BROAD_ROOT_MARKERS = frozenset({WORLD_MANIFEST, API_BUNDLE_MANIFEST, BENCHMARK_CONFIG, BUNDLE_MANIFEST})
|
|
61
46
|
_HASH_CHUNK = 1 << 20
|
|
62
47
|
_HARBOR_TASK = re.compile(r"^(?:tasks/)?([^/]+)/task\.toml$")
|
|
63
48
|
|
|
64
|
-
#
|
|
65
|
-
#
|
|
66
|
-
# pyproject — minor >= 2 on the 0.x line or any major >= 1, never 0.0/0.1 —
|
|
67
|
-
# and/or imports the namespace or subclasses Taskset alongside the v1
|
|
68
|
-
# packaging convention of an ``__all__`` export (any library may name a class
|
|
69
|
-
# Taskset). A bare unversioned dependency or a pre-0.2 pin is v0.
|
|
49
|
+
# `verifiers.v1` first shipped in verifiers 0.2.0: a v1 package pins >=0.2 (or any major >= 1), imports the
|
|
50
|
+
# namespace, or subclasses Taskset beside an ``__all__`` export (any library may name a class Taskset).
|
|
70
51
|
_V1_DEP = re.compile(
|
|
71
52
|
r"""["']verifiers\s*(?:\[[^\]]*\])?\s*(?:>=|~=|==|>)\s*""" r"""(?:0\.(?:[2-9]\d*|[1-9]\d+)|[1-9]\d*)"""
|
|
72
53
|
)
|
|
@@ -92,8 +73,6 @@ def _ordinary_root_file(name: str, broad: bool) -> bool:
|
|
|
92
73
|
|
|
93
74
|
|
|
94
75
|
def is_hashed_path(relative: str, broad_root: bool) -> bool:
|
|
95
|
-
"""Twin of ``worldTree.ts isHashedPath``: the path-only half of the archive
|
|
96
|
-
rule (hidden names, pruned directories, the root globs)."""
|
|
97
76
|
parts = relative.split("/")
|
|
98
77
|
name = parts[-1]
|
|
99
78
|
if name.startswith(".") or "__pycache__" in parts:
|
|
@@ -186,9 +165,6 @@ WorldManifest.ABSENT = WorldManifest(None, None, None)
|
|
|
186
165
|
|
|
187
166
|
@dataclass(frozen=True)
|
|
188
167
|
class Exclusion:
|
|
189
|
-
"""One entry the archive rules dropped: a whole directory (``name/``,
|
|
190
|
-
``files`` counted) or a single root file."""
|
|
191
|
-
|
|
192
168
|
path: str
|
|
193
169
|
files: int
|
|
194
170
|
|
|
@@ -233,17 +209,9 @@ class WorldTree:
|
|
|
233
209
|
def has_connector(self) -> bool:
|
|
234
210
|
return self.has(self.world_path(CONNECTOR_SPEC))
|
|
235
211
|
|
|
236
|
-
# Vendored from Prime Intellect's ``prime`` CLI (MIT; THIRD_PARTY_LICENSES)
|
|
237
|
-
#
|
|
238
|
-
#
|
|
239
|
-
# path order, over README.md / pyproject.toml / *.py at the root plus every
|
|
240
|
-
# non-hidden nested file outside dist, build, outputs, __pycache__ and
|
|
241
|
-
# *.egg-info. A root Gateway marker widens the root to every ordinary file
|
|
242
|
-
# (the marker itself must be hashed or a manifest-only edit dedups into the
|
|
243
|
-
# previous version and is silently discarded). Symlinks and ``.gitignore``-d
|
|
244
|
-
# paths are dropped. This is the version primary key, NOT a tarball digest.
|
|
245
|
-
# Twin: ``packages/shared/src/world/worldTree.ts`` (``isHashedPath`` +
|
|
246
|
-
# ``contentHash``); the corpus under ``conformance/worlds/`` pins both.
|
|
212
|
+
# Vendored from Prime Intellect's ``prime`` CLI (MIT; THIRD_PARTY_LICENSES) so a tree hashes to the same version
|
|
213
|
+
# on their hub. It is the version primary key, not a tarball digest: a root marker must be hashed, or a
|
|
214
|
+
# manifest-only edit dedups into the previous version and is silently discarded.
|
|
247
215
|
|
|
248
216
|
@property
|
|
249
217
|
def broad_root(self) -> bool:
|
|
@@ -390,6 +358,8 @@ class World:
|
|
|
390
358
|
def from_tree(tree: WorldTree) -> World:
|
|
391
359
|
if tree.is_api_bundle:
|
|
392
360
|
return ApiBundle(tree)
|
|
361
|
+
if WorldBundle.marks(tree):
|
|
362
|
+
return WorldBundle(tree)
|
|
393
363
|
if tree.has(WORLD_MANIFEST):
|
|
394
364
|
schema = tree.has_schema_marker or tree.manifest.declares_schema
|
|
395
365
|
return SchemaWorld(tree) if schema else ToolsWorld(tree)
|
|
@@ -521,6 +491,25 @@ class ApiBundle(World):
|
|
|
521
491
|
return API_BUNDLE_RUN_REFUSAL
|
|
522
492
|
|
|
523
493
|
|
|
494
|
+
class WorldBundle(World):
|
|
495
|
+
"""``gateway-bundle.toml`` at the root: the member worlds it opens together. It runs nothing itself."""
|
|
496
|
+
|
|
497
|
+
kind = KIND_BUNDLE
|
|
498
|
+
shape = "bundle"
|
|
499
|
+
|
|
500
|
+
@staticmethod
|
|
501
|
+
def marks(tree: WorldTree) -> bool:
|
|
502
|
+
return tree.has(BUNDLE_MANIFEST)
|
|
503
|
+
|
|
504
|
+
@property
|
|
505
|
+
def local_runtime(self) -> bool:
|
|
506
|
+
return False
|
|
507
|
+
|
|
508
|
+
@property
|
|
509
|
+
def agent_run_refusal(self) -> str:
|
|
510
|
+
return BUNDLE_RUN_REFUSAL
|
|
511
|
+
|
|
512
|
+
|
|
524
513
|
class ContainerBench(World):
|
|
525
514
|
@property
|
|
526
515
|
def substrate(self) -> str:
|
|
@@ -567,6 +556,7 @@ class PlainTree(VerifiersBench):
|
|
|
567
556
|
|
|
568
557
|
__all__ = [
|
|
569
558
|
"API_BUNDLE_MANIFEST",
|
|
559
|
+
"BUNDLE_MANIFEST",
|
|
570
560
|
"BUNDLED_WORLD_PREFIX",
|
|
571
561
|
"CONNECTOR_SPEC",
|
|
572
562
|
"PYPROJECT",
|
|
@@ -580,6 +570,7 @@ __all__ = [
|
|
|
580
570
|
"ToolsWorld",
|
|
581
571
|
"VerifiersBench",
|
|
582
572
|
"World",
|
|
573
|
+
"WorldBundle",
|
|
583
574
|
"WorldManifest",
|
|
584
575
|
"WorldTree",
|
|
585
576
|
]
|
|
@@ -1,61 +1,31 @@
|
|
|
1
|
-
"""
|
|
2
|
-
|
|
3
|
-
Stdlib only, and inside ``gatewaysdk.environment`` because that package is
|
|
4
|
-
what gets vendored on its own — the web/worker images ship
|
|
5
|
-
``/opt/gateway-schema/gatewaysdk/environment``, ``installSandboxRuntime``
|
|
6
|
-
copies it into agent sandboxes and api bundles stage it beside
|
|
7
|
-
``server/main.py`` — so the World Host's grader, the SDK client
|
|
8
|
-
(:mod:`gatewaysdk.world_sessions`) and the CLI all read this one module.
|
|
9
|
-
|
|
10
|
-
The TypeScript source of truth is
|
|
11
|
-
``gateway/packages/shared/src/server/services/worldSessionContract.ts``;
|
|
12
|
-
both are pinned to ``conformance/world-sessions.json`` by a test on each
|
|
13
|
-
side, so the route, the World Host and the two CLIs cannot drift apart.
|
|
14
|
-
"""
|
|
1
|
+
"""Stdlib only, inside ``gatewaysdk.environment``: that package is vendored alone into images, sandboxes and bundles."""
|
|
15
2
|
|
|
16
3
|
from __future__ import annotations
|
|
17
4
|
|
|
18
5
|
from datetime import datetime, timezone
|
|
19
6
|
|
|
20
|
-
#: The largest body ``POST world-sessions/{id}/calls`` accepts. The CLI
|
|
21
|
-
#: measures the serialized body against the byte count and refuses before
|
|
22
|
-
#: sending; the label is what help and the refusal name.
|
|
23
7
|
CALL_BODY_LIMIT_BYTES = 4 * 1024 * 1024
|
|
24
8
|
CALL_BODY_LIMIT_LABEL = "4mb"
|
|
25
9
|
|
|
26
|
-
#: ``session status`` warns once an unpinned session has less than this left.
|
|
27
10
|
IDLE_WARNING_MINUTES = 5
|
|
28
11
|
|
|
29
|
-
#: The most entries one page of the world request ledger holds, as the platform lists it
|
|
30
|
-
#: and as a World Host drains a session's outbox.
|
|
31
12
|
REQUEST_LOG_PAGE_MAX = 200
|
|
32
13
|
|
|
33
|
-
#: How much of each body the request ledger keeps: the first this many bytes of its text.
|
|
34
14
|
REQUEST_BODY_CAPTURE_BYTES = 64 * 1024
|
|
35
15
|
|
|
36
|
-
#: What a World Host's heartbeat names to say it serves open sessions; the platform places an
|
|
37
|
-
#: open session only on a host that does.
|
|
38
16
|
OPEN_DOOR_FEATURE = "open-door"
|
|
39
17
|
|
|
40
|
-
|
|
18
|
+
WORLD_STATES_FEATURE = "world-states"
|
|
19
|
+
|
|
41
20
|
REQUESTS_NOT_RECORDED = "requests_not_recorded"
|
|
42
21
|
|
|
43
|
-
#: The task an exploratory session runs on when the caller names none, and
|
|
44
|
-
#: the ``task.source`` the platform reports for it.
|
|
45
22
|
EXPLORATORY_TASK: dict[str, str] = {"instruction": "exploratory session"}
|
|
46
23
|
EXPLORATORY_TASK_SOURCE = "none"
|
|
47
24
|
|
|
48
|
-
#: What a session that has no grader answers ``grade`` with, beside
|
|
49
|
-
#: ``reward: null``.
|
|
50
25
|
NO_GRADER_REASON = "no grader"
|
|
51
26
|
|
|
52
|
-
#: Where a world's server and its runner find the token for the runner's
|
|
53
|
-
#: ``/__world/*`` routes: set by the platform on a session pod's two
|
|
54
|
-
#: containers, by the Batch runner on a world it boots.
|
|
55
27
|
ADMIN_TOKEN_ENV = "WORLD_ADMIN_TOKEN"
|
|
56
28
|
|
|
57
|
-
#: The code and words of a call by a route's name: a world's routes answer
|
|
58
|
-
#: over its HTTP api, never through the tool door.
|
|
59
29
|
NOT_A_TOOL = "not_a_tool"
|
|
60
30
|
ROUTE_NOT_A_TOOL = "'{name}' is a route of this world, not a tool; call it over the session's api URL"
|
|
61
31
|
|
|
@@ -64,7 +34,10 @@ def route_not_a_tool(name: str) -> str:
|
|
|
64
34
|
return ROUTE_NOT_A_TOOL.format(name=name)
|
|
65
35
|
|
|
66
36
|
|
|
67
|
-
|
|
37
|
+
BUNDLE_RUN_REFUSAL = (
|
|
38
|
+
"A world bundle runs nothing on its own: its member worlds run, opened together as one bundle session. "
|
|
39
|
+
"Run or open a member world."
|
|
40
|
+
)
|
|
68
41
|
API_BUNDLE_RUN_REFUSAL = (
|
|
69
42
|
"an api bundle serves no tools: its routes answer over its HTTP api and are never an agent's tools, so "
|
|
70
43
|
"the benchmark runner's agent has nothing to call. Migrate it to a schema world (`gateway worlds migrate "
|
|
@@ -326,7 +326,7 @@ fields and the reward signature against the verifiers version you install.
|
|
|
326
326
|
|
|
327
327
|
```bash
|
|
328
328
|
gateway benchmarks init ./crm-bench # custom contract: example entity, three tools, one verifier, one task
|
|
329
|
-
gateway benchmarks init ./slack-bench --connector slack #
|
|
329
|
+
gateway benchmarks init ./slack-bench --connector slack # an official template (needs a login): the vendor's entities, routes and tools
|
|
330
330
|
gateway benchmarks init ./x --task onboard --prompt "Create an account for Acme." --model openai/gpt-5-mini -k 3
|
|
331
331
|
```
|
|
332
332
|
|
|
@@ -174,7 +174,7 @@ No `upsert`: `get`, then `insert` or `update`. Read-only SQL: `gateway_env.db.on
|
|
|
174
174
|
|
|
175
175
|
### 7. Ship the template; register platform integration only when in scope
|
|
176
176
|
|
|
177
|
-
- [ ]
|
|
177
|
+
- [ ] Official: an official editor pushes the template tree into the official organization (`gateway worlds create <slug> --from <dir>` with `GATEWAY_TOKEN` + `GATEWAY_PROJECT_ID`, then publish it), and every reader serves it from that world's head (`gateway worlds schema templates`, `schema init --connector <slug>`, `worlds create --from <slug>`). Authored trees still sit under `gatewaysdk/sdk/src/gatewaysdk/environment/schema/connectors/<slug>/` until O4 moves them out; `tests/test_official_template_world.py` pins that a world built from the files is byte-identical to the old directory init. Schema-only templates declare an empty tools map and have no operation handlers.
|
|
178
178
|
- [ ] Platform integration, if separately in scope: map an existing source kind in `schemaWorldTemplates.ts` so "Build from connector" offers it. Do not register a native provider or invent a source kind for an SDK-only schema milestone.
|
|
179
179
|
- [ ] Treat `connectionMode` as the primary authentication path, not the only setup path. A managed connector may retain `remoteMcpPreset` as a fallback; render that action from the preset's presence. For native source connectors such as Slack, the source-backed Link action is the managed authentication path because native-provider dispatch intentionally precedes Merge.
|
|
180
180
|
- [ ] User-added templates can use `--connector custom` and SDK publication. Generic schema upload and shared/project registry infrastructure remain unimplemented.
|
|
@@ -265,7 +265,6 @@ Python SDK as package data so an agent in any repository can install it.
|
|
|
265
265
|
Revalidated 2026-09-07 while integrating `ba89fe16` with `015d6b25`:
|
|
266
266
|
`schema/scaffold.py`, `schema/platform.py`, `tests/environment/test_schema_scaffold.py`,
|
|
267
267
|
`worldSchemaPublication.ts`, `worldSchemaRuntime.ts`, `environmentBundleTester.ts`,
|
|
268
|
-
`environmentBuildWorkbench.ts`, `environmentSchemaSandbox.ts`,
|
|
269
268
|
`NativeSlackService.ts`, and `deploy/benchmark-runner/engines/{session_server,schema_session}.py`.
|
|
270
269
|
Full source paths and runtime boundaries are listed in [world-schema.md](../../../documentation/features/world-schema.md).
|
|
271
270
|
These source checks do not imply live-provider validation or executed fidelity scores.
|
|
@@ -618,8 +618,8 @@ gateway worlds connector skill --install . # the authoring skill + agen
|
|
|
618
618
|
- **Compile before accept.** Every push is run through the schema runtime on the platform
|
|
619
619
|
(`validateConnectorTemplate`); a template that does not make a world is refused with a 400
|
|
620
620
|
carrying the reason and nothing is committed. The digest is `template_digest`, the same
|
|
621
|
-
algorithm an
|
|
622
|
-
template pin identically.
|
|
621
|
+
algorithm an official template pins with (over its official world head's files), so a workspace
|
|
622
|
+
connector and an identical official template pin identically.
|
|
623
623
|
- **Re-publishing is a commit.** A second publish to the same slug pulls the head, sends
|
|
624
624
|
`parent_commit`, and deletes paths no longer in the directory, so the connector always equals
|
|
625
625
|
the directory. `--workspace-visible` makes it visible to the whole workspace rather than the
|
|
@@ -23,12 +23,12 @@ session](#raw-ingestion-schema-gated-sql), and connector
|
|
|
23
23
|
| SDK `gwenv.init_from_path` | Checks artifacts and materializes isolated schema-aware worlds. |
|
|
24
24
|
| Direct benchmark `mock-tools` runner | Reuses SDK materialization and `World` enforcement. |
|
|
25
25
|
| SDK/public and platform publication, including READY/dedup/fork/ref promotion | Verifies the stored SHA-256, generated artifacts and exact lock through the trusted compiler/materializer using actual archive bytes; uploaded Python is parsed, not imported during publication. |
|
|
26
|
-
| Worker
|
|
26
|
+
| Worker Environment Actions (`BundleTester`, `BundleCompleteness`) | Never run a schema world: Environment Actions skip every check for it, and the tester and the completeness gate refuse a schema tree (`WORLD_SCHEMA_UNSUPPORTED`). The environment builder and its E2B workbench were deleted (2026-10-13). |
|
|
27
27
|
| Hosted `mock-tools` sessions | Use the shared `World` in a child process for validated calls, reset and grading; dependency worlds are unsupported. |
|
|
28
28
|
| Platform agent (`run_gateway_cli`) | Edits schema worlds in its sandbox with the `gateway worlds` CLI and publishes as the user through its doors (`create`, `push`, `data import <slug>`), checked like any CLI push; see [agent.md](./agent.md#platform-actions-worlds-tasks-rollouts-connectors-ingestion-self-schedules). |
|
|
29
29
|
| SDK Harbor worlds and Harbor/API/verifiers engines | Retain their separate unsupported-mode guards; do not combine their bundle markers with schema mode. |
|
|
30
30
|
|
|
31
|
-
Environment Actions remain advisory. See [Environment
|
|
31
|
+
Environment Actions remain advisory. See [Environment Actions](../../system-architecture/worlds/environment-actions.md) and
|
|
32
32
|
[Benchmark Container Hub](./benchmark-containers.md).
|
|
33
33
|
|
|
34
34
|
## Bundle layout and authoring
|
|
@@ -403,12 +403,13 @@ committed and a rejected session.
|
|
|
403
403
|
|
|
404
404
|
## Connector templates and `init`
|
|
405
405
|
|
|
406
|
-
|
|
407
|
-
`gatewaysdk/sdk/src/gatewaysdk/environment/schema/connectors
|
|
408
|
-
|
|
409
|
-
`
|
|
410
|
-
|
|
411
|
-
|
|
406
|
+
Vendor templates are authored `gateway-world/1` contracts kept under
|
|
407
|
+
`gatewaysdk/sdk/src/gatewaysdk/environment/schema/connectors/` until O4, and served
|
|
408
|
+
from the official organization: each one is an ordinary schema world built from its
|
|
409
|
+
template (`init_official_world`), which keeps every file the template brought and
|
|
410
|
+
records `schema/template.json` (`connector`, `digest`: the template's
|
|
411
|
+
`template_digest`, the digest every world made from it pins). Only the one-entity
|
|
412
|
+
`custom` template ships in code. The
|
|
412
413
|
[Microsoft Teams guide](./microsoft-teams-schema.md) documents its schema-only
|
|
413
414
|
Graph v1.0 base, synthetic sample, and provisional subset assessment.
|
|
414
415
|
|
|
@@ -418,17 +419,23 @@ gateway worlds schema init ./teams-world --connector microsoft-teams
|
|
|
418
419
|
gateway worlds schema init ./acme-crm --connector custom --name acme-crm
|
|
419
420
|
```
|
|
420
421
|
|
|
421
|
-
`init
|
|
422
|
-
the
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
`
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
422
|
+
`init --connector <slug>` reads the official world's head and copies it under the
|
|
423
|
+
new name (`init_bundle_from_world`, the runtime's `init-world-files`): the package id
|
|
424
|
+
and the manifest's name change, the contract is compiled again and its data follows
|
|
425
|
+
it; nothing is rebuilt from the template. `worlds create <slug> --from <template>` is
|
|
426
|
+
the same copy on the platform, and the new world's first version records
|
|
427
|
+
`forkedFromVersionId` = the official version. Building a world from template files
|
|
428
|
+
(`init_bundle_from_files`, a workspace connector or an official world's own build)
|
|
429
|
+
writes the manifest, the template's schema definitions and metadata under `schema/`,
|
|
430
|
+
shared `schema/base.json`, `tools/handlers.py`, and a starter verifier into a new or
|
|
431
|
+
empty directory. Supporting files must be flat regular `.json`, `.md`, or `.toml`
|
|
432
|
+
files; symlinks and collisions with shared `base.json` reject, and generated names
|
|
433
|
+
(`README.md`, `lock.json`, …) are not laid out. `api/`, `scenarios/`, `tests/` and
|
|
434
|
+
`ui/` copy verbatim to the world root, as do the carried `verifiers/`, `openapi/`,
|
|
435
|
+
`readers/`, `evidence/`, `reports/` and `tasks.json`; other directories reject.
|
|
436
|
+
Supporting bytes are preserved except Slack's `capabilities.json`, whose defaults
|
|
437
|
+
expand as described below. Descriptive metadata is not a compiler dependency or lock
|
|
438
|
+
input; referenced schemas are.
|
|
432
439
|
|
|
433
440
|
Initialization compiles the contract and writes a zero-mutation
|
|
434
441
|
`data/initial.json`, so the world starts empty and is filled by ingestion or
|
|
@@ -526,7 +533,7 @@ world back against the document it came from.
|
|
|
526
533
|
**Build from connector** for Slack creates a durable populated world job in
|
|
527
534
|
Gateway. Other registered source kinds show their CLI twin under **Use the CLI instead**:
|
|
528
535
|
`gateway worlds schema init`, `schema check`, then `gateway worlds create <slug> --from <dir>`.
|
|
529
|
-
A blank (custom) contract starts from the
|
|
536
|
+
A blank (custom) contract starts from the WorldHub page's **New connector** form. SDK template
|
|
530
537
|
availability does not register a platform source kind or supply a live mapper;
|
|
531
538
|
Teams remains schema-only. The SDK checks the contract before push, and the
|
|
532
539
|
shared publication validator checks actual stored bundle bytes before the world
|
|
@@ -576,7 +583,7 @@ remain exposed.
|
|
|
576
583
|
|
|
577
584
|
### Populated Slack worlds in Gateway
|
|
578
585
|
|
|
579
|
-
The
|
|
586
|
+
The WorldHub page offers synthetic data or selected public/private channels
|
|
580
587
|
from the caller's native Slack connection. Synthetic worlds include fictional
|
|
581
588
|
collaboration data and a graded scenario. Live jobs create a dedicated import,
|
|
582
589
|
read projected evidence, verify each artifact, map it through the shared store,
|
|
@@ -723,14 +730,13 @@ Revalidated during the merge of `ba89fe16` and `015d6b25` on 2026-09-07:
|
|
|
723
730
|
- `deploy/benchmark-runner/engines/{mock_tools_runner,session_server,api_runner,harbor_runner,verifiers_runner}.py`
|
|
724
731
|
- `gateway/packages/shared/src/domain/worldSchema.ts`
|
|
725
732
|
- `gateway/web/src/features/benchmark-hub/server/{worldSchemaPublication,containerVersionService}.ts`
|
|
726
|
-
- `gateway/worker/src/features/
|
|
733
|
+
- `gateway/worker/src/features/environmentOperator/{environmentBundleCompleteness,environmentBundleTester}.ts` (moved from `environmentBuild/` on 2026-10-13, when the builder and its workbench were deleted)
|
|
727
734
|
- `samples/schema-worlds/`
|
|
728
735
|
- `gateway/web/src/features/environment-files/{schemaWorldTemplates.ts,components/BuildSchemaWorldDialog.tsx}`
|
|
729
736
|
|
|
730
737
|
Additional sources: `gateway/packages/shared/src/server/services/worldSchemaRuntime.ts`
|
|
731
738
|
(template digest and trusted bridge), `gateway/web/src/features/environment-files/server/connectorWorldService.ts`
|
|
732
739
|
(durable job), `gatewaysdk/sdk/src/gatewaysdk/environment/schema/{slack,_slack_fidelity,platform}.py`,
|
|
733
|
-
`gateway/worker/src/features/environmentBuild/environmentSchemaSandbox.ts`,
|
|
734
740
|
`gateway/packages/shared/src/server/services/NativeSlackService.ts`, and
|
|
735
741
|
`deploy/benchmark-runner/engines/{session_server,schema_session}.py`.
|
|
736
742
|
|
|
@@ -140,6 +140,7 @@ gateway worlds data import <WORLD> rows.json --redact apply # run the w
|
|
|
140
140
|
gateway worlds data import <slug> export.jsonl -m "Q3 tenants" # platform: chunked upload, new version
|
|
141
141
|
gateway worlds data import <slug> export.jsonl --per-chunk --publish later --report refusals.jsonl
|
|
142
142
|
gateway worlds data import <slug> export.jsonl --resume # pick a dead upload back up
|
|
143
|
+
gateway worlds data import <slug> rows.jsonl --state q4-messy # into a world state only: no version, main untouched
|
|
143
144
|
gateway worlds data check <WORLD> rows.json --report refusals.jsonl # the dry run on its own; exit 2 on refusals
|
|
144
145
|
```
|
|
145
146
|
|
|
@@ -162,6 +163,7 @@ state}` and `gateway worlds data status <batchId> [--report <file>]` reads it la
|
|
|
162
163
|
published, 2 refused (the report is written when `--report` is given: JSONL of refusal
|
|
163
164
|
records, at most 10,000 then `{"truncated": true, "total": N}`), 1 error.
|
|
164
165
|
|
|
166
|
+
`--state <name>` lands the batch in that world state (`worlds state create` first): `published`, no `versionId`, `worldState` in the view; `worlds state show|pull` reads it on any version (`--ref`); `--rebase` rebuilds a state its rows cannot follow on main's data; `--publish later` is refused.
|
|
165
167
|
A manifest at `.gateway/imports/<batchId>.json` records every chunk's digest as it lands;
|
|
166
168
|
`--resume` reopens the newest incomplete batch for that slug and files and uploads only the
|
|
167
169
|
chunks the platform does not already hold. `--publish later` applies without a version;
|
|
@@ -178,7 +180,7 @@ refused row is a tool error naming the field, and nothing is written.
|
|
|
178
180
|
### 2a. Pull a connector's data through an active connection
|
|
179
181
|
|
|
180
182
|
For a schema world created from a connector template (`worlds create --from-connection`, or
|
|
181
|
-
the
|
|
183
|
+
the WorldHub page), the provider is the source — no rows file:
|
|
182
184
|
|
|
183
185
|
```bash
|
|
184
186
|
gateway worlds data pull <slug> --connection google_drive # connector slug when the project has one connection for it
|
|
@@ -194,7 +196,7 @@ contract like `data import`. `replace` (default) rebuilds the mapped entities fr
|
|
|
194
196
|
`pulled|unchanged <slug> from <connector> connection <id> (<mode>, <n> calls[, k unmatched (tool…)])
|
|
195
197
|
<hash> [entity=count …]`; `changed: false` in `--json` when the pull reproduced the tip (no new
|
|
196
198
|
version). The key reaches the connections shared with its project; a personal connection serves
|
|
197
|
-
its owner alone (the
|
|
199
|
+
its owner alone (the WorldHub page, or the MCP tool as that user) and is refused here. An
|
|
198
200
|
inactive connection, a world without a contract, or a template that does not read the connector
|
|
199
201
|
is a refusal (exit 1) and nothing is written; a provider failure is reported as
|
|
200
202
|
`provider tool failed (HTTP n)` with no provider body.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: worlds-getting-started
|
|
3
|
-
description: Starter guide for building worlds and environments on the platform, end to end, for an agent (Claude Code, Cursor, Codex). Use when starting a world from scratch, building a world or environment, mocking a vendor, importing a Swagger or OpenAPI spec into a world (schema init --from-openapi), choosing between
|
|
3
|
+
description: Starter guide for building worlds and environments on the platform, end to end, for an agent (Claude Code, Cursor, Codex). Use when starting a world from scratch, building a world or environment, mocking a vendor, importing a Swagger or OpenAPI spec into a world (schema init --from-openapi), choosing between an official template, a workspace connector, an OpenAPI document, a vendor API capture or a custom contract, provisioning worlds for tenants in one call (worlds create), publishing with bench push, opening a session, reading every request a world received (worlds requests), checks over those requests (journal checks on gateway_requests, calls, verify.py, SQL verifiers; task try before you save, task regrade of past runs), running and grading, or iterating with pull, fork, diff and edit sessions (worlds edit status/close/rollback: version control without PRs). Every CLI step names its MCP twin (list_connectors, publish_connector, create_world, init_world_from_connector, env_write_file, env_commit, import_world_data, run_evaluation and the rest) and where the result shows in the UI.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Worlds: getting started
|
|
@@ -55,7 +55,7 @@ first, then `guide({ topic: "connectors" })` for the connector loop and `guide({
|
|
|
55
55
|
`schema init` writes: `schema/world.json` (the contract), `gateway-env.toml` with `[schema]`,
|
|
56
56
|
and on top of it, optional, `tools/handlers.py` (tools, the `list_messages` style) and
|
|
57
57
|
`connector.toml` + `api/handlers.py` (the vendor's HTTP routes) with a `[ui]` section for the
|
|
58
|
-
page over those routes (every
|
|
58
|
+
page over those routes (every official template declares one; `schema compile` generates
|
|
59
59
|
`ui/static` from the contract, `gateway worlds schema ui init ./x` declares it for a world of
|
|
60
60
|
your own, `[ui] generated = false` keeps a hand-written page — the UI-twin templates such as
|
|
61
61
|
notion, servicenow and zendesk ship a built twin under `ui/static` that way). It is stored as it is, and
|
|
@@ -75,7 +75,7 @@ browser; the tools are always there). Everything else is derived or retired (own
|
|
|
75
75
|
|
|
76
76
|
| You have | Path | First command |
|
|
77
77
|
| --- | --- | --- |
|
|
78
|
-
| A vendor
|
|
78
|
+
| A vendor with an official template (`gateway worlds schema templates`: github, slack, salesforce, jira, linear, workday, netsuite, microsoft-teams, google-drive, google-calendar, jamf, kandji, apple-business-manager, …; fetched from the platform, so log in first) | official template | `gateway worlds schema init ./x --connector github` |
|
|
79
79
|
| A connector someone in your org (or any org) already published | workspace connector | `gateway worlds connector list --hub` then `schema init ./x --connector workspace:<slug>` |
|
|
80
80
|
| A Swagger 2.0 / OpenAPI 3.x document (JSON or YAML; a file, `drive:<path>` or a URL) | OpenAPI import | `gateway worlds schema init ./x --from-openapi petstore.yaml` — entities + routes from the spec, plan printed first; §2 "From an OpenAPI spec" |
|
|
81
81
|
| A vendor API with a dev key and no template | vendor API capture | `schema init ./x --connector custom`, write `connector.toml`, capture, ingest (`documentation/features/connector-worlds.md`) |
|
|
@@ -231,7 +231,7 @@ makes the world under a PAT session; under an API key it returns the initialized
|
|
|
231
231
|
For a world you provision rather than iterate on (a tenant's Slack, one per customer):
|
|
232
232
|
|
|
233
233
|
```bash
|
|
234
|
-
gateway worlds create acme-slack --from slack --rows rows.json --name "Acme Slack" #
|
|
234
|
+
gateway worlds create acme-slack --from slack --rows rows.json --name "Acme Slack" # official template + their rows
|
|
235
235
|
gateway worlds create acme-crm --from workspace:acme-crm --overlay ./overlay --json # hub connector + your edits
|
|
236
236
|
gateway worlds create acme-custom --from ./x # a directory, any kind
|
|
237
237
|
gateway worlds create acme-drive --from-connection google_drive # the connector's template filled from an active connection (id or slug); `--from <template>` picks the template
|
|
@@ -246,7 +246,7 @@ version, attributed to the key (`apikey:<id>`), owned by nobody. 409 when the sl
|
|
|
246
246
|
project. `--layout api-bundle` (body `layout`) packages the tree as its api bundle instead —
|
|
247
247
|
deprecated, and the answer's `deprecations` says so. A legacy tools bundle, a Harbor tree or a
|
|
248
248
|
verifiers package is a 400 `world_kind_retired`. `--from-connection` binds an active connection
|
|
249
|
-
(
|
|
249
|
+
(WorldHub page) shared with the key's project — a personal one serves its owner alone (MCP as
|
|
250
250
|
that user); an inactive connection or a template that does not read the connector is refused,
|
|
251
251
|
nothing created. Refresh later with `gateway worlds data pull <slug> --connection …`.
|
|
252
252
|
|
|
@@ -256,7 +256,7 @@ is the same request and answer; a PAT session reaches its own personal connectio
|
|
|
256
256
|
|
|
257
257
|
### Migrate a stored world: `worlds migrate`
|
|
258
258
|
|
|
259
|
-
The platform's connector worlds (the ones the
|
|
259
|
+
The platform's connector worlds (the ones the WorldHub page lists — containers created from
|
|
260
260
|
a template) that were stored as api bundles become schema trees again:
|
|
261
261
|
|
|
262
262
|
```bash
|
|
@@ -321,7 +321,7 @@ gateway worlds session state <SESSION_ID> # every entity's row
|
|
|
321
321
|
gateway worlds session reset <SESSION_ID> # back to the snapshot (+ the task's seed); `session restart <SESSION_ID> [--version <pin>]` does it on what its pin (x@ref; unpinned = newest you may read) points to NOW, same id, URLs + token, running or closed; a grade then reads only the requests after its session.restart ledger entry
|
|
322
322
|
gateway worlds session grade <SESSION_ID> [--timeout S] # {reward, rewards, raw}; exploratory → {reward: null, reason: "no grader"}
|
|
323
323
|
gateway worlds session export <SESSION_ID> --out calls.jsonl [--requests] # the platform's ledger; --requests adds the session's entries from the world's request ledger (kind "request": via, status, sizes; bodies by result.requestId), live or closed
|
|
324
|
-
gateway worlds requests x [--session <SESSION_ID>] [--via api|ui|tool|webhook] [--status 4xx] [--since 2026-10-05] [--json] # every request the world received (every session, version and door), newest first, kept for its life; reading records nothing; `requests show x <REQUEST_ID> [--out f]` adds headers + bodies, `session requests <SESSION_ID>` lists one session's (exit 3: its engine records no requests, only World Host sessions do)
|
|
324
|
+
gateway worlds requests x [--session <SESSION_ID>] [--via api|ui|tool|webhook|page] [--status 4xx] [--since 2026-10-05] [--json] # every request the world received (every session, version and door), newest first, kept for its life; reading records nothing; `requests show x <REQUEST_ID> [--out f]` adds headers + bodies, `session requests <SESSION_ID>` lists one session's (exit 3: its engine records no requests, only World Host sessions do)
|
|
325
325
|
gateway worlds data ingest x calls.jsonl --transform shape.py # the calls back in as rows, shaped by your code or --map ingest.toml (world-data-ingestion §2c)
|
|
326
326
|
gateway worlds session close <SESSION_ID> # a closed session reopens by id, same URLs + token, from its last checkpoint: gateway worlds session reopen <SESSION_ID>
|
|
327
327
|
```
|
|
@@ -16,12 +16,17 @@ Reference for `worlds-getting-started`: every CLI step and its MCP twin, then ho
|
|
|
16
16
|
| `worlds create <slug> --from … [--overlay] [--rows] [--batch] [--layout]` | `create_world` |
|
|
17
17
|
| `worlds migrate <slug> [--apply] [--force]` / `--all` | `migrate_world` |
|
|
18
18
|
| `bench push` | `env_write_file` + `env_commit`, or `create_environment_version` (one file) |
|
|
19
|
-
| `worlds data import` | `import_world_data` |
|
|
19
|
+
| `worlds data import [--state <name>]` | `import_world_data` (`worldState`: the rows land in that world state; main's data and versions do not move; the bulk lane is `request_data_upload` with `worldState`, refused with `publish: "later"`) |
|
|
20
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) |
|
|
21
|
+
| `worlds state list <world>` | `list_world_states({ slug })` (`GET /api/public/worlds/{slug}/states`): the world's states by name, each with its `bindings` and `dataSnapshotId` (null = the state opens on the version's own data). A world state is a named starting point: data plus knob values, opened on any version |
|
|
22
|
+
| `worlds state show <world> <name> [--ref <ref>]` | `get_world_state({ slug, name, ref? })` (`GET …/states/{name}?ref=`): how the state opens on that version (`opens`: `source` `version`\|`state`\|`carried`, `snapshot`, `bindings`, `fingerprint`), or why it does not (`refusal.code`: `state_knobs`, `state_not_carried`, `state_carrying`, `state_data_not_dispatched`); a world with no READY version answers `versionId`, `opens` and `refusal` null |
|
|
23
|
+
| `worlds state create <world> <name> [--description <text>] [--param <k=v>]… [--from-snapshot <id> \| --from-state <name>]` | `create_world_state({ slug, name, description?, bindings?, fromSnapshot?, fromState? })` (`POST …/states`, secret key, 201): answers what `show` answers on main, and a `refusal` there still means the state exists (the CLI prints it as `warning:` and exits 0); a taken name is 409 `state_exists`, both sources 400 |
|
|
24
|
+
| `worlds state delete <world> <name>` | `delete_world_state({ slug, name })` (`DELETE …/states/{name}`): `{ state, deleted: true, runCount }` |
|
|
25
|
+
| `worlds state pull <world> <name> [--ref <ref>] [--out <dir>] [--force]` | `pull_world_state({ slug, name, ref? })` (`GET …/states/{name}/pull`): `opens` plus `download` `{url, expiresAt}`, a signed GET (1 h) of the gzipped SQLite snapshot, null when the state opens on the version's own tree files; the MCP twin hands back the URL, the CLI downloads it into `state.json` + `state.sqlite` and checks the un-gzipped file against `opens.snapshot.sha256` |
|
|
21
26
|
| `worlds session open [-t\|--task-id\|--task-file]` (none: exploratory) / `status` / `call` / `close` / `list` / `pin` | none on the public MCP server — CLI or REST only (`/api/public/world-sessions[/{id}[/calls]]`; the open answers `idleExpiresAt` + `pinned`) |
|
|
22
27
|
| `worlds session seed` | `seed_world_session` |
|
|
23
28
|
| `worlds session export` | `export_world_session` |
|
|
24
|
-
| `worlds requests [list] <slug> [--session <id>] [--version <ref>] [--via api\|ui\|tool\|webhook] [--operation <name>] [--status 200\|2xx\|4xx\|5xx] [--since <time>] [--until <time>] [--limit N] [--cursor <c>] [--json]` | `list_world_requests({ slug, sessionId?, versionId?, via?, operation?, status?, since?, until?, cursor?, limit? })` (`GET /api/public/worlds/{slug}/requests`): every request the world received, from every session, version and door (`via` api, ui, tool, webhook), newest first, a page of at most 200 with `nextCursor`; metadata only (method, path, query, status, rows, found, duration, each body's size and `truncated`). The world keeps them for its life under the project's retention setting, and reading records nothing in any session's ledger. `--since`/`--until` take an ISO 8601 date or time (no zone is UTC); a bad filter is exit 2 before any request. UI: the world's Requests view, the session page's activity feed |
|
|
29
|
+
| `worlds requests [list] <slug> [--session <id>] [--version <ref>] [--via api\|ui\|tool\|webhook\|page] [--operation <name>] [--status 200\|2xx\|4xx\|5xx] [--since <time>] [--until <time>] [--limit N] [--cursor <c>] [--json]` | `list_world_requests({ slug, sessionId?, versionId?, via?, operation?, status?, since?, until?, cursor?, limit? })` (`GET /api/public/worlds/{slug}/requests`): every request the world received, from every session, version and door (`via` api, ui, tool, webhook, page), newest first, a page of at most 200 with `nextCursor`; metadata only (method, path, query, status, rows, found, duration, each body's size and `truncated`). The world keeps them for its life under the project's retention setting, and reading records nothing in any session's ledger. `--since`/`--until` take an ISO 8601 date or time (no zone is UTC); a bad filter is exit 2 before any request. UI: the world's Requests view, the session page's activity feed |
|
|
25
30
|
| `worlds requests show <slug> <requestId> [--json] [--out <file>]` | `get_world_request({ slug, requestId })` (`GET /api/public/worlds/{slug}/requests/{requestId}`): the request's headers (credentials `[redacted]`) and the first 64 KB of each body as text (`null` for a body that is not text; `bodyBytes` is the full size, `truncated` says it was cut); `--out` writes the whole entry as JSON. MCP only: the console agent's `get_world_request` is a different tool (it polls a world build) |
|
|
26
31
|
| `worlds session requests <sessionId>` (the list's filters but `--session`/`--version`) | `list_world_requests({ slug, sessionId })` (the CLI reads `GET /api/public/world-sessions/{id}/requests`, the world's list for one session; both MCP tools call the platform's `WorldRequestLedger` directly). A session whose engine is not the World Host records no requests: the route answers 409 `requests_not_recorded`, the CLI prints its one line and exits 3, and `session export --requests` notes the same line on stderr and writes the call log. `worlds requests <slug> --session <id>` and `list_world_requests({ slug, sessionId })` answer such a session the same way: 409, exit 3, the tool's error naming the engine |
|
|
27
32
|
| `worlds session webhooks <sessionId> [--json]` · `worlds session listen <sessionId> --forward-to <url> [--once] [--replay] [--interval-ms N] [--json]` | — (TypeScript CLI only). `webhooks` reads `GET /api/public/world-sessions/{id}/webhooks` (read key): the subscriptions the world's `[webhooks]` finds and how many deliveries each was sent, never a secret. `listen` polls `POST` the same route (secret key) and replays each delivery to `--forward-to` with its signed headers and exact body, then sends the receiver's status back, kept in the request ledger as `via: webhook` (`query.answer`), once per delivery; only deliveries sent from now unless `--replay`. A session on another engine: 409 `webhooks_not_served`, exit 1 |
|
|
@@ -48,6 +53,31 @@ Reference for `worlds-getting-started`: every CLI step and its MCP twin, then ho
|
|
|
48
53
|
| `worlds skill <name>` / `worlds connector skill` | `get_connector_authoring_skill`, `guide` |
|
|
49
54
|
| `worlds connector capture --remote` / poll + download | `start_connector_capture`, `get_connector_capture` (platform agent only) |
|
|
50
55
|
|
|
56
|
+
## Agents that build worlds (the agent SDK)
|
|
57
|
+
|
|
58
|
+
An agent (instructions, a model, the tool servers it may use: `sandbox`, `drive`, `web`, `docs`) runs on the
|
|
59
|
+
platform as your project key, in a thread per input; it builds worlds through the same CLI (`run_gateway_cli`) and
|
|
60
|
+
asks you through `ask_user`. Create it once and edit it live: every edit is a tracked version, live unless
|
|
61
|
+
`--no-deploy`, and a run keeps the version it was sent on. A key, not a personal token, drives all of these.
|
|
62
|
+
|
|
63
|
+
| CLI | MCP |
|
|
64
|
+
| --- | --- |
|
|
65
|
+
| `agents create <name> --instructions <text> [--model] [--effort] [--max-turns] [--tool <server[:tool,…]>]…` | `create_agent({ name, instructions, model?, effort?, maxTurns?, tools? })` |
|
|
66
|
+
| `agents update <name> [--instructions\|--model\|--effort\|--clear-effort\|--max-turns] [--from] [--no-deploy]`, `agents tools attach <name> <server[:tool,…]>…`, `agents tools detach <name> <server>…` | `edit_agent({ name, set?, attach?, detach?, from?, deploy? })` |
|
|
67
|
+
| `agents versions <name>` | `list_agent_versions({ name })` |
|
|
68
|
+
| `agents rollback <name> <versionId> [--force]` | `rollback_agent({ name, versionId, from?, force? })` |
|
|
69
|
+
| `agents push <file.mjs[#export]\|file.py[:attr]\|file.json> [--deploy]` | `push_agent_definition({ definition, deploy? })` |
|
|
70
|
+
| `agents deploy <name> <versionId> [--force]` | `deploy_agent_definition({ agent, versionId, force? })` |
|
|
71
|
+
| `threads create --agent <name> [--autonomy provisionWorlds=true …]` | `create_agent_thread({ agent, title?, autonomy? })` |
|
|
72
|
+
| `threads send <thread> <input> [--watch]`, `agents run <name> <input>` | `send_agent_message({ threadId, input, version? })` |
|
|
73
|
+
| `threads watch <thread> [--run] [--after <cursor>]` (exit 4: it waits for a person) | `get_agent_run({ threadId, runId, waitSeconds? })` |
|
|
74
|
+
| `threads resolve <thread> --action <id> --answer <text>` | `answer_agent_run({ threadId, runId, actionId, answer })` |
|
|
75
|
+
| `threads cancel <thread> [--run]` | `cancel_agent_run({ threadId, runId })` |
|
|
76
|
+
|
|
77
|
+
SDKs: `@withgateway/sdk` (`Gateway`, `tools`; `gateway.agents.create(...)` returns a live `Agent` with `update`,
|
|
78
|
+
`tools.attach|detach`, `versions`, `rollback`, `run`; `defineAgent` + `agents.push` for CI) and `gatewaysdk.agents`
|
|
79
|
+
(the same in snake_case).
|
|
80
|
+
|
|
51
81
|
## Size and time limits (one source: `packages/shared/src/world/limits.ts`)
|
|
52
82
|
|
|
53
83
|
Every door enforces the same number and names it in the refusal; the CLI checks the file
|
|
@@ -2,12 +2,12 @@
|
|
|
2
2
|
|
|
3
3
|
The things that bite once and never again, moved out of `SKILL.md` to keep it under 500 lines.
|
|
4
4
|
|
|
5
|
-
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
`
|
|
10
|
-
|
|
5
|
+
- Connector templates live on the platform as official worlds: `schema init ./x --connector salesforce`
|
|
6
|
+
fetches the template's current version (`GET /api/public/worlds/templates/salesforce`) and needs a login
|
|
7
|
+
(`gateway auth login` or the `GATEWAY_*` keys); without one it exits 2 and says so, and `schema templates`
|
|
8
|
+
lists `custom` alone with a note. Only `--connector custom` scaffolds offline. The platform agent's
|
|
9
|
+
`run_gateway_cli` has no platform credentials: open a sandbox from the template instead
|
|
10
|
+
(`sandbox open --new <slug> --from salesforce`). No `python3 >= 3.12`? The platform's runtime builds it.
|
|
11
11
|
- `bench push` and `worlds create --from ./x` store the tree as it is; nothing is repackaged into
|
|
12
12
|
an api-kind bundle on the way up. `worlds migrate` turns a bundle pushed before that back into
|
|
13
13
|
the tree. Either way, edit the schema world, not a bundle.
|
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
# Journal checks: verifiers over the requests a session's world received
|
|
2
2
|
|
|
3
3
|
A World Host session records every request its world receives, through every door: the api origin,
|
|
4
|
-
the page's `api_path` (ui) and a declared tool's call
|
|
4
|
+
the page's `api_path` (ui) and a declared tool's call; and, on a UI world, every interaction on its
|
|
5
|
+
page (page). Before a grade the platform waits until the
|
|
5
6
|
host has stored every request it holds for the session (the flush barrier), reads them back and
|
|
6
7
|
hands the grader those requests with whether they are all of them. Three ways to check them, one
|
|
7
8
|
implementation underneath: a declarative check, a `verify.py`, a SQL verifier.
|
|
@@ -26,7 +27,21 @@ as `not recorded`, whatever the grader accepts.
|
|
|
26
27
|
"contentType": "application/json" } }
|
|
27
28
|
```
|
|
28
29
|
|
|
29
|
-
- `via` is `api`, `ui` or `
|
|
30
|
+
- `via` is `api`, `ui`, `tool`, `webhook` or `page`; a tool call has no `method` or `path`.
|
|
31
|
+
- `page` is a UI world's page:
|
|
32
|
+
- **Operations:** `ui.click`, `ui.dblclick`, `ui.contextmenu`, `ui.hover`, `ui.change`, `ui.submit`, `ui.key`, `ui.copy`, `ui.cut`, `ui.paste`, `ui.drag`, `ui.drop`, `ui.file`, `ui.scroll`, `ui.visibility`, `ui.open` and `ui.navigate`. Each has no `method` and the page as its `path`.
|
|
33
|
+
- **The body:** `request.body` (`args` in `calls`) holds the `target`:
|
|
34
|
+
- `name`, `role`, `id`, `testid`, `selector`, `xpath`;
|
|
35
|
+
- `checked`, `expanded`, `pressed`, `selected`, `disabled`;
|
|
36
|
+
- `group` and `options` (a radio's legend and every option, a select's every option);
|
|
37
|
+
- `within` (the enclosing dialog or region) and `context` (the text of its row or card).
|
|
38
|
+
|
|
39
|
+
It also holds the `value`, a `point`, `files`, a drop's `source`, and the page load's `load` and `seq`; `load` and `seq` are in the entry's `query` too, so a journal read without bodies still shows a gap.
|
|
40
|
+
- **Who sees page rows:** only a check that names the page (`via: page`, a `ui.*` operation, or an `args.target.*` / `request.body.target.*` path). Every other check reads what it read before. SQL and python graders see page rows in `gateway_requests` and filter on `via`; before reading them, require one `ui.recording` row and no `ui.unrecorded` row (the host's notes, path `/`, one per UI session: a row count or a `path = '/'` match includes them).
|
|
41
|
+
- **When a check is ungraded:** if the grade has no journal (a cross-world `<alias>.calls` check, or a grade off the platform), if the journal does not show every life of the session recorded its pages (no `ui.recording`, which a World Host with the recorder writes when it first opens a UI session, or a `ui.unrecorded`, which a restore writes when the export it restores came from a host from before the recorder), if pages were served and none reported (a page that never ran the recorder), or if a page load's numbered interactions have a gap (a report lost). A check that names the page on a world with no ui is refused when the session opens.
|
|
42
|
+
- **What is recorded:** clicks and keys count only when trusted; an agent's `el.click()` by script is not a click. A value set by script still counts as a `ui.change`.
|
|
43
|
+
- **Trust:** an interaction is what the page reported. The session's token holder can send one without a browser.
|
|
44
|
+
- **Example** (picked High out of Low, Normal and High): `{"entity": "calls", "where": {"via": "page", "operation": "ui.change", "args.target.group": "Priority", "args.target.name": "High", "args.value": "true"}}`
|
|
30
45
|
- A JSON body reads as JSON, any other as text. Bodies are what the ledger stored: redacted when
|
|
31
46
|
captured, the first 64 KB (`truncated: true` past that). A request past the grade's budget (2,000
|
|
32
47
|
bodies, 8 MiB) carries `withheld: ["request.headers", "request.body", "response.body"]`.
|