@withgateway/sdk 0.2.4 → 0.2.6

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.
Files changed (85) hide show
  1. package/dist/cli.js +4304 -2381
  2. package/dist/cli.js.map +1 -1
  3. package/dist/cli.mjs +4266 -2343
  4. package/dist/cli.mjs.map +1 -1
  5. package/dist/files/index.js +56 -31
  6. package/dist/files/index.js.map +1 -1
  7. package/dist/files/index.mjs +52 -27
  8. package/dist/files/index.mjs.map +1 -1
  9. package/dist/hooks/index.d.mts +1 -1
  10. package/dist/hooks/index.d.ts +1 -1
  11. package/dist/hooks/index.js +280 -8
  12. package/dist/hooks/index.js.map +1 -1
  13. package/dist/hooks/index.mjs +272 -8
  14. package/dist/hooks/index.mjs.map +1 -1
  15. package/dist/{index-1xnxt0Cc.d.ts → index-BO2SNSgy.d.ts} +12 -1
  16. package/dist/{index-B0R3IgsV.d.mts → index-BaKu5ZSU.d.mts} +124 -2
  17. package/dist/{index-B0R3IgsV.d.ts → index-BaKu5ZSU.d.ts} +124 -2
  18. package/dist/{index-C1wDEwH4.d.mts → index-Cz8Q6Keo.d.mts} +12 -1
  19. package/dist/index.d.mts +4 -4
  20. package/dist/index.d.ts +4 -4
  21. package/dist/index.js +1100 -438
  22. package/dist/index.js.map +1 -1
  23. package/dist/index.mjs +1079 -424
  24. package/dist/index.mjs.map +1 -1
  25. package/dist/traces/index.js +45 -20
  26. package/dist/traces/index.js.map +1 -1
  27. package/dist/traces/index.mjs +41 -16
  28. package/dist/traces/index.mjs.map +1 -1
  29. package/dist/tracing/index.d.mts +1 -1
  30. package/dist/tracing/index.d.ts +1 -1
  31. package/dist/tracing/index.js +98 -61
  32. package/dist/tracing/index.js.map +1 -1
  33. package/dist/tracing/index.mjs +98 -61
  34. package/dist/tracing/index.mjs.map +1 -1
  35. package/dist/worlds/index.d.mts +179 -25
  36. package/dist/worlds/index.d.ts +179 -25
  37. package/dist/worlds/index.js +639 -284
  38. package/dist/worlds/index.js.map +1 -1
  39. package/dist/worlds/index.mjs +631 -276
  40. package/dist/worlds/index.mjs.map +1 -1
  41. package/package.json +2 -1
  42. package/runtime/gatewaysdk/environment/_bundle.py +15 -25
  43. package/runtime/gatewaysdk/environment/_materialize.py +53 -9
  44. package/runtime/gatewaysdk/environment/_toml.py +13 -0
  45. package/runtime/gatewaysdk/environment/schema/api.py +40 -25
  46. package/runtime/gatewaysdk/environment/schema/batch.py +15 -11
  47. package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +24 -0
  48. package/runtime/gatewaysdk/environment/schema/compiler.py +60 -28
  49. package/runtime/gatewaysdk/environment/schema/conform.py +1 -1
  50. package/runtime/gatewaysdk/environment/schema/connector.py +1 -1
  51. package/runtime/gatewaysdk/environment/schema/connectors/google-drive/readers/merge.ingest.toml +25 -0
  52. package/runtime/gatewaysdk/environment/schema/connectors/google-drive/readers/merge.toml +17 -0
  53. package/runtime/gatewaysdk/environment/schema/data.py +21 -19
  54. package/runtime/gatewaysdk/environment/schema/extract.py +1 -5
  55. package/runtime/gatewaysdk/environment/schema/grading.py +225 -0
  56. package/runtime/gatewaysdk/environment/schema/host.py +156 -546
  57. package/runtime/gatewaysdk/environment/schema/host_surfaces.py +1 -5
  58. package/runtime/gatewaysdk/environment/schema/ingest.py +3 -11
  59. package/runtime/gatewaysdk/environment/schema/local.py +32 -126
  60. package/runtime/gatewaysdk/environment/schema/mapping.py +1 -1
  61. package/runtime/gatewaysdk/environment/schema/platform.py +30 -26
  62. package/runtime/gatewaysdk/environment/schema/proof.py +237 -0
  63. package/runtime/gatewaysdk/environment/schema/redaction.py +1 -1
  64. package/runtime/gatewaysdk/environment/schema/runtime.py +686 -0
  65. package/runtime/gatewaysdk/environment/schema/scaffold.py +9 -2
  66. package/runtime/gatewaysdk/environment/schema/skill.py +1 -0
  67. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +67 -9
  68. package/runtime/gatewaysdk/environment/schema/skills/hooks-getting-started/SKILL.md +67 -6
  69. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +4 -1
  70. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +11 -11
  71. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +17 -1
  72. package/runtime/gatewaysdk/environment/schema/snapshot.py +1 -5
  73. package/runtime/gatewaysdk/environment/schema/tools_world.py +71 -23
  74. package/runtime/gatewaysdk/environment/schema/ui.py +1 -5
  75. package/runtime/gatewaysdk/environment/schema/verbs.py +136 -0
  76. package/runtime/gatewaysdk/environment/schema/workers.py +14 -0
  77. package/runtime/gatewaysdk/environment/schema/world_tests.py +1 -1
  78. package/runtime/gatewaysdk/environment/world.py +507 -0
  79. package/skills/benchmarks-getting-started/SKILL.md +67 -9
  80. package/skills/connector-schema-authoring/connector-worlds.md +8 -1
  81. package/skills/connector-schema-authoring/world-schema.md +1 -1
  82. package/skills/hooks-getting-started/SKILL.md +67 -6
  83. package/skills/world-data-ingestion/SKILL.md +4 -1
  84. package/skills/worlds-getting-started/SKILL.md +11 -11
  85. package/skills/worlds-getting-started/references/cli-mcp-map.md +17 -1
