@withgateway/sdk 0.3.3 → 0.6.0

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 (158) hide show
  1. package/README.md +4 -3
  2. package/dist/cli.js +3005 -1401
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +2996 -1392
  5. package/dist/cli.mjs.map +1 -1
  6. package/dist/files/index.js +128 -37
  7. package/dist/files/index.js.map +1 -1
  8. package/dist/files/index.mjs +126 -35
  9. package/dist/files/index.mjs.map +1 -1
  10. package/dist/hooks/index.d.mts +1 -1
  11. package/dist/hooks/index.d.ts +1 -1
  12. package/dist/hooks/index.js +124 -11
  13. package/dist/hooks/index.js.map +1 -1
  14. package/dist/hooks/index.mjs +124 -11
  15. package/dist/hooks/index.mjs.map +1 -1
  16. package/dist/{index-C3UzD0G3.d.mts → index-CDPQBsU5.d.mts} +19 -3
  17. package/dist/{index-C3UzD0G3.d.ts → index-CDPQBsU5.d.ts} +19 -3
  18. package/dist/{index-mJhG3vZU.d.mts → index-Di9nNqOY.d.mts} +26 -3
  19. package/dist/{index-DUHmS74p.d.ts → index-LA-PMRJT.d.ts} +26 -3
  20. package/dist/index.d.mts +4 -4
  21. package/dist/index.d.ts +4 -4
  22. package/dist/index.js +1078 -260
  23. package/dist/index.js.map +1 -1
  24. package/dist/index.mjs +1040 -251
  25. package/dist/index.mjs.map +1 -1
  26. package/dist/replay/index.d.mts +1 -1
  27. package/dist/replay/index.d.ts +1 -1
  28. package/dist/replay/index.js.map +1 -1
  29. package/dist/replay/index.mjs.map +1 -1
  30. package/dist/traces/index.js +125 -34
  31. package/dist/traces/index.js.map +1 -1
  32. package/dist/traces/index.mjs +123 -32
  33. package/dist/traces/index.mjs.map +1 -1
  34. package/dist/tracing/index.d.mts +1 -1
  35. package/dist/tracing/index.d.ts +1 -1
  36. package/dist/tracing/index.js +7 -1
  37. package/dist/tracing/index.js.map +1 -1
  38. package/dist/tracing/index.mjs +7 -1
  39. package/dist/tracing/index.mjs.map +1 -1
  40. package/dist/worlds/index.d.mts +819 -438
  41. package/dist/worlds/index.d.ts +819 -438
  42. package/dist/worlds/index.js +912 -236
  43. package/dist/worlds/index.js.map +1 -1
  44. package/dist/worlds/index.mjs +908 -232
  45. package/dist/worlds/index.mjs.map +1 -1
  46. package/package.json +1 -1
  47. package/runtime/gatewaysdk/environment/_bundle.py +4 -6
  48. package/runtime/gatewaysdk/environment/_materialize.py +5 -25
  49. package/runtime/gatewaysdk/environment/_world.py +82 -66
  50. package/runtime/gatewaysdk/environment/backing.py +20 -24
  51. package/runtime/gatewaysdk/environment/core.py +1 -16
  52. package/runtime/gatewaysdk/environment/legacy_sqlite.py +14 -27
  53. package/runtime/gatewaysdk/environment/runtime.py +45 -2
  54. package/runtime/gatewaysdk/environment/schema/admission.py +174 -0
  55. package/runtime/gatewaysdk/environment/schema/api.py +198 -474
  56. package/runtime/gatewaysdk/environment/schema/assertions.py +458 -0
  57. package/runtime/gatewaysdk/environment/schema/batch.py +3 -3
  58. package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +1 -0
  59. package/runtime/gatewaysdk/environment/schema/cache_layout.py +5 -0
  60. package/runtime/gatewaysdk/environment/schema/call_capture.py +321 -0
  61. package/runtime/gatewaysdk/environment/schema/call_log.py +276 -18
  62. package/runtime/gatewaysdk/environment/schema/call_redaction.py +207 -19
  63. package/runtime/gatewaysdk/environment/schema/cast.py +15 -35
  64. package/runtime/gatewaysdk/environment/schema/compiler.py +4 -1
  65. package/runtime/gatewaysdk/environment/schema/conform.py +38 -35
  66. package/runtime/gatewaysdk/environment/schema/connector.py +94 -152
  67. package/runtime/gatewaysdk/environment/schema/connectors/confluence/connector.toml +1 -12
  68. package/runtime/gatewaysdk/environment/schema/connectors/custom/handlers.py +2 -1
  69. package/runtime/gatewaysdk/environment/schema/connectors/github/api/handlers.py +217 -58
  70. package/runtime/gatewaysdk/environment/schema/connectors/github/connector.toml +10 -19
  71. package/runtime/gatewaysdk/environment/schema/connectors/github/scenarios/default/seed/github_webhooks.json +10 -2
  72. package/runtime/gatewaysdk/environment/schema/connectors/github/tests/webhooks.json +47 -0
  73. package/runtime/gatewaysdk/environment/schema/connectors/github/world.json +21 -0
  74. package/runtime/gatewaysdk/environment/schema/connectors/jamf/api/handlers.py +185 -18
  75. package/runtime/gatewaysdk/environment/schema/connectors/jamf/connector.toml +29 -14
  76. package/runtime/gatewaysdk/environment/schema/connectors/jamf/provenance.json +43 -12
  77. package/runtime/gatewaysdk/environment/schema/connectors/jamf/scenarios/default/seed/jamf_webhooks.json +2 -2
  78. package/runtime/gatewaysdk/environment/schema/connectors/jamf/scope.toml +4 -17
  79. package/runtime/gatewaysdk/environment/schema/connectors/jamf/tests/webhooks.json +107 -0
  80. package/runtime/gatewaysdk/environment/schema/connectors/jamf/vendor-openapi.json +1 -1
  81. package/runtime/gatewaysdk/environment/schema/connectors/linear/api/handlers.py +85 -1
  82. package/runtime/gatewaysdk/environment/schema/connectors/linear/connector.toml +19 -31
  83. package/runtime/gatewaysdk/environment/schema/connectors/linear/provenance.json +18 -8
  84. package/runtime/gatewaysdk/environment/schema/connectors/linear/scenarios/default/seed/webhooks.json +19 -3
  85. package/runtime/gatewaysdk/environment/schema/connectors/linear/tests/test_webhooks.py +71 -0
  86. package/runtime/gatewaysdk/environment/schema/connectors/servicenow/connector.toml +2 -5
  87. package/runtime/gatewaysdk/environment/schema/cors.py +54 -0
  88. package/runtime/gatewaysdk/environment/schema/credentials.py +313 -8
  89. package/runtime/gatewaysdk/environment/schema/data.py +14 -13
  90. package/runtime/gatewaysdk/environment/schema/database/base.py +106 -165
  91. package/runtime/gatewaysdk/environment/schema/database/guard.py +45 -37
  92. package/runtime/gatewaysdk/environment/schema/database/reads.py +169 -0
  93. package/runtime/gatewaysdk/environment/schema/database/sqlite.py +57 -31
  94. package/runtime/gatewaysdk/environment/schema/declared_routes.py +210 -0
  95. package/runtime/gatewaysdk/environment/schema/door.py +899 -0
  96. package/runtime/gatewaysdk/environment/schema/envelope.py +86 -28
  97. package/runtime/gatewaysdk/environment/schema/grading.py +58 -86
  98. package/runtime/gatewaysdk/environment/schema/handler_errors.py +52 -5
  99. package/runtime/gatewaysdk/environment/schema/host.py +229 -1695
  100. package/runtime/gatewaysdk/environment/schema/host_control.py +144 -0
  101. package/runtime/gatewaysdk/environment/schema/host_handoff.py +370 -0
  102. package/runtime/gatewaysdk/environment/schema/host_loops.py +97 -0
  103. package/runtime/gatewaysdk/environment/schema/host_owners.py +121 -0
  104. package/runtime/gatewaysdk/environment/schema/host_proxy.py +111 -0
  105. package/runtime/gatewaysdk/environment/schema/host_requests.py +6 -0
  106. package/runtime/gatewaysdk/environment/schema/host_session.py +126 -0
  107. package/runtime/gatewaysdk/environment/schema/host_surfaces.py +79 -21
  108. package/runtime/gatewaysdk/environment/schema/host_transfers.py +127 -0
  109. package/runtime/gatewaysdk/environment/schema/host_versions.py +242 -0
  110. package/runtime/gatewaysdk/environment/schema/host_workers.py +577 -0
  111. package/runtime/gatewaysdk/environment/schema/journal.py +438 -0
  112. package/runtime/gatewaysdk/environment/schema/ledger_spill.py +828 -0
  113. package/runtime/gatewaysdk/environment/schema/local.py +32 -116
  114. package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +20 -5
  115. package/runtime/gatewaysdk/environment/schema/platform.py +29 -234
  116. package/runtime/gatewaysdk/environment/schema/request_body.py +238 -0
  117. package/runtime/gatewaysdk/environment/schema/request_ledger.py +958 -0
  118. package/runtime/gatewaysdk/environment/schema/route_bindings.py +25 -3
  119. package/runtime/gatewaysdk/environment/schema/route_miss.py +54 -0
  120. package/runtime/gatewaysdk/environment/schema/runtime.py +136 -176
  121. package/runtime/gatewaysdk/environment/schema/scaffold.py +2 -1
  122. package/runtime/gatewaysdk/environment/schema/session_files.py +133 -24
  123. package/runtime/gatewaysdk/environment/schema/session_move.py +275 -0
  124. package/runtime/gatewaysdk/environment/schema/skills/agents/connector-template-author.md +5 -1
  125. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +8 -9
  126. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/CONNECTORS.md +3 -3
  127. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +50 -28
  128. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +12 -8
  129. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +20 -22
  130. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +25 -25
  131. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +24 -16
  132. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +71 -7
  133. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +182 -0
  134. package/runtime/gatewaysdk/environment/schema/snapshot.py +150 -30
  135. package/runtime/gatewaysdk/environment/schema/spill_files.py +228 -0
  136. package/runtime/gatewaysdk/environment/schema/tasks.py +229 -323
  137. package/runtime/gatewaysdk/environment/schema/tools_world.py +103 -203
  138. package/runtime/gatewaysdk/environment/schema/validation.py +69 -1
  139. package/runtime/gatewaysdk/environment/schema/verbs.py +38 -36
  140. package/runtime/gatewaysdk/environment/schema/webhooks.py +687 -0
  141. package/runtime/gatewaysdk/environment/schema/worker.py +6 -4
  142. package/runtime/gatewaysdk/environment/schema/workers.py +203 -39
  143. package/runtime/gatewaysdk/environment/schema/world_host.py +970 -0
  144. package/runtime/gatewaysdk/environment/schema/world_tests.py +83 -11
  145. package/runtime/gatewaysdk/environment/world.py +1 -1
  146. package/runtime/gatewaysdk/environment/world_session_contract.py +14 -0
  147. package/skills/agents/connector-template-author.md +5 -1
  148. package/skills/benchmarks-getting-started/SKILL.md +8 -9
  149. package/skills/connector-schema-authoring/CONNECTORS.md +3 -3
  150. package/skills/connector-schema-authoring/SKILL.md +50 -28
  151. package/skills/connector-schema-authoring/connector-worlds.md +282 -18
  152. package/skills/connector-schema-authoring/world-schema.md +7 -6
  153. package/skills/world-data-ingestion/ROWS.md +12 -8
  154. package/skills/world-data-ingestion/SKILL.md +20 -22
  155. package/skills/worlds-getting-started/SKILL.md +25 -25
  156. package/skills/worlds-getting-started/references/cli-mcp-map.md +24 -16
  157. package/skills/worlds-getting-started/references/gotchas.md +71 -7
  158. package/skills/worlds-getting-started/references/journal-checks.md +182 -0
