@withgateway/sdk 0.6.0 → 0.9.3

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 (150) hide show
  1. package/dist/agents/index.d.mts +581 -0
  2. package/dist/agents/index.d.ts +581 -0
  3. package/dist/agents/index.js +1473 -0
  4. package/dist/agents/index.js.map +1 -0
  5. package/dist/agents/index.mjs +1424 -0
  6. package/dist/agents/index.mjs.map +1 -0
  7. package/dist/apiError-DHpfbmdx.d.mts +17 -0
  8. package/dist/apiError-DHpfbmdx.d.ts +17 -0
  9. package/dist/cli.js +11611 -6845
  10. package/dist/cli.js.map +1 -1
  11. package/dist/cli.mjs +10090 -5325
  12. package/dist/cli.mjs.map +1 -1
  13. package/dist/files/index.d.mts +3 -1
  14. package/dist/files/index.d.ts +3 -1
  15. package/dist/files/index.js +371 -102
  16. package/dist/files/index.js.map +1 -1
  17. package/dist/files/index.mjs +371 -102
  18. package/dist/files/index.mjs.map +1 -1
  19. package/dist/hooks/index.js +346 -136
  20. package/dist/hooks/index.js.map +1 -1
  21. package/dist/hooks/index.mjs +346 -136
  22. package/dist/hooks/index.mjs.map +1 -1
  23. package/dist/{index-LA-PMRJT.d.ts → index-DIN14Lhg.d.ts} +1 -1
  24. package/dist/{index-Di9nNqOY.d.mts → index-DuB-eQ0Z.d.mts} +1 -1
  25. package/dist/index.d.mts +7 -4
  26. package/dist/index.d.ts +7 -4
  27. package/dist/index.js +3177 -748
  28. package/dist/index.js.map +1 -1
  29. package/dist/index.mjs +2987 -590
  30. package/dist/index.mjs.map +1 -1
  31. package/dist/media-CQUC7TkS.d.mts +39 -0
  32. package/dist/media-DQnBloaX.d.ts +39 -0
  33. package/dist/traces/index.d.mts +3 -1
  34. package/dist/traces/index.d.ts +3 -1
  35. package/dist/traces/index.js +371 -102
  36. package/dist/traces/index.js.map +1 -1
  37. package/dist/traces/index.mjs +371 -102
  38. package/dist/traces/index.mjs.map +1 -1
  39. package/dist/tracing/index.d.mts +3 -2
  40. package/dist/tracing/index.d.ts +3 -2
  41. package/dist/tracing/index.js +257 -16
  42. package/dist/tracing/index.js.map +1 -1
  43. package/dist/tracing/index.mjs +257 -16
  44. package/dist/tracing/index.mjs.map +1 -1
  45. package/dist/transport-CpRe7zgd.d.mts +123 -0
  46. package/dist/transport-CpRe7zgd.d.ts +123 -0
  47. package/dist/worlds/index.d.mts +1986 -1746
  48. package/dist/worlds/index.d.ts +1986 -1746
  49. package/dist/worlds/index.js +1470 -290
  50. package/dist/worlds/index.js.map +1 -1
  51. package/dist/worlds/index.mjs +1465 -286
  52. package/dist/worlds/index.mjs.map +1 -1
  53. package/package.json +6 -1
  54. package/runtime/gatewaysdk/environment/bundle_manifest.py +531 -0
  55. package/runtime/gatewaysdk/environment/factory_documents.py +670 -0
  56. package/runtime/gatewaysdk/environment/factory_rules.py +973 -0
  57. package/runtime/gatewaysdk/environment/factory_shapes.py +253 -0
  58. package/runtime/gatewaysdk/environment/factory_spine.py +1155 -0
  59. package/runtime/gatewaysdk/environment/factory_spine_shapes.py +480 -0
  60. package/runtime/gatewaysdk/environment/schema/__main__.py +2 -2
  61. package/runtime/gatewaysdk/environment/schema/_slack_fidelity.py +8 -23
  62. package/runtime/gatewaysdk/environment/schema/admission.py +61 -59
  63. package/runtime/gatewaysdk/environment/schema/api.py +3 -4
  64. package/runtime/gatewaysdk/environment/schema/assertions.py +7 -1
  65. package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +1 -0
  66. package/runtime/gatewaysdk/environment/schema/call_log.py +20 -0
  67. package/runtime/gatewaysdk/environment/schema/cast.py +133 -67
  68. package/runtime/gatewaysdk/environment/schema/compiler.py +16 -17
  69. package/runtime/gatewaysdk/environment/schema/database/base.py +2 -2
  70. package/runtime/gatewaysdk/environment/schema/handler_errors.py +58 -4
  71. package/runtime/gatewaysdk/environment/schema/host.py +94 -12
  72. package/runtime/gatewaysdk/environment/schema/host_browser.py +48 -0
  73. package/runtime/gatewaysdk/environment/schema/host_control.py +35 -2
  74. package/runtime/gatewaysdk/environment/schema/host_handoff.py +4 -1
  75. package/runtime/gatewaysdk/environment/schema/host_loops.py +27 -4
  76. package/runtime/gatewaysdk/environment/schema/host_metrics.py +69 -0
  77. package/runtime/gatewaysdk/environment/schema/host_requests.py +35 -0
  78. package/runtime/gatewaysdk/environment/schema/host_session.py +20 -2
  79. package/runtime/gatewaysdk/environment/schema/host_surfaces.py +6 -0
  80. package/runtime/gatewaysdk/environment/schema/host_versions.py +100 -19
  81. package/runtime/gatewaysdk/environment/schema/host_workers.py +172 -50
  82. package/runtime/gatewaysdk/environment/schema/ingest.py +12 -3
  83. package/runtime/gatewaysdk/environment/schema/journal.py +7 -2
  84. package/runtime/gatewaysdk/environment/schema/local.py +32 -7
  85. package/runtime/gatewaysdk/environment/schema/mapping.py +1 -1
  86. package/runtime/gatewaysdk/environment/schema/measured_tests.py +187 -0
  87. package/runtime/gatewaysdk/environment/schema/page_checks.py +123 -0
  88. package/runtime/gatewaysdk/environment/schema/platform.py +80 -270
  89. package/runtime/gatewaysdk/environment/schema/platform_query.py +4 -3
  90. package/runtime/gatewaysdk/environment/schema/platform_templates.py +420 -0
  91. package/runtime/gatewaysdk/environment/schema/process_memory.py +76 -0
  92. package/runtime/gatewaysdk/environment/schema/redaction.py +13 -0
  93. package/runtime/gatewaysdk/environment/schema/request_ledger.py +4 -1
  94. package/runtime/gatewaysdk/environment/schema/run_parameters.py +25 -0
  95. package/runtime/gatewaysdk/environment/schema/runtime.py +57 -5
  96. package/runtime/gatewaysdk/environment/schema/scaffold.py +386 -219
  97. package/runtime/gatewaysdk/environment/schema/session_files.py +13 -2
  98. package/runtime/gatewaysdk/environment/schema/shape_catalog.py +493 -0
  99. package/runtime/gatewaysdk/environment/schema/shape_declarations.py +219 -0
  100. package/runtime/gatewaysdk/environment/schema/skill.py +1 -0
  101. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +1 -1
  102. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +2 -2
  103. package/runtime/gatewaysdk/environment/schema/skills/factory-orchestrator/SKILL.md +147 -0
  104. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +5 -1
  105. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +8 -6
  106. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +9 -9
  107. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +33 -2
  108. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +6 -6
  109. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +17 -2
  110. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/new-world-sandbox.md +1 -1
  111. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/shape-catalog.md +59 -0
  112. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/ui-map.md +3 -2
  113. package/runtime/gatewaysdk/environment/schema/slack.py +55 -10
  114. package/runtime/gatewaysdk/environment/schema/snapshot.py +28 -2
  115. package/runtime/gatewaysdk/environment/schema/tasks.py +25 -2
  116. package/runtime/gatewaysdk/environment/schema/template_record.py +131 -0
  117. package/runtime/gatewaysdk/environment/schema/tools_world.py +7 -5
  118. package/runtime/gatewaysdk/environment/schema/ui.py +54 -33
  119. package/runtime/gatewaysdk/environment/schema/ui_interactions.py +419 -0
  120. package/runtime/gatewaysdk/environment/schema/ui_recorder.js +895 -0
  121. package/runtime/gatewaysdk/environment/schema/ui_replay.py +366 -0
  122. package/runtime/gatewaysdk/environment/schema/ui_replay_record.LICENSE +25 -0
  123. package/runtime/gatewaysdk/environment/schema/ui_replay_record.js +109 -0
  124. package/runtime/gatewaysdk/environment/schema/validation.py +24 -1
  125. package/runtime/gatewaysdk/environment/schema/worker.py +12 -5
  126. package/runtime/gatewaysdk/environment/schema/worker_key.py +38 -0
  127. package/runtime/gatewaysdk/environment/schema/worker_peaks.py +38 -0
  128. package/runtime/gatewaysdk/environment/schema/worker_watch.py +50 -0
  129. package/runtime/gatewaysdk/environment/schema/workers.py +245 -69
  130. package/runtime/gatewaysdk/environment/schema/world_host.py +96 -73
  131. package/runtime/gatewaysdk/environment/schema/world_tests.py +3 -1
  132. package/runtime/gatewaysdk/environment/secret_values.py +1 -1
  133. package/runtime/gatewaysdk/environment/world.py +34 -43
  134. package/runtime/gatewaysdk/environment/world_session_contract.py +7 -34
  135. package/skills/benchmarks-getting-started/SKILL.md +1 -1
  136. package/skills/connector-schema-authoring/SKILL.md +2 -2
  137. package/skills/connector-schema-authoring/connector-worlds.md +3 -2
  138. package/skills/connector-schema-authoring/world-schema.md +36 -23
  139. package/skills/factory-orchestrator/SKILL.md +147 -0
  140. package/skills/world-data-ingestion/ROWS.md +5 -1
  141. package/skills/world-data-ingestion/SKILL.md +8 -6
  142. package/skills/worlds-getting-started/SKILL.md +9 -9
  143. package/skills/worlds-getting-started/references/cli-mcp-map.md +33 -2
  144. package/skills/worlds-getting-started/references/gotchas.md +6 -6
  145. package/skills/worlds-getting-started/references/journal-checks.md +17 -2
  146. package/skills/worlds-getting-started/references/new-world-sandbox.md +1 -1
  147. package/skills/worlds-getting-started/references/shape-catalog.md +59 -0
  148. package/skills/worlds-getting-started/references/ui-map.md +3 -2
  149. package/dist/media-BIApiPzS.d.mts +0 -102
  150. package/dist/media-BIApiPzS.d.ts +0 -102