@@ -0,0 +1,136 @@
1
+ """The session protocol, once: every verb a world session answers, with the
2
+ method it takes and how its body is read. Both HTTP transports dispatch
3
+ through this table — the local session (``local.py``, ``/__session/<verb>``)
4
+ and the World Host control plane (``host.py``, ``/__host/sessions/<sid>/
5
+ <verb>``) — so the two cannot drift: a verb added here is served by both, a
6
+ body shape accepted here is accepted by both. The transports stay distinct
7
+ (loopback with no secret against a fleet with leases, workers and exports);
8
+ only the verbs are shared.
9
+
10
+ A verb marked ``hosted`` is the platform's rendezvous with a session it keeps
11
+ alive across hosts (the lease, the state export, DELETE as the platform's
12
+ close); the local session, which lives as long as the process serving it,
13
+ refuses them by name."""
14
+
15
+ from __future__ import annotations
16
+
17
+ from collections.abc import Callable
18
+ from dataclasses import dataclass
19
+ from typing import Any
20
+
21
+ from .redaction import parse_mode
22
+ from .validation import ContractError, fail
23
+
24
+
25
+ @dataclass(frozen=True)
26
+ class SessionVerb:
27
+ """One row of the protocol: ``method`` and ``name`` are the route (``name``
28
+ None addresses the session itself, as ``DELETE`` does); ``read`` turns the
29
+ request body into the keyword arguments the session operation takes, or
30
+ refuses the shape (a :class:`ContractError` the transport answers 400)."""
31
+
32
+ method: str
33
+ name: str | None
34
+ read: Callable[[dict], dict[str, Any]]
35
+ hosted: bool = False
36
+
37
+ @property
38
+ def route(self) -> str:
39
+ return f"{self.method} {self.name}" if self.name is not None else f"{self.method} <session>"
40
+
41
+ def matches(self, method: str, name: str | None) -> bool:
42
+ return self.method == method and self.name == (name or None)
43
+
44
+
45
+ def read_nothing(_body: dict) -> dict[str, Any]:
46
+ return {}
47
+
48
+
49
+ def read_seed(body: dict) -> dict[str, Any]:
50
+ """``{rows, mode, redact}``, the same under ``args`` (the platform wraps
51
+ the seed it forwards), or bare ``{entity: [row, ...]}`` — the shape a rows
52
+ file has — taken as the rows of an append."""
53
+ args = body["args"] if isinstance(body.get("args"), dict) else body
54
+ if "rows" not in args and "mode" not in args and args and all(isinstance(v, list) for v in args.values()):
55
+ args = {"rows": args}
56
+ rows = args.get("rows")
57
+ if not isinstance(rows, dict):
58
+ fail(
59
+ "host",
60
+ 'seed needs rows as {"rows": {entity: [row, ...]}, "mode": "append"|"replace"}; '
61
+ "a dependency's entity is named alias.entity",
62
+ )
63
+ mode = args.get("mode", "append")
64
+ if mode not in ("append", "replace"):
65
+ fail("host", 'seed mode must be "append" or "replace"', "/args/mode")
66
+ return {"rows": rows, "mode": mode, "redact": parse_mode(args.get("redact"), "/args/redact")}
67
+
68
+
69
+ def read_grade(body: dict) -> dict[str, Any]:
70
+ """``report`` is the agent's own account of the run, read by a rubric
71
+ judge or put beside the state for a deterministic grader; absent is fine,
72
+ anything but a string is not."""
73
+ report = body.get("report")
74
+ if report is not None and not isinstance(report, str):
75
+ fail("input", "report must be a string", "/report")
76
+ return {"report": report}
77
+
78
+
79
+ def read_call(body: dict) -> dict[str, Any]:
80
+ tool = body.get("tool")
81
+ if not isinstance(tool, str) or not tool:
82
+ fail("input", "tool must be a tool name (root) or alias.tool (a dependency's)", "/tool")
83
+ args = body.get("args") or {}
84
+ if not isinstance(args, dict):
85
+ fail("input", "args must be an object of the tool's arguments", "/args")
86
+ return {"tool": tool, "args": args}
87
+
88
+
89
+ def read_export(body: dict) -> dict[str, Any]:
90
+ known = body.get("knownSha256")
91
+ return {"known_sha256": known if isinstance(known, str) else None}
92
+
93
+
94
+ SESSION_VERBS: tuple[SessionVerb, ...] = (
95
+ SessionVerb("GET", "tools", read_nothing),
96
+ SessionVerb("GET", "task", read_nothing),
97
+ SessionVerb("GET", "state", read_nothing),
98
+ SessionVerb("POST", "grade", read_grade),
99
+ SessionVerb("POST", "reset", read_nothing),
100
+ SessionVerb("POST", "seed", read_seed),
101
+ SessionVerb("POST", "call", read_call),
102
+ SessionVerb("POST", "close", read_nothing),
103
+ SessionVerb("POST", "renew", read_nothing, hosted=True),
104
+ SessionVerb("POST", "export", read_export, hosted=True),
105
+ SessionVerb("DELETE", None, read_nothing, hosted=True),
106
+ )
107
+
108
+
109
+ def session_verb(method: str, name: str | None) -> SessionVerb | None:
110
+ return next((verb for verb in SESSION_VERBS if verb.matches(method, name)), None)
111
+
112
+
113
+ def served_verbs(*, hosted: bool) -> tuple[SessionVerb, ...]:
114
+ """The rows a transport answers: every one on the host, the session's own
115
+ (not the lease's) locally."""
116
+ return tuple(verb for verb in SESSION_VERBS if hosted or not verb.hosted)
117
+
118
+
119
+ def unknown_verb(method: str, name: str | None, *, hosted: bool, prefix: str) -> dict:
120
+ """The 404 body for a route off the table, naming what is on it. A hosted
121
+ verb sent to the local session is refused by name, not as unknown."""
122
+ verb = session_verb(method, name)
123
+ if verb is not None and verb.hosted and not hosted:
124
+ return {"error": f"{verb.route} is a hosted session's verb (the platform's lease); the local session has none"}
125
+ known = ", ".join(
126
+ f"{v.method} {prefix}{v.name}" if v.name else f"{v.method} {prefix.rstrip('/')}"
127
+ for v in served_verbs(hosted=hosted)
128
+ )
129
+ return {"error": f"unknown session route {method} {prefix}{name or ''}; one of {known}"}
130
+
131
+
132
+ def refusal(error: ContractError) -> dict:
133
+ """A refused call as the answer a session gives it: an unknown tool,
134
+ arguments off the schema, a tool outside the task's allow-list, a write the
135
+ store will not take, all ``{status: 400, body: {error, detail}}``."""
136
+ return {"status": 400, "body": {"error": error.detail.get("code", "host"), "detail": str(error)}}
@@ -51,6 +51,8 @@ from dataclasses import dataclass, field
51
51
  from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
