@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
@@ -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
@@ -69,26 +67,24 @@ from contextlib import contextmanager
69
67
  from dataclasses import dataclass, field
70
68
  from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
71
69
  from pathlib import Path
72
- from typing import Any, Protocol
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,40 +100,24 @@ 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,
110
+ DEFAULT_WORKER_FOOTPRINT_MB,
128
111
  DEFAULT_WORKER_MEMORY_MB,
129
112
  Worker,
130
113
  WorkerCapacity,
131
114
  WorkerGone,
132
115
  WorkerPool,
133
- confined_command,
134
- verifier_environment,
135
116
  )
136
117
 
137
118
  #: The world tree inside an api bundle, or the bundle root for a bare tree.
138
119
  BUNDLED_WORLD = "server/world"
139
- API_BUNDLE = "gateway-api-world.toml"
140
- VERIFY_TIMEOUT_S = 30.0
120
+ WORLD_SPEC = "schema/world.json"
141
121
  #: How long a session lives with no control call or request renewing it.
142
122
  DEFAULT_LEASE_S = 3600.0
143
123
  #: How often the host sweeps expired leases.
@@ -201,28 +181,6 @@ MAX_BUNDLE_MEMBERS = 200_000
201
181
  DEFAULT_MAX_BODY_MB = 32
202
182
 
203
183
 
204
- # --------------------------------------------------------------------------- #
205
- # Reflink: a session's state is a copy-on-write clone of the version snapshot.
206
- # --------------------------------------------------------------------------- #
207
-
208
- _FICLONE = 0x40049409 # ioctl: clone one file's extents into another (btrfs/XFS)
209
-
210
-
211
- def clone_file(src: Path, dst: Path) -> None:
212
- """Copy ``src`` to ``dst`` cheaply. A reflink (``FICLONE``) shares the
213
- version snapshot's blocks copy-on-write, so opening a session costs the
214
- same whatever the snapshot's size; a filesystem without reflink falls back
215
- to a plain copy, which is what the pod engine does today."""
216
- dst.parent.mkdir(parents=True, exist_ok=True)
217
- try:
218
- with open(src, "rb") as s, open(dst, "wb") as d:
219
- fcntl.ioctl(d.fileno(), _FICLONE, s.fileno())
220
- return
221
- except OSError:
222
- pass # not supported here (tmpfs, ext4, cross-device) — copy instead
223
- shutil.copyfile(src, dst)
224
-
225
-
226
184
  OBJECT_STORE_ANY = "any"
227
185
  _ORIGIN_HOST = re.compile(r"^[A-Za-z0-9.-]+(:[0-9]+)?$")
228
186
 