@@ -16,22 +16,23 @@ from contextlib import contextmanager
16
16
  from pathlib import Path
17
17
  from typing import Any, Optional
18
18
 
19
- from ..world_session_contract import OPEN_DOOR_FEATURE, REQUEST_LOG_PAGE_MAX
19
+ from ..world_session_contract import OPEN_DOOR_FEATURE, REQUEST_LOG_PAGE_MAX, WORLD_STATES_FEATURE
20
20
  from .admission import RETRY_AFTER_S, Admission
21
21
  from .cache_layout import SESSIONS_DIR, VERSIONS_DIR
22
22
  from .door import VENDOR_MODE, session_mode
23
- from .host_handoff import OUTCOMES
24
23
  from .host_loops import swept
24
+ from .host_metrics import exposition
25
25
  from .host_owners import PlatformOwners
26
- from .host_requests import BrowserRelay, DependencyRef, parse_dependency_refs, restore_sha256
26
+ from .host_requests import BrowserRelay, DependencyRef, parse_dependency_refs, restore_sha256, worker_snapshot
27
27
  from .host_session import Export, Session
28
28
  from .host_surfaces import SessionHost
29
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
30
+ from .host_versions import DEFAULT_MAX_BUNDLE_MB, CachedVersion, DataKey, VersionCache
31
+ from .host_workers import CALL_TIMEOUT_S, EXPORT_TIMEOUT_S, LOST, OUT_OF_MEMORY_RETRY, UNKNOWN_SESSION, VersionWorkers
32
32
  from .journal import WorldJournal