52
52
  from pathlib import Path
53
53
 
54
+ from .grading import VerifierSandbox
55
+
54
56
  #: Address space a worker may use, in MiB, unless ``WORLDS_WORKER_MEMORY_MB`` says otherwise.
55
57
  DEFAULT_WORKER_MEMORY_MB = 2048
56
58
  #: Memory every worker together may use, in MiB, unless
@@ -281,6 +283,18 @@ def confined_command(script: Path, python: str = sys.executable) -> list[str]:
281
283
  return [python, "-c", _CONFINED_PRELUDE, str(script)]
282
284
 
283
285
 
286
+ class ConfinedVerifierSandbox(VerifierSandbox):
287
+ """How the host runs a task's ``verify.py``: confined like a worker, with a
288
+ scrubbed environment and a home under the session. World-authored code
289
+ sees no secret of this process, be it the host's or a worker's."""
290
+
291
+ def command(self, script: Path) -> list[str]:
292
+ return confined_command(script)
293
+
294
+ def environment(self, home: Path) -> dict[str, str]:
295
+ return verifier_environment(home=home)
296
+
297
+
284
298
  # --------------------------------------------------------------------------- #
285
299
  # The supervisor's side: start, reach and stop workers.
286
300
  # --------------------------------------------------------------------------- #
