@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
@@ -45,7 +45,6 @@ guessing.
45
45
  from __future__ import annotations
46
46
 
47
47
  import base64
48
- import fcntl
49
48
  import hashlib
50
49
  import hmac
51
50
  import http.client
@@ -54,7 +53,6 @@ import os
54
53
  import re
55
54
  import shutil
56
55
  import signal
57
- import subprocess
58
56
  import sys
59
57
  import tarfile
60
58
  import threading
@@ -72,23 +70,21 @@ from pathlib import Path
72
70
  from typing import Any, Optional, Protocol
73
71
 
74
72
  from .._tar import safe_tar_extract
73
+ from ..world import WorldTree
75
74
  from . import snapshot as snapshots
76
75
  from .api import (
77
- SCENARIOS,
78
76
  ApiSettings,
79
77
  Handler,
80
78
  Router,
81
79
  WorldApp,
82
- WorldState,
83
80
  load_api_settings,
84
81
  load_handlers,
85
- operation_request,
86
82
  send_response,
87
- vendor_credential,
88
83
  with_query,
89
84
  )
90
85
  from .compiler import check_bundle
91
86
  from .connector import Spec, load_spec
87
+ from .dependencies import Dependency
92
88
  from .host_surfaces import (
93
89
  HOP_HEADER,
94
90
  UiSurface,
@@ -104,25 +100,11 @@ from .host_surfaces import (
104
100
  verify_live_grant,
105
101
  without_query_token,
106
102
  )
107
- from .tasks import (
108
- TaskSpec,
109
- evaluate_assertions,
110
- parse_task_spec,
111
- unknown_task_entities,
112
- unknown_task_tools,
113
- write_task_dir,
114
- )
115
- from .tools_world import (
116
- DependencyWorld,
117
- ToolsVersion,
118
- ToolsWorld,
119
- ToolsWorldState,
120
- inline_task,
121
- is_tools_bundle,
122
- load_tools_version,
123
- served_with_dependencies,
124
- )
103
+ from .runtime import SnapshotRuntime, TreeRuntime, WorldRuntime
104
+ from .tasks import TaskSpec, parse_task_spec, unknown_task_tools
105
+ from .tools_world import DependencyWorld, ToolsVersion, is_tools_bundle, load_tools_version
125
106
  from .validation import ContractError, fail
107
+ from .verbs import SESSION_VERBS, session_verb, unknown_verb
126
108
  from .workers import (
127
109
  DEFAULT_WORKER_BUDGET_MB,
128
110
  DEFAULT_WORKER_FOOTPRINT_MB,
@@ -131,14 +113,11 @@ from .workers import (
131
113
  WorkerCapacity,
132
114
  WorkerGone,
133
115
  WorkerPool,
134
- confined_command,
135
- verifier_environment,
136
116
  )
137
117
 
138
118
  #: The world tree inside an api bundle, or the bundle root for a bare tree.
139
119
  BUNDLED_WORLD = "server/world"
140
- API_BUNDLE = "gateway-api-world.toml"
141
- VERIFY_TIMEOUT_S = 30.0
120
+ WORLD_SPEC = "schema/world.json"
142
121
  #: How long a session lives with no control call or request renewing it.
143
122
  DEFAULT_LEASE_S = 3600.0
144
123
  #: How often the host sweeps expired leases.
@@ -202,28 +181,6 @@ MAX_BUNDLE_MEMBERS = 200_000
202
181
  DEFAULT_MAX_BODY_MB = 32
203
182
 
204
183
 
205
- # --------------------------------------------------------------------------- #
206
- # Reflink: a session's state is a copy-on-write clone of the version snapshot.
207
- # --------------------------------------------------------------------------- #
208
-
209
- _FICLONE = 0x40049409 # ioctl: clone one file's extents into another (btrfs/XFS)
210
-
211
-
212
- def clone_file(src: Path, dst: Path) -> None:
213
- """Copy ``src`` to ``dst`` cheaply. A reflink (``FICLONE``) shares the
214
- version snapshot's blocks copy-on-write, so opening a session costs the
215
- same whatever the snapshot's size; a filesystem without reflink falls back
216
- to a plain copy, which is what the pod engine does today."""
217
- dst.parent.mkdir(parents=True, exist_ok=True)
218
- try:
219
- with open(src, "rb") as s, open(dst, "wb") as d:
220
- fcntl.ioctl(d.fileno(), _FICLONE, s.fileno())
221
- return
222
- except OSError:
223
- pass # not supported here (tmpfs, ext4, cross-device) — copy instead
224
- shutil.copyfile(src, dst)
225
-
226
-
227
184
  OBJECT_STORE_ANY = "any"
228
185
  _ORIGIN_HOST = re.compile(r"^[A-Za-z0-9.-]+(:[0-9]+)?$")
229
186
 
@@ -343,31 +300,21 @@ def upload_file(url: str, path: Path, sha256: str, size: int, content_type: str
343
300
 
344
301
 
345
302
  def world_tree(bundle: Path) -> Path:
346
- """The gateway-world tree inside an extracted bundle. ``bench push`` packages
347
- a schema world as its api bundle with the tree under ``server/world``; a bare
348
- tree is its own root."""
349
- nested = bundle / BUNDLED_WORLD
350
- if (bundle / API_BUNDLE).is_file() and (nested / "schema/world.json").is_file():
351
- return nested
352
- if (bundle / "schema/world.json").is_file():
353
- return bundle
303
+ """The compiled schema world inside an extracted bundle (``WorldTree.world``:
304
+ ``bench push`` packages a schema world as its api bundle with the tree
305
+ under ``server/world``; a bare tree is its own root). The host opens
306
+ compiled worlds only, so a tree without ``schema/world.json`` refuses."""
307
+ tree = WorldTree.from_dir(bundle)
308
+ if tree.has(tree.world_path(WORLD_SPEC)):
309
+ return tree.world
354
310
  fail(
355
311
  "host",
356
- f"{bundle} holds no schema world the host can open (no {BUNDLED_WORLD}/schema/world.json "
357
- "nor schema/world.json); the host serves schema worlds and api bundles only",
312
+ f"{bundle} holds no schema world the host can open (no {BUNDLED_WORLD}/{WORLD_SPEC} "
313
+ f"nor {WORLD_SPEC}); the host serves schema worlds and api bundles only",
358
314
  )
359
315
  raise AssertionError # fail() never returns
360
316
 
361
317
 
362
- def _scenario_dir(bundle: Path, tree: Path, task: str) -> Path | None:
363
- """A task's scenario directory, checked at the bundle root first (where
364
- ``build_api_bundle`` writes them) then in the tree."""
365
- for root in (bundle / SCENARIOS / task, tree / SCENARIOS / task):
366
- if (root / "scenario.toml").is_file():
367
- return root
368
- return None
369
-
370
-
371
318
  # --------------------------------------------------------------------------- #
372
319
  # Per-version cache: bundle + snapshot + parsed spec, fetched once per host.
373
320
  # --------------------------------------------------------------------------- #
@@ -397,12 +344,11 @@ class CachedVersion:
397
344
  tools: ToolsVersion | None = None
398
345
 
399
346
  @property
400
- def needs_worker(self) -> bool:
401
- """Whether the version runs world-authored code: a mock-tools world
402
- always (its tools ARE handlers), an api world when it declares some."""
403
- if self.tools is not None:
404
- return True
405
- return self.settings is not None and self.settings.handlers is not None
347
+ def runtime_class(self) -> type[WorldRuntime]:
348
+ """The one place a session's engine is chosen: a schema world runs as
349
+ the tree it is; an api bundle on the snapshot READ PATH that step 6
350
+ deletes with the bundle shape itself."""
351
+ return TreeRuntime if self.tools is not None else SnapshotRuntime
406
352
 
407
353
  def router(self) -> Router:
408
354
  """A fresh router per session: routes are compiled from the shared spec,
@@ -410,6 +356,24 @@ class CachedVersion:
410
356
  assert self.spec is not None and self.settings is not None
411
357
  return Router(self.spec, self.settings)
412
358
 
359
+ @property
360
+ def authored_code(self) -> str | None:
361
+ """What world-authored code the version runs, None for none: only a
362
+ worker may open a version that runs any."""
363
+ return self.runtime_class.authored_code(self)
364
+
365
+ @property
366
+ def needs_worker(self) -> bool:
367
+ return self.authored_code is not None
368
+
369
+ def served_tools(self, dependencies: dict[str, DependencyWorld]) -> list[str]:
370
+ """Every name a session task may allow."""
371
+ return self.runtime_class.served_by(self, dependencies)
372
+
373
+ @property
374
+ def declared_dependencies(self) -> dict[str, Dependency]:
375
+ return self.runtime_class.declared_dependencies(self)
376
+
413
377
 
414
378
  class VersionCache:
415
379
  """Every world version this host has seen, on local disk. The first session
@@ -555,61 +519,6 @@ class VersionCache:
555
519
  # --------------------------------------------------------------------------- #
556
520
 
557
521
 
558
- class HostWorldState(WorldState):
559
- """A session's world, opened by cloning the version's cached snapshot into a
560
- file on the host's own volume — the reflink is the whole per-session cost.
561
- Otherwise a plain :class:`WorldState`."""
562
-
563
- def __init__(self, cached: CachedVersion, session_dir: Path):
564
- self._session_dir = Path(session_dir)
565
- self._session_dir.mkdir(parents=True, exist_ok=True)
566
- self._cached = cached
567
- self._database: Path | None = None
568
- super().__init__(cached.tree)
569
-
570
- @property
571
- def session_dir(self) -> Path:
572
- return self._session_dir
573
-
574
- def _open(self, snapshot: Path | None, *, initial: bool = True) -> None:
575
- # A snapshot start is a clone of the version's cached snapshot into this
576
- # session's file; the legacy no-snapshot path stays as the base class runs it.
577
- if snapshot is None:
578
- return super()._open(None, initial=initial)
579
- if self.store is not None:
580
- self.store.close()
581
- if self._database is not None:
582
- self._database.unlink(missing_ok=True)
583
- database = self._session_dir / f"{uuid.uuid4().hex}.db"
584
- clone_file(snapshot, database)
585
- self.store = snapshots.SQLiteStore.open(database, self.contract, audit=False)
586
- self._database = database
587
-
588
- def export(self, destination: Path) -> Path:
589
- """The session's state as one sqlite file: the store's own audited
590
- online backup, consistent while requests keep writing."""
591
- assert self.store is not None
592
- with self._lock:
593
- return self.store.snapshot(destination)
594
-
595
- def restore(self, source: Path) -> None:
596
- """Continue from a file :meth:`export` wrote. The file is audited row by
597
- row on open: it came over the network, not from this store."""
598
- with self._lock:
599
- if self.store is not None:
600
- self.store.close()
601
- if self._database is not None:
602
- self._database.unlink(missing_ok=True)
603
- database = self._session_dir / f"{uuid.uuid4().hex}.db"
604
- clone_file(source, database)
605
- self.store = snapshots.SQLiteStore.open(database, self.contract, audit=True)
606
- self._database = database
607
-
608
- def close(self) -> None:
609
- super().close()
610
- shutil.rmtree(self._session_dir, ignore_errors=True)
611
-
612
-
613
522
  @dataclass
614
523
  class Export:
615
524
  """A session's state copied to a file on this host, hashed, waiting for the
@@ -645,12 +554,9 @@ class Session:
645
554
  tree: Path
646
555
  #: Unix time the lease runs out unless renewed.
647
556
  lease_until: float
648
- #: The world, when this process serves it. None for a session placed on a
649
- #: worker, whose state lives in that process.
650
- state: HostWorldState | None = None
651
- app: WorldApp | None = None
652
- #: The mock-tools world, when this process (a worker) serves one.
653
- tools: ToolsWorld | None = None
557
+ #: The world, when this process serves it (:class:`WorldRuntime`). None
558
+ #: for a session placed on a worker, whose world lives in that process.
559
+ runtime: WorldRuntime | None = None
654
560
  #: The version worker serving this session, or None for in-process.
655
561
  worker: Worker | None = None
656
562
  #: The version's static ui, served by the supervisor for this session.
@@ -660,9 +566,6 @@ class Session:
660
566
  #: browser surface.
661
567
  browser_url: str | None = None
662
568
  browser_token: str | None = None
663
- #: For an oauth2 world: the bearer this world minted for the host itself,
664
- #: presented on behalf of a caller who authenticated with the session token.
665
- grant: str | None = None
666
569
  #: Requests inside the world right now. A session is only torn down once
667
570
  #: this reaches zero, so a close or an expiry never pulls the database out
668
571
  #: from under a handler mid-request.
@@ -687,6 +590,12 @@ class Session:
687
590
  #: ``grade``, and it lives under ``<session>/task/`` (:mod:`tasks`).
688
591
  task_spec: TaskSpec | None = None
689
592
 
593
+ @property
594
+ def app(self) -> WorldApp | None:
595
+ """The world's routes over this session's store, when this process
596
+ serves it and the tree has any."""
597
+ return self.runtime.app if self.runtime is not None else None
598
+
690
599
  @property
691
600
  def task_key(self) -> tuple[str | None, dict | None]:
692
601
  """What an open retry must match: the bundled name or the spec itself."""
@@ -910,54 +819,35 @@ class WorldHost:
910
819
  dependencies = self._dependency_worlds(cached, deps)
911
820
  # A session task runs on either shape the host serves: an api bundle
912
821
  # clones its snapshot and grades by the spec; a schema world copies its
913
- # template and grades with its bundled verifiers (:func:`inline_task`
914
- # refuses a spec that brings a grader of its own). Its allow-list may
915
- # name a tool or, on a tree with connector.toml, an operation.
822
+ # template and grades by the spec too, else with its bundled verifiers
823
+ # (:meth:`_grade`). Its allow-list may name a tool or, on a tree
824
+ # with connector.toml, an operation.
916
825
  if cached.spec is not None:
917
826
  unsupported = unsupported_auth(cached.spec)
918
827
  if unsupported:
919
828
  fail("host", unsupported)
920
829
  if spec is not None:
921
- if cached.tools is not None:
922
- self._check_task_tools(spec, served_with_dependencies(cached.tools, dependencies))
923
- else:
924
- assert cached.spec is not None
925
- self._check_task_tools(spec, cached.spec.operations)
830
+ self._check_task_tools(spec, cached.served_tools(dependencies))
926
831
  browser_url, browser_token = browser_lease(browser)
927
832
  if cached.needs_worker and not self.run_handlers:
928
833
  if self.workers is None:
929
834
  fail(
930
835
  "host",
931
- f"version {version_id} runs world-authored code ({_code_of(cached)}); "
836
+ f"version {version_id} runs world-authored code ({cached.authored_code}); "
932
837
  "this host runs none in its process and has no version workers",
933
838
  )
934
839
  return self._open_on_worker(
935
840
  cached, session_id, bundle_url, task, spec, token, browser_url, browser_token, restore, deps
936
841
  )
937
- if cached.tools is not None:
938
- return self._open_tools(cached, cached.tools, session_id, task, spec, token, restore, dependencies)
939
- assert cached.snapshot is not None and cached.spec is not None
940
- state = HostWorldState(cached, self.sessions_root / session_id)
941
- try:
942
- if spec is not None:
943
- self._check_task_entities(spec, state)
944
- write_task_dir(spec, state.session_dir)
945
- self._apply_task_seed(state, spec)
946
- else:
947
- assert task is not None
948
- self._apply_scenario(cached, state, task)
949
- restored = self._restore_into(restore, self.sessions_root / session_id, state.restore)
950
- except Exception:
951
- state.close()
952
- raise
953
- # ``handlers={}`` for a code-free world: WorldApp would otherwise import
954
- # the module itself, and only a worker may do that.
955
- app = WorldApp(
956
- state,
957
- cached.router(),
958
- token,
959
- handlers=cached.handlers or {},
960
- allowed=frozenset(spec.tools) if spec is not None and spec.tools is not None else None,
842
+ session_dir = self.sessions_root / session_id
843
+ runtime = WorldRuntime.open(
844
+ cached,
845
+ session_dir,
846
+ task=task,
847
+ spec=spec,
848
+ token=token,
849
+ dependencies=dependencies,
850
+ restore=lambda load: self._restore_into(restore, session_dir, load),
961
851
  )
962
852
  session = Session(
963
853
  session_id=session_id,
@@ -968,92 +858,13 @@ class WorldHost:
968
858
  bundle=cached.bundle,
969
859
  tree=cached.tree,
970
860
  lease_until=time.time() + self.lease_s,
971
- state=state,
972
- app=app,
861
+ runtime=runtime,
973
862
  ui=cached.ui,
974
863
  browser_url=browser_url,
975
864
  browser_token=browser_token,
976
- restored=restored,
865
+ restored=runtime.restored,
977
866
  task_spec=spec,
978
867
  )
979
- if cached.spec.scheme == "oauth2":
980
- # The host's own client-credentials grant, so a caller admitted by
981
- # the session token is presented to the world as a granted client.
982
- issued = app.router.issue_token(
983
- {"grant_type": "client_credentials", "client_secret": token or ""},
984
- token,
985
- )
986
- session.grant = issued["access_token"] if issued else None
987
- self._register(session)
988
- return self._describe(session)
989
-
990
- def _open_tools(
991
- self,
992
- cached: CachedVersion,
993
- tools: ToolsVersion,
994
- session_id: str,
995
- task: str | None,
996
- spec: TaskSpec | None,
997
- token: str | None,
998
- restore: dict[str, str] | None,
999
- dependencies: dict[str, DependencyWorld],
1000
- ) -> dict:
1001
- """A schema world's session in this (worker) process: a copy of the
1002
- version's template, executed through its handlers, on a bundled ``task``
1003
- or on the session's own ``spec`` (its seed on the copy, the bundle's
1004
- verifiers as its grade), beside a copy of each dependency world's. When
1005
- the tree carries connector.toml the same session answers its HTTP
1006
- surface over the same store (:class:`ToolsWorldState` under a
1007
- :class:`WorldApp`), and the static ui its ``[ui]`` declares (served by
1008
- whichever process fronts the session: the supervisor for a worker's
1009
- session, this one when it runs the handlers itself); without it there
1010
- is no http surface, so no ui and no browser, and the agent reaches the
1011
- world through ``call`` alone."""
1012
- session_dir = self.sessions_root / session_id
1013
- allowed = frozenset(spec.tools) if spec is not None and spec.tools is not None else None
1014
- if spec is not None:
1015
- world = ToolsWorld(
1016
- tools, session_dir, inline_task(spec), seed=spec.seed, allowed=allowed, dependencies=dependencies
1017
- )
1018
- else:
1019
- assert task is not None
1020
- world = ToolsWorld(tools, session_dir, task, dependencies=dependencies)
1021
- app: WorldApp | None = None
1022
- try:
1023
- if spec is not None:
1024
- # Under the session, as an api session keeps it: where a grade
1025
- # and a restart find the task.
1026
- write_task_dir(spec, session_dir)
1027
- restored = self._restore_into(restore, session_dir, world.restore)
1028
- if cached.spec is not None:
1029
- app = WorldApp(
1030
- ToolsWorldState(world, cached.tree),
1031
- cached.router(),
1032
- token,
1033
- handlers=cached.handlers or {},
1034
- allowed=allowed,
1035
- )
1036
- except Exception:
1037
- world.close()
1038
- raise
1039
- session = Session(
1040
- session_id=session_id,
1041
- version_id=cached.version_id,
1042
- task=task,
1043
- spec=cached.spec,
1044
- token=token,
1045
- bundle=cached.bundle,
1046
- tree=cached.tree,
1047
- lease_until=time.time() + self.lease_s,
1048
- app=app,
1049
- tools=world,
1050
- ui=cached.ui,
1051
- restored=restored,
1052
- task_spec=spec,
1053
- )
1054
- if app is not None and cached.spec is not None and cached.spec.scheme == "oauth2":
1055
- issued = app.router.issue_token({"grant_type": "client_credentials", "client_secret": token or ""}, token)
1056
- session.grant = issued["access_token"] if issued else None
1057
868
  self._register(session)
1058
869
  return self._describe(session)
1059
870
 
@@ -1242,11 +1053,8 @@ class WorldHost:
1242
1053
  exports = self.sessions_root / session_id / "exports"
1243
1054
  shutil.rmtree(exports, ignore_errors=True)
1244
1055
  path = exports / f"{uuid.uuid4().hex}.sqlite"
1245
- if session.tools is not None:
1246
- session.tools.export(path)
1247
- else:
1248
- assert session.state is not None
1249
- session.state.export(path)
1056
+ assert session.runtime is not None
1057
+ session.runtime.export(path)
1250
1058
  sha256, size = file_digest(path)
1251
1059
  if known_sha256 is not None and sha256 == known_sha256:
1252
1060
  path.unlink(missing_ok=True)
@@ -1329,11 +1137,8 @@ class WorldHost:
1329
1137
  self._counters[f"closed.{reason}"] += 1
1330
1138
  self._session_seconds += session.seconds
1331
1139
  if session.worker is None:
1332
- if session.tools is not None:
1333
- session.tools.close()
1334
- return
1335
- assert session.state is not None
1336
- session.state.close()
1140
+ assert session.runtime is not None
1141
+ session.runtime.close()
1337
1142
  return
1338
1143
  worker = session.worker
1339
1144
  with self._lock:
@@ -1358,7 +1163,7 @@ class WorldHost:
1358
1163
  answer = json.loads(payload or b"null")
1359
1164
  if status != 200:
1360
1165
  detail = answer if isinstance(answer, dict) else {}
1361
- fail(str(detail.get("error") or "host"), str(detail.get("detail") or answer))
1166
+ fail(str(detail.get("error") or "host"), str(detail.get("message") or detail.get("detail") or answer))
1362
1167
  return answer if isinstance(answer, dict) else {"result": answer}
1363
1168
 
1364
1169
  def lose_worker(self, worker: Worker) -> list[str]:
@@ -1471,78 +1276,38 @@ class WorldHost:
1471
1276
  lines.append(f'worlds_host_requests_total{{surface="{surface}"}} {counters.get(f"requests.{surface}", 0)}')
1472
1277
  return "\n".join(lines) + "\n"
1473
1278
 
1474
- def _apply_scenario(self, cached: CachedVersion, state: HostWorldState, task: str) -> None:
1475
- """Start the session in its task's scenario. The compiled snapshot the
1476
- session is cloned from IS the base state, so a scenario with no seed
1477
- overlay (the synthesized ``default``) needs nothing; one with an overlay
1478
- applies it on top of the pinned snapshot the way the runner does."""
1479
- scenario = _scenario_dir(cached.bundle, cached.tree, task)
1480
- if scenario is None:
1481
- if task in state.scenarios():
1482
- state.apply_scenario(task) # a tree-authored scenario
1483
- return
1484
- fail(
1485
- "host",
1486
- f"no scenario '{task}' in this world; it has {', '.join(state.scenarios()) or 'default'}",
1487
- )
1488
- overlay = snapshots.scenario_overlay(scenario)
1489
- if not overlay:
1490
- return # base state; the cloned snapshot already holds it
1491
- digest = state.digest
1492
- if digest is None:
1493
- fail("host", "a scenario overlay needs a compiled snapshot to apply against")
1494
- state.seed({"base": digest, "rows": overlay, "mode": "replace"})
1495
-
1496
- @staticmethod
1497
- def _check_task_entities(spec: TaskSpec, state: HostWorldState) -> None:
1498
- """A task is refused for a world that does not define every entity it
1499
- names. The seed would fail on its own; an assertion over an unknown
1500
- entity would not, selecting no rows, so `absent` or `count: eq 0`
1501
- checks would pass on a typo and grade a task that can never be graded."""
1502
- unknown = unknown_task_entities(spec, state.contract.entities)
1503
- if unknown:
1504
- defined = ", ".join(sorted(state.contract.entities)) or "none"
1505
- fail(
1506
- "task",
1507
- f"the task names {', '.join(unknown)}, which this world does not define; its entities are {defined}",
1508
- "/task",
1509
- )
1510
-
1511
1279
  def _dependency_worlds(self, cached: CachedVersion, deps: list[DependencyRef]) -> dict[str, DependencyWorld]:
1512
1280
  """The dependency versions a session opens beside ``cached``, cached the
1513
1281
  way the root is (a worker imports their handlers too). Every alias the
1514
1282
  root's manifest declares must be resolved, and nothing else: a version
1515
1283
  without ``[dependencies]`` opened with any is refused, as is a
1516
1284
  dependency that is not a schema world."""
1285
+ declared = cached.declared_dependencies
1517
1286
  if not deps:
1518
- if cached.tools is not None and cached.tools.dependencies:
1519
- declared = ", ".join(sorted(cached.tools.dependencies))
1520
- fail("host", f"version {cached.version_id} declares dependencies ({declared}); the open resolved none")
1287
+ if declared:
1288
+ names = ", ".join(sorted(declared))
1289
+ fail("host", f"version {cached.version_id} declares dependencies ({names}); the open resolved none")
1521
1290
  return {}
1522
- if cached.tools is None:
1523
- fail("host", f"version {cached.version_id} is an api bundle; only a schema world opens beside dependencies")
1524
- raise AssertionError # fail() never returns
1525
1291
  worlds: dict[str, DependencyWorld] = {}
1526
1292
  for ref in deps:
1527
- declared = cached.tools.dependencies.get(ref.alias)
1528
- if declared is None:
1529
- known = ", ".join(sorted(cached.tools.dependencies)) or "none"
1293
+ dependency = declared.get(ref.alias)
1294
+ if dependency is None:
1295
+ known = ", ".join(sorted(declared)) or "none"
1530
1296
  fail("host", f"version {cached.version_id} declares no dependency '{ref.alias}' (it declares: {known})")
1531
1297
  raise AssertionError # fail() never returns
1532
1298
  dep = self.cache.ensure(ref.version_id, *self._trusted_version(ref.bundle_url, ref.snapshot))
1533
1299
  if dep.tools is None:
1534
1300
  fail("host", f"dependency '{ref.alias}' ({ref.version_id}) is an api bundle, not a schema world")
1535
1301
  raise AssertionError # fail() never returns
1536
- worlds[ref.alias] = DependencyWorld.of(declared, dep.tools)
1537
- served_with_dependencies(cached.tools, worlds)
1302
+ worlds[ref.alias] = DependencyWorld.of(dependency, dep.tools)
1303
+ cached.served_tools(worlds) # refuses a root tool that reads as a dependency's
1538
1304
  return worlds
1539
1305
 
1540
1306
  @staticmethod
1541
1307
  def _check_task_tools(spec: TaskSpec, served_tools: Iterable[str]) -> None:
1542
1308
  """A task's allow-list names tools the world serves, every one of them:
1543
1309
  a misspelt name would narrow the list without anyone noticing. The
1544
- served tools are an api world's operations or a mock-tools world's
1545
- handlers."""
1310
+ served tools are what :meth:`CachedVersion.served_tools` lists."""
1546
1311
  served_tools = list(served_tools)
1547
1312
  unknown = unknown_task_tools(spec, served_tools)
1548
1313
  if unknown:
@@ -1553,14 +1318,6 @@ class WorldHost:
1553
1318
  "/task/tools",
1554
1319
  )
1555
1320
 
1556
- def _apply_task_seed(self, state: HostWorldState, spec: TaskSpec) -> None:
1557
- """Start the session in its own task's state: the version's snapshot
1558
- (already cloned) with the task's rows on top, as a session seed lands
1559
- them. A task without a seed starts on the base data."""
1560
- if spec.seed is None:
1561
- return
1562
- state.seed_live(spec.seed["rows"], spec.seed["mode"], spec.seed.get("redact", "off"))
1563
-
1564
1321
  @contextmanager
1565
1322
  def using(self, session_id: str, *, touch: bool = True) -> Iterator[Session]:
1566
1323
  """The session for the duration of one request: its lease renewed (any
@@ -1595,70 +1352,44 @@ class WorldHost:
1595
1352
 
1596
1353
  # -- control operations (the platform's rendezvous, run in-process) ----- #
1597
1354
 
1598
- def reset(self, session_id: str) -> dict:
1355
+ def _control(self, session: Session, method: str, verb: str, body: dict | None) -> dict:
1356
+ return self._worker_control(session.worker, method, f"/__host/sessions/{session.session_id}/{verb}", body)
1357
+
1358
+ def tools(self, session_id: str) -> dict:
1599
1359
  with self.using(session_id) as session:
1600
1360
  if session.worker is not None:
1601
- return self._worker_control(session.worker, "POST", f"/__host/sessions/{session_id}/reset", {})
1602
- if session.tools is not None:
1603
- return session.tools.reset()
1604
- assert session.state is not None
1605
- # Back to the task's starting state: re-clone the snapshot, then
1606
- # re-apply the task's seed or the scenario overlay if it had one.
1607
- session.state.reset()
1608
- if session.task_spec is not None:
1609
- self._apply_task_seed(session.state, session.task_spec)
1610
- else:
1611
- assert session.task is not None
1612
- self._apply_scenario(self.cache._versions[session.version_id], session.state, session.task)
1613
- return {"reset": True}
1361
+ return self._control(session, "GET", "tools", None)
1362
+ assert session.runtime is not None
1363
+ return {"tools": session.runtime.served()}
1614
1364
 
1615
- def seed(self, session_id: str, args: dict) -> dict:
1616
- rows = args.get("rows")
1617
- if not isinstance(rows, dict):
1618
- fail(
1619
- "host",
1620
- 'seed needs rows as {"rows": {entity: [row, ...]}, "mode": "append"|"replace"}; '
1621
- "a dependency's entity is named alias.entity",
1622
- )
1623
- mode = args.get("mode", "append")
1624
- from .redaction import parse_mode
1365
+ def task(self, session_id: str) -> dict:
1366
+ with self.using(session_id) as session:
1367
+ if session.worker is not None:
1368
+ return self._control(session, "GET", "task", None)
1369
+ assert session.runtime is not None
1370
+ return session.runtime.task_card()
1625
1371
 
1626
- redact = parse_mode(args.get("redact"), "/args/redact")
1372
+ def reset(self, session_id: str) -> dict:
1627
1373
  with self.using(session_id) as session:
1628
1374
  if session.worker is not None:
1629
- return self._worker_control(
1630
- session.worker, "POST", f"/__host/sessions/{session_id}/seed", {"args": args}
1631
- )
1632
- if session.tools is not None:
1633
- if redact != "off":
1634
- fail("host", "a mock-tools world has no [redact] policy; seed it with redact=off")
1635
- return session.tools.seed(args)
1636
- assert session.state is not None
1637
- # Onto the live state, the way the runner's session seed lands: an
1638
- # append upserts by key, a replace swaps the named entities.
1639
- session.state.seed_live(rows, mode, redact)
1640
- return {
1641
- "seeded": sum(len(v) for v in rows.values()),
1642
- "mode": mode,
1643
- **({"redact": redact} if redact != "off" else {}),
1644
- "entity_counts": {
1645
- entity: len(session.state.rows(entity))
1646
- for entity in rows
1647
- if entity in session.state.contract.entities
1648
- },
1649
- }
1375
+ return self._control(session, "POST", "reset", {})
1376
+ assert session.runtime is not None
1377
+ return session.runtime.reset()
1378
+
1379
+ def seed(self, session_id: str, rows: dict, mode: str = "append", redact: str = "off") -> dict:
1380
+ with self.using(session_id) as session:
1381
+ if session.worker is not None:
1382
+ args = {"rows": rows, "mode": mode, **({"redact": redact} if redact != "off" else {})}
1383
+ return self._control(session, "POST", "seed", {"args": args})
1384
+ assert session.runtime is not None
1385
+ return session.runtime.seed(rows, mode, redact)
1650
1386
 
1651
1387
  def state(self, session_id: str) -> dict:
1652
1388
  with self.using(session_id) as session:
1653
1389
  if session.worker is not None:
1654
- return self._worker_control(session.worker, "GET", f"/__host/sessions/{session_id}/state", None)
1655
- if session.tools is not None:
1656
- return session.tools.state()
1657
- assert session.state is not None
1658
- state = {**session.state.dump(), "snapshot": session.state.describe_snapshot()}
1659
- if session.app is not None:
1660
- state["calls"] = session.app.calls.describe()["calls"]
1661
- return state
1390
+ return self._control(session, "GET", "state", None)
1391
+ assert session.runtime is not None
1392
+ return session.runtime.state()
1662
1393
 
1663
1394
  def grade(self, session_id: str, report: Optional[str] = None) -> dict:
1664
1395
  """Grade the session. ``report`` is the agent's own account of the run — the
@@ -1668,129 +1399,38 @@ class WorldHost:
1668
1399
  with self.using(session_id) as session:
1669
1400
  if session.worker is not None:
1670
1401
  body = {"report": report} if report is not None else {}
1671
- return self._worker_control(session.worker, "POST", f"/__host/sessions/{session_id}/grade", body)
1672
- if session.tools is not None:
1673
- return session.tools.grade()
1674
- return self._grade(session, report)
1675
-
1676
- def _grade(self, session: Session, report: Optional[str] = None) -> dict:
1677
- assert session.state is not None
1678
- state = {**session.state.dump(), "snapshot": session.state.describe_snapshot()}
1679
- if session.app is not None:
1680
- # What the agent asked, beside what it left: a read-only investigation
1681
- # writes nothing, so its calls are the evidence a grader reads.
1682
- state["calls"] = session.app.calls.describe()["calls"]
1683
- if report is not None:
1684
- # The agent's claim, beside the evidence. A reserved key like ``calls``
1685
- # and ``snapshot``: no world entity may be named ``report``.
1686
- state["report"] = report
1687
- spec = session.task_spec
1688
- if spec is not None:
1689
- # The session's own task: its assertions are evaluated here, pure
1690
- # Python over the dump; its verify.py runs as a bundled one would.
1691
- if spec.grader is None:
1692
- return {"reward": None, "rewards": {}}
1693
- if spec.grader["kind"] == "assertions":
1694
- return evaluate_assertions(spec.grader["checks"], state)
1695
- if spec.graded_on_platform:
1696
- # A rubric is an LLM judge's brief. The host has no model, no
1697
- # key and no business calling one from a tenant's session: the
1698
- # platform grades it from the state and the calls log.
1699
- return {"reward": None, "rewards": {}, "pending": True, "grader": "rubric"}
1700
- verify = session.state.session_dir / "task" / "checks" / "verify.py"
1701
- return self._run_verifier(session, verify, state, spec.grader.get("timeoutSeconds") or VERIFY_TIMEOUT_S)
1702
- assert session.task is not None
1703
- scenario = _scenario_dir(session.bundle, session.tree, session.task)
1704
- verify = scenario / "checks" / "verify.py" if scenario else None
1705
- if verify is None or not verify.is_file():
1706
- return {"reward": None, "rewards": {}}
1707
- return self._run_verifier(session, verify, state, VERIFY_TIMEOUT_S)
1708
-
1709
- def _run_verifier(self, session: Session, verify: Path, state: dict, timeout_s: float) -> dict:
1710
- assert session.state is not None
1711
- if not verify.is_file():
1712
- fail("host", f"the task's verify.py is missing at {verify}")
1713
- dump = json.dumps(state)
1714
- # The verifier is the world's code: it runs confined like a worker, with
1715
- # a scrubbed environment, and is told the state on stdin. It sees no
1716
- # secret of this process, be it the host's or a worker's.
1717
- home = session.state.session_dir / "verify"
1718
- home.mkdir(parents=True, exist_ok=True)
1719
- try:
1720
- proc = subprocess.run(
1721
- confined_command(verify),
1722
- input=dump,
1723
- check=False,
1724
- capture_output=True,
1725
- text=True,
1726
- timeout=timeout_s,
1727
- cwd=str(verify.parent),
1728
- env=verifier_environment(home=home),
1729
- )
1730
- except subprocess.TimeoutExpired:
1731
- fail("host", f"verify.py timed out after {timeout_s:g}s")
1732
- if proc.returncode != 0:
1733
- fail(
1734
- "host",
1735
- f"verify.py exited {proc.returncode}: {proc.stderr.strip()[-800:]}",
1736
- )
1737
- try:
1738
- rewards = json.loads(proc.stdout.strip().splitlines()[-1])
1739
- except (json.JSONDecodeError, IndexError):
1740
- fail(
1741
- "host",
1742
- f"verify.py printed no rewards JSON: {proc.stdout.strip()[-400:]}",
1743
- )
1744
- if not isinstance(rewards, dict):
1745
- fail("host", "verify.py rewards output is not an object")
1746
- # The runner's shape (``api_runner.grade_scenario``): the scalar under
1747
- # ``reward``, every other key the verifier printed under ``rewards``.
1748
- reward = rewards.get("reward")
1749
- return {
1750
- "reward": float(reward) if isinstance(reward, (int, float)) else None,
1751
- "rewards": {
1752
- k: (float(v) if isinstance(v, (int, float)) else None) for k, v in rewards.items() if k != "reward"
1753
- },
1754
- }
1402
+ return self._control(session, "POST", "grade", body)
1403
+ assert session.runtime is not None
1404
+ return session.runtime.grade(report)
1755
1405
 
1756
1406
  def call(self, session_id: str, tool: str, args: dict) -> dict:
1757
- """Invoke one of the world's vendor routes by operation name, in process.
1758
- The arg shape mirrors the runner's ``execute_route``: ``path``/``query``/
1759
- ``body``, or leftover top-level keys as the body."""
1407
+ """Invoke one of the world's tools or vendor routes by name, in process.
1408
+ A route's arg shape mirrors the runner's ``execute_route``: ``path``/
1409
+ ``query``/``body``, or leftover top-level keys as the body."""
1760
1410
  with self.using(session_id) as session:
1761
1411
  if session.worker is not None:
1762
- return self._worker_control(
1763
- session.worker,
1764
- "POST",
1765
- f"/__host/sessions/{session_id}/call",
1766
- {"tool": tool, "args": args},
1767
- )
1768
- if session.tools is not None:
1769
- # A tool by name; on a tree with connector.toml, an operation
1770
- # by name too, answered by the route over the same store.
1771
- if (
1772
- session.spec is not None
1773
- and session.app is not None
1774
- and tool not in (session.tools.version.handlers or {})
1775
- and tool in session.spec.operations
1776
- ):
1777
- return self._call(session, tool, args)
1778
- return session.tools.call(tool, args)
1779
- return self._call(session, tool, args)
1780
-
1781
- def _call(self, session: Session, tool: str, args: dict) -> dict:
1782
- assert session.app is not None and session.spec is not None
1783
- operation = session.spec.operations.get(tool)
1784
- if operation is None:
1785
- known = ", ".join(sorted(session.spec.operations)) or "(none)"
1786
- fail("host", f"unknown tool '{tool}'; this world serves: {known}")
1787
- if session.task_spec is not None and not session.task_spec.allows_tool(tool):
1788
- allowed = ", ".join(session.task_spec.tools or ())
1789
- fail("tool_not_allowed", f"tool '{tool}' is not allowed by this session's task; it allows: {allowed}")
1790
- method, target, raw = operation_request(session.spec, operation, args)
1791
- headers, credential_query = world_credential(session)
1792
- status, answer, _ = session.app.handle(method, with_query(target, credential_query), headers, raw, "127.0.0.1")
1793
- return {"status": status, "body": answer}
1412
+ return self._control(session, "POST", "call", {"tool": tool, "args": args})
1413
+ assert session.runtime is not None
1414
+ return session.runtime.call(tool, args)
1415
+
1416
+
1417
+ #: The session protocol (:data:`verbs.SESSION_VERBS`) bound to the host's
1418
+ #: operations, by route. Every row of the table is served: the local session
1419
+ #: (``local.py``) binds the same rows to its own, so the two cannot drift.
1420
+ HOSTED_OPERATIONS: dict[str, Callable[..., dict]] = {
1421
+ "GET tools": WorldHost.tools,
1422
+ "GET task": WorldHost.task,
1423
+ "GET state": WorldHost.state,
1424
+ "POST grade": WorldHost.grade,
1425
+ "POST reset": WorldHost.reset,
1426
+ "POST seed": WorldHost.seed,
1427
+ "POST call": WorldHost.call,
1428
+ "POST close": WorldHost.close,
1429
+ "POST renew": WorldHost.renew,
1430
+ "POST export": WorldHost.export,
1431
+ "DELETE <session>": WorldHost.close,
1432
+ }
1433
+ assert set(HOSTED_OPERATIONS) == {verb.route for verb in SESSION_VERBS}, "the host serves every session verb"
1794
1434
 
1795
1435
 
1796
1436
  # --------------------------------------------------------------------------- #
@@ -1829,21 +1469,6 @@ def session_from_host(host_header: str | None) -> tuple[str, str] | None:
1829
1469
  #: refused at open rather than admitted with no credential.
1830
1470
  SUPPORTED_AUTH_SCHEMES = ("none", "header", "bearer", "basic", "query", "oauth2")
1831
1471
 
1832
- #: A caller that satisfies the host's session-token gate has already been
1833
- #: authorized; the host then presents the credential the WORLD itself expects,
1834
- #: so the emulated vendor's own auth check passes. The session token is that
1835
- #: credential; with no session token a sentinel satisfies the world's
1836
- #: non-empty check (the host's gate is the real access control either way).
1837
- _WORLD_AUTH_SENTINEL = "gateway-session"
1838
-
1839
-
1840
- def _code_of(cached: CachedVersion) -> str:
1841
- """What world-authored code a version runs, for a refusal message."""
1842
- if cached.tools is not None:
1843
- return "mock-tools handlers"
1844
- assert cached.settings is not None and cached.settings.handlers is not None
1845
- return f"api handlers module {cached.settings.handlers.name}"
1846
-
1847
1472
 
1848
1473
  def unsupported_auth(spec: Spec) -> str | None:
1849
1474
  if spec.scheme in SUPPORTED_AUTH_SCHEMES:
@@ -1854,15 +1479,13 @@ def unsupported_auth(spec: Spec) -> str | None:
1854
1479
 
1855
1480
 
1856
1481
  def world_credential(session: Session) -> tuple[dict[str, str], dict[str, str]]:
1857
- """(headers, query) carrying the world's own credential for this session:
1858
- the session token in the vendor's shape (:func:`api.vendor_credential`),
1859
- or for an oauth2 world the grant the host minted for itself."""
1860
- spec = session.spec
1861
- assert spec is not None, "a mock-tools session has no http surface to present a credential on"
1862
- unsupported = unsupported_auth(spec)
1863
- if unsupported:
1864
- fail("host", unsupported)
1865
- return vendor_credential(spec, session.token or _WORLD_AUTH_SENTINEL, grant=session.grant)
1482
+ """(headers, query) carrying the world's own credential for this session.
1483
+ A caller that satisfies the host's session-token gate has already been
1484
+ authorized; the host then presents the credential the WORLD itself expects
1485
+ (the session token in the vendor's shape, or an oauth2 world's grant), so
1486
+ the emulated vendor's own auth check passes."""
1487
+ assert session.runtime is not None, "a session on a worker presents its credential there"
1488
+ return session.runtime.credential()
1866
1489
 
1867
1490
 
1868
1491
  def bearer_of(headers: dict[str, str]) -> str | None:
@@ -2123,34 +1746,17 @@ def make_host_handler(
2123
1746
  if len(parts) >= 3 and parts[:2] == ["__host", "sessions"]:
2124
1747
  sid = parts[2]
2125
1748
  verb = parts[3] if len(parts) > 3 else None
2126
- if method == "DELETE" and verb is None:
2127
- return self._reply(200, host.close(sid))
2128
- if method == "POST" and verb == "renew":
2129
- return self._reply(200, host.renew(sid))
2130
- if method == "POST" and verb == "reset":
2131
- return self._reply(200, host.reset(sid))
2132
- if method == "POST" and verb == "seed":
2133
- return self._reply(200, host.seed(sid, body.get("args") or {}))
2134
- if method == "POST" and verb == "export" and len(parts) == 4:
2135
- known = body.get("knownSha256")
2136
- return self._reply(200, host.export(sid, known if isinstance(known, str) else None))
2137
1749
  if method == "POST" and verb == "export" and len(parts) == 5:
2138
1750
  url = body.get("url")
2139
1751
  if not isinstance(url, str) or not url.startswith(("https://", "http://")):
2140
1752
  return self._reply(400, {"error": "url must be the presigned upload url"})
2141
1753
  return self._reply(200, host.upload_export(sid, parts[4], url))
2142
- if method == "GET" and verb == "state":
2143
- return self._reply(200, host.state(sid))
2144
- if method == "POST" and verb == "grade":
2145
- report = body.get("report")
2146
- if report is not None and not isinstance(report, str):
2147
- return self._reply(400, {"error": "report must be a string"})
2148
- return self._reply(200, host.grade(sid, report))
2149
- if method == "POST" and verb == "call":
2150
- tool = body.get("tool")
2151
- if not isinstance(tool, str):
2152
- return self._reply(400, {"error": "tool must be a string"})
2153
- return self._reply(200, host.call(sid, tool, body.get("args") or {}))
1754
+ row = session_verb(method, verb)
1755
+ if row is None or len(parts) > 4:
1756
+ return self._reply(
1757
+ 404, unknown_verb(method, verb, hosted=True, prefix=f"/__host/sessions/{sid}/")
1758
+ )
1759
+ return self._reply(200, HOSTED_OPERATIONS[row.route](host, sid, **row.read(body)))
2154
1760
  return self._reply(404, {"error": "unknown control route"})
2155
1761
  except ContractError as error:
2156
1762
  code = error.detail.get("code", "host")
@@ -2164,7 +1770,9 @@ def make_host_handler(
2164
1770
  status = 404
2165
1771
  else:
2166
1772
  status = 400
2167
- return self._reply(status, {"error": code, "detail": str(error)})
1773
+ return self._reply(
1774
+ status, {"error": code, "detail": str(error), "message": str(error.detail.get("message", ""))}
1775
+ )
2168
1776
  except KeyError as error:
2169
1777
  return self._reply(400, {"error": "missing field", "field": str(error)})
2170
1778
  except WorkerGone as error:
@@ -2527,9 +2135,11 @@ def serve(cache_root: str | Path, *, port: int = 8080, host_addr: str = "0.0.0.0
2527
2135
  worlds_domain=worlds_domain,
2528
2136
  memory_mb=int(os.environ.get("WORLDS_WORKER_MEMORY_MB") or DEFAULT_WORKER_MEMORY_MB),
2529
2137
  budget_mb=int(os.environ.get("WORLDS_WORKER_BUDGET_MB") or DEFAULT_WORKER_BUDGET_MB),
2530
- footprint_mb=int(os.environ["WORLDS_WORKER_FOOTPRINT_MB"])
2531
- if os.environ.get("WORLDS_WORKER_FOOTPRINT_MB")
2532
- else DEFAULT_WORKER_FOOTPRINT_MB,
2138
+ footprint_mb=(
2139
+ int(os.environ["WORLDS_WORKER_FOOTPRINT_MB"])
2140
+ if os.environ.get("WORLDS_WORKER_FOOTPRINT_MB")
2141
+ else DEFAULT_WORKER_FOOTPRINT_MB
2142
+ ),
2533
2143
  )
2534
2144
  world_host = WorldHost(
2535
2145
  Path(cache_root),