33
33
  from .lanes import Lanes
34
34
  from .request_ledger import HostLedger, LedgerLife, NoLedger
35
+ from .run_parameters import parse_run_parameters
35
36
  from .webhooks import WebhookPoll
36
37
  from .runtime import WorldRuntime
37
38
  from .session_files import (
@@ -40,13 +41,19 @@ from .session_files import (
40
41
  RecoveredSession,
41
42
  SessionExport,
42
43
  real_dir,
44
+ restore_vouches_pages,
43
45
  )
44
46
  from .session_move import PENDING_LEASE_S, Forwarding, platform_close
45
47
  from .tasks import TaskSpec, parse_task_spec
48
+ from .ui_interactions import RECORDER_ANSWER
46
49
  from .tools_world import DependencyWorld
47
50
  from .validation import fail
48
51
  from .verbs import SESSION_VERBS
49
- from .workers import Finishing, Worker, WorkerPool
52
+ from .worker_key import WorkerKey
53
+ from .process_memory import MemoryNeed
54
+ from .worker_peaks import PeakReport
55
+ from .worker_watch import WorkerMemoryWatch
56
+ from .workers import NO_WORKERS, Finishing, Worker, WorkerPool
50
57
 
51
58
  DEFAULT_LEASE_S = 3600.0
52
59
  DEFAULT_MAX_SESSIONS = 1500
@@ -98,6 +105,7 @@ class WorldHost:
98
105
  self.advertise_url = advertise_url
99
106
  self.workers = workers
100
107
  self.placement = VersionWorkers(workers, self) if workers is not None else None
108
+ self.memory_watch = WorkerMemoryWatch(workers, self.tally) if workers is not None else None
101
109
  self.run_handlers = run_handlers
102
110
  self.pinned_version = pinned_version
103
111
  self.limits = limits
@@ -105,6 +113,7 @@ class WorldHost:
105
113
  self.draining = False
106
114
  self.ledger: HostLedger = NoLedger()
107
115
  self.finishing = Finishing()
116
+ self.peaks = PeakReport()
108
117
  self.started_at = time.time()
109
118
  self._lock = threading.Lock()
110
119
  self._sessions: dict[str, Session] = {}
@@ -133,6 +142,9 @@ class WorldHost:
133
142
  pending: bool = False,
134
143
  auth: str | None = None,
135
144
  ledger_source: str | None = None,
145
+ parameters: dict[str, str] | None = None,
146
+ world_state: bool | None = None,
147
+ memory_peak_mb: int | None = None,
136
148
  ) -> dict:
137
149
  """Open ``session_id`` on ``version_id``, either on the bundled ``task``
138
150
  or on ``task_spec``, a session task of its own (:mod:`tasks`); exactly
@@ -141,7 +153,10 @@ class WorldHost:
141
153
  snapshot?}`` per alias the manifest declares, opened beside it. A
142
154
  ``pending`` open is a session moving here from another host: it serves
143
155
  nothing until the platform's row names this host (:class:`SessionMove`).
144
- ``auth`` (``vendor`` or ``open``) overrides the world's ``[auth] mode``."""
156
+ ``auth`` (``vendor`` or ``open``) overrides the world's ``[auth] mode``.
157
+ A ``world_state`` session is served in its version's states lane (:class:`WorkerKey`); a retry that
158
+ names no lane (``None``, a platform from before lanes) gets the session already open on either.
159
+ ``memory_peak_mb`` is what the platform measured the world to need: its worker is provisioned by it."""
145
160
  if self.pinned_version is not None and version_id != self.pinned_version:
146
161
  fail("host", f"this worker serves version {self.pinned_version} only, not {version_id}")
147
162
  if (task is None) == (task_spec is None):
@@ -150,7 +165,10 @@ class WorldHost:
150
165
  fail("host", "task is the bundled task's name")
151
166
  spec = parse_task_spec(task_spec) if task_spec is not None else None
152
167
  deps = parse_dependency_refs(dependencies)
168
+ knobs = parse_run_parameters(parameters)
153
169
  life = LedgerLife.of(ledger_source)
170
+ key = WorkerKey.of(version_id, world_state is True)
171
+ need = MemoryNeed(memory_peak_mb).mb if memory_peak_mb else 0
154
172
  self._replace_pending(session_id, restore, browser, pending)
155
173
  with self._lock:
156
174
  existing = self._sessions.get(session_id)
@@ -162,14 +180,18 @@ class WorldHost:
162
180
  self._refuse_closing(session_id)
163
181
  self._admit(session_id)
164
182
  if existing is not None:
165
- wanted = (version_id, (task, spec.raw if spec is not None else None), token)
183
+ data = DataKey.of(version_id, snapshot).sha256
184
+ lane = WorkerKey(version_id, existing.key.states) if world_state is None else key
185
+ wanted = (lane, data, knobs, (task, spec.raw if spec is not None else None), token)
166
186
  return self._reopened(existing, wanted, restore, pending, auth)
167
187
  try:
168
188
  session = self._open(
169
- session_id, version_id, bundle_url, task, spec, token, snapshot, browser, restore, deps, pending, auth
189
+ session_id, key, bundle_url, task, spec, token, snapshot, browser, restore, deps, pending, auth, knobs,
190
+ need,
170
191
  )
171
192
  session.life = life
172
193
  self._register(session)
194
+ self._refuse_poisoned(session)
173
195
  described = self._describe(session)
174
196
  except Exception:
175
197
  self.tally("open_failures")
@@ -186,6 +208,14 @@ class WorldHost:
186
208
  fail(UNKNOWN_SESSION, f"session {session_id} was closed while it opened")
187
209
  return described
188
210
 
211
+ def _refuse_poisoned(self, session: Session) -> None:
212
+ """A session registered on a worker poisoned since it was placed missed that worker's recovery: it is
213
+ closed here and its open is told to come back, never left on a worker about to stop."""
214
+ if session.worker is None or not session.worker.poisoned:
215
+ return
216
+ self.close(session.session_id, reason="replaced")
217
+ fail("busy", OUT_OF_MEMORY_RETRY, retryAfter=RETRY_AFTER_S)
218
+
189
219
  def _replace_pending(self, session_id: str, restore: dict[str, str] | None, browser: Any, pending: bool) -> None:
190
220
  """A draining host takes no move, refused before anything here changes. A copy pending a move here that
191
221
  a later open reuses gets a fresh lease; one from another export or browser is closed first."""
@@ -205,8 +235,9 @@ class WorldHost:
205
235
  this host is another host's to open, and one opened from another export or auth is refused."""
206
236
  if existing.move.leaving:
207
237
  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")
238
+ identity = (existing.key, existing.snapshot_sha256, existing.parameters, existing.task_key, existing.token)
239
+ if identity != wanted or auth not in (None, existing.auth):
240
+ fail("host", f"session {existing.session_id} is already open as another version, data, task, token or auth")
210
241
  if restore and restore_sha256(restore) != existing.restore_sha256:
211
242
  fail("host", f"session {existing.session_id} is already open from another export")
212
243
  if not pending:
@@ -234,7 +265,7 @@ class WorldHost:
234
265
  def _open(
235
266
  self,
236
267
  session_id: str,
237
- version_id: str,
268
+ key: WorkerKey,
238
269
  bundle_url: str,
239
270
  task: str | None,
240
271
  spec: TaskSpec | None,
@@ -245,8 +276,12 @@ class WorldHost:
245
276
  deps: list[DependencyRef],
246
277
  pending: bool,
247
278
  auth: str | None = None,
279
+ knobs: dict[str, str] | None = None,
280
+ need_mb: int = 0,
248
281
  ) -> Session:
282
+ version_id = key.version_id
249
283
  cached = self.cache.ensure(version_id, *self._trusted_version(bundle_url, snapshot))
284
+ data = DataKey.of(version_id, snapshot).sha256
250
285
  mode = session_mode(auth, token)
251
286
  dependencies = self._dependency_worlds(cached, deps)
252
287
  if spec is not None:
@@ -254,10 +289,11 @@ class WorldHost:
254
289
  relay = BrowserRelay.parse(browser)
255
290
  if cached.needs_worker and not self.run_handlers:
256
291
  return self._open_on_worker(
257
- cached, session_id, bundle_url, task, spec, token, relay, restore, deps, pending, mode
292
+ cached, key, session_id, bundle_url, task, spec, token, relay, restore, deps, pending, mode, snapshot, knobs,
293
+ need_mb,
258
294
  )
259
295
  session_dir = self.sessions_root / session_id