@@ -0,0 +1,970 @@
1
+ """The session registry and the control operations of a World Host (:class:`WorldHost`): the
2
+ sessions it holds, their leases, exports and moves, and the platform's session verbs
3
+ (:data:`HOSTED_OPERATIONS`), which :mod:`.host` serves over HTTP."""
4
+
5
+ from __future__ import annotations
6
+
7
+ import functools
8
+ import os
9
+ import shutil
10
+ import threading
11
+ import time
12
+ import uuid
13
+ from collections import Counter
14
+ from collections.abc import Callable, Iterator
15
+ from contextlib import contextmanager
16
+ from pathlib import Path
17
+ from typing import Any, Optional
18
+
19
+ from ..world_session_contract import OPEN_DOOR_FEATURE, REQUEST_LOG_PAGE_MAX
20
+ from .admission import RETRY_AFTER_S, Admission
21
+ from .cache_layout import SESSIONS_DIR, VERSIONS_DIR
22
+ from .door import VENDOR_MODE, session_mode
23
+ from .host_handoff import OUTCOMES
24
+ from .host_loops import swept
25
+ from .host_owners import PlatformOwners
26
+ from .host_requests import BrowserRelay, DependencyRef, parse_dependency_refs, restore_sha256
27
+ from .host_session import Export, Session
28
+ from .host_surfaces import SessionHost
29
+ from .host_transfers import check_object_store_url, download_verified, file_digest, upload_file
30
+ from .host_versions import DEFAULT_MAX_BUNDLE_MB, CachedVersion, VersionCache
31
+ from .host_workers import CALL_TIMEOUT_S, EXPORT_TIMEOUT_S, LOST, UNKNOWN_SESSION, VersionWorkers
32
+ from .journal import WorldJournal
33
+ from .lanes import Lanes
34
+ from .request_ledger import HostLedger, LedgerLife, NoLedger
35
+ from .webhooks import WebhookPoll
36
+ from .runtime import WorldRuntime
37
+ from .session_files import (
38
+ RECOVERED_DIR,
39
+ ExportFile,
40
+ RecoveredSession,
41
+ SessionExport,
42
+ real_dir,
43
+ )
44
+ from .session_move import PENDING_LEASE_S, Forwarding, platform_close
45
+ from .tasks import TaskSpec, parse_task_spec
46
+ from .tools_world import DependencyWorld
47
+ from .validation import fail
48
+ from .verbs import SESSION_VERBS
49
+ from .workers import Finishing, Worker, WorkerPool
50
+
51
+ DEFAULT_LEASE_S = 3600.0
52
+ DEFAULT_MAX_SESSIONS = 1500
53
+
54
+
55
+ class WorldHost:
56
+ """The session registry and the control operations, in one of two roles:
57
+
58
+ * the **supervisor** (the deployed host): serves code-free worlds in
59
+ process and places worlds with handlers on its :class:`WorkerPool`;
60
+ * a **worker** (``run_handlers=True``, ``pinned_version=...``): serves one
61
+ version, handlers included, for its supervisor.
62
+ """
63
+
64
+ def __init__(
65
+ self,
66
+ cache_root: Path,
67
+ *,
68
+ lease_s: float = DEFAULT_LEASE_S,
69
+ advertise_url: str | None = None,
70
+ workers: WorkerPool | None = None,
71
+ versions_root: Path | None = None,
72
+ run_handlers: bool = False,
73
+ pinned_version: str | None = None,
74
+ limits: dict[str, int] | None = None,
75
+ max_sessions: int = DEFAULT_MAX_SESSIONS,
76
+ max_bundle_mb: int = DEFAULT_MAX_BUNDLE_MB,
77
+ object_store: frozenset[str] | None = None,
78
+ admission: Admission | None = None,
79
+ build: str | None = None,
80
+ owners: PlatformOwners | None = None,
81
+ clock: Callable[[], float] = time.time,
82
+ ):
83
+ #: Every presigned URL the control plane hands this host must point here; None admits any.
84
+ self.object_store = object_store
85
+ self.build = build
86
+ self.owners = owners
87
+ self.forwarding = Forwarding(advertise_url)
88
+ self.clock = clock
89
+ self.admission = admission or Admission()
90
+ self.cache = VersionCache(
91
+ versions_root or Path(cache_root) / VERSIONS_DIR, run_handlers=run_handlers, max_bundle_mb=max_bundle_mb
92
+ )
93
+ self.sessions_root = Path(cache_root) / SESSIONS_DIR
94
+ # Sessions live in this process, so whatever a previous one left on disk is unreachable.
95
+ shutil.rmtree(self.sessions_root, ignore_errors=True)
96
+ self.sessions_root.mkdir(parents=True, exist_ok=True)
97
+ self.lease_s = lease_s
98
+ self.advertise_url = advertise_url
99
+ self.workers = workers
100
+ self.placement = VersionWorkers(workers, self) if workers is not None else None
101
+ self.run_handlers = run_handlers
102
+ self.pinned_version = pinned_version
103
+ self.limits = limits
104
+ self.max_sessions = max_sessions
105
+ self.draining = False
106
+ self.ledger: HostLedger = NoLedger()
107
+ self.finishing = Finishing()
108
+ self.started_at = time.time()
109
+ self._lock = threading.Lock()
110
+ self._sessions: dict[str, Session] = {}
111
+ #: Each holds a slot from admission, so concurrent opens cannot all pass the capacity check.
112
+ self._opening: set[str] = set()
113
+ #: Opens the platform closed before they finished: closed the moment they exist, not at lease end.
114
+ self._abandoned: set[str] = set()
115
+ #: Sessions out of the registry and not closed yet: their files are theirs until the close is done.
116
+ self._draining: dict[str, Session] = {}
117
+ self._opens = Lanes()
118
+ self._counters: Counter[str] = Counter()
119
+ self._session_seconds = 0.0
120
+
121
+ def open(
122
+ self,
123
+ session_id: str,
124
+ version_id: str,
125
+ bundle_url: str,
126
+ task: str | None,
127
+ token: str | None,
128
+ snapshot: dict[str, str] | None,
129
+ browser: dict[str, str] | None = None,
130
+ restore: dict[str, str] | None = None,
131
+ task_spec: Any = None,
132
+ dependencies: list[dict[str, Any]] | None = None,
133
+ pending: bool = False,
134
+ auth: str | None = None,
135
+ ledger_source: str | None = None,
136
+ ) -> dict:
137
+ """Open ``session_id`` on ``version_id``, either on the bundled ``task``
138
+ or on ``task_spec``, a session task of its own (:mod:`tasks`); exactly
139
+ one of the two. ``dependencies`` are the versions the world's
140
+ ``[dependencies]`` resolved to, one ``{alias, versionId, bundleUrl,
141
+ snapshot?}`` per alias the manifest declares, opened beside it. A
142
+ ``pending`` open is a session moving here from another host: it serves
143
+ nothing until the platform's row names this host (:class:`SessionMove`).
144
+ ``auth`` (``vendor`` or ``open``) overrides the world's ``[auth] mode``."""
145
+ if self.pinned_version is not None and version_id != self.pinned_version:
146
+ fail("host", f"this worker serves version {self.pinned_version} only, not {version_id}")
147
+ if (task is None) == (task_spec is None):
148
+ fail("host", "an open names a bundled task or carries a task spec, one of the two")
149
+ if task is not None and not isinstance(task, str):
150
+ fail("host", "task is the bundled task's name")
151
+ spec = parse_task_spec(task_spec) if task_spec is not None else None
152
+ deps = parse_dependency_refs(dependencies)
153
+ life = LedgerLife.of(ledger_source)
154
+ self._replace_pending(session_id, restore, browser, pending)
155
+ with self._lock:
156
+ existing = self._sessions.get(session_id)
157
+ if existing is None:
158
+ # A retry of an open already served is answered even while draining: refusing it would
159
+ # send the platform to open the same id elsewhere while this copy holds the live writes.
160
+ if self.draining:
161
+ fail("draining", "this host is draining and takes no new sessions")
162
+ self._refuse_closing(session_id)
163
+ self._admit(session_id)
164
+ if existing is not None:
165
+ wanted = (version_id, (task, spec.raw if spec is not None else None), token)
166
+ return self._reopened(existing, wanted, restore, pending, auth)
167
+ try:
168
+ session = self._open(
169
+ session_id, version_id, bundle_url, task, spec, token, snapshot, browser, restore, deps, pending, auth
170
+ )
171
+ session.life = life
172
+ self._register(session)
173
+ described = self._describe(session)
174
+ except Exception:
175
+ self.tally("open_failures")
176
+ with self._lock:
177
+ self._opening.discard(session_id)
178
+ self._abandoned.discard(session_id)
179
+ raise
180
+ with self._lock:
181
+ self._opening.discard(session_id)
182
+ abandoned = session_id in self._abandoned
183
+ self._abandoned.discard(session_id)
184
+ if abandoned:
185
+ self.close(session_id)
186
+ fail(UNKNOWN_SESSION, f"session {session_id} was closed while it opened")
187
+ return described
188
+
189
+ def _replace_pending(self, session_id: str, restore: dict[str, str] | None, browser: Any, pending: bool) -> None:
190
+ """A draining host takes no move, refused before anything here changes. A copy pending a move here that
191
+ a later open reuses gets a fresh lease; one from another export or browser is closed first."""
192
+ if pending and self.draining:
193
+ fail("draining", f"this host is draining and takes no session moving here; place {session_id} elsewhere")
194
+ existing = self.held(session_id)
195
+ if existing is None or not existing.move.pending:
196
+ return
197
+ existing.lease_until = max(existing.lease_until, time.time() + PENDING_LEASE_S)
198
+ if (existing.restore_sha256, existing.browser) != (restore_sha256(restore), BrowserRelay.parse(browser)):
199
+ self.close(session_id, reason="replaced")
200
+
201
+ def _reopened(
202
+ self, existing: Session, wanted: tuple, restore: dict[str, str] | None, pending: bool, auth: str | None
203
+ ) -> dict:
204
+ """A retried open gets the same session, never a rebuild that drops its writes. One moving off
205
+ this host is another host's to open, and one opened from another export or auth is refused."""
206
+ if existing.move.leaving:
207
+ fail("draining", f"session {existing.session_id} is moving to another host; place it elsewhere")
208
+ if (existing.version_id, existing.task_key, existing.token) != wanted or auth not in (None, existing.auth):
209
+ fail("host", f"session {existing.session_id} is already open as another version, task, token or auth")
210
+ if restore and restore_sha256(restore) != existing.restore_sha256:
211
+ fail("host", f"session {existing.session_id} is already open from another export")
212
+ if not pending:
213
+ existing.move.commit()
214
+ return self._describe(existing)
215
+
216
+ def _refuse_closing(self, session_id: str) -> None:
217
+ """Under ``_lock``: an id whose earlier open still has a request inside keeps its files until it leaves."""
218
+ if session_id in self._draining:
219
+ fail(
220
+ "busy",
221
+ f"session {session_id} is still closing; retry after {RETRY_AFTER_S} s",
222
+ retryAfter=RETRY_AFTER_S,
223
+ )
224
+
225
+ def _admit(self, session_id: str) -> None:
226
+ """Reserve one of this host's ``max_sessions`` for ``session_id`` while it
227
+ opens. Under ``_lock``."""
228
+ if session_id in self._opening:
229
+ fail("host", f"session {session_id} is being opened already")
230
+ if len(self._sessions) + len(self._opening) >= self.max_sessions:
231
+ fail("at_capacity", f"this host holds its {self.max_sessions} sessions; place elsewhere")
232
+ self._opening.add(session_id)
233
+
234
+ def _open(
235
+ self,
236
+ session_id: str,
237
+ version_id: str,
238
+ bundle_url: str,
239
+ task: str | None,
240
+ spec: TaskSpec | None,
241
+ token: str | None,
242
+ snapshot: dict[str, str] | None,
243
+ browser: dict[str, str] | None,
244
+ restore: dict[str, str] | None,
245
+ deps: list[DependencyRef],
246
+ pending: bool,
247
+ auth: str | None = None,
248
+ ) -> Session:
249
+ cached = self.cache.ensure(version_id, *self._trusted_version(bundle_url, snapshot))
250
+ mode = session_mode(auth, token)
251
+ dependencies = self._dependency_worlds(cached, deps)
252
+ if spec is not None:
253
+ cached.served_names(dependencies).check_allowed(spec.tools)
254
+ relay = BrowserRelay.parse(browser)
255
+ if cached.needs_worker and not self.run_handlers:
256
+ return self._open_on_worker(
257
+ cached, session_id, bundle_url, task, spec, token, relay, restore, deps, pending, mode
258
+ )
259
+ session_dir = self.sessions_root / session_id
260
+ with self._opens.turn(version_id):
261
+ runtime = WorldRuntime.open(
262
+ cached,
263
+ session_dir,
264
+ task=task,
265
+ spec=spec,
266
+ token=token,
267
+ dependencies=dependencies,
268
+ restore=lambda load: self._restore_into(restore, session_dir, load, cached),
269
+ journaled=self.run_handlers,
270
+ )
271
+ runtime.calls.outbox.on_pressure = lambda: self.ledger.wake(session_id)
272
+ session = Session(
273
+ session_id=session_id,
274
+ version_id=version_id,
275
+ task=task,
276
+ spec=cached.spec,
277
+ token=token,
278
+ bundle=cached.bundle,
279
+ tree=cached.tree,
280
+ lease_until=time.time() + (PENDING_LEASE_S if pending else self.lease_s),
281
+ engine=cached.engine,
282
+ runtime=runtime,
283
+ door=cached.door(token, self.clock),
284
+ ui=cached.ui,
285
+ browser=relay,
286
+ restored=runtime.restored,
287
+ task_spec=spec,
288
+ settings=cached.settings,
289
+ restore_sha256=restore_sha256(restore),
290
+ pending=pending,
291
+ auth=mode,
292
+ )
293
+ return session
294
+
295
+ def _open_on_worker(
296
+ self,
297
+ cached: CachedVersion,
298
+ session_id: str,
299
+ bundle_url: str,
300
+ task: str | None,
301
+ spec: TaskSpec | None,
302
+ token: str | None,
303
+ relay: BrowserRelay | None,
304
+ restore: dict[str, str] | None,
305
+ deps: list[DependencyRef],
306
+ pending: bool,
307
+ mode: str = VENDOR_MODE,
308
+ ) -> Session:
309
+ """Place the session on the version's worker (:class:`VersionWorkers`), which opens it from the bundle
310
+ this process cached; the supervisor keeps the ui's files and the browser tunnel, relays the ui's api
311
+ calls as they came (``via: ui``), and hands an export it fetched and verified to the worker as a local
312
+ file with its sha256, checked again there. No worker past the pool's memory budget: ``at_capacity``."""
313
+ if self.placement is None:
314
+ fail(
315
+ "host",
316
+ f"version {cached.version_id} runs world-authored code ({cached.authored_code}); "
317
+ "this host runs none in its process and has no version workers",
318
+ )
319
+ body = {
320
+ "sessionId": session_id,
321
+ "versionId": cached.version_id,
322
+ "bundleUrl": bundle_url,
323
+ "task": task,
324
+ "taskSpec": spec.raw if spec is not None else None,
325
+ "token": token,
326
+ "dependencies": [dep.raw for dep in deps],
327
+ "auth": mode,
328
+ }
329
+ fetch = functools.partial(self._restore_source, restore)
330
+ worker = self.placement.place(cached.version_id, session_id, body, fetch, self._opens)
331
+ session = Session(
332
+ session_id=session_id,
333
+ version_id=cached.version_id,
334
+ task=task,
335
+ spec=cached.spec,
336
+ token=token,
337
+ bundle=cached.bundle,
338
+ tree=cached.tree,
339
+ lease_until=time.time() + (PENDING_LEASE_S if pending else self.lease_s),
340
+ engine=cached.engine,
341
+ worker=worker,
342
+ door=cached.door(token, self.clock),
343
+ ui=cached.ui,
344
+ browser=relay,
345
+ restored=bool(restore),
346
+ task_spec=spec,
347
+ placement=body,
348
+ settings=cached.settings,
349
+ restore_sha256=restore_sha256(restore),
350
+ pending=pending,
351
+ auth=mode,
352
+ )
353
+ return session
354
+
355
+ def _restore_into(
356
+ self,
357
+ restore: dict[str, str] | None,
358
+ session_dir: Path,
359
+ load: Callable[[SessionExport], None],
360
+ cached: CachedVersion,
361
+ ) -> bool:
362
+ """Load the checkpoint ``restore`` names into a freshly opened world (an export's
363
+ bytes checked against the recorded sha256 here, where they are opened), then drop
364
+ what was fetched or set aside. False when there was nothing to restore."""
365
+ source = self._restore_source(restore, session_dir)
366
+ if source is None:
367
+ return False
368
+ try:
369
+ load(source.checkpoint(cached.engine, cached.runtime_class))
370
+ finally:
371
+ source.discard()
372
+ return True
373
+
374
+ def _restore_source(
375
+ self, restore: dict[str, str] | None, session_dir: Path
376
+ ) -> ExportFile | RecoveredSession | None:
377
+ """The checkpoint a session continues from, or None for a fresh session. The
378
+ platform names an export by ``{url, sha256}`` and the file is fetched into the
379
+ session's directory and verified; a supervisor names one to its worker by
380
+ ``{path, sha256}``, or a dead worker's session directory it set aside by
381
+ ``{recovered}``, and only the supervisor reaches a worker's control socket."""
382
+ if not restore:
383
+ return None
384
+ if restore.get("recovered") is not None:
385
+ return self._recovered_source(Path(str(restore["recovered"])))
386
+ path = restore.get("path")
387
+ if path is not None:
388
+ return self._worker_restore_source(Path(path), restore.get("sha256"))
389
+ url, sha256 = restore.get("url"), restore.get("sha256")
390
+ if not isinstance(url, str) or not isinstance(sha256, str) or len(sha256) != 64:
391
+ fail("host", "restore must be {url: <presigned export url>, sha256: <hex digest>}")
392
+ check_object_store_url(url, self.object_store, "restore.url")
393
+ return ExportFile(download_verified(url, sha256, session_dir / "restore.db"), sha256)
394
+
395
+ def _recovered_source(self, directory: Path) -> RecoveredSession:
396
+ root = self.sessions_root.parent / RECOVERED_DIR
397
+ inside = directory.parent == root and directory.name not in ("", ".", "..")
398
+ if not (self.run_handlers and inside and real_dir(root) and real_dir(directory)):
399
+ fail("host", "a recovered session is a worker's, from its own recovered directory")
400
+ return RecoveredSession(directory)
401
+
402
+ def _worker_restore_source(self, path: Path, sha256: object) -> ExportFile:
403
+ if not self.run_handlers:
404
+ fail("host", "restore by path is a worker's; name the export by {url, sha256}")
405
+ if not path.is_file():
406
+ fail("host", f"restore file {path} is missing")
407
+ if not isinstance(sha256, str) or len(sha256) != 64:
408
+ fail("host", "restore by path names the export's sha256 beside it")
409
+ return ExportFile(path, sha256)
410
+
411
+ def _trusted_version(self, bundle_url: str, snapshot: dict[str, str] | None) -> tuple[str, dict[str, str] | None]:
412
+ check_object_store_url(bundle_url, self.object_store, "bundleUrl")
413
+ if snapshot:
414
+ check_object_store_url(snapshot.get("url"), self.object_store, "snapshot.url")
415
+ return bundle_url, snapshot
416
+
417
+ def _register(self, session: Session) -> None:
418
+ with self._lock:
419
+ replaced = self._retire(self._sessions.pop(session.session_id, None), "replaced")
420
+ self._sessions[session.session_id] = session
421
+ self._counters["opened"] += 1
422
+ if replaced is not None:
423
+ self._finish(replaced)
424
+
425
+ def _describe(self, session: Session) -> dict:
426
+ return {
427
+ "sessionId": session.session_id,
428
+ "versionId": session.version_id,
429
+ "task": session.task,
430
+ "taskName": session.task if session.task_spec is None else session.task_spec.name,
431
+ "taskSource": "bundled" if session.task_spec is None else "inline",
432
+ "tools": (
433
+ list(session.task_spec.tools)
434
+ if session.task_spec is not None and session.task_spec.tools is not None
435
+ else None
436
+ ),
437
+ "ready": True,
438
+ "hostUrl": self.advertise_url,
439
+ "leaseSeconds": self.lease_s,
440
+ "leaseUntil": session.lease_until,
441
+ "workerPid": session.worker.pid if session.worker is not None else None,
442
+ "ui": {"entry": session.ui.entry, "apiPath": session.ui.api_path} if session.ui is not None else None,
443
+ "browser": session.browser is not None,
444
+ "restored": session.restored,
445
+ "openedAt": session.opened_at,
446
+ "sessionSeconds": session.seconds,
447
+ "touchedAt": session.touched_at,
448
+ "ledgerSource": session.life.source,
449
+ "auth": session.auth,
450
+ }
451
+
452
+ def close(self, session_id: str, reason: str = "closed") -> dict:
453
+ with self._lock:
454
+ session = self._sessions.pop(session_id, None)
455
+ idle = self._retire(session, reason)
456
+ if session is None and session_id in self._opening:
457
+ self._abandoned.add(session_id)
458
+ if idle is not None:
459
+ self._finish(idle)
460
+ if session is None:
461
+ return {"closed": True, "openedAt": None, "sessionSeconds": 0.0}
462
+ return {"closed": True, "openedAt": session.opened_at, "sessionSeconds": session.seconds}
463
+
464
+ def set_browser(self, session_id: str, browser: Any) -> dict:
465
+ """Point the session's browser surface at another pool relay: the one
466
+ it had died and the platform leased a replacement. Connections open
467
+ on the old relay end with it; every connection after this reaches the
468
+ new one. A session opened without a browser never gains one here."""
469
+ relay = BrowserRelay.parse(browser)
470
+ if relay is None:
471
+ fail("host", "browser must be {url: 'ws://host:port', token: <relay token>}")
472
+ with self._lock:
473
+ session = self._sessions.get(session_id)
474
+ if session is None:
475
+ fail(UNKNOWN_SESSION, f"no session {session_id} on this host")
476
+ if session.browser is None:
477
+ fail("host", f"session {session_id} was opened without a browser surface")
478
+ session.browser = relay
479
+ return {"sessionId": session_id, "browser": True}
480
+
481
+ def export(self, session_id: str, known_sha256: str | None = None, handoff: bool = False) -> dict:
482
+ """Copy the session's state to a file on this host and hash it, one export of
483
+ a session at a time; it waits for :meth:`upload_export`, and a new one discards
484
+ the last. A copy hashing to ``known_sha256`` (the platform's last export of the
485
+ session) is thrown away and reported ``unchanged``: nothing to upload. In a
486
+ version worker it names its ``path``, for the supervisor that uploads it. A
487
+ ``handoff`` export is the final one of a session this host is moving, and is
488
+ refused for any other: only the host that holds a session hands it off."""
489
+ with self.using(session_id, touch=False, confirm=True) as session, session.exporting:
490
+ session.move.check_export(handoff)
491
+ engine = session.engine
492
+ if session.worker is not None:
493
+ answer = self.placement.control(session, "POST", "export", {}, timeout=EXPORT_TIMEOUT_S)
494
+ path = self.placement.export_path(session, answer)
495
+ else:
496
+ exports = self.sessions_root / session_id / "exports"
497
+ shutil.rmtree(exports, ignore_errors=True)
498
+ path = exports / f"{uuid.uuid4().hex}{Path(engine.snapshot_name).suffix}"
499
+ assert session.runtime is not None
500
+ session.runtime.export(path)
501
+ sha256, size = file_digest(path)
502
+ if known_sha256 is not None and sha256 == known_sha256:
503
+ path.unlink(missing_ok=True)
504
+ with self._lock:
505
+ session.export = None
506
+ self._counters["exports_unchanged"] += 1
507
+ return {"exportId": None, "sha256": sha256, "bytes": size, "unchanged": True}
508
+ export = Export(export_id=path.stem, path=path, sha256=sha256, bytes=size, content_type=engine.content_type)
509
+ with self._lock:
510
+ session.export = export
511
+ self._counters["exports"] += 1
512
+ described = export.describe()
513
+ if self.run_handlers:
514
+ described["path"] = str(path)
515
+ return described
516
+
517
+ def upload_export(self, session_id: str, export_id: str, url: str) -> dict:
518
+ """PUT the export :meth:`export` took to the presigned URL the platform
519
+ signed for its hash and size; the local copy goes once it is up."""
520
+ check_object_store_url(url, self.object_store, "url")
521
+ with self.using(session_id, touch=False, confirm=True) as session:
522
+ export = session.export
523
+ if export is None or export.export_id != export_id:
524
+ fail("host", f"no export {export_id} for session {session_id}; take one first")
525
+ upload_file(url, export.path, export.sha256, export.bytes, export.content_type)
526
+ export.path.unlink(missing_ok=True)
527
+ with self._lock:
528
+ session.export = None
529
+ self._counters["exports_uploaded"] += 1
530
+ return {"uploaded": True, **export.describe()}
531
+
532
+ def renew(self, session_id: str) -> dict:
533
+ with self.using(session_id, touch=False, confirm=True) as session:
534
+ return self._describe(session)
535
+
536
+ def expire_leases(self, now: float | None = None) -> list[str]:
537
+ """Close the sessions whose lease has run out and return their ids, under one lock so a renewal that
538
+ lands in between keeps its session; one on a worker is finished in the background (:class:`Finishing`)."""
539
+ now = time.time() if now is None else now
540
+ with self._lock:
541
+ expired = [s for s in self._sessions.values() if s.lease_until <= now and s.inflight == 0]
542
+ for session in expired:
543
+ self._retire(self._sessions.pop(session.session_id), "expired")
544
+ for session in expired:
545
+ self._finish_later(session)
546
+ return [s.session_id for s in expired]
547
+
548
+ def _retire(self, session: Session | None, reason: str = "closed") -> Session | None:
549
+ """Mark a session that has left the registry, for ``reason``, its id held from a new open
550
+ until :meth:`_finish` has closed it; returns it when nobody is inside it, so the caller
551
+ closes the state now. Otherwise the last request out does (see :meth:`_release`).
552
+ Call under the lock."""
553
+ if session is None:
554
+ return None
555
+ session.closing = True
556
+ session.close_reason = reason
557
+ self._draining[session.session_id] = session
558
+ return None if session.inflight else session
559
+
560
+ def _finish(self, session: Session) -> None:
561
+ """Free a session that has left the registry and has nobody inside it, once: close its
562
+ state here, or tell its worker to; its id takes a new open once that is done. One a
563
+ recovery holds is left to it (:meth:`given_back`), since it may still act on that id."""
564
+ if not self._claimed(session):
565
+ return
566
+ try:
567
+ self.ledger.leave(session)
568
+ self._close_state(session)
569
+ finally:
570
+ with self._lock:
571
+ if self._draining.get(session.session_id) is session:
572
+ del self._draining[session.session_id]
573
+
574
+ def _claimed(self, session: Session) -> bool:
575
+ with self._lock:
576
+ if session.finish_claimed or session.recoveries:
577
+ return False
578
+ session.finish_claimed = True
579
+ self._count_closed(session)
580
+ return True
581
+
582
+ def _count_closed(self, session: Session) -> None:
583
+ """Under ``_lock``."""
584
+ self._counters[f"closed.{session.close_reason}"] += 1
585
+ self._session_seconds += session.seconds
586
+
587
+ def _finish_later(self, session: Session) -> None:
588
+ """:meth:`_finish` handed to :class:`Finishing`: off the caller's thread, behind its version's other
589
+ finishes, for a session on a live worker, whose tenant code answers the finish's drain and DELETE at
590
+ its own pace; at once for one served in this process or whose worker is gone, which no tenant code
591
+ paces (a dead worker's journal is read up to ``LEFT_JOURNAL_BYTES``)."""
592
+ self.finishing.leave(session.live_worker, functools.partial(self._finish, session))
593
+
594
+ def _close_state(self, session: Session) -> None:
595
+ if session.worker is None:
596
+ assert session.runtime is not None
597
+ session.runtime.close()
598
+ return
599
+ assert self.placement is not None
600
+ self.placement.finish(session)
601
+
602
+ def recovering(self, worker: Worker) -> tuple[list[Session], list[Session]]:
603
+ """What a recovery of ``worker`` takes until it gives each back (:meth:`given_back`): the sessions
604
+ it serves, and those closing on it that no finish has claimed. A session may be held by a second
605
+ recovery as well, of the worker that replaced this one; no other finish runs it while any holds it."""
606
+ with self._lock:
607
+ serving = [s for s in self._sessions.values() if s.worker is worker and not s.closing]
608
+ closing = [s for s in self._draining.values() if s.worker is worker and not s.finish_claimed]
609
+ for session in (*serving, *closing):
610
+ session.recoveries += 1
611
+ return serving, closing
612
+
613
+ def given_back(self, session: Session) -> None:
614
+ """A recovery is done with ``session``: one that closed meanwhile and that nobody is inside is
615
+ finished, unless another recovery still holds it (:meth:`_claimed`), off the recovery's thread when
616
+ its worker runs tenant code (:meth:`_finish_later`), so no sweep waits on it; its id takes a new open
617
+ only after the last action on it."""
618
+ with self._lock:
619
+ session.recoveries -= 1
620
+ left = self._draining.get(session.session_id) is session and session.inflight == 0
621
+ if left:
622
+ self._finish_later(session)
623
+
624
+ def worker_died(self, session: Session, entries: list[dict]) -> None:
625
+ self.ledger.adopt(session.session_id, entries)
626
+
627
+ def forget_lost(self, session: Session) -> None:
628
+ """A session its dead worker took with it: gone from this host (the platform learns of it
629
+ on the next renew and reopens it from its last export). One a request is still inside keeps
630
+ its id from a new open until the last one out has finished it, since that finish acts on the
631
+ session's id: its spill account and its directory on the worker; that finish counts its close."""
632
+ with self._lock:
633
+ if self._sessions.get(session.session_id) is not session:
634
+ return
635
+ del self._sessions[session.session_id]
636
+ session.closing = True
637
+ session.close_reason = LOST
638
+ if session.inflight:
639
+ self._draining[session.session_id] = session
640
+ return
641
+ self._count_closed(session)
642
+
643
+ def reap_workers(self) -> list[str]:
644
+ """Recover version workers that died holding sessions, recycle those holding a turn past
645
+ ``STUCK_TURN_S``, and stop those idle for a while, a step that fails never stopping the
646
+ next; returns the versions whose idle workers were stopped."""
647
+ if self.workers is None or self.placement is None:
648
+ return []
649
+ swept(self.placement.recover_dead, "recovered the dead worker of version")
650
+ swept(self.placement.recover_stuck, "recycled the stuck worker of version")
651
+ return self.workers.reap_idle()
652
+
653
+ def session_count(self) -> int:
654
+ with self._lock:
655
+ return len(self._sessions)
656
+
657
+ def held(self, session_id: str) -> Session | None:
658
+ with self._lock:
659
+ return self._sessions.get(session_id)
660
+
661
+ def turn_held(self, session: Session) -> bool:
662
+ """Whether a call of the session still holds its turn on its worker (one past its time)."""
663
+ return self.placement is not None and session.worker is not None and self.placement.holds_turn(session)
664
+
665
+ def worker_count(self) -> int:
666
+ return len(self.workers._workers) if self.workers is not None else 0
667
+
668
+ def warm(self, version_id: str, bundle_url: str, snapshot: dict[str, str] | None) -> dict:
669
+ """Cache a version before any session asks for it, so the first open
670
+ pays nothing. Idempotent: a version already here is reported, not
671
+ rebuilt."""
672
+ already = self.cache.has(version_id)
673
+ if not already:
674
+ self.cache.ensure(version_id, *self._trusted_version(bundle_url, snapshot))
675
+ return {"versionId": version_id, "cached": True, "alreadyCached": already}
676
+
677
+ def drain(self) -> None:
678
+ """Stop taking sessions; the ones here are served until they close."""
679
+ self.draining = True
680
+
681
+ def tally(self, key: str) -> None:
682
+ with self._lock:
683
+ self._counters[key] += 1
684
+
685
+ def stats(self) -> dict:
686
+ """What this host is and holds, for the heartbeat and ``/__host/stats``:
687
+ the placement inputs (address, load, capacity, draining, which versions
688
+ are already cached) plus the lifetime counters."""
689
+ with self._lock:
690
+ sessions = len(self._sessions)
691
+ versions_in_use = sorted({s.version_id for s in self._sessions.values()})
692
+ counters = dict(self._counters)
693
+ session_seconds = self._session_seconds
694
+ return {
695
+ "hostUrl": self.advertise_url,
696
+ "sessions": sessions,
697
+ "capacity": self.max_sessions,
698
+ "draining": self.draining,
699
+ "workers": self.worker_count(),
700
+ "maxWorkers": self.workers.max_workers if self.workers is not None else 0,
701
+ "versions": self.cache.version_ids(),
702
+ "versionsInUse": versions_in_use,
703
+ "uptimeSeconds": time.time() - self.started_at,
704
+ "startedAt": self.started_at,
705
+ "build": self.build,
706
+ "counters": counters,
707
+ "sessionSeconds": session_seconds,
708
+ "pid": os.getpid(),
709
+ "limits": self.limits,
710
+ "features": [OPEN_DOOR_FEATURE],
711
+ }
712
+
713
+ def metrics_text(self) -> str:
714
+ """The prometheus exposition of :meth:`stats`. ``worlds_host_sessions``
715
+ is the number the fleet scales on (sessions per host, not cpu)."""
716
+ stats = self.stats()
717
+ counters: dict[str, int] = stats["counters"]
718
+ lines = [
719
+ "# TYPE worlds_host_sessions gauge",
720
+ f"worlds_host_sessions {stats['sessions']}",
721
+ "# TYPE worlds_host_capacity gauge",
722
+ f"worlds_host_capacity {stats['capacity']}",
723
+ "# TYPE worlds_host_draining gauge",
724
+ f"worlds_host_draining {int(stats['draining'])}",
725
+ "# TYPE worlds_host_workers gauge",
726
+ f"worlds_host_workers {stats['workers']}",
727
+ "# TYPE worlds_host_versions_cached gauge",
728
+ f"worlds_host_versions_cached {len(stats['versions'])}",
729
+ "# TYPE worlds_host_uptime_seconds gauge",
730
+ f"worlds_host_uptime_seconds {stats['uptimeSeconds']:.0f}",
731
+ "# TYPE worlds_host_sessions_opened_total counter",
732
+ f"worlds_host_sessions_opened_total {counters.get('opened', 0)}",
733
+ "# TYPE worlds_host_open_failures_total counter",
734
+ f"worlds_host_open_failures_total {counters.get('open_failures', 0)}",
735
+ "# TYPE worlds_host_session_seconds_total counter",
736
+ f"worlds_host_session_seconds_total {stats['sessionSeconds']:.0f}",
737
+ "# TYPE worlds_host_exports_total counter",
738
+ f"worlds_host_exports_total {counters.get('exports', 0)}",
739
+ "# TYPE worlds_host_exports_uploaded_total counter",
740
+ f"worlds_host_exports_uploaded_total {counters.get('exports_uploaded', 0)}",
741
+ "# TYPE worlds_host_sessions_closed_total counter",
742
+ ]
743
+ for reason in ("closed", "expired", "lost", "replaced", "moved"):
744
+ lines.append(
745
+ f'worlds_host_sessions_closed_total{{reason="{reason}"}} {counters.get(f"closed.{reason}", 0)}'
746
+ )
747
+ lines.append("# TYPE worlds_host_handoffs_total counter")
748
+ for outcome in OUTCOMES:
749
+ lines.append(f'worlds_host_handoffs_total{{outcome="{outcome}"}} {counters.get(f"handoffs.{outcome}", 0)}')
750
+ for name in ("workers_replaced", "workers_recycled", "sessions_recovered", "sessions_unrecovered"):
751
+ lines += [f"# TYPE worlds_host_{name}_total counter", f"worlds_host_{name}_total {counters.get(name, 0)}"]
752
+ lines.append("# TYPE worlds_host_requests_total counter")
753
+ for surface in ("api", "ui", "browser", "proxied"):
754
+ lines.append(f'worlds_host_requests_total{{surface="{surface}"}} {counters.get(f"requests.{surface}", 0)}')
755
+ lines += [
756
+ "# TYPE worlds_host_platform_bearer_requests_total counter",
757
+ f"worlds_host_platform_bearer_requests_total {counters.get('requests.platform_bearer', 0)}",
758
+ ]
759
+ return "\n".join(lines) + "\n"
760
+
761
+ def _dependency_worlds(self, cached: CachedVersion, deps: list[DependencyRef]) -> dict[str, DependencyWorld]:
762
+ """The dependency versions a session opens beside ``cached``, cached the
763
+ way the root is (a worker imports their handlers too). Every alias the
764
+ root's manifest declares must be resolved, and nothing else: a version
765
+ without ``[dependencies]`` opened with any is refused, as is a
766
+ dependency that is not a schema world."""
767
+ declared = cached.declared_dependencies
768
+ if not deps:
769
+ if declared:
770
+ names = ", ".join(sorted(declared))
771
+ fail("host", f"version {cached.version_id} declares dependencies ({names}); the open resolved none")
772
+ return {}
773
+ worlds: dict[str, DependencyWorld] = {}
774
+ for ref in deps:
775
+ dependency = declared.get(ref.alias)
776
+ if dependency is None:
777
+ known = ", ".join(sorted(declared)) or "none"
778
+ fail("host", f"version {cached.version_id} declares no dependency '{ref.alias}' (it declares: {known})")
779
+ dep = self.cache.ensure(ref.version_id, *self._trusted_version(ref.bundle_url, ref.snapshot))
780
+ if dep.tools is None:
781
+ fail("host", f"dependency '{ref.alias}' ({ref.version_id}) is an api bundle, not a schema world")
782
+ worlds[ref.alias] = DependencyWorld.of(dependency, dep.tools)
783
+ cached.served_names(worlds)
784
+ return worlds
785
+
786
+ @contextmanager
787
+ def using(
788
+ self, session_id: str, *, touch: bool = True, ledger: bool = False, confirm: bool = False
789
+ ) -> Iterator[Session]:
790
+ """The session for the duration of one request: its lease renewed unless it is a ``ledger`` drain
791
+ (which must not keep a session alive) or a copy pending a move here, its ``touched_at`` moved
792
+ unless ``touch`` is off (a renewal or export observing the session, not using it), and its
793
+ teardown held off until the block ends, then run by the last one out; a ``ledger`` drain hands it
794
+ to :class:`Finishing`, which runs a worker session's finish off the drain's thread, so a close that
795
+ lands inside the spiller's drain never holds the spiller on tenant code, and an in-process
796
+ session's at once, inside its take's 5 s, as it does one whose worker is gone.
797
+ A platform request (``confirm``) goes only to the host the platform's row names, so it confirms
798
+ a copy pending a move here."""
799
+ with self._lock:
800
+ session = self._sessions.get(session_id)
801
+ if session is not None:
802
+ self._enter(session, touch=touch, renew=not ledger, confirm=confirm)
803
+ if session is None:
804
+ fail(UNKNOWN_SESSION, f"no session {session_id} on this host")
805
+ try:
806
+ yield session
807
+ finally:
808
+ self._release(session, self._finish_later if ledger else self._finish)
809
+
810
+ def _enter(self, session: Session, *, touch: bool, renew: bool, confirm: bool) -> None:
811
+ if confirm:
812
+ session.move.commit()
813
+ renewed = renew and not session.move.pending
814
+ session.lease_until = time.time() + self.lease_s if renewed else session.lease_until
815
+ session.touched_at = time.time() if touch else session.touched_at
816
+ session.inflight += 1
817
+
818
+ def _release(self, session: Session, finish: Callable[[Session], None]) -> None:
819
+ with self._lock:
820
+ session.inflight -= 1
821
+ last_out = session.closing and session.inflight == 0
822
+ if last_out:
823
+ finish(session)
824
+
825
+ def owns(self, session_id: str) -> bool:
826
+ with self._lock:
827
+ return session_id in self._sessions
828
+
829
+ def reached_by(self, named: SessionHost) -> bool:
830
+ """``named`` reaches the session it names: a ``w-`` host always (its door decides),
831
+ an ``o-`` host only on the open session whose label it carries. Asked before the
832
+ session is used, so a wrong label renews and touches nothing."""
833
+ if named.capability is None:
834
+ return True
835
+ session = self.held(named.session_id)
836
+ return session is not None and session.opened_by(named)
837
+
838
+ @contextmanager
839
+ def admitted(self, session: Session, hopped: bool = False) -> Iterator[None]:
840
+ """One of the session's version's turns (:class:`Admission`) for a data-plane request, once its
841
+ move lets it in (:class:`SessionMove`): held while the session moves, counted against the
842
+ version's waiting bounds, served by a copy pending a move here once the platform names it."""
843
+ waiting = functools.partial(self.admission.waiting, session.version_id, session.session_id)
844
+ owner_now = functools.partial(self._owner_now, session.session_id)
845
+ with session.move.request(waiting, owner_now, self.advertise_url, hopped):
846
+ with self.admission.turn(session.version_id, session.session_id):
847
+ yield
848
+
849
+ def _owner_now(self, session_id: str) -> str | None:
850
+ return self.owners.current(session_id) if self.owners is not None else self.advertise_url
851
+
852
+ def _verb(
853
+ self,
854
+ session_id: str,
855
+ method: str,
856
+ verb: str,
857
+ body: dict | None,
858
+ local: Callable[[Any], dict],
859
+ *,
860
+ touch: bool = True,
861
+ ) -> dict:
862
+ """One session verb, the platform's: never held while the session moves (:meth:`SessionMove.verb`),
863
+ admitted on its version, forwarded to the session's worker when it has one, else answered by its
864
+ in-process runtime through ``local``; ``touch`` off for a reader that must not keep it busy."""
865
+ with (
866
+ self.using(session_id, confirm=True, touch=touch) as session,
867
+ session.move.verb(),
868
+ self.admission.turn(session.version_id, session.session_id),
869
+ ):
870
+ if session.worker is not None:
871
+ assert self.placement is not None
872
+ return self.placement.control(session, method, verb, body)
873
+ assert session.runtime is not None
874
+ return local(session.runtime)
875
+
876
+ def tools(self, session_id: str) -> dict:
877
+ return self._verb(session_id, "GET", "tools", None, lambda runtime: {"tools": runtime.served()})
878
+
879
+ def task(self, session_id: str) -> dict:
880
+ return self._verb(session_id, "GET", "task", None, lambda runtime: runtime.task_card())
881
+
882
+ def reset(self, session_id: str) -> dict:
883
+ return self._verb(session_id, "POST", "reset", {}, lambda runtime: runtime.reset())
884
+
885
+ def seed(self, session_id: str, rows: dict, mode: str = "append", redact: str = "off") -> dict:
886
+ args = {"rows": rows, "mode": mode, **({"redact": redact} if redact != "off" else {})}
887
+ return self._verb(session_id, "POST", "seed", {"args": args}, lambda runtime: runtime.seed(rows, mode, redact))
888
+
889
+ def state(self, session_id: str) -> dict:
890
+ return self._verb(session_id, "GET", "state", None, lambda runtime: runtime.state())
891
+
892
+ def evidence(self, session_id: str) -> dict:
893
+ return self._verb(session_id, "GET", "evidence", None, lambda runtime: runtime.grader_state())
894
+
895
+ def requests(
896
+ self,
897
+ session_id: str,
898
+ cursor: str | None = None,
899
+ limit: int = REQUEST_LOG_PAGE_MAX,
900
+ timeout: float | None = None,
901
+ ) -> dict:
902
+ """The next page of the session's request ledger outbox, everything up to ``cursor``
903
+ stored: the ledger's flush, which takes no turn, moves no clock and renews no lease."""
904
+ with self.using(session_id, touch=False, ledger=True) as session:
905
+ return self.ledger_page(session, cursor, limit, timeout)
906
+
907
+ def ledger_page(
908
+ self, session: Session, cursor: str | None, limit: int = REQUEST_LOG_PAGE_MAX, timeout: float | None = None
909
+ ) -> dict:
910
+ if session.worker is not None:
911
+ assert self.placement is not None
912
+ asked = {"cursor": cursor, "limit": limit}
913
+ return session.life.stamp(self.placement.outbox(session, asked, timeout or CALL_TIMEOUT_S))
914
+ assert session.runtime is not None and session.runtime.calls.outbox is not None
915
+ return session.life.stamp(session.runtime.calls.outbox.drain(cursor, limit))
916
+
917
+ def session_ids(self, draining: bool = False) -> list[str]:
918
+ with self._lock:
919
+ return [*self._sessions, *(self._draining if draining else ())]
920
+
921
+ def grade(
922
+ self,
923
+ session_id: str,
924
+ report: Optional[str] = None,
925
+ context: Optional[dict] = None,
926
+ journal: Optional[dict] = None,
927
+ grader: Optional[dict] = None,
928
+ ) -> dict:
929
+ sent = (("report", report), ("context", context), ("journal", journal), ("grader", grader))
930
+ body = {key: value for key, value in sent if value is not None}
931
+ parsed = WorldJournal.of(journal)
932
+ return self._verb(
933
+ session_id, "POST", "grade", body, lambda runtime: runtime.grade(report, context, parsed, grader)
934
+ )
935
+
936
+ def webhooks(self, session_id: str, poll: WebhookPoll = WebhookPoll()) -> dict:
937
+ """The world's subscriptions and a page of the deliveries it sent, a forwarder's answers kept
938
+ first; a poll that does not count as the session being used."""
939
+ body = poll.as_json()
940
+ return self._verb(session_id, "POST", "webhooks", body, lambda runtime: runtime.webhooks(poll), touch=False)
941
+
942
+ def flush(self, session_id: str) -> dict:
943
+ with self.using(session_id, touch=False, ledger=True) as session:
944
+ return self.ledger.barrier(session)
945
+
946
+ def call(self, session_id: str, tool: str, args: dict) -> dict:
947
+ """One of the session's declared tools by name, a dependency's as
948
+ ``alias.tool``; a route's name is refused (routes answer over HTTP)."""
949
+ body = {"tool": tool, "args": args}
950
+ return self._verb(session_id, "POST", "call", body, lambda runtime: runtime.call(tool, args))
951
+
952
+
953
+ HOSTED_OPERATIONS: dict[str, Callable[..., dict]] = {
954
+ "GET tools": WorldHost.tools,
955
+ "GET task": WorldHost.task,
956
+ "GET state": WorldHost.state,
957
+ "GET evidence": WorldHost.evidence,
958
+ "POST requests": WorldHost.requests,
959
+ "POST flush": WorldHost.flush,
960
+ "POST webhooks": WorldHost.webhooks,
961
+ "POST grade": WorldHost.grade,
962
+ "POST reset": WorldHost.reset,
963
+ "POST seed": WorldHost.seed,
964
+ "POST call": WorldHost.call,
965
+ "POST close": platform_close,
966
+ "POST renew": WorldHost.renew,
967
+ "POST export": WorldHost.export,
968
+ "DELETE <session>": platform_close,
969
+ }
970
+ assert set(HOSTED_OPERATIONS) == {verb.route for verb in SESSION_VERBS}, "the host serves every session verb"