@@ -342,31 +300,21 @@ def upload_file(url: str, path: Path, sha256: str, size: int, content_type: str
342
300
 
343
301
 
344
302
  def world_tree(bundle: Path) -> Path:
345
- """The gateway-world tree inside an extracted bundle. ``bench push`` packages
346
- a schema world as its api bundle with the tree under ``server/world``; a bare
347
- tree is its own root."""
348
- nested = bundle / BUNDLED_WORLD
349
- if (bundle / API_BUNDLE).is_file() and (nested / "schema/world.json").is_file():
350
- return nested
351
- if (bundle / "schema/world.json").is_file():
352
- 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
353
310
  fail(
354
311
  "host",
355
- f"{bundle} holds no schema world the host can open (no {BUNDLED_WORLD}/schema/world.json "
356
- "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",
357
314
  )
358
315
  raise AssertionError # fail() never returns
359
316
 
360
317
 
361
- def _scenario_dir(bundle: Path, tree: Path, task: str) -> Path | None:
362
- """A task's scenario directory, checked at the bundle root first (where
363
- ``build_api_bundle`` writes them) then in the tree."""
364
- for root in (bundle / SCENARIOS / task, tree / SCENARIOS / task):
365
- if (root / "scenario.toml").is_file():
366
- return root
367
- return None
368
-
369
-
370
318
  # --------------------------------------------------------------------------- #
371
319
  # Per-version cache: bundle + snapshot + parsed spec, fetched once per host.
372
320
  # --------------------------------------------------------------------------- #
@@ -396,12 +344,11 @@ class CachedVersion:
396
344
  tools: ToolsVersion | None = None
397
345
 
398
346
  @property
399
- def needs_worker(self) -> bool:
400
- """Whether the version runs world-authored code: a mock-tools world
401
- always (its tools ARE handlers), an api world when it declares some."""
402
- if self.tools is not None:
403
- return True
404
- 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
405
352
 
406
353
  def router(self) -> Router:
407
354
  """A fresh router per session: routes are compiled from the shared spec,
@@ -409,6 +356,24 @@ class CachedVersion:
409
356
  assert self.spec is not None and self.settings is not None
410
357
  return Router(self.spec, self.settings)
411
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
+
412
377
 
413
378
  class VersionCache:
414
379
  """Every world version this host has seen, on local disk. The first session
@@ -554,61 +519,6 @@ class VersionCache:
554
519
  # --------------------------------------------------------------------------- #
555
520
 
556
521
 
557
- class HostWorldState(WorldState):
558
- """A session's world, opened by cloning the version's cached snapshot into a
559
- file on the host's own volume — the reflink is the whole per-session cost.
560
- Otherwise a plain :class:`WorldState`."""
561
-
562
- def __init__(self, cached: CachedVersion, session_dir: Path):
563
- self._session_dir = Path(session_dir)
564
- self._session_dir.mkdir(parents=True, exist_ok=True)
565
- self._cached = cached
566
- self._database: Path | None = None
567
- super().__init__(cached.tree)
568
-
569
- @property
570
- def session_dir(self) -> Path:
571
- return self._session_dir
572
-
573
- def _open(self, snapshot: Path | None, *, initial: bool = True) -> None:
574
- # A snapshot start is a clone of the version's cached snapshot into this
575
- # session's file; the legacy no-snapshot path stays as the base class runs it.
576
- if snapshot is None:
577
- return super()._open(None, initial=initial)
578
- if self.store is not None:
579
- self.store.close()
580
- if self._database is not None:
581
- self._database.unlink(missing_ok=True)
582
- database = self._session_dir / f"{uuid.uuid4().hex}.db"
583
- clone_file(snapshot, database)
584
- self.store = snapshots.SQLiteStore.open(database, self.contract, audit=False)
585
- self._database = database
586
-
587
- def export(self, destination: Path) -> Path:
588
- """The session's state as one sqlite file: the store's own audited
589
- online backup, consistent while requests keep writing."""
590
- assert self.store is not None
591
- with self._lock:
592
- return self.store.snapshot(destination)
593
-
594
- def restore(self, source: Path) -> None:
595
- """Continue from a file :meth:`export` wrote. The file is audited row by
596
- row on open: it came over the network, not from this store."""
597
- with self._lock:
598
- if self.store is not None:
599
- self.store.close()
600
- if self._database is not None:
601
- self._database.unlink(missing_ok=True)
602
- database = self._session_dir / f"{uuid.uuid4().hex}.db"
603
- clone_file(source, database)
604
- self.store = snapshots.SQLiteStore.open(database, self.contract, audit=True)
605
- self._database = database
606
-
607
- def close(self) -> None:
608
- super().close()
609
- shutil.rmtree(self._session_dir, ignore_errors=True)
610
-
611
-
612
522
  @dataclass
613
523
  class Export:
614
524
  """A session's state copied to a file on this host, hashed, waiting for the
@@ -644,12 +554,9 @@ class Session:
644
554
  tree: Path
645
555
  #: Unix time the lease runs out unless renewed.
646
556
  lease_until: float
647
- #: The world, when this process serves it. None for a session placed on a
648
- #: worker, whose state lives in that process.
649
- state: HostWorldState | None = None
650
- app: WorldApp | None = None
651
- #: The mock-tools world, when this process (a worker) serves one.
652
- 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
653
560
  #: The version worker serving this session, or None for in-process.
654
561
  worker: Worker | None = None
655
562
  #: The version's static ui, served by the supervisor for this session.
@@ -659,9 +566,6 @@ class Session:
659
566
  #: browser surface.
660
567
  browser_url: str | None = None
661
568
  browser_token: str | None = None
662
- #: For an oauth2 world: the bearer this world minted for the host itself,
663
- #: presented on behalf of a caller who authenticated with the session token.
664
- grant: str | None = None
665
569
  #: Requests inside the world right now. A session is only torn down once
666
570
  #: this reaches zero, so a close or an expiry never pulls the database out
667
571
  #: from under a handler mid-request.
@@ -686,6 +590,12 @@ class Session:
686
590
  #: ``grade``, and it lives under ``<session>/task/`` (:mod:`tasks`).
687
591
  task_spec: TaskSpec | None = None
688
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
+
689
599
  @property
690
600
  def task_key(self) -> tuple[str | None, dict | None]:
691
601
  """What an open retry must match: the bundled name or the spec itself."""
@@ -909,54 +819,35 @@ class WorldHost:
909
819
  dependencies = self._dependency_worlds(cached, deps)
910
820
  # A session task runs on either shape the host serves: an api bundle
911
821
  # clones its snapshot and grades by the spec; a schema world copies its
912
- # template and grades with its bundled verifiers (:func:`inline_task`
913
- # refuses a spec that brings a grader of its own). Its allow-list may
914
- # 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.
915
825
  if cached.spec is not None:
916
826
  unsupported = unsupported_auth(cached.spec)
917
827
  if unsupported:
918
828
  fail("host", unsupported)
919
829
  if spec is not None:
920
- if cached.tools is not None:
921
- self._check_task_tools(spec, served_with_dependencies(cached.tools, dependencies))
922
- else:
923
- assert cached.spec is not None
924
- self._check_task_tools(spec, cached.spec.operations)
830
+ self._check_task_tools(spec, cached.served_tools(dependencies))
925
831
  browser_url, browser_token = browser_lease(browser)
926
832
  if cached.needs_worker and not self.run_handlers:
927
833
  if self.workers is None:
928
834
  fail(
929
835
  "host",
930
- f"version {version_id} runs world-authored code ({_code_of(cached)}); "
836
+ f"version {version_id} runs world-authored code ({cached.authored_code}); "
931
837
  "this host runs none in its process and has no version workers",
932
838
  )
933
839
  return self._open_on_worker(
934
840
  cached, session_id, bundle_url, task, spec, token, browser_url, browser_token, restore, deps
935
841
  )
936
- if cached.tools is not None:
937
- return self._open_tools(cached, cached.tools, session_id, task, spec, token, restore, dependencies)
938
- assert cached.snapshot is not None and cached.spec is not None
939
- state = HostWorldState(cached, self.sessions_root / session_id)
940
- try:
941
- if spec is not None:
942
- self._check_task_entities(spec, state)
943
- write_task_dir(spec, state.session_dir)
944
- self._apply_task_seed(state, spec)
945
- else:
946
- assert task is not None
947
- self._apply_scenario(cached, state, task)
948
- restored = self._restore_into(restore, self.sessions_root / session_id, state.restore)
949
- except Exception:
950
- state.close()
951
- raise
952
- # ``handlers={}`` for a code-free world: WorldApp would otherwise import
953
- # the module itself, and only a worker may do that.
954
- app = WorldApp(
955
- state,
956
- cached.router(),
957
- token,
958
- handlers=cached.handlers or {},
959
- 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),
960
851
  )
961
852
  session = Session(
962
853
  session_id=session_id,
@@ -967,92 +858,13 @@ class WorldHost:
967
858
  bundle=cached.bundle,
968
859
  tree=cached.tree,
969
860
  lease_until=time.time() + self.lease_s,
970
- state=state,
971
- app=app,
861
+ runtime=runtime,
972
862
  ui=cached.ui,
973
863
  browser_url=browser_url,
974
864
  browser_token=browser_token,
975
- restored=restored,
976
- task_spec=spec,
977
- )
978
- if cached.spec.scheme == "oauth2":
979
- # The host's own client-credentials grant, so a caller admitted by
980
- # the session token is presented to the world as a granted client.
981
- issued = app.router.issue_token(
982
- {"grant_type": "client_credentials", "client_secret": token or ""},
983
- token,
984
- )
985
- session.grant = issued["access_token"] if issued else None
986
- self._register(session)
987
- return self._describe(session)
988
-
989
- def _open_tools(
990
- self,
991
- cached: CachedVersion,
992
- tools: ToolsVersion,
993
- session_id: str,
994
- task: str | None,
995
- spec: TaskSpec | None,
996
- token: str | None,
997
- restore: dict[str, str] | None,
998
- dependencies: dict[str, DependencyWorld],
999
- ) -> dict:
1000
- """A schema world's session in this (worker) process: a copy of the
1001
- version's template, executed through its handlers, on a bundled ``task``
1002
- or on the session's own ``spec`` (its seed on the copy, the bundle's
1003
- verifiers as its grade), beside a copy of each dependency world's. When
1004
- the tree carries connector.toml the same session answers its HTTP
1005
- surface over the same store (:class:`ToolsWorldState` under a
1006
- :class:`WorldApp`), and the static ui its ``[ui]`` declares (served by
1007
- whichever process fronts the session: the supervisor for a worker's
1008
- session, this one when it runs the handlers itself); without it there
1009
- is no http surface, so no ui and no browser, and the agent reaches the
1010
- world through ``call`` alone."""
1011
- session_dir = self.sessions_root / session_id
1012
- allowed = frozenset(spec.tools) if spec is not None and spec.tools is not None else None
1013
- if spec is not None:
1014
- world = ToolsWorld(
1015
- tools, session_dir, inline_task(spec), seed=spec.seed, allowed=allowed, dependencies=dependencies
1016
- )
1017
- else:
1018
- assert task is not None
1019
- world = ToolsWorld(tools, session_dir, task, dependencies=dependencies)
1020
- app: WorldApp | None = None
1021
- try:
1022
- if spec is not None:
1023
- # Under the session, as an api session keeps it: where a grade
1024
- # and a restart find the task.
1025
- write_task_dir(spec, session_dir)
1026
- restored = self._restore_into(restore, session_dir, world.restore)
1027
- if cached.spec is not None:
1028
- app = WorldApp(
1029
- ToolsWorldState(world, cached.tree),
1030
- cached.router(),
1031
- token,
1032
- handlers=cached.handlers or {},
1033
- allowed=allowed,
1034
- )
1035
- except Exception:
1036
- world.close()
1037
- raise
1038
- session = Session(
1039
- session_id=session_id,
1040
- version_id=cached.version_id,
1041
- task=task,
1042
- spec=cached.spec,
1043
- token=token,
1044
- bundle=cached.bundle,
1045
- tree=cached.tree,
1046
- lease_until=time.time() + self.lease_s,
1047
- app=app,
1048
- tools=world,
1049
- ui=cached.ui,
1050
- restored=restored,
865
+ restored=runtime.restored,
1051
866
  task_spec=spec,
1052
867
  )
1053
- if app is not None and cached.spec is not None and cached.spec.scheme == "oauth2":
1054
- issued = app.router.issue_token({"grant_type": "client_credentials", "client_secret": token or ""}, token)
1055
- session.grant = issued["access_token"] if issued else None
1056
868
  self._register(session)
1057
869
  return self._describe(session)
1058
870
 
@@ -1241,11 +1053,8 @@ class WorldHost:
1241
1053
  exports = self.sessions_root / session_id / "exports"
1242
1054
  shutil.rmtree(exports, ignore_errors=True)
1243
1055
  path = exports / f"{uuid.uuid4().hex}.sqlite"
1244
- if session.tools is not None:
1245
- session.tools.export(path)
1246
- else:
1247
- assert session.state is not None
1248
- session.state.export(path)
1056
+ assert session.runtime is not None
1057
+ session.runtime.export(path)
1249
1058
  sha256, size = file_digest(path)
1250
1059
  if known_sha256 is not None and sha256 == known_sha256:
1251
1060
  path.unlink(missing_ok=True)
@@ -1328,11 +1137,8 @@ class WorldHost:
1328
1137
  self._counters[f"closed.{reason}"] += 1
1329
1138
  self._session_seconds += session.seconds
1330
1139
  if session.worker is None:
1331
- if session.tools is not None:
1332
- session.tools.close()
1333
- return
1334
- assert session.state is not None
1335
- session.state.close()
1140
+ assert session.runtime is not None
1141
+ session.runtime.close()
1336
1142
  return
1337
1143
  worker = session.worker
1338
1144
  with self._lock:
@@ -1357,7 +1163,7 @@ class WorldHost:
1357
1163
  answer = json.loads(payload or b"null")
1358
1164
  if status != 200:
1359
1165
  detail = answer if isinstance(answer, dict) else {}
1360
- 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))
1361
1167
  return answer if isinstance(answer, dict) else {"result": answer}
1362
1168
 
1363
1169
  def lose_worker(self, worker: Worker) -> list[str]:
@@ -1421,6 +1227,7 @@ class WorldHost:
1421
1227
  "capacity": self.max_sessions,
1422
1228
  "draining": self.draining,
1423
1229
  "workers": self.worker_count(),
1230
+ "maxWorkers": self.workers.max_workers if self.workers is not None else 0,
1424
1231
  "versions": self.cache.version_ids(),
1425
1232
  "versionsInUse": versions_in_use,
1426
1233
  "uptimeSeconds": time.time() - self.started_at,
@@ -1469,78 +1276,38 @@ class WorldHost:
1469
1276
  lines.append(f'worlds_host_requests_total{{surface="{surface}"}} {counters.get(f"requests.{surface}", 0)}')
1470
1277
  return "\n".join(lines) + "\n"
1471
1278
 
1472
- def _apply_scenario(self, cached: CachedVersion, state: HostWorldState, task: str) -> None:
1473
- """Start the session in its task's scenario. The compiled snapshot the
1474
- session is cloned from IS the base state, so a scenario with no seed
1475
- overlay (the synthesized ``default``) needs nothing; one with an overlay
1476
- applies it on top of the pinned snapshot the way the runner does."""
1477
- scenario = _scenario_dir(cached.bundle, cached.tree, task)
1478
- if scenario is None:
1479
- if task in state.scenarios():
1480
- state.apply_scenario(task) # a tree-authored scenario
1481
- return
1482
- fail(
1483
- "host",
1484
- f"no scenario '{task}' in this world; it has {', '.join(state.scenarios()) or 'default'}",
1485
- )
1486
- overlay = snapshots.scenario_overlay(scenario)
1487
- if not overlay:
1488
- return # base state; the cloned snapshot already holds it
1489
- digest = state.digest
1490
- if digest is None:
1491
- fail("host", "a scenario overlay needs a compiled snapshot to apply against")
1492
- state.seed({"base": digest, "rows": overlay, "mode": "replace"})
1493
-
1494
- @staticmethod
1495
- def _check_task_entities(spec: TaskSpec, state: HostWorldState) -> None:
1496
- """A task is refused for a world that does not define every entity it
1497
- names. The seed would fail on its own; an assertion over an unknown
1498
- entity would not, selecting no rows, so `absent` or `count: eq 0`
1499
- checks would pass on a typo and grade a task that can never be graded."""
1500
- unknown = unknown_task_entities(spec, state.contract.entities)
1501
- if unknown:
1502
- defined = ", ".join(sorted(state.contract.entities)) or "none"
1503
- fail(
1504
- "task",
1505
- f"the task names {', '.join(unknown)}, which this world does not define; its entities are {defined}",
1506
- "/task",
1507
- )
1508
-
1509
1279
  def _dependency_worlds(self, cached: CachedVersion, deps: list[DependencyRef]) -> dict[str, DependencyWorld]:
1510
1280
  """The dependency versions a session opens beside ``cached``, cached the