260
- with self._opens.turn(version_id):
296
+ with self._opens.turn(key.name):
261
297
  runtime = WorldRuntime.open(
262
298
  cached,
263
299
  session_dir,
@@ -266,7 +302,9 @@ class WorldHost:
266
302
  token=token,
267
303
  dependencies=dependencies,
268
304
  restore=lambda load: self._restore_into(restore, session_dir, load, cached),
305
+ pages_vouched=restore_vouches_pages(restore),
269
306
  journaled=self.run_handlers,
307
+ parameters=knobs,
270
308
  )
271
309
  runtime.calls.outbox.on_pressure = lambda: self.ledger.wake(session_id)
272
310
  session = Session(
@@ -287,14 +325,18 @@ class WorldHost:
287
325
  task_spec=spec,
288
326
  settings=cached.settings,
289
327
  restore_sha256=restore_sha256(restore),
328
+ snapshot_sha256=data,
329
+ parameters=dict(knobs or {}),
290
330
  pending=pending,
291
331
  auth=mode,
332
+ world_state=key.states,
292
333
  )
293
334
  return session
294
335
 
295
336
  def _open_on_worker(
296
337
  self,
297
338
  cached: CachedVersion,
339
+ key: WorkerKey,
298
340
  session_id: str,
299
341
  bundle_url: str,
300
342
  task: str | None,
@@ -305,8 +347,11 @@ class WorldHost:
305
347
  deps: list[DependencyRef],
306
348
  pending: bool,
307
349
  mode: str = VENDOR_MODE,
350
+ snapshot: dict[str, str] | None = None,
351
+ knobs: dict[str, str] | None = None,
352
+ need_mb: int = 0,
308
353
  ) -> Session:
309
- """Place the session on the version's worker (:class:`VersionWorkers`), which opens it from the bundle
354
+ """Place the session on its key's worker (:class:`VersionWorkers`), which opens it from the bundle
310
355
  this process cached; the supervisor keeps the ui's files and the browser tunnel, relays the ui's api
311
356
  calls as they came (``via: ui``), and hands an export it fetched and verified to the worker as a local
312
357
  file with its sha256, checked again there. No worker past the pool's memory budget: ``at_capacity``."""
@@ -323,11 +368,14 @@ class WorldHost:
323
368
  "task": task,
324
369
  "taskSpec": spec.raw if spec is not None else None,
325
370
  "token": token,
326
- "dependencies": [dep.raw for dep in deps],
371
+ "dependencies": [dep.for_worker for dep in deps],
372
+ "snapshot": worker_snapshot(snapshot),
373
+ "parameters": dict(knobs or {}),
327
374
  "auth": mode,
375
+ "worldState": key.states,
328
376
  }
329
377
  fetch = functools.partial(self._restore_source, restore)
330
- worker = self.placement.place(cached.version_id, session_id, body, fetch, self._opens)
378
+ worker = self.placement.place(key, session_id, body, fetch, self._opens, cached.world, need_mb)
331
379
  session = Session(
332
380
  session_id=session_id,
333
381
  version_id=cached.version_id,
@@ -347,8 +395,11 @@ class WorldHost:
347
395
  placement=body,
348
396
  settings=cached.settings,
349
397
  restore_sha256=restore_sha256(restore),
398
+ snapshot_sha256=DataKey.of(cached.version_id, snapshot).sha256,
399
+ parameters=dict(knobs or {}),
350
400
  pending=pending,
351
401
  auth=mode,
402
+ world_state=key.states,
352
403
  )
353
404
  return session
354
405
 
@@ -390,7 +441,7 @@ class WorldHost:
390
441
  if not isinstance(url, str) or not isinstance(sha256, str) or len(sha256) != 64:
391
442
  fail("host", "restore must be {url: <presigned export url>, sha256: <hex digest>}")
392
443
  check_object_store_url(url, self.object_store, "restore.url")
393
- return ExportFile(download_verified(url, sha256, session_dir / "restore.db"), sha256)
444
+ return ExportFile(download_verified(url, sha256, session_dir / "restore.db"), sha256, restore.get("recorder"))
394
445
 
395
446
  def _recovered_source(self, directory: Path) -> RecoveredSession:
396
447
  root = self.sessions_root.parent / RECOVERED_DIR
@@ -410,7 +461,7 @@ class WorldHost:
410
461
 
411
462
  def _trusted_version(self, bundle_url: str, snapshot: dict[str, str] | None) -> tuple[str, dict[str, str] | None]:
412
463
  check_object_store_url(bundle_url, self.object_store, "bundleUrl")
413
- if snapshot:
464
+ if snapshot and snapshot.get("url") is not None:
414
465
  check_object_store_url(snapshot.get("url"), self.object_store, "snapshot.url")
415
466
  return bundle_url, snapshot
416
467
 
@@ -461,6 +512,15 @@ class WorldHost:
461
512
  return {"closed": True, "openedAt": None, "sessionSeconds": 0.0}
462
513
  return {"closed": True, "openedAt": session.opened_at, "sessionSeconds": session.seconds}
463
514
 
515
+ def browser_hosts(self, session_id: str, domain: str) -> list[str]:
516
+ with self._lock:
517
+ session = self._sessions.get(session_id)
518
+ if session is None:
519
+ fail(UNKNOWN_SESSION, f"no session {session_id} on this host")
520
+ if session.browser is None:
521
+ fail("host", f"session {session_id} was opened without a browser surface")
522
+ return session.browser_hosts(domain)
523
+
464
524
  def set_browser(self, session_id: str, browser: Any) -> dict:
465
525
  """Point the session's browser surface at another pool relay: the one
466
526
  it had died and the platform leased a replacement. Connections open
@@ -504,12 +564,12 @@ class WorldHost:
504
564
  with self._lock:
505
565
  session.export = None
506
566
  self._counters["exports_unchanged"] += 1
507
- return {"exportId": None, "sha256": sha256, "bytes": size, "unchanged": True}
567
+ return {"exportId": None, "sha256": sha256, "bytes": size, "unchanged": True, **RECORDER_ANSWER}
508
568
  export = Export(export_id=path.stem, path=path, sha256=sha256, bytes=size, content_type=engine.content_type)
509
569
  with self._lock:
510
570
  session.export = export
511
571
  self._counters["exports"] += 1
512
- described = export.describe()
572
+ described = {**export.describe(), **RECORDER_ANSWER}
513
573
  if self.run_handlers:
514
574
  described["path"] = str(path)
515
575
  return described
@@ -648,6 +708,7 @@ class WorldHost:
648
708
  return []
649
709
  swept(self.placement.recover_dead, "recovered the dead worker of version")
650
710
  swept(self.placement.recover_stuck, "recycled the stuck worker of version")
711
+ swept(self.memory_watch.sweep, "found near its memory cap the worker of version")
651
712
  return self.workers.reap_idle()
652
713
 
653
714
  def session_count(self) -> int:
@@ -662,6 +723,10 @@ class WorldHost:
662
723
  """Whether a call of the session still holds its turn on its worker (one past its time)."""
663
724
  return self.placement is not None and session.worker is not None and self.placement.holds_turn(session)
664
725
 
726
+ def reported(self, stats: dict) -> None:
727
+ """The platform took a heartbeat of ``stats``: the peaks it carried are its now."""
728
+ self.peaks.taken(stats.get("workerPeaks") or [])
729
+
665
730
  def worker_count(self) -> int:
666
731
  return len(self.workers._workers) if self.workers is not None else 0
667
732
 
@@ -669,7 +734,7 @@ class WorldHost:
669
734
  """Cache a version before any session asks for it, so the first open
670
735
  pays nothing. Idempotent: a version already here is reported, not
671
736
  rebuilt."""
672
- already = self.cache.has(version_id)
737
+ already = self.cache.has(version_id, snapshot)
673
738
  if not already:
674
739
  self.cache.ensure(version_id, *self._trusted_version(bundle_url, snapshot))
675
740
  return {"versionId": version_id, "cached": True, "alreadyCached": already}
@@ -697,9 +762,12 @@ class WorldHost:
697
762
  "capacity": self.max_sessions,
698
763
  "draining": self.draining,
699
764
  "workers": self.worker_count(),
700
- "maxWorkers": self.workers.max_workers if self.workers is not None else 0,
765
+ **(self.workers.stats() if self.workers is not None else NO_WORKERS),
766
+ "workerPeaks": self.peaks.pending(self.workers.peaks()) if self.workers is not None else [],
767
+ "workerMemory": self.memory_watch.readings() if self.memory_watch is not None else [],
701
768
  "versions": self.cache.version_ids(),
702
769
  "versionsInUse": versions_in_use,
770
+ "cloneMode": self.cache.clone_mode,
703
771
  "uptimeSeconds": time.time() - self.started_at,
704
772
  "startedAt": self.started_at,
705
773
  "build": self.build,
@@ -707,56 +775,11 @@ class WorldHost:
707
775
  "sessionSeconds": session_seconds,
708
776
  "pid": os.getpid(),
709
777
  "limits": self.limits,
710
- "features": [OPEN_DOOR_FEATURE],
778
+ "features": [OPEN_DOOR_FEATURE, WORLD_STATES_FEATURE],
711
779
  }
712
780
 
713
781
  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"
782
+ return exposition(self.stats())
760
783
 
761
784
  def _dependency_worlds(self, cached: CachedVersion, deps: list[DependencyRef]) -> dict[str, DependencyWorld]:
762
785
  """The dependency versions a session opens beside ``cached``, cached the
@@ -840,10 +863,10 @@ class WorldHost:
840
863
  """One of the session's version's turns (:class:`Admission`) for a data-plane request, once its
841
864
  move lets it in (:class:`SessionMove`): held while the session moves, counted against the
842
865
  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)
866
+ waiting = functools.partial(self.admission.waiting, session.key.name, session.session_id)
844
867
  owner_now = functools.partial(self._owner_now, session.session_id)
845
868
  with session.move.request(waiting, owner_now, self.advertise_url, hopped):
846
- with self.admission.turn(session.version_id, session.session_id):
869
+ with self.admission.turn(session.key.name, session.session_id):
847
870
  yield
848
871
 
849
872
  def _owner_now(self, session_id: str) -> str | None:
@@ -865,7 +888,7 @@ class WorldHost:
865
888
  with (
866
889
  self.using(session_id, confirm=True, touch=touch) as session,
867
890
  session.move.verb(),
868
- self.admission.turn(session.version_id, session.session_id),
891
+ self.admission.turn(session.key.name, session.session_id),
869
892
  ):
870
893
  if session.worker is not None:
871
894
  assert self.placement is not None
@@ -147,6 +147,7 @@ class Report:
147
147
  cases: list[CaseResult]
148
148
  python: PythonResult
149
149
  scenario: str | None = None
150
+ served: bool = False
150
151
 
151
152
  @property
152
153
  def summary(self) -> dict:
@@ -378,9 +379,10 @@ def run(world: str | Path, *, scenario: str | None = None) -> Report:
378
379
  python = _run_python(root, python_files, session)
379
380
  finally:
380
381
  session.close()
382
+ served = bool(results) or python.tests > python.skipped
381
383
  if not results and python.ran_nothing and declares_on_push_tests(root):
382
384
  python = _unkept_promise(python)
383
- return Report(str(root), results, python, scenario)
385
+ return Report(str(root), results, python, scenario, served)
384
386
 
385
387
 
386
388
  def _unkept_promise(python: PythonResult) -> PythonResult:
@@ -1,7 +1,7 @@
1
1
  """What a secret looks like on its own, whatever field it sits in.
