@withgateway/sdk 0.2.3 → 0.2.5

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 (62) hide show
  1. package/dist/cli.js +13267 -5869
  2. package/dist/cli.js.map +1 -1
  3. package/dist/cli.mjs +13272 -5874
  4. package/dist/cli.mjs.map +1 -1
  5. package/dist/files/index.js +83 -31
  6. package/dist/files/index.js.map +1 -1
  7. package/dist/files/index.mjs +79 -28
  8. package/dist/files/index.mjs.map +1 -1
  9. package/dist/hooks/index.d.mts +1 -0
  10. package/dist/hooks/index.d.ts +1 -0
  11. package/dist/hooks/index.js +4355 -0
  12. package/dist/hooks/index.js.map +1 -0
  13. package/dist/hooks/index.mjs +4243 -0
  14. package/dist/hooks/index.mjs.map +1 -0
  15. package/dist/{index-Dpo-t8iO.d.ts → index-1xnxt0Cc.d.ts} +58 -2
  16. package/dist/index-B0R3IgsV.d.mts +1279 -0
  17. package/dist/index-B0R3IgsV.d.ts +1279 -0
  18. package/dist/{index-B5HUQQDE.d.mts → index-C1wDEwH4.d.mts} +58 -2
  19. package/dist/index.d.mts +4 -3
  20. package/dist/index.d.ts +4 -3
  21. package/dist/index.js +6698 -1606
  22. package/dist/index.js.map +1 -1
  23. package/dist/index.mjs +6793 -1713
  24. package/dist/index.mjs.map +1 -1
  25. package/dist/traces/index.js +72 -20
  26. package/dist/traces/index.js.map +1 -1
  27. package/dist/traces/index.mjs +68 -17
  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 +47 -3
  32. package/dist/tracing/index.js.map +1 -1
  33. package/dist/tracing/index.mjs +42 -2
  34. package/dist/tracing/index.mjs.map +1 -1
  35. package/dist/worlds/index.d.mts +390 -27
  36. package/dist/worlds/index.d.ts +390 -27
  37. package/dist/worlds/index.js +2291 -366
  38. package/dist/worlds/index.js.map +1 -1
  39. package/dist/worlds/index.mjs +2281 -356
  40. package/dist/worlds/index.mjs.map +1 -1
  41. package/package.json +7 -1
  42. package/runtime/gatewaysdk/environment/_bundle.py +14 -24
  43. package/runtime/gatewaysdk/environment/_materialize.py +3 -3
  44. package/runtime/gatewaysdk/environment/schema/api.py +153 -20
  45. package/runtime/gatewaysdk/environment/schema/compiler.py +14 -0
  46. package/runtime/gatewaysdk/environment/schema/data.py +21 -19
  47. package/runtime/gatewaysdk/environment/schema/grading.py +225 -0
  48. package/runtime/gatewaysdk/environment/schema/host.py +171 -535
  49. package/runtime/gatewaysdk/environment/schema/ingest.py +3 -11
  50. package/runtime/gatewaysdk/environment/schema/local.py +32 -126
  51. package/runtime/gatewaysdk/environment/schema/platform.py +14 -22
  52. package/runtime/gatewaysdk/environment/schema/proof.py +237 -0
  53. package/runtime/gatewaysdk/environment/schema/runtime.py +686 -0
  54. package/runtime/gatewaysdk/environment/schema/skill.py +1 -0
  55. package/runtime/gatewaysdk/environment/schema/skills/hooks-getting-started/SKILL.md +156 -0
  56. package/runtime/gatewaysdk/environment/schema/snapshot.py +6 -5
  57. package/runtime/gatewaysdk/environment/schema/tasks.py +12 -2
  58. package/runtime/gatewaysdk/environment/schema/tools_world.py +75 -23
  59. package/runtime/gatewaysdk/environment/schema/verbs.py +136 -0
  60. package/runtime/gatewaysdk/environment/schema/workers.py +44 -13
  61. package/runtime/gatewaysdk/environment/world.py +391 -0
  62. package/skills/hooks-getting-started/SKILL.md +156 -0