1511
1281
  way the root is (a worker imports their handlers too). Every alias the
1512
1282
  root's manifest declares must be resolved, and nothing else: a version
1513
1283
  without ``[dependencies]`` opened with any is refused, as is a
1514
1284
  dependency that is not a schema world."""
1285
+ declared = cached.declared_dependencies
1515
1286
  if not deps:
1516
- if cached.tools is not None and cached.tools.dependencies:
1517
- declared = ", ".join(sorted(cached.tools.dependencies))
1518
- 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")
1519
1290
  return {}
1520
- if cached.tools is None:
1521
- fail("host", f"version {cached.version_id} is an api bundle; only a schema world opens beside dependencies")
1522
- raise AssertionError # fail() never returns
1523
1291
  worlds: dict[str, DependencyWorld] = {}
1524
1292
  for ref in deps:
1525
- declared = cached.tools.dependencies.get(ref.alias)
1526
- if declared is None:
1527
- 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"
1528
1296
  fail("host", f"version {cached.version_id} declares no dependency '{ref.alias}' (it declares: {known})")
1529
1297
  raise AssertionError # fail() never returns
1530
1298
  dep = self.cache.ensure(ref.version_id, *self._trusted_version(ref.bundle_url, ref.snapshot))
1531
1299
  if dep.tools is None:
1532
1300
  fail("host", f"dependency '{ref.alias}' ({ref.version_id}) is an api bundle, not a schema world")
1533
1301
  raise AssertionError # fail() never returns
1534
- worlds[ref.alias] = DependencyWorld.of(declared, dep.tools)
1535
- 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
1536
1304
  return worlds
1537
1305
 
1538
1306
  @staticmethod
1539
1307
  def _check_task_tools(spec: TaskSpec, served_tools: Iterable[str]) -> None:
1540
1308
  """A task's allow-list names tools the world serves, every one of them:
1541
1309
  a misspelt name would narrow the list without anyone noticing. The
1542
- served tools are an api world's operations or a mock-tools world's
1543
- handlers."""
1310
+ served tools are what :meth:`CachedVersion.served_tools` lists."""
1544
1311
  served_tools = list(served_tools)
1545
1312
  unknown = unknown_task_tools(spec, served_tools)
1546
1313
  if unknown:
@@ -1551,14 +1318,6 @@ class WorldHost:
1551
1318
  "/task/tools",
1552
1319
  )
1553
1320
 
1554
- def _apply_task_seed(self, state: HostWorldState, spec: TaskSpec) -> None:
1555
- """Start the session in its own task's state: the version's snapshot
1556
- (already cloned) with the task's rows on top, as a session seed lands
1557
- them. A task without a seed starts on the base data."""
1558
- if spec.seed is None:
1559
- return
1560
- state.seed_live(spec.seed["rows"], spec.seed["mode"], spec.seed.get("redact", "off"))
1561
-
1562
1321
  @contextmanager
1563
1322
  def using(self, session_id: str, *, touch: bool = True) -> Iterator[Session]:
1564
1323
  """The session for the duration of one request: its lease renewed (any
@@ -1593,186 +1352,85 @@ class WorldHost:
1593
1352
 
1594
1353
  # -- control operations (the platform's rendezvous, run in-process) ----- #
1595
1354
 
1596
- 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:
1597
1359
  with self.using(session_id) as session:
1598
1360
  if session.worker is not None:
1599
- return self._worker_control(session.worker, "POST", f"/__host/sessions/{session_id}/reset", {})
1600
- if session.tools is not None:
1601
- return session.tools.reset()
1602
- assert session.state is not None
1603
- # Back to the task's starting state: re-clone the snapshot, then
1604
- # re-apply the task's seed or the scenario overlay if it had one.
1605
- session.state.reset()
1606
- if session.task_spec is not None:
1607
- self._apply_task_seed(session.state, session.task_spec)
1608
- else:
1609
- assert session.task is not None
1610
- self._apply_scenario(self.cache._versions[session.version_id], session.state, session.task)
1611
- return {"reset": True}
1361
+ return self._control(session, "GET", "tools", None)
1362
+ assert session.runtime is not None
1363
+ return {"tools": session.runtime.served()}
1612
1364
 
1613
- def seed(self, session_id: str, args: dict) -> dict:
1614
- rows = args.get("rows")
1615
- if not isinstance(rows, dict):
1616
- fail(
1617
- "host",
1618
- 'seed needs rows as {"rows": {entity: [row, ...]}, "mode": "append"|"replace"}; '
1619
- "a dependency's entity is named alias.entity",
1620
- )
1621
- mode = args.get("mode", "append")
1622
- 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()
1623
1371
 
1624
- redact = parse_mode(args.get("redact"), "/args/redact")
1372
+ def reset(self, session_id: str) -> dict:
1625
1373
  with self.using(session_id) as session:
1626
1374
  if session.worker is not None:
1627
- return self._worker_control(
1628
- session.worker, "POST", f"/__host/sessions/{session_id}/seed", {"args": args}
1629
- )
1630
- if session.tools is not None:
1631
- if redact != "off":
1632
- fail("host", "a mock-tools world has no [redact] policy; seed it with redact=off")
1633
- return session.tools.seed(args)
1634
- assert session.state is not None
1635
- # Onto the live state, the way the runner's session seed lands: an
1636
- # append upserts by key, a replace swaps the named entities.
1637
- session.state.seed_live(rows, mode, redact)
1638
- return {
1639
- "seeded": sum(len(v) for v in rows.values()),
1640
- "mode": mode,
1641
- **({"redact": redact} if redact != "off" else {}),
1642
- "entity_counts": {
1643
- entity: len(session.state.rows(entity))
1644
- for entity in rows
1645
- if entity in session.state.contract.entities
1646
- },
1647
- }
1375
+ return self._control(session, "POST", "reset", {})
1376
+ assert session.runtime is not None
1377
+ return session.runtime.reset()
1648
1378
 
1649
- def state(self, session_id: str) -> dict:
1379
+ def seed(self, session_id: str, rows: dict, mode: str = "append", redact: str = "off") -> dict:
1650
1380
  with self.using(session_id) as session:
1651
1381
  if session.worker is not None:
1652
- return self._worker_control(session.worker, "GET", f"/__host/sessions/{session_id}/state", None)
1653
- if session.tools is not None:
1654
- return session.tools.state()
1655
- assert session.state is not None
1656
- return {**session.state.dump(), "snapshot": session.state.describe_snapshot()}
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)
1657
1386
 
1658
- def grade(self, session_id: str) -> dict:
1387
+ def state(self, session_id: str) -> dict:
1659
1388
  with self.using(session_id) as session:
1660
1389
  if session.worker is not None:
1661
- return self._worker_control(session.worker, "POST", f"/__host/sessions/{session_id}/grade", {})
1662
- if session.tools is not None:
1663
- return session.tools.grade()
1664
- return self._grade(session)
1665
-
1666
- def _grade(self, session: Session) -> dict:
1667
- assert session.state is not None
1668
- state = {**session.state.dump(), "snapshot": session.state.describe_snapshot()}
1669
- spec = session.task_spec
1670
- if spec is not None:
1671
- # The session's own task: its assertions are evaluated here, pure
1672
- # Python over the dump; its verify.py runs as a bundled one would.
1673
- if spec.grader is None:
1674
- return {"reward": None, "rewards": {}}
1675
- if spec.grader["kind"] == "assertions":
1676
- return evaluate_assertions(spec.grader["checks"], state)
1677
- if spec.graded_on_platform:
1678
- # A rubric is an LLM judge's brief. The host has no model, no
1679
- # key and no business calling one from a tenant's session: the
1680
- # platform grades it from the state and the calls log.
1681
- return {"reward": None, "rewards": {}, "pending": True, "grader": "rubric"}
1682
- verify = session.state.session_dir / "task" / "checks" / "verify.py"
1683
- return self._run_verifier(session, verify, state, spec.grader.get("timeoutSeconds") or VERIFY_TIMEOUT_S)
1684
- assert session.task is not None
1685
- scenario = _scenario_dir(session.bundle, session.tree, session.task)
1686
- verify = scenario / "checks" / "verify.py" if scenario else None
1687
- if verify is None or not verify.is_file():
1688
- return {"reward": None, "rewards": {}}
1689
- return self._run_verifier(session, verify, state, VERIFY_TIMEOUT_S)
1690
-
1691
- def _run_verifier(self, session: Session, verify: Path, state: dict, timeout_s: float) -> dict:
1692
- assert session.state is not None
1693
- if not verify.is_file():
1694
- fail("host", f"the task's verify.py is missing at {verify}")
1695
- dump = json.dumps(state)
1696
- # The verifier is the world's code: it runs confined like a worker, with
1697
- # a scrubbed environment, and is told the state on stdin. It sees no
1698
- # secret of this process, be it the host's or a worker's.
1699
- home = session.state.session_dir / "verify"
1700
- home.mkdir(parents=True, exist_ok=True)
1701
- try:
1702
- proc = subprocess.run(
1703
- confined_command(verify),
1704
- input=dump,
1705
- check=False,
1706
- capture_output=True,
1707
- text=True,
1708
- timeout=timeout_s,
1709
- cwd=str(verify.parent),
1710
- env=verifier_environment(home=home),
1711
- )
1712
- except subprocess.TimeoutExpired:
1713
- fail("host", f"verify.py timed out after {timeout_s:g}s")
1714
- if proc.returncode != 0:
1715
- fail(
1716
- "host",
1717
- f"verify.py exited {proc.returncode}: {proc.stderr.strip()[-800:]}",
1718
- )
1719
- try:
1720
- rewards = json.loads(proc.stdout.strip().splitlines()[-1])
1721
- except (json.JSONDecodeError, IndexError):
1722
- fail(
1723
- "host",
1724
- f"verify.py printed no rewards JSON: {proc.stdout.strip()[-400:]}",
1725
- )
1726
- if not isinstance(rewards, dict):
1727
- fail("host", "verify.py rewards output is not an object")
1728
- # The runner's shape (``api_runner.grade_scenario``): the scalar under
1729
- # ``reward``, every other key the verifier printed under ``rewards``.
1730
- reward = rewards.get("reward")
1731
- return {
1732
- "reward": float(reward) if isinstance(reward, (int, float)) else None,
1733
- "rewards": {
1734
- k: (float(v) if isinstance(v, (int, float)) else None) for k, v in rewards.items() if k != "reward"
1735
- },
1736
- }
1390
+ return self._control(session, "GET", "state", None)
1391
+ assert session.runtime is not None
1392
+ return session.runtime.state()
1393
+
1394
+ def grade(self, session_id: str, report: Optional[str] = None) -> dict:
1395
+ """Grade the session. ``report`` is the agent's own account of the run — the
1396
+ text a rubric judge reads; here it is put beside the state as ``report`` so a
1397
+ deterministic grader (assertions, verify.py) can check what the agent CLAIMED
1398
+ against what the calls show, without a judge."""
1399
+ with self.using(session_id) as session:
1400
+ if session.worker is not None:
1401
+ body = {"report": report} if report is not None else {}
1402
+ return self._control(session, "POST", "grade", body)
1403
+ assert session.runtime is not None
1404
+ return session.runtime.grade(report)
1737
1405
 
1738
1406
  def call(self, session_id: str, tool: str, args: dict) -> dict:
1739
- """Invoke one of the world's vendor routes by operation name, in process.
1740
- The arg shape mirrors the runner's ``execute_route``: ``path``/``query``/
1741
- ``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."""
1742
1410
  with self.using(session_id) as session:
1743
1411
  if session.worker is not None:
1744
- return self._worker_control(
1745
- session.worker,
1746
- "POST",
1747
- f"/__host/sessions/{session_id}/call",
1748
- {"tool": tool, "args": args},
1749
- )
1750
- if session.tools is not None:
1751
- # A tool by name; on a tree with connector.toml, an operation
1752
- # by name too, answered by the route over the same store.
1753
- if (
1754
- session.spec is not None
1755
- and session.app is not None
1756
- and tool not in (session.tools.version.handlers or {})
1757
- and tool in session.spec.operations
1758
- ):
1759
- return self._call(session, tool, args)
1760
- return session.tools.call(tool, args)
1761
- return self._call(session, tool, args)
1762
-
1763
- def _call(self, session: Session, tool: str, args: dict) -> dict:
1764
- assert session.app is not None and session.spec is not None
1765
- operation = session.spec.operations.get(tool)
1766
- if operation is None:
1767
- known = ", ".join(sorted(session.spec.operations)) or "(none)"
1768
- fail("host", f"unknown tool '{tool}'; this world serves: {known}")
1769
- if session.task_spec is not None and not session.task_spec.allows_tool(tool):
1770
- allowed = ", ".join(session.task_spec.tools or ())
1771
- fail("tool_not_allowed", f"tool '{tool}' is not allowed by this session's task; it allows: {allowed}")
1772
- method, target, raw = operation_request(session.spec, operation, args)
1773
- headers, credential_query = world_credential(session)
1774
- status, answer, _ = session.app.handle(method, with_query(target, credential_query), headers, raw, "127.0.0.1")
1775
- 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"
1776
1434
 
1777
1435
 
1778
1436
  # --------------------------------------------------------------------------- #
@@ -1811,21 +1469,6 @@ def session_from_host(host_header: str | None) -> tuple[str, str] | None:
1811
1469
  #: refused at open rather than admitted with no credential.
1812
1470
  SUPPORTED_AUTH_SCHEMES = ("none", "header", "bearer", "basic", "query", "oauth2")
1813
1471
 
1814
- #: A caller that satisfies the host's session-token gate has already been
1815
- #: authorized; the host then presents the credential the WORLD itself expects,
1816
- #: so the emulated vendor's own auth check passes. The session token is that
1817
- #: credential; with no session token a sentinel satisfies the world's
1818
- #: non-empty check (the host's gate is the real access control either way).
1819
- _WORLD_AUTH_SENTINEL = "gateway-session"
1820
-
1821
-
1822
- def _code_of(cached: CachedVersion) -> str:
1823
- """What world-authored code a version runs, for a refusal message."""
1824
- if cached.tools is not None:
1825
- return "mock-tools handlers"
1826
- assert cached.settings is not None and cached.settings.handlers is not None
1827
- return f"api handlers module {cached.settings.handlers.name}"
1828
-
1829
1472
 
1830
1473
  def unsupported_auth(spec: Spec) -> str | None:
1831
1474
  if spec.scheme in SUPPORTED_AUTH_SCHEMES:
@@ -1836,15 +1479,13 @@ def unsupported_auth(spec: Spec) -> str | None:
1836
1479
 
1837
1480
 
1838
1481
  def world_credential(session: Session) -> tuple[dict[str, str], dict[str, str]]:
1839
- """(headers, query) carrying the world's own credential for this session:
1840
- the session token in the vendor's shape (:func:`api.vendor_credential`),
1841
- or for an oauth2 world the grant the host minted for itself."""
1842
- spec = session.spec
1843
- assert spec is not None, "a mock-tools session has no http surface to present a credential on"
1844
- unsupported = unsupported_auth(spec)
1845
- if unsupported:
1846
- fail("host", unsupported)
1847
- 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()
1848
1489
 
1849
1490
 
1850
1491
  def bearer_of(headers: dict[str, str]) -> str | None:
@@ -2105,31 +1746,17 @@ def make_host_handler(
2105
1746
  if len(parts) >= 3 and parts[:2] == ["__host", "sessions"]:
2106
1747
  sid = parts[2]
2107
1748
  verb = parts[3] if len(parts) > 3 else None
2108
- if method == "DELETE" and verb is None:
2109
- return self._reply(200, host.close(sid))
2110
- if method == "POST" and verb == "renew":
2111
- return self._reply(200, host.renew(sid))
2112
- if method == "POST" and verb == "reset":
2113
- return self._reply(200, host.reset(sid))
2114
- if method == "POST" and verb == "seed":
2115
- return self._reply(200, host.seed(sid, body.get("args") or {}))
2116
- if method == "POST" and verb == "export" and len(parts) == 4:
2117
- known = body.get("knownSha256")
2118
- return self._reply(200, host.export(sid, known if isinstance(known, str) else None))
2119
1749
  if method == "POST" and verb == "export" and len(parts) == 5:
2120
1750
  url = body.get("url")
2121
1751
  if not isinstance(url, str) or not url.startswith(("https://", "http://")):
2122
1752
  return self._reply(400, {"error": "url must be the presigned upload url"})
2123
1753
  return self._reply(200, host.upload_export(sid, parts[4], url))
2124
- if method == "GET" and verb == "state":
2125
- return self._reply(200, host.state(sid))
2126
- if method == "POST" and verb == "grade":
2127
- return self._reply(200, host.grade(sid))
2128
- if method == "POST" and verb == "call":
2129
- tool = body.get("tool")
2130
- if not isinstance(tool, str):
2131
- return self._reply(400, {"error": "tool must be a string"})
2132
- 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)))
2133
1760
  return self._reply(404, {"error": "unknown control route"})
2134
1761
  except ContractError as error:
2135
1762
  code = error.detail.get("code", "host")
@@ -2143,7 +1770,9 @@ def make_host_handler(
2143
1770
  status = 404
2144
1771
  else:
2145
1772
  status = 400
2146
- 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
+ )
2147
1776
  except KeyError as error:
2148
1777
  return self._reply(400, {"error": "missing field", "field": str(error)})
2149
1778
  except WorkerGone as error:
@@ -2476,9 +2105,11 @@ def serve(cache_root: str | Path, *, port: int = 8080, host_addr: str = "0.0.0.0
2476
2105
  ``WORLDS_HOST_HEARTBEAT_S`` is how often it reports to the platform (with
2477
2106
  ``WORLDS_PLATFORM_URL`` and an advertised address, else no heartbeat);
2478
2107
  ``WORLDS_HOST_DRAIN_S`` is how long a SIGTERM waits for sessions to close;
2479
- ``WORLDS_WORKER_MEMORY_MB`` caps each version worker's address space and
2480
- ``WORLDS_WORKER_BUDGET_MB`` all of them together (their count is the
2481
- quotient; one more version answers 503 ``at_capacity``),
2108
+ ``WORLDS_WORKER_MEMORY_MB`` caps each version worker's address space,
2109
+ ``WORLDS_WORKER_BUDGET_MB`` is the memory all of them together are held to
2110
+ and ``WORLDS_WORKER_FOOTPRINT_MB`` what each is counted at against it
2111
+ (unset, its whole address-space cap; their count is the quotient, and one
2112
+ more version answers 503 ``at_capacity``),
2482
2113
  ``WORLDS_HOST_OBJECT_STORE`` is where every presigned URL it is handed
2483
2114
  may point (required; ``any`` for a dev host),
2484
2115
  ``WORLDS_HOST_MAX_BUNDLE_MB`` is the largest version bundle the cache
@@ -2504,6 +2135,11 @@ def serve(cache_root: str | Path, *, port: int = 8080, host_addr: str = "0.0.0.0
2504
2135
  worlds_domain=worlds_domain,
2505
2136
  memory_mb=int(os.environ.get("WORLDS_WORKER_MEMORY_MB") or DEFAULT_WORKER_MEMORY_MB),
2506
2137
  budget_mb=int(os.environ.get("WORLDS_WORKER_BUDGET_MB") or DEFAULT_WORKER_BUDGET_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
+ ),
2507
2143
  )
2508
2144
  world_host = WorldHost(
2509
2145
  Path(cache_root),