2
2
 
3
3
  ``SECRET_VALUE`` is the key shapes the browser recorder
4
- (``world_browser.redact_action_args``, twinned by the TypeScript recorders) and
4
+ (``credential_field.redact_action_args``, twinned by the TypeScript recorders) and
5
5
  the world call log (``schema.call_log.CallRedaction``) both redact: a provider
6
6
  key by its prefix, an AWS access key id, a bearer header. ``SECRET_TOKEN`` and
7
7
  :func:`basic_credentials` add what the call log also redacts: a JSON Web Token,
@@ -1,17 +1,4 @@
1
- """What a tree on disk IS, decided once.
2
-
3
- ``World.from_tree`` is the one Python detector: the local runtime
4
- (``_bundle.detect_kind``), the data commands (``data.world_kind``), the hub
5
- client (``harbor_adapter.detect_env_kind``), the benchmark runner
6
- (``engines/hub_bundle.detect_env_kind``), the platform bridge
7
- (``platform.world_root``) and the World Host (``host_versions.world_tree``) all read
8
- their answer from here. The TypeScript twin is
9
- ``packages/shared/src/world/`` (``WorldTree`` + ``World.fromTree``); the
10
- corpus under ``conformance/worlds/`` pins both to the same answers.
11
-
12
- Stdlib only: the benchmark runner vendors this subpackage without the SDK's
13
- dependencies.
14
- """
1
+ """Stdlib only: the benchmark runner vendors this subpackage without the SDK's dependencies."""
15
2
 
16
3
  from __future__ import annotations
17
4
 
@@ -26,15 +13,14 @@ from typing import ClassVar
26
13
 
27
14
  from ._toml import tomllib
28
15
  from .errors import WorldStartError
29
- from .world_session_contract import API_BUNDLE_RUN_REFUSAL
16
+ from .bundle_manifest import BUNDLE_MANIFEST
17
+ from .world_session_contract import API_BUNDLE_RUN_REFUSAL, BUNDLE_RUN_REFUSAL
30
18
 
31
19
  try: # optional: only consulted when a tree ships a root .gitignore
32
20
  from gitignore_parser import parse_gitignore
33
21
  except ImportError: # pragma: no cover - the runner and the sandbox vendor this module alone
34
22
  parse_gitignore = None # type: ignore[assignment]
35
23
 
36
- # Twin of packages/shared/src/world/markers.ts.
37
-
38
24
  WORLD_MANIFEST = "gateway-env.toml"
39
25
  API_BUNDLE_MANIFEST = "gateway-api-world.toml"
40
26
  BUNDLED_WORLD_PREFIX = "server/world/"
@@ -52,21 +38,16 @@ KIND_API = "api"
52
38
  KIND_HARBOR = "harbor"
53
39
  KIND_VERIFIERS = "verifiers"
54
40
  KIND_VERIFIERS_V1 = "verifiers-v1"
41
+ KIND_BUNDLE = "bundle"
55
42
 
56
43
  _SKIPPED_DIRS = frozenset({"dist", "build", "outputs", "__pycache__", "node_modules"})
57
- # A root Gateway marker widens the hashed root from Prime's source globs to
58
- # every ordinary root file: those kinds keep executable contract (tasks.json,
59
- # connector.toml, a benchmark's config and fixtures) at the root.
60
- _BROAD_ROOT_MARKERS = frozenset({WORLD_MANIFEST, API_BUNDLE_MANIFEST, BENCHMARK_CONFIG})
44
+ # A root Gateway marker widens the hashed root to every ordinary root file: those kinds keep executable contract there.
45
+ _BROAD_ROOT_MARKERS = frozenset({WORLD_MANIFEST, API_BUNDLE_MANIFEST, BENCHMARK_CONFIG, BUNDLE_MANIFEST})
61
46
  _HASH_CHUNK = 1 << 20
62
47
  _HARBOR_TASK = re.compile(r"^(?:tasks/)?([^/]+)/task\.toml$")
63
48
 