@@ -0,0 +1,686 @@
1
+ """The one engine a session runs on. :class:`WorldRuntime` is what the World
2
+ Host holds for a session opened in its process: the store, the task's
3
+ starting state, the HTTP surface when the tree declares one, and every
4
+ control verb (reset, seed, state, grade, call, export, restore, close). The
5
+ host asks the runtime; it never asks what shape the version was stored as.
6
+
7
+ Two runtimes exist because two stored shapes still do:
8
+
9
+ - :class:`TreeRuntime` — a schema world stored as itself (``gateway-env.toml``
10
+ with a ``[schema]`` table): a copy of the version's materialized template,
11
+ executed through its handlers, beside a copy of each dependency world, its
12
+ routes (``connector.toml``) over the same store. This is the runtime every
13
+ new push opens on.
14
+ - :class:`SnapshotRuntime` — an api bundle (``gateway-api-world.toml`` over
15
+ ``server/world``): a clone of the version's compiled snapshot behind its
16
+ routes. **READ PATH, marked for deletion**: it exists so the worlds the
17
+ platform already stores as bundles keep opening until the migration
18
+ (handoff step 5) has rewritten them as schema worlds; nothing new is
19
+ stored in this shape. Delete it, ``CachedVersion.snapshot`` and the
20
+ api-bundle arm of ``VersionCache._build`` together (step 6).
21
+
22
+ The shape is chosen once, in :meth:`WorldRuntime.open`, from what the version
23
+ cache loaded; from there the host sees one interface."""
24
+
25
+ from __future__ import annotations
26
+
27
+ import fcntl
28
+ import json
29
+ import shutil
30
+ import uuid
31
+ from abc import ABC, abstractmethod
32
+ from collections.abc import Callable, Iterable
33
+ from pathlib import Path
34
+ from typing import TYPE_CHECKING, Any, Optional
35
+
36
+ from . import snapshot as snapshots
37
+ from .api import WorldApp, WorldState, operation_request, vendor_credential, with_query
38
+ from .dependencies import Dependency
39
+ from .grading import Grade, GraderError, TaskGrader
40
+ from .snapshot import SCENARIOS
41
+ from .tasks import TASK_DIR, TaskSpec, unknown_task_entities, write_task_dir
42
+ from .tools_world import DependencyWorld, ToolsWorld, ToolsWorldState, inline_task, served_with_dependencies
43
+ from .validation import fail
44
+ from .workers import ConfinedVerifierSandbox
45
+
46
+ if TYPE_CHECKING:
47
+ from .host import CachedVersion
48
+
49
+ #: The token an api world is handed when the session was opened without one:
50
+ #: the router still authorizes by it, so the host's own calls carry it.
51
+ WORLD_AUTH_SENTINEL = "gateway-session"
52
+
53
+ Restorer = Callable[[Callable[[Path], None]], bool]
54
+
55
+
56
+ class WorldRuntime(ABC):
57
+ """One session's world, in process. Built by :meth:`open`; the host keeps
58
+ it on the session and calls nothing else of the world's."""
59
+
60
+ def __init__(
61
+ self,
62
+ cached: CachedVersion,
63
+ session_dir: Path,
64
+ *,
65
+ task: str | None,
66
+ spec: TaskSpec | None,
67
+ token: str | None,
68
+ ) -> None:
69
+ self.cached = cached
70
+ self.session_dir = Path(session_dir)
71
+ self.task = task
72
+ self.task_spec = spec
73
+ self.token = token
74
+ #: The routes of connector.toml over the session's store, when the
75
+ #: tree declares any; None for a world of tools alone.
76
+ self.app: WorldApp | None = None
77
+ #: An ``oauth2`` world's client-credentials grant the host minted for
78
+ #: itself, so a caller the session token admits is presented to the
79
+ #: world as a granted client.
80
+ self.grant: str | None = None
81
+ self.restored = False
82
+
83
+ # -- what the shape knows before a session opens ------------------------ #
84
+
85
+ @classmethod
86
+ @abstractmethod
87
+ def served_by(cls, cached: CachedVersion, dependencies: dict[str, DependencyWorld]) -> list[str]:
88
+ """Every name a session task on ``cached`` may allow."""
89
+
90
+ @classmethod
91
+ @abstractmethod
92
+ def authored_code(cls, cached: CachedVersion) -> str | None:
93
+ """What world-authored code ``cached`` runs (so only a worker may open
94
+ it), None when it runs none."""
95
+
96
+ @classmethod
97
+ def declared_dependencies(cls, cached: CachedVersion) -> dict[str, Dependency]:
98
+ """The ``[dependencies]`` the version's manifest declares, by alias."""
99
+ return {}
100
+
101
+ # -- construction ------------------------------------------------------ #
102
+
103
+ @classmethod
104
+ def open(
105
+ cls,
106
+ cached: CachedVersion,
107
+ session_dir: Path,
108
+ *,
109
+ task: str | None,
110
+ spec: TaskSpec | None,
111
+ token: str | None,
112
+ dependencies: dict[str, DependencyWorld],
113
+ restore: Restorer,
114
+ ) -> WorldRuntime:
115
+ """The runtime for ``cached``, started in its task's state, an export
116
+ restored into it when the platform names one, its HTTP surface
117
+ attached. A start that fails leaves no session directory behind."""
118
+ runtime = cached.runtime_class(cached, session_dir, task=task, spec=spec, token=token)
119
+ runtime._start(dependencies)
120
+ try:
121
+ if spec is not None:
122
+ runtime._check_task_entities(spec)
123
+ # Under the session, where a grade and a restart find the task.
124
+ write_task_dir(spec, runtime.session_dir)
125
+ runtime._to_start()
126
+ runtime.restored = restore(runtime.restore)
127
+ runtime._attach_app()
128
+ except BaseException:
129
+ runtime.close()
130
+ raise
131
+ return runtime
132
+
133
+ def _attach_app(self) -> None:
134
+ cached = self.cached
135
+ if cached.spec is None:
136
+ return
137
+ # ``handlers={}`` for a code-free world: WorldApp would otherwise
138
+ # import the module itself, and only a worker may do that.
139
+ self.app = WorldApp(
140
+ self._app_state(),
141
+ cached.router(),
142
+ self.token,
143
+ handlers=cached.handlers or {},
144
+ allowed=self.allowed,
145
+ )
146
+ self.grant = client_grant(self.app, self.token)
147
+
148
+ @property
149
+ def allowed(self) -> frozenset[str] | None:
150
+ spec = self.task_spec
151
+ return frozenset(spec.tools) if spec is not None and spec.tools is not None else None
152
+
153
+ def _check_task_entities(self, spec: TaskSpec) -> None:
154
+ """A task is refused for a world that does not define every entity it
155
+ names. The seed would fail on its own; an assertion over an unknown
156
+ entity would not, selecting no rows, so ``absent`` or ``count: eq 0``
157
+ checks would pass on a typo and grade a task that can never be graded."""
158
+ defined = self.entity_names()
159
+ unknown = unknown_task_entities(spec, defined)
160
+ if unknown:
161
+ fail(
162
+ "task",
163
+ f"the task names {', '.join(unknown)}, which this world does not define; "
164
+ f"its entities are {', '.join(sorted(defined)) or 'none'}",
165
+ "/task",
166
+ )
167
+
168
+ # -- what a subclass supplies ------------------------------------------ #
169
+
170
+ @abstractmethod
171
+ def _start(self, dependencies: dict[str, DependencyWorld]) -> None:
172
+ """Bring the store up. A failure here leaves nothing to close."""
173
+
174
+ def _to_start(self) -> None:
175
+ """Lay the task's starting state on the store, when :meth:`_start` did not."""
176
+
177
+ @abstractmethod
178
+ def _app_state(self) -> Any:
179
+ """The :class:`api.WorldState` the routes read and write."""
180
+
181
+ @abstractmethod
182
+ def entity_names(self) -> list[str]:
183
+ """Every entity a grader may name (a dependency's as ``alias.entity``)."""
184
+
185
+ @abstractmethod
186
+ def served(self) -> list[str]:
187
+ """Every name :meth:`call` answers: tools, operations, a dependency's ``alias.tool``."""
188
+
189
+ @abstractmethod
190
+ def reset(self) -> dict: ...
191
+
192
+ @abstractmethod
193
+ def seed(self, rows: dict, mode: str, redact: str) -> dict: ...
194
+
195
+ @abstractmethod
196
+ def _rows(self) -> dict:
197
+ """The state without the calls: rows by entity, and what the store started from."""
198
+
199
+ @abstractmethod
200
+ def _grader_rows(self) -> dict:
201
+ """The rows as a session task's grader reads them (keyed by primary key)."""
202
+
203
+ @abstractmethod
204
+ def bundled_grade(self) -> dict | None:
205
+ """The grade of the version's own task by the version's own graders
206
+ (a schema world's SQL verifiers), or None when the version grades a
207
+ bundled task through a ``verify.py`` the :class:`TaskGrader` runs."""
208
+
209
+ @abstractmethod
210
+ def _bundled_verifier(self) -> Path | None:
211
+ """The ``verify.py`` of the bundled task, when the version carries one."""
212
+
213
+ @abstractmethod
214
+ def _call_tool(self, tool: str, args: dict) -> dict | None:
215
+ """A tool by name, or None when ``tool`` is an operation of the routes."""
216
+
217
+ @abstractmethod
218
+ def export(self, destination: Path) -> Path: ...
219
+
220
+ @abstractmethod
221
+ def restore(self, source: Path) -> None: ...
222
+
223
+ @abstractmethod
224
+ def close(self) -> None: ...
225
+
226
+ @abstractmethod
227
+ def task_card(self) -> dict:
228
+ """What an outside agent is handed about the session's task."""
229
+
230
+ # -- the control verbs, shared ----------------------------------------- #
231
+
232
+ def _with_calls(self, state: dict) -> dict:
233
+ if self.app is not None:
234
+ state["calls"] = self.app.calls.describe()["calls"]
235
+ return state
236
+
237
+ def state(self) -> dict:
238
+ return self._with_calls(self._rows())
239
+
240
+ def grader_state(self, report: Optional[str] = None) -> dict:
241
+ """The evidence a grader reads: the rows keyed by primary key (a
242
+ dependency's as ``<alias>.<entity>``), the snapshot in use, the calls
243
+ the agent made (a read-only investigation writes nothing) and, under
244
+ ``report``, the agent's own claim. Reserved keys: no world entity may
245
+ be named ``calls``, ``snapshot`` or ``report``."""
246
+ state = self._with_calls(self._grader_rows())
247
+ if report is not None:
248
+ state["report"] = report
249
+ return state
250
+
251
+ def grade(self, report: Optional[str] = None) -> dict:
252
+ """One grader path. The session's own task grades by its grader —
253
+ assertions in process, verify.py confined like a worker, a rubric
254
+ pending on the platform (the host has no model, no key and no business
255
+ calling one from a tenant's session) — over the same state dump
256
+ whatever the world's shape. A bundled task grades by the version's own
257
+ graders."""
258
+ spec = self.task_spec
259
+ if spec is None or spec.grader is None:
260
+ bundled = self.bundled_grade()
261
+ if bundled is not None:
262
+ return bundled
263
+ grader = self._task_grader(spec)
264
+ if grader is None:
265
+ return Grade(None).as_dict()
266
+ try:
267
+ return grader.grade(self.grader_state(report)).as_dict()
268
+ except GraderError as error:
269
+ fail("host", str(error))
270
+ raise AssertionError # fail() never returns
271
+
272
+ def _task_grader(self, spec: Optional[TaskSpec]) -> Optional[TaskGrader]:
273
+ """The session's grader: the spec's, with its verify.py where
274
+ :func:`write_task_dir` put it; else the bundled task's verify.py; else
275
+ none (an ungraded task grades null)."""
276
+ sandbox = ConfinedVerifierSandbox()
277
+ home = self.session_dir / "verify"
278
+ if spec is not None:
279
+ if spec.grader is None:
280
+ return None
281
+ verify = self.session_dir / TASK_DIR / "checks" / "verify.py"
282
+ return TaskGrader(spec.grader, verify=verify, sandbox=sandbox, home=home)
283
+ verify = self._bundled_verifier()
284
+ if verify is None or not verify.is_file():
285
+ return None
286
+ return TaskGrader.for_verifier(verify, sandbox=sandbox, home=home)
287
+
288
+ def call(self, tool: str, args: dict) -> dict:
289
+ """One name of what the session serves: a tool by name (a dependency's
290
+ as ``alias.tool``); on a tree with connector.toml, an operation by name
291
+ too, answered by its route over the same store, ``{status, body}`` the
292
+ route's own. A name that is both is the tool's."""
293
+ answer = self._call_tool(tool, args)
294
+ if answer is not None:
295
+ return answer
296
+ if self.app is None:
297
+ fail("host", f"unknown tool '{tool}'; this world serves: {', '.join(sorted(self.served())) or '(none)'}")
298
+ raise AssertionError # fail() never returns
299
+ return call_operation(
300
+ self.app, tool, args, self.token or WORLD_AUTH_SENTINEL, allowed=self.allowed, grant=self.grant
301
+ )
302
+
303
+ def credential(self) -> tuple[dict[str, str], dict[str, str]]:
304
+ """(headers, query) carrying the world's own credential for this
305
+ session: the session token in the vendor's shape, or for an oauth2
306
+ world the grant the host minted for itself."""
307
+ assert self.app is not None, "a world of tools alone has no http surface to present a credential on"
308
+ return vendor_credential(self.app.router.spec, self.token or WORLD_AUTH_SENTINEL, grant=self.grant)
309
+
310
+
311
+ class TreeRuntime(WorldRuntime):
312
+ """A schema world stored as itself: :class:`ToolsWorld` over a copy of the
313
+ version's template, beside a copy of each dependency's, graded by the
314
+ version's SQL verifiers unless the session's own task brings a grader."""
315
+
316
+ world: ToolsWorld
317
+
318
+ @classmethod
319
+ def served_by(cls, cached: CachedVersion, dependencies: dict[str, DependencyWorld]) -> list[str]:
320
+ assert cached.tools is not None
321
+ return served_with_dependencies(cached.tools, dependencies)
322
+
323
+ @classmethod
324
+ def authored_code(cls, cached: CachedVersion) -> str:
325
+ return "schema world handlers" # its tools ARE handlers
326
+
327
+ @classmethod
328
+ def declared_dependencies(cls, cached: CachedVersion) -> dict[str, Dependency]:
329
+ assert cached.tools is not None
330
+ return cached.tools.dependencies
331
+
332
+ def _start(self, dependencies: dict[str, DependencyWorld]) -> None:
333
+ tools = self.cached.tools
334
+ assert tools is not None
335
+ spec = self.task_spec
336
+ if spec is not None:
337
+ self.world = ToolsWorld(
338
+ tools,
339
+ self.session_dir,
340
+ inline_task(spec),
341
+ seed=spec.seed,
342
+ allowed=self.allowed,
343
+ dependencies=dependencies,
344
+ )
345
+ return
346
+ assert self.task is not None
347
+ self.world = ToolsWorld(tools, self.session_dir, self.task, dependencies=dependencies)
348
+
349
+ def _app_state(self) -> ToolsWorldState:
350
+ return ToolsWorldState(self.world, self.cached.tree)
351
+
352
+ def entity_names(self) -> list[str]:
353
+ return self.world.entity_names()
354
+
355
+ def served(self) -> list[str]:
356
+ return list(self.world.served)
357
+
358
+ def reset(self) -> dict:
359
+ return self.world.reset()
360
+
361
+ def seed(self, rows: dict, mode: str, redact: str) -> dict:
362
+ if redact != "off":
363
+ fail("host", "a schema world has no [redact] policy; seed it with redact=off")
364
+ return self.world.seed({"rows": rows, "mode": mode})
365
+
366
+ def _rows(self) -> dict:
367
+ return self.world.state()
368
+
369
+ def _grader_rows(self) -> dict:
370
+ return self.world.grader_state()
371
+
372
+ def bundled_grade(self) -> dict | None:
373
+ return None if self.world.task.verify is not None else self.world.grade()
374
+
375
+ def _bundled_verifier(self) -> Path | None:
376
+ return self.world.task.verify
377
+
378
+ def _call_tool(self, tool: str, args: dict) -> dict | None:
379
+ version = self.world.version
380
+ if self.app is not None and tool not in version.tool_names and tool in self.app.router.spec.operations:
381
+ return None
382
+ return self.world.call(tool, args)
383
+
384
+ def export(self, destination: Path) -> Path:
385
+ return self.world.export(destination)
386
+
387
+ def restore(self, source: Path) -> None:
388
+ self.world.restore(source)
389
+
390
+ def close(self) -> None:
391
+ self.world.close()
392
+
393
+ def task_card(self) -> dict:
394
+ return task_card(self.world)
395
+
396
+
397
+ # --------------------------------------------------------------------------- #
398
+ # READ PATH, marked for deletion (handoff step 6): the api-bundle runtime and
399
+ # the reflink-cloned store under it. Nothing new is stored in this shape.
400
+ # --------------------------------------------------------------------------- #
401
+
402
+ _FICLONE = 0x40049409 # ioctl: clone one file's extents into another (btrfs/XFS)
403
+
404
+
405
+ def clone_file(src: Path, dst: Path) -> None:
406
+ """Copy ``src`` to ``dst`` cheaply. A reflink (``FICLONE``) shares the
407
+ version snapshot's blocks copy-on-write, so opening a session costs the
408
+ same whatever the snapshot's size; a filesystem without reflink falls back
409
+ to a plain copy, which is what the pod engine does today."""
410
+ dst.parent.mkdir(parents=True, exist_ok=True)
411
+ try:
412
+ with open(src, "rb") as s, open(dst, "wb") as d:
413
+ fcntl.ioctl(d.fileno(), _FICLONE, s.fileno())
414
+ return
415
+ except OSError:
416
+ pass # not supported here (tmpfs, ext4, cross-device) — copy instead
417
+ shutil.copyfile(src, dst)
418
+
419
+
420
+ def scenario_dir(bundle: Path, tree: Path, task: str) -> Path | None:
421
+ """A bundled task's scenario directory, checked at the bundle root first
422
+ (where ``build_api_bundle`` writes them) then in the tree."""
423
+ for root in (bundle / SCENARIOS / task, tree / SCENARIOS / task):
424
+ if (root / "scenario.toml").is_file():
425
+ return root
426
+ return None
427
+
428
+
429
+ class HostWorldState(WorldState):
430
+ """A session's world, opened by cloning the version's cached snapshot into a
431
+ file on the host's own volume — the reflink is the whole per-session cost.
432
+ Otherwise a plain :class:`WorldState`."""
433
+
434
+ def __init__(self, cached: CachedVersion, session_dir: Path):
435
+ self._session_dir = Path(session_dir)
436
+ self._session_dir.mkdir(parents=True, exist_ok=True)
437
+ self._cached = cached
438
+ self._database: Path | None = None
439
+ super().__init__(cached.tree)
440
+
441
+ @property
442
+ def session_dir(self) -> Path:
443
+ return self._session_dir
444
+
445
+ def _open(self, snapshot: Path | None, *, initial: bool = True) -> None:
446
+ # A snapshot start is a clone of the version's cached snapshot into this
447
+ # session's file; the legacy no-snapshot path stays as the base class runs it.
448
+ if snapshot is None:
449
+ return super()._open(None, initial=initial)
450
+ if self.store is not None:
451
+ self.store.close()
452
+ if self._database is not None:
453
+ self._database.unlink(missing_ok=True)
454
+ database = self._session_dir / f"{uuid.uuid4().hex}.db"
455
+ clone_file(snapshot, database)
456
+ self.store = snapshots.SQLiteStore.open(database, self.contract, audit=False)
457
+ self._database = database
458
+
459
+ def export(self, destination: Path) -> Path:
460
+ """The session's state as one sqlite file: the store's own audited
461
+ online backup, consistent while requests keep writing."""
462
+ assert self.store is not None
463
+ with self._lock:
464
+ return self.store.snapshot(destination)
465
+
466
+ def restore(self, source: Path) -> None:
467
+ """Continue from a file :meth:`export` wrote. The file is audited row by
468
+ row on open: it came over the network, not from this store."""
469
+ with self._lock:
470
+ if self.store is not None:
471
+ self.store.close()
472
+ if self._database is not None:
473
+ self._database.unlink(missing_ok=True)
474
+ database = self._session_dir / f"{uuid.uuid4().hex}.db"
475
+ clone_file(source, database)
476
+ self.store = snapshots.SQLiteStore.open(database, self.contract, audit=True)
477
+ self._database = database
478
+
479
+ def close(self) -> None:
480
+ super().close()
481
+ shutil.rmtree(self._session_dir, ignore_errors=True)
482
+
483
+
484
+ class SnapshotRuntime(WorldRuntime):
485
+ """An api bundle: :class:`HostWorldState` cloned from the version's compiled
486
+ snapshot, the bundled task's scenario overlay (or the session task's seed)
487
+ on top, graded by the scenario's ``verify.py``. READ PATH — see above."""
488
+
489
+ state_: HostWorldState
490
+
491
+ @classmethod
492
+ def served_by(cls, cached: CachedVersion, dependencies: dict[str, DependencyWorld]) -> list[str]:
493
+ assert cached.spec is not None
494
+ return list(cached.spec.operations)
495
+
496
+ @classmethod
497
+ def authored_code(cls, cached: CachedVersion) -> str | None:
498
+ if cached.settings is None or cached.settings.handlers is None:
499
+ return None
500
+ return f"api handlers module {cached.settings.handlers.name}"
501
+
502
+ def _start(self, dependencies: dict[str, DependencyWorld]) -> None:
503
+ if dependencies:
504
+ fail(
505
+ "host",
506
+ f"version {self.cached.version_id} is an api bundle; only a schema world opens beside dependencies",
507
+ )
508
+ assert self.cached.snapshot is not None
509
+ self.state_ = HostWorldState(self.cached, self.session_dir)
510
+
511
+ def _to_start(self) -> None:
512
+ """The task's starting state on a fresh clone: the session task's seed,
513
+ else the bundled task's scenario overlay. The compiled snapshot the
514
+ session is cloned from IS the base state, so a scenario with no seed
515
+ overlay (the synthesized ``default``) needs nothing."""
516
+ spec = self.task_spec
517
+ if spec is not None:
518
+ if spec.seed is not None:
519
+ self.state_.seed_live(spec.seed["rows"], spec.seed["mode"], spec.seed.get("redact", "off"))
520
+ return
521
+ assert self.task is not None
522
+ scenario = scenario_dir(self.cached.bundle, self.cached.tree, self.task)
523
+ if scenario is None:
524
+ if self.task in self.state_.scenarios():
525
+ self.state_.apply_scenario(self.task) # a tree-authored scenario
526
+ return
527
+ fail(
528
+ "host",
529
+ f"no scenario '{self.task}' in this world; it has {', '.join(self.state_.scenarios()) or 'default'}",
530
+ )
531
+ overlay = snapshots.scenario_overlay(scenario)
532
+ if not overlay:
533
+ return # base state; the cloned snapshot already holds it
534
+ digest = self.state_.digest
535
+ if digest is None:
536
+ fail("host", "a scenario overlay needs a compiled snapshot to apply against")
537
+ self.state_.seed({"base": digest, "rows": overlay, "mode": "replace"})
538
+
539
+ def _app_state(self) -> HostWorldState:
540
+ return self.state_
541
+
542
+ def entity_names(self) -> list[str]:
543
+ return list(self.state_.contract.entities)
544
+
545
+ def served(self) -> list[str]:
546
+ spec = self.cached.spec
547
+ return sorted(spec.operations) if spec is not None else []
548
+
549
+ def reset(self) -> dict:
550
+ # Back to the task's starting state: re-clone the snapshot, then
551
+ # re-apply the task's seed or the scenario overlay if it had one.
552
+ self.state_.reset()
553
+ self._to_start()
554
+ return {"reset": True}
555
+
556
+ def seed(self, rows: dict, mode: str, redact: str) -> dict:
557
+ # Onto the live state, the way the runner's session seed lands: an
558
+ # append upserts by key, a replace swaps the named entities.
559
+ self.state_.seed_live(rows, mode, redact)
560
+ return {
561
+ "seeded": sum(len(v) for v in rows.values()),
562
+ "mode": mode,
563
+ **({"redact": redact} if redact != "off" else {}),
564
+ "entity_counts": {
565
+ entity: len(self.state_.rows(entity)) for entity in rows if entity in self.state_.contract.entities
566
+ },
567
+ }
568
+
569
+ def _rows(self) -> dict:
570
+ return {**self.state_.dump(), "snapshot": self.state_.describe_snapshot()}
571
+
572
+ def _grader_rows(self) -> dict:
573
+ return self._rows()
574
+
575
+ def bundled_grade(self) -> dict | None:
576
+ return None
577
+
578
+ def _bundled_verifier(self) -> Path | None:
579
+ assert self.task is not None
580
+ scenario = scenario_dir(self.cached.bundle, self.cached.tree, self.task)
581
+ return scenario / "checks" / "verify.py" if scenario else None
582
+
583
+ def _call_tool(self, tool: str, args: dict) -> dict | None:
584
+ return None
585
+
586
+ def export(self, destination: Path) -> Path:
587
+ return self.state_.export(destination)
588
+
589
+ def restore(self, source: Path) -> None:
590
+ self.state_.restore(source)
591
+
592
+ def close(self) -> None:
593
+ self.state_.close()
594
+
595
+ def task_card(self) -> dict:
596
+ spec = self.task_spec
597
+ return {
598
+ "task": self.task if spec is None else spec.name,
599
+ "prompt": spec.instruction if spec is not None else None,
600
+ "tools": self.served(),
601
+ "contracts": {},
602
+ "verifiers": [],
603
+ "worlds": {},
604
+ "metadata": {},
605
+ }
606
+
607
+
608
+ # --------------------------------------------------------------------------- #
609
+ # Shared by the runtimes and the local session: an operation by name, the
610
+ # client grant, the task card.
611
+ # --------------------------------------------------------------------------- #
612
+
613
+
614
+ def client_grant(app: WorldApp | None, credential: str | None) -> str | None:
615
+ """The bearer an ``oauth2`` world's routes take when the session itself
616
+ calls them (the page's api prefix, an operation by name); None for any
617
+ other scheme, or when the world refuses the client-credentials grant."""
618
+ if app is None or app.router.spec.scheme != "oauth2":
619
+ return None
620
+ issued = app.router.issue_token({"grant_type": "client_credentials", "client_secret": credential or ""}, credential)
621
+ return issued["access_token"] if issued else None
622
+
623
+
624
+ def call_operation(
625
+ app: WorldApp,
626
+ name: str,
627
+ args: dict,
628
+ credential: str,
629
+ *,
630
+ allowed: Iterable[str] | None = None,
631
+ grant: str | None = None,
632
+ ) -> dict:
633
+ """An operation of connector.toml called by name (:func:`operation_request`
634
+ reads the args: ``path``/``query``/``body``, or leftover top-level keys as
635
+ the body); the world's own credential is presented, as the host presents a
636
+ session's. The answer is the route's ``{status, body}``."""
637
+ spec = app.router.spec
638
+ operation = spec.operations.get(name)
639
+ if operation is None:
640
+ known = ", ".join(sorted(spec.operations)) or "(none)"
641
+ fail("host", f"unknown tool '{name}'; this world serves: {known}")
642
+ if allowed is not None and name not in allowed:
643
+ fail(
644
+ "tool_not_allowed",
645
+ f"tool '{name}' is not allowed by this session's task; it allows: {', '.join(sorted(allowed))}",
646
+ )
647
+ method, target, raw = operation_request(spec, operation, args)
648
+ headers, credential_query = vendor_credential(spec, credential, grant=grant)
649
+ status, answer, _ = app.handle(
650
+ method, with_query(target, credential_query), {"content-type": "application/json", **headers}, raw, "127.0.0.1"
651
+ )
652
+ return {"status": status, "body": answer}
653
+
654
+
655
+ def tool_contracts(bundle: Path, prefix: str = "") -> dict[str, dict]:
656
+ """Each compiled tool's ``{description, input}`` from the bundle's
657
+ ``tool-schemas.json`` (refs inlined by the compiler), keyed by served name."""
658
+ path = bundle / "tool-schemas.json"
659
+ if not path.is_file():
660
+ return {}
661
+ tools = json.loads(path.read_text(encoding="utf-8")).get("tools") or {}
662
+ return {
663
+ f"{prefix}{name}": {"description": str(entry.get("description") or ""), "input": entry.get("input_schema")}
664
+ for name, entry in tools.items()
665
+ }
666
+
667
+
668
+ def task_card(world: ToolsWorld) -> dict:
669
+ """What an outside agent is handed about the session's task: ``{task,
670
+ prompt, tools, contracts, verifiers, worlds}`` — ``tools`` the served names,
671
+ ``contracts`` each one's description and input schema, ``verifiers`` the
672
+ root's that grade, ``worlds`` each dependency alias to the verifiers of its
673
+ own that grade (``slack/message_posted`` in the grade's ``rewards``)."""
674
+ task = world.task
675
+ contracts = tool_contracts(world.version.bundle)
676
+ for alias, dep in world.dependencies.items():
677
+ contracts.update(tool_contracts(dep.version.bundle, f"{alias}."))
678
+ return {
679
+ "task": task.id,
680
+ "prompt": task.prompt,
681
+ "tools": list(world.served),
682
+ "contracts": {name: contracts[name] for name in world.served if name in contracts},
683
+ "verifiers": task.selected(world.version.verifiers),
684
+ "worlds": {alias: task.selected_of(alias, dep.version.verifiers) for alias, dep in world.dependencies.items()},
685
+ "metadata": dict(task.metadata),
686
+ }
@@ -32,6 +32,7 @@ NEXT_STEPS = {
32
32
  "world-data-ingestion": "gateway worlds data import <world> rows.json",
33
33
  "worlds-getting-started": "gateway worlds schema init ./my-world --connector custom",
34
34
  "benchmarks-getting-started": "gateway benchmarks init ./my-benchmark --connector custom",
35
+ "hooks-getting-started": "gateway hooks check gateway-hooks.toml",
35
36
  }
36
37
 
37
38