@@ -64,7 +64,6 @@ import shutil
64
64
  import subprocess
65
65
  import sys
66
66
  import tempfile
67
- import tomllib
68
67
  import urllib.error
69
68
  import urllib.parse
70
69
  import urllib.request
@@ -72,6 +71,7 @@ from dataclasses import asdict, dataclass, field
72
71
  from pathlib import Path
73
72
  from typing import Any
74
73
 
74
+ from .._toml import tomllib
75
75
  from .api import load_api_settings
76
76
  from .conform import PIN, _credentials
77
77
  from .connector import load_spec
@@ -0,0 +1,507 @@
1
+ """What a tree on disk IS, decided once.
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.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
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ import hashlib
19
+ import os
20
+ import re
21
+ from collections.abc import Callable, Iterator
22
+ from dataclasses import dataclass
23
+ from functools import cached_property
24
+ from pathlib import Path
25
+ from typing import ClassVar
26
+ from ._toml import tomllib
27
+
28
+ try: # optional: only consulted when a tree ships a root .gitignore
29
+ from gitignore_parser import parse_gitignore
30
+ except ImportError: # pragma: no cover - the runner and the sandbox vendor this module alone
31
+ parse_gitignore = None # type: ignore[assignment]
32
+
33
+ # ── Markers (twin of packages/shared/src/world/markers.ts) ──────────────────
34
+
35
+ WORLD_MANIFEST = "gateway-env.toml"
36
+ API_BUNDLE_MANIFEST = "gateway-api-world.toml"
37
+ BUNDLED_WORLD_PREFIX = "server/world/"
38
+ CONNECTOR_SPEC = "connector.toml"
39
+ PYPROJECT = "pyproject.toml"
40
+ WORLD_SCHEMA_MARKERS = ("schema/world.json", "schema/runtime.json", "schema/lock.json")
41
+ WORLD_ROOT_MARKERS = (CONNECTOR_SPEC, *WORLD_SCHEMA_MARKERS)
42
+ SCHEMA_MANIFEST_KIND = "schema"
43
+ SCHEMA_MANIFEST_KINDS = frozenset({SCHEMA_MANIFEST_KIND, "mock-tools"})
44
+
45
+ KIND_MOCK_TOOLS = "mock-tools"
46
+ KIND_API = "api"
47
+ KIND_HARBOR = "harbor"
48
+ KIND_VERIFIERS = "verifiers"
49
+ KIND_VERIFIERS_V1 = "verifiers-v1"
50
+
51
+ _SKIPPED_DIRS = frozenset({"dist", "build", "outputs", "__pycache__"})
52
+ # A root Gateway marker widens the hashed root from Prime's source globs to
53
+ # every ordinary root file: those kinds keep executable contract at the root.
54
+ _BROAD_ROOT_MARKERS = frozenset({WORLD_MANIFEST, API_BUNDLE_MANIFEST})
55
+ _HASH_CHUNK = 1 << 20
56
+ _HARBOR_TASK = re.compile(r"^(?:tasks/)?([^/]+)/task\.toml$")
57
+
58
+ # The `verifiers.v1` namespace first shipped in verifiers 0.2.0, so a v1
59
+ # package declares verifiers>=0.2 (or ~=0.2 / ==0.2.* / >=1 / ==1.*) in
60
+ # pyproject — minor >= 2 on the 0.x line or any major >= 1, never 0.0/0.1 —
61
+ # and/or imports the namespace or subclasses Taskset alongside the v1
62
+ # packaging convention of an ``__all__`` export (any library may name a class
63
+ # Taskset). A bare unversioned dependency or a pre-0.2 pin is v0.
64
+ _V1_DEP = re.compile(
65
+ r"""["']verifiers\s*(?:\[[^\]]*\])?\s*(?:>=|~=|==|>)\s*""" r"""(?:0\.(?:[2-9]\d*|[1-9]\d+)|[1-9]\d*)"""
66
+ )
67
+ _V1_IMPORT = re.compile(
68
+ r"^\s*(?:from\s+verifiers\.v1\s+import\b|from\s+verifiers\s+import\s+v1\b|import\s+verifiers\.v1\b)",
69
+ re.MULTILINE,
70
+ )
71
+ _V1_TASKSET = re.compile(r"class\s+\w+\s*\(\s*(?:(?:vf|v1|verifiers(?:\.v1)?)\.)?Taskset\s*[,)]")
72
+
73
+
74
+ def _present(path: Path) -> bool:
75
+ """A file exists — or a symlink to one is dangling: a broken authority
76
+ must fail loudly downstream, never quietly downgrade the tree."""
77
+ return path.is_file() or path.is_symlink()
78
+
79
+
80
+ def _skipped_dir(name: str) -> bool:
81
+ return name.startswith(".") or name in _SKIPPED_DIRS or name.endswith(".egg-info")
82
+
83
+
84
+ def _ordinary_root_file(name: str, broad: bool) -> bool:
85
+ return broad or name in ("README.md", PYPROJECT) or name in _BROAD_ROOT_MARKERS or name.endswith(".py")
86
+
87
+
88
+ def is_hashed_path(relative: str, broad_root: bool) -> bool:
89
+ """Twin of ``worldTree.ts isHashedPath``: the path-only half of the archive
90
+ rule (hidden names, pruned directories, the root globs)."""
91
+ parts = relative.split("/")
92
+ name = parts[-1]
93
+ if name.startswith(".") or "__pycache__" in parts:
94
+ return False
95
+ directories = parts[:-1]
96
+ if not directories:
97
+ return _ordinary_root_file(name, broad_root)
98
+ return not any(_skipped_dir(component) for component in directories)
99
+
100
+
101
+ def _gitignore_matcher(root: Path) -> Callable[[str], bool] | None:
102
+ gitignore = root / ".gitignore"
103
+ if not gitignore.exists():
104
+ return None
105
+ if parse_gitignore is None:
106
+ raise RuntimeError(
107
+ "A .gitignore is present but 'gitignore_parser' is not installed. Install it (a declared "
108
+ "dependency of gatewaysdk) so the content hash stays compatible with the hub."
109
+ )
110
+ return parse_gitignore(str(gitignore), base_dir=str(root))
111
+
112
+
113
+ def pyproject_pins_v1(path: str, text: str) -> bool:
114
+ if path != PYPROJECT:
115
+ return False
116
+ return _V1_DEP.search(text) is not None
117
+
118
+
119
+ def module_uses_v1(path: str, text: str) -> bool:
120
+ if not path.endswith(".py"):
121
+ return False
122
+ return bool(_V1_IMPORT.search(text)) or ("__all__" in text and bool(_V1_TASKSET.search(text)))
123
+
124
+
125
+ class WorldManifest:
126
+ """A world's ``gateway-env.toml``, parsed once. An absent manifest and an
127
+ unparsable one are both manifests: ``present`` and ``error`` say which,
128
+ and every accessor answers "declares nothing" for them."""
129
+
130
+ def __init__(self, text: str | None, root: dict | None, error: str | None) -> None:
131
+ self.text = text
132
+ self._root = root
133
+ self.error = error
134
+
135
+ ABSENT: ClassVar[WorldManifest]
136
+
137
+ @staticmethod
138
+ def parse(text: str) -> WorldManifest:
139
+ try:
140
+ return WorldManifest(text, tomllib.loads(text), None)
141
+ except tomllib.TOMLDecodeError as error:
142
+ return WorldManifest(text, None, f"{WORLD_MANIFEST} is invalid TOML: {error}")
143
+
144
+ @property
145
+ def present(self) -> bool:
146
+ return self.text is not None
147
+
148
+ @property
149
+ def invalid(self) -> bool:
150
+ return self.present and self._root is None
151
+
152
+ def table(self, name: str) -> dict | None:
153
+ value = (self._root or {}).get(name)
154
+ return value if isinstance(value, dict) else None
155
+
156
+ def has(self, name: str) -> bool:
157
+ return self._root is not None and name in self._root
158
+
159
+ @property
160
+ def environment(self) -> dict | None:
161
+ if self._root is None:
162
+ return None
163
+ if self.has("environment"):
164
+ return self.table("environment")
165
+ value = self._root.get("env", {})
166
+ return value if isinstance(value, dict) else None
167
+
168
+ @property
169
+ def kind(self) -> object:
170
+ env = self.environment
171
+ return None if env is None else env.get("kind")
172
+
173
+ @property
174
+ def declares_schema(self) -> bool:
175
+ return self.has("schema")
176
+
177
+
178
+ WorldManifest.ABSENT = WorldManifest(None, None, None)
179
+
180
+
181
+ @dataclass(frozen=True)
182
+ class WorldTree:
183
+ """A tree on disk and where the authored world lives inside it. Immutable;
184
+ the root decision is made once at construction."""
185
+
186
+ root: Path
187
+ world_root: str
188
+
189
+ @classmethod
190
+ def from_dir(cls, root: str | os.PathLike[str]) -> WorldTree:
191
+ root = Path(root)
192
+ nested = root / BUNDLED_WORLD_PREFIX
193
+ bundled = _present(root / API_BUNDLE_MANIFEST) and any(
194
+ _present(nested / marker) for marker in WORLD_ROOT_MARKERS
195
+ )
196
+ return cls(root, BUNDLED_WORLD_PREFIX if bundled else "")
197
+
198
+ def has(self, relative: str) -> bool:
199
+ return _present(self.root / relative)
200
+
201
+ def world_path(self, relative: str) -> str:
202
+ return self.world_root + relative
203
+
204
+ @property
205
+ def world(self) -> Path:
206
+ """The authored world's directory."""
207
+ return self.root / self.world_root if self.world_root else self.root
208
+
209
+ @property
210
+ def is_api_bundle(self) -> bool:
211
+ return self.has(API_BUNDLE_MANIFEST)
212
+
213
+ @property
214
+ def has_schema_marker(self) -> bool:
215
+ return any(self.has(self.world_path(marker)) for marker in WORLD_SCHEMA_MARKERS)
216
+
217
+ @property
218
+ def has_connector(self) -> bool:
219
+ return self.has(self.world_path(CONNECTOR_SPEC))
220
+
221
+ # ── The archive: the file set a version IS ───────────────────────────────
222
+ #
223
+ # Vendored from Prime Intellect's ``prime`` CLI (MIT; THIRD_PARTY_LICENSES)
224
+ # so a container hashed here resolves to the same logical version on their
225
+ # Environments Hub: SHA-256 over ``file:<relpath>`` + raw bytes, in sorted
226
+ # path order, over README.md / pyproject.toml / *.py at the root plus every
227
+ # non-hidden nested file outside dist, build, outputs, __pycache__ and
228
+ # *.egg-info. A root Gateway marker widens the root to every ordinary file
229
+ # (the marker itself must be hashed or a manifest-only edit dedups into the
230
+ # previous version and is silently discarded). Symlinks and ``.gitignore``-d
231
+ # paths are dropped. This is the version primary key, NOT a tarball digest.
232
+ # Twin: ``packages/shared/src/world/worldTree.ts`` (``isHashedPath`` +
233
+ # ``contentHash``); the corpus under ``conformance/worlds/`` pins both.
234
+
235
+ @property
236
+ def broad_root(self) -> bool:
237
+ return any(self.has(marker) for marker in _BROAD_ROOT_MARKERS)
238
+
239
+ def archive_files(self) -> list[Path]:
240
+ """The hashed files, absolute, in sorted relative-path order."""
241
+ ignored = _gitignore_matcher(self.root)
242
+ broad = self.broad_root
243
+ found: dict[str, Path] = {}
244
+
245
+ def keep(path: Path) -> None:
246
+ if not path.is_file() or path.is_symlink():
247
+ return
248
+ relative = path.relative_to(self.root).as_posix()
249
+ if not is_hashed_path(relative, broad):
250
+ return
251
+ if ignored is not None and ignored(str(path)):
252
+ return
253
+ found[relative] = path
254
+
255
+ def pruned(directory: Path) -> bool:
256
+ """A symlinked directory is not part of the tree: it can point anywhere."""
257
+ return (
258
+ directory.is_symlink()
259
+ or _skipped_dir(directory.name)
260
+ or (ignored is not None and ignored(str(directory)))
261
+ )
262
+
263
+ for entry in sorted(self.root.iterdir(), key=lambda p: p.name):
264
+ if entry.is_file():
265
+ keep(entry)
266
+ continue
267
+ if not entry.is_dir() or pruned(entry):
268
+ continue
269
+ for dirpath, dirnames, filenames in os.walk(entry):
270
+ here = Path(dirpath)
271
+ dirnames[:] = sorted(name for name in dirnames if not pruned(here / name))
272
+ for filename in sorted(filenames):
273
+ keep(here / filename)
274
+ return [found[relative] for relative in sorted(found)]
275
+
276
+ def hashed_paths(self) -> list[str]:
277
+ return [path.relative_to(self.root).as_posix() for path in self.archive_files()]
278
+
279
+ @property
280
+ def content_hash(self) -> str:
281
+ """Streams every file; a large tree never has to fit in memory.
282
+
283
+ An unreadable file raises: a digest that silently omitted it would
284
+ name a tree the manifest and archive do not describe.
285
+ """
286
+ digest = hashlib.sha256()
287
+ for path in self.archive_files():
288
+ relative = path.relative_to(self.root).as_posix()
289
+ digest.update(f"file:{relative}".encode("utf-8"))
290
+ try:
291
+ with open(path, "rb") as handle:
292
+ for chunk in iter(lambda: handle.read(_HASH_CHUNK), b""):
293
+ digest.update(chunk)
294
+ except OSError as error:
295
+ raise OSError(f"cannot read {relative} while hashing the tree: {error}") from error
296
+ return digest.hexdigest()
297
+
298
+ @cached_property
299
+ def manifest(self) -> WorldManifest:
300
+ path = self.world / WORLD_MANIFEST
301
+ if not _present(path):
302
+ return WorldManifest.ABSENT
303
+ try:
304
+ return WorldManifest.parse(path.read_text(encoding="utf-8"))
305
+ except (OSError, UnicodeDecodeError) as error:
306
+ return WorldManifest("", None, f"cannot read {WORLD_MANIFEST}: {error}")
307
+
308
+ def harbor_task_names(self) -> list[str]:
309
+ names = set()
310
+ for pattern in ("tasks/*/task.toml", "*/task.toml"):
311
+ for path in self.root.glob(pattern):
312
+ match = _HARBOR_TASK.match(path.relative_to(self.root).as_posix())
313
+ if match:
314
+ names.add(match.group(1))
315
+ return sorted(names)
316
+
317
+ def scenario_names(self) -> list[str]:
318
+ return sorted(path.parent.name for path in self.root.glob("scenarios/*/scenario.toml") if path.is_file())
319
+
320
+ def v1_evidence(self) -> Iterator[tuple[str, str]]:
321
+ """``(relpath, text)`` of the files a verifiers package's API version is
322
+ read from: the root pyproject and every ``.py`` the archive rules keep
323
+ (``archive_files``: no hidden, build, dist, outputs, pycache or egg-info
324
+ directories)."""
325
+ for dirpath, dirnames, filenames in os.walk(self.root):
326
+ dirnames[:] = sorted(name for name in dirnames if not _skipped_dir(name))
327
+ for filename in sorted(filenames):
328
+ path = Path(dirpath) / filename
329
+ relative = path.relative_to(self.root).as_posix()
330
+ if filename.startswith(".") or not (relative == PYPROJECT or filename.endswith(".py")):
331
+ continue
332
+ try:
333
+ yield relative, path.read_text(encoding="utf-8", errors="replace")
334
+ except OSError:
335
+ continue
336
+
337
+
338
+ class World:
339
+ """What a tree is, and what that means for the paths that touch it.
340
+ Construct through ``World.from_tree`` / ``World.from_dir`` only."""
341
+
342
+ kind: str
343
+ shape: str
344
+
345
+ def __init__(self, tree: WorldTree) -> None:
346
+ self.tree = tree
347
+
348
+ @staticmethod
349
+ def from_tree(tree: WorldTree) -> World:
350
+ if tree.is_api_bundle:
351
+ return ApiBundle(tree)
352
+ if tree.has(WORLD_MANIFEST):
353
+ schema = tree.has_schema_marker or tree.manifest.declares_schema
354
+ return SchemaWorld(tree) if schema else ToolsWorld(tree)
355
+ if tree.harbor_task_names():
356
+ return HarborBench(tree)
357
+ v1 = VerifiersBench.is_v1(tree)
358
+ if v1 or tree.has(PYPROJECT):
359
+ return VerifiersBench(tree, v1)
360
+ return PlainTree(tree)
361
+
362
+ @staticmethod
363
+ def from_dir(root: str | os.PathLike[str]) -> World:
364
+ return World.from_tree(WorldTree.from_dir(root))
365
+
366
+ @property
367
+ def reported_kind(self) -> str:
368
+ """What ``worlds create|describe|list`` and the data commands report."""
369
+ return self.kind
370
+
371
+ @property
372
+ def runner_engine(self) -> str:
373
+ return "openai-compatible"
374
+
375
+ @property
376
+ def substrate(self) -> str:
377
+ """Hosted on the World Host, or executed by the benchmark runner."""
378
+ return "world"
379
+
380
+ @property
381
+ def tools_engine(self) -> bool:
382
+ """Runs on the tools engine: handlers over a per-session SQLite."""
383
+ return False
384
+
385
+ @property
386
+ def local_runtime(self) -> bool:
387
+ """``gwenv`` can run the tree in-process."""
388
+ return True
389
+
390
+ def task_names(self) -> list[str]:
391
+ """The tasks the tree defines by layout; a schema world's live in
392
+ its manifest."""
393
+ return []
394
+
395
+ @property
396
+ def schema_mode(self) -> str:
397
+ """``schema`` (a compiled marker or a declared ``[schema]``),
398
+ ``invalid`` (a manifest that does not parse) or ``legacy``."""
399
+ if self.tree.has_schema_marker:
400
+ return "schema"
401
+ if self.tree.manifest.invalid:
402
+ return "invalid"
403
+ return "schema" if self.tree.manifest.declares_schema else "legacy"
404
+
405
+ @property
406
+ def is_schema(self) -> bool:
407
+ return self.schema_mode == "schema"
408
+
409
+
410
+ class SchemaWorld(World):
411
+ """A gateway-world/1 contract tree stored as itself."""
412
+
413
+ kind = KIND_MOCK_TOOLS
414
+ shape = "schema"
415
+
416
+ @property
417
+ def reported_kind(self) -> str:
418
+ return SCHEMA_MANIFEST_KIND
419
+
420
+ @property
421
+ def tools_engine(self) -> bool:
422
+ return True
423
+
424
+
425
+ class ToolsWorld(World):
426
+ """``gateway-env.toml`` + ``db/schema.sql`` + handlers, no contract."""
427
+
428
+ kind = KIND_MOCK_TOOLS
429
+ shape = "legacy-tools"
430
+
431
+ @property
432
+ def tools_engine(self) -> bool:
433
+ return True
434
+
435
+
436
+ class ApiBundle(World):
437
+ """A world packaged with ``gateway-api-world.toml`` over ``server/world/``."""
438
+
439
+ kind = KIND_API
440
+ shape = "api-bundle"
441
+
442
+ def task_names(self) -> list[str]:
443
+ return self.tree.scenario_names()
444
+
445
+
446
+ class ContainerBench(World):
447
+ @property
448
+ def substrate(self) -> str:
449
+ return "container"
450
+
451
+
452
+ class HarborBench(ContainerBench):
453
+ """``<task>/task.toml`` or ``tasks/<task>/task.toml`` directories."""
454
+
455
+ kind = KIND_HARBOR
456
+ shape = "harbor"
457
+
458
+ @property
459
+ def runner_engine(self) -> str:
460
+ return "harbor"
461
+
462
+ def task_names(self) -> list[str]:
463
+ return self.tree.harbor_task_names()
464
+
465
+
466
+ class VerifiersBench(ContainerBench):
467
+ """A Python package the runner installs and grades with reward functions."""
468
+
469
+ shape = "verifiers"
470
+
471
+ def __init__(self, tree: WorldTree, v1: bool = False) -> None:
472
+ super().__init__(tree)
473
+ self.kind = KIND_VERIFIERS_V1 if v1 else KIND_VERIFIERS
474
+
475
+ @staticmethod
476
+ def is_v1(tree: WorldTree) -> bool:
477
+ return any(pyproject_pins_v1(path, text) or module_uses_v1(path, text) for path, text in tree.v1_evidence())
478
+
479
+ @property
480
+ def local_runtime(self) -> bool:
481
+ return False
482
+
483
+
484
+ class PlainTree(VerifiersBench):
485
+ """No Gateway marker, no harbor task, no Python package: not yet a world
486
+ and not a benchmark. The runner's fallback reads it as a verifiers
487
+ package, so that is the kind it answers."""
488
+
489
+
490
+ __all__ = [
491
+ "API_BUNDLE_MANIFEST",
492
+ "BUNDLED_WORLD_PREFIX",
493
+ "CONNECTOR_SPEC",
494
+ "PYPROJECT",
495
+ "WORLD_MANIFEST",
496
+ "WORLD_ROOT_MARKERS",
497
+ "WORLD_SCHEMA_MARKERS",
498
+ "ApiBundle",
499
+ "HarborBench",
500
+ "PlainTree",
501
+ "SchemaWorld",
502
+ "ToolsWorld",
503
+ "VerifiersBench",
504
+ "World",
505
+ "WorldManifest",
506
+ "WorldTree",
507
+ ]