64
- # The `verifiers.v1` namespace first shipped in verifiers 0.2.0, so a v1
65
- # package declares verifiers>=0.2 (or ~=0.2 / ==0.2.* / >=1 / ==1.*) in
66
- # pyproject — minor >= 2 on the 0.x line or any major >= 1, never 0.0/0.1 —
67
- # and/or imports the namespace or subclasses Taskset alongside the v1
68
- # packaging convention of an ``__all__`` export (any library may name a class
69
- # Taskset). A bare unversioned dependency or a pre-0.2 pin is v0.
49
+ # `verifiers.v1` first shipped in verifiers 0.2.0: a v1 package pins >=0.2 (or any major >= 1), imports the
50
+ # namespace, or subclasses Taskset beside an ``__all__`` export (any library may name a class Taskset).
70
51
  _V1_DEP = re.compile(
71
52
  r"""["']verifiers\s*(?:\[[^\]]*\])?\s*(?:>=|~=|==|>)\s*""" r"""(?:0\.(?:[2-9]\d*|[1-9]\d+)|[1-9]\d*)"""
72
53
  )
@@ -92,8 +73,6 @@ def _ordinary_root_file(name: str, broad: bool) -> bool:
92
73
 
93
74
 
94
75
  def is_hashed_path(relative: str, broad_root: bool) -> bool:
95
- """Twin of ``worldTree.ts isHashedPath``: the path-only half of the archive
96
- rule (hidden names, pruned directories, the root globs)."""
97
76
  parts = relative.split("/")
98
77
  name = parts[-1]
99
78
  if name.startswith(".") or "__pycache__" in parts:
@@ -186,9 +165,6 @@ WorldManifest.ABSENT = WorldManifest(None, None, None)
186
165
 
187
166
  @dataclass(frozen=True)
188
167
  class Exclusion:
189
- """One entry the archive rules dropped: a whole directory (``name/``,
190
- ``files`` counted) or a single root file."""
191
-
192
168
  path: str
193
169
  files: int
194
170
 
@@ -233,17 +209,9 @@ class WorldTree:
233
209
  def has_connector(self) -> bool:
234
210
  return self.has(self.world_path(CONNECTOR_SPEC))
235
211
 
236
- # Vendored from Prime Intellect's ``prime`` CLI (MIT; THIRD_PARTY_LICENSES)
237
- # so a container hashed here resolves to the same logical version on their
238
- # Environments Hub: SHA-256 over ``file:<relpath>`` + raw bytes, in sorted
239
- # path order, over README.md / pyproject.toml / *.py at the root plus every
240
- # non-hidden nested file outside dist, build, outputs, __pycache__ and
241
- # *.egg-info. A root Gateway marker widens the root to every ordinary file
242
- # (the marker itself must be hashed or a manifest-only edit dedups into the
243
- # previous version and is silently discarded). Symlinks and ``.gitignore``-d
244
- # paths are dropped. This is the version primary key, NOT a tarball digest.
245
- # Twin: ``packages/shared/src/world/worldTree.ts`` (``isHashedPath`` +
246
- # ``contentHash``); the corpus under ``conformance/worlds/`` pins both.
212
+ # Vendored from Prime Intellect's ``prime`` CLI (MIT; THIRD_PARTY_LICENSES) so a tree hashes to the same version
213
+ # on their hub. It is the version primary key, not a tarball digest: a root marker must be hashed, or a
214
+ # manifest-only edit dedups into the previous version and is silently discarded.
247
215
 
248
216
  @property
249
217
  def broad_root(self) -> bool:
@@ -390,6 +358,8 @@ class World:
390
358
  def from_tree(tree: WorldTree) -> World:
391
359
  if tree.is_api_bundle:
392
360
  return ApiBundle(tree)
361
+ if WorldBundle.marks(tree):
362
+ return WorldBundle(tree)
393
363
  if tree.has(WORLD_MANIFEST):
394
364
  schema = tree.has_schema_marker or tree.manifest.declares_schema
395
365
  return SchemaWorld(tree) if schema else ToolsWorld(tree)
@@ -521,6 +491,25 @@ class ApiBundle(World):
521
491
  return API_BUNDLE_RUN_REFUSAL
522
492
 
523
493
 
494
+ class WorldBundle(World):
495
+ """``gateway-bundle.toml`` at the root: the member worlds it opens together. It runs nothing itself."""
496
+
497
+ kind = KIND_BUNDLE
498
+ shape = "bundle"
499
+
500
+ @staticmethod
501
+ def marks(tree: WorldTree) -> bool:
502
+ return tree.has(BUNDLE_MANIFEST)
503
+
504
+ @property
505
+ def local_runtime(self) -> bool:
506
+ return False
507
+
508
+ @property
509
+ def agent_run_refusal(self) -> str:
510
+ return BUNDLE_RUN_REFUSAL
511
+
512
+
524
513
  class ContainerBench(World):
525
514
  @property
526
515
  def substrate(self) -> str:
@@ -567,6 +556,7 @@ class PlainTree(VerifiersBench):
567
556
 
568
557
  __all__ = [
569
558
  "API_BUNDLE_MANIFEST",
559
+ "BUNDLE_MANIFEST",
570
560
  "BUNDLED_WORLD_PREFIX",
571
561
  "CONNECTOR_SPEC",
572
562
  "PYPROJECT",
@@ -580,6 +570,7 @@ __all__ = [
580
570
  "ToolsWorld",
581
571
  "VerifiersBench",
582
572
  "World",
573
+ "WorldBundle",
583
574
  "WorldManifest",
584
575
  "WorldTree",
585
576
  ]