@withgateway/sdk 0.4.0 → 0.9.1

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 (157) hide show
  1. package/dist/agents/index.d.mts +573 -0
  2. package/dist/agents/index.d.ts +573 -0
  3. package/dist/agents/index.js +1443 -0
  4. package/dist/agents/index.js.map +1 -0
  5. package/dist/agents/index.mjs +1394 -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 +5655 -1890
  10. package/dist/cli.js.map +1 -1
  11. package/dist/cli.mjs +5769 -2005
  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 +418 -120
  16. package/dist/files/index.js.map +1 -1
  17. package/dist/files/index.mjs +418 -120
  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-DUHmS74p.d.ts → index-DIN14Lhg.d.ts} +27 -4
  24. package/dist/{index-mJhG3vZU.d.mts → index-DuB-eQ0Z.d.mts} +27 -4
  25. package/dist/index.d.mts +7 -4
  26. package/dist/index.d.ts +7 -4
  27. package/dist/index.js +2862 -438
  28. package/dist/index.js.map +1 -1
  29. package/dist/index.mjs +2820 -431
  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/replay/index.d.mts +1 -1
  34. package/dist/replay/index.d.ts +1 -1
  35. package/dist/replay/index.js.map +1 -1
  36. package/dist/replay/index.mjs.map +1 -1
  37. package/dist/traces/index.d.mts +3 -1
  38. package/dist/traces/index.d.ts +3 -1
  39. package/dist/traces/index.js +418 -120
  40. package/dist/traces/index.js.map +1 -1
  41. package/dist/traces/index.mjs +418 -120
  42. package/dist/traces/index.mjs.map +1 -1
  43. package/dist/tracing/index.d.mts +3 -2
  44. package/dist/tracing/index.d.ts +3 -2
  45. package/dist/tracing/index.js +257 -16
  46. package/dist/tracing/index.js.map +1 -1
  47. package/dist/tracing/index.mjs +257 -16
  48. package/dist/tracing/index.mjs.map +1 -1
  49. package/dist/transport-CpRe7zgd.d.mts +123 -0
  50. package/dist/transport-CpRe7zgd.d.ts +123 -0
  51. package/dist/worlds/index.d.mts +2086 -1749
  52. package/dist/worlds/index.d.ts +2086 -1749
  53. package/dist/worlds/index.js +1471 -269
  54. package/dist/worlds/index.js.map +1 -1
  55. package/dist/worlds/index.mjs +1466 -265
  56. package/dist/worlds/index.mjs.map +1 -1
  57. package/package.json +6 -1
  58. package/runtime/gatewaysdk/environment/_bundle.py +4 -6
  59. package/runtime/gatewaysdk/environment/_world.py +24 -1
  60. package/runtime/gatewaysdk/environment/bundle_manifest.py +243 -0
  61. package/runtime/gatewaysdk/environment/runtime.py +45 -2
  62. package/runtime/gatewaysdk/environment/schema/__main__.py +2 -2
  63. package/runtime/gatewaysdk/environment/schema/_slack_fidelity.py +8 -23
  64. package/runtime/gatewaysdk/environment/schema/api.py +27 -7
  65. package/runtime/gatewaysdk/environment/schema/assertions.py +7 -1
  66. package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +2 -0
  67. package/runtime/gatewaysdk/environment/schema/call_capture.py +13 -1
  68. package/runtime/gatewaysdk/environment/schema/call_log.py +66 -0
  69. package/runtime/gatewaysdk/environment/schema/call_redaction.py +6 -0
  70. package/runtime/gatewaysdk/environment/schema/compiler.py +4 -1
  71. package/runtime/gatewaysdk/environment/schema/conform.py +32 -8
  72. package/runtime/gatewaysdk/environment/schema/connector.py +5 -0
  73. package/runtime/gatewaysdk/environment/schema/connectors/custom/handlers.py +2 -1
  74. package/runtime/gatewaysdk/environment/schema/connectors/github/api/handlers.py +217 -58
  75. package/runtime/gatewaysdk/environment/schema/connectors/github/connector.toml +9 -19
  76. package/runtime/gatewaysdk/environment/schema/connectors/github/scenarios/default/seed/github_webhooks.json +10 -2
  77. package/runtime/gatewaysdk/environment/schema/connectors/github/tests/webhooks.json +47 -0
  78. package/runtime/gatewaysdk/environment/schema/connectors/github/world.json +21 -0
  79. package/runtime/gatewaysdk/environment/schema/connectors/jamf/api/handlers.py +185 -18
  80. package/runtime/gatewaysdk/environment/schema/connectors/jamf/connector.toml +29 -14
  81. package/runtime/gatewaysdk/environment/schema/connectors/jamf/provenance.json +43 -12
  82. package/runtime/gatewaysdk/environment/schema/connectors/jamf/scenarios/default/seed/jamf_webhooks.json +2 -2
  83. package/runtime/gatewaysdk/environment/schema/connectors/jamf/scope.toml +4 -17
  84. package/runtime/gatewaysdk/environment/schema/connectors/jamf/tests/webhooks.json +107 -0
  85. package/runtime/gatewaysdk/environment/schema/connectors/jamf/vendor-openapi.json +1 -1
  86. package/runtime/gatewaysdk/environment/schema/connectors/linear/api/handlers.py +85 -1
  87. package/runtime/gatewaysdk/environment/schema/connectors/linear/connector.toml +19 -31
  88. package/runtime/gatewaysdk/environment/schema/connectors/linear/provenance.json +18 -8
  89. package/runtime/gatewaysdk/environment/schema/connectors/linear/scenarios/default/seed/webhooks.json +19 -3
  90. package/runtime/gatewaysdk/environment/schema/connectors/linear/tests/test_webhooks.py +71 -0
  91. package/runtime/gatewaysdk/environment/schema/database/base.py +2 -2
  92. package/runtime/gatewaysdk/environment/schema/database/guard.py +2 -1
  93. package/runtime/gatewaysdk/environment/schema/handler_errors.py +27 -1
  94. package/runtime/gatewaysdk/environment/schema/host.py +74 -11
  95. package/runtime/gatewaysdk/environment/schema/host_browser.py +48 -0
  96. package/runtime/gatewaysdk/environment/schema/host_control.py +33 -2
  97. package/runtime/gatewaysdk/environment/schema/host_handoff.py +4 -1
  98. package/runtime/gatewaysdk/environment/schema/host_requests.py +14 -0
  99. package/runtime/gatewaysdk/environment/schema/host_session.py +13 -2
  100. package/runtime/gatewaysdk/environment/schema/host_surfaces.py +6 -0
  101. package/runtime/gatewaysdk/environment/schema/host_versions.py +96 -19
  102. package/runtime/gatewaysdk/environment/schema/journal.py +10 -4
  103. package/runtime/gatewaysdk/environment/schema/local.py +33 -7
  104. package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +20 -5
  105. package/runtime/gatewaysdk/environment/schema/page_checks.py +123 -0
  106. package/runtime/gatewaysdk/environment/schema/platform.py +33 -480
  107. package/runtime/gatewaysdk/environment/schema/platform_templates.py +332 -0
  108. package/runtime/gatewaysdk/environment/schema/request_ledger.py +4 -1
  109. package/runtime/gatewaysdk/environment/schema/run_parameters.py +25 -0
  110. package/runtime/gatewaysdk/environment/schema/runtime.py +49 -4
  111. package/runtime/gatewaysdk/environment/schema/scaffold.py +369 -218
  112. package/runtime/gatewaysdk/environment/schema/session_files.py +13 -2
  113. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +1 -1
  114. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/CONNECTORS.md +3 -3
  115. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +20 -24
  116. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +11 -11
  117. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +9 -9
  118. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +45 -12
  119. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +40 -9
  120. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +17 -2
  121. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/new-world-sandbox.md +1 -1
  122. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/ui-map.md +3 -2
  123. package/runtime/gatewaysdk/environment/schema/slack.py +55 -10
  124. package/runtime/gatewaysdk/environment/schema/snapshot.py +30 -4
  125. package/runtime/gatewaysdk/environment/schema/tasks.py +25 -2
  126. package/runtime/gatewaysdk/environment/schema/template_record.py +131 -0
  127. package/runtime/gatewaysdk/environment/schema/tools_world.py +26 -5
  128. package/runtime/gatewaysdk/environment/schema/ui.py +54 -33
  129. package/runtime/gatewaysdk/environment/schema/ui_interactions.py +419 -0
  130. package/runtime/gatewaysdk/environment/schema/ui_recorder.js +895 -0
  131. package/runtime/gatewaysdk/environment/schema/ui_replay.py +366 -0
  132. package/runtime/gatewaysdk/environment/schema/ui_replay_record.LICENSE +25 -0
  133. package/runtime/gatewaysdk/environment/schema/ui_replay_record.js +109 -0
  134. package/runtime/gatewaysdk/environment/schema/validation.py +10 -1
  135. package/runtime/gatewaysdk/environment/schema/verbs.py +6 -0
  136. package/runtime/gatewaysdk/environment/schema/webhooks.py +687 -0
  137. package/runtime/gatewaysdk/environment/schema/worker.py +5 -1
  138. package/runtime/gatewaysdk/environment/schema/workers.py +8 -1
  139. package/runtime/gatewaysdk/environment/schema/world_host.py +64 -18
  140. package/runtime/gatewaysdk/environment/schema/world_tests.py +74 -0
  141. package/runtime/gatewaysdk/environment/secret_values.py +1 -1
  142. package/runtime/gatewaysdk/environment/world.py +34 -43
  143. package/runtime/gatewaysdk/environment/world_session_contract.py +7 -34
  144. package/skills/benchmarks-getting-started/SKILL.md +1 -1
  145. package/skills/connector-schema-authoring/CONNECTORS.md +3 -3
  146. package/skills/connector-schema-authoring/SKILL.md +20 -24
  147. package/skills/connector-schema-authoring/connector-worlds.md +155 -13
  148. package/skills/connector-schema-authoring/world-schema.md +36 -29
  149. package/skills/world-data-ingestion/SKILL.md +11 -11
  150. package/skills/worlds-getting-started/SKILL.md +9 -9
  151. package/skills/worlds-getting-started/references/cli-mcp-map.md +45 -12
  152. package/skills/worlds-getting-started/references/gotchas.md +40 -9
  153. package/skills/worlds-getting-started/references/journal-checks.md +17 -2
  154. package/skills/worlds-getting-started/references/new-world-sandbox.md +1 -1
  155. package/skills/worlds-getting-started/references/ui-map.md +3 -2
  156. package/dist/media-BIApiPzS.d.mts +0 -102
  157. package/dist/media-BIApiPzS.d.ts +0 -102
@@ -18,6 +18,7 @@ from pathlib import Path
18
18
  from .cache_layout import VERSIONS_DIR, WORKERS_DIR
19
19
  from .host import make_host_handler
20
20
  from .workers import (
21
+ DEFAULT_WORKER_FILE_MB,
21
22
  DEFAULT_WORKER_MEMORY_MB,
22
23
  WORKER_LEASE_S,
23
24
  UnixHTTPServer,
@@ -46,7 +47,10 @@ def main(argv: list[str] | None = None) -> int:
46
47
  else:
47
48
  listening = args.socket
48
49
  seal_process()
49
- limits = apply_limits(memory_mb=int(os.environ.get("WORLDS_WORKER_MEMORY_MB") or DEFAULT_WORKER_MEMORY_MB))
50
+ limits = apply_limits(
51
+ memory_mb=int(os.environ.get("WORLDS_WORKER_MEMORY_MB") or DEFAULT_WORKER_MEMORY_MB),
52
+ file_mb=int(os.environ.get("WORLDS_WORKER_FILE_MB") or DEFAULT_WORKER_FILE_MB),
53
+ )
50
54
 
51
55
  cache_root = Path(args.cache_root)
52
56
  world_host = WorldHost(
@@ -77,7 +77,7 @@ DEFAULT_WORKER_BUDGET_MB = 4096
77
77
  #: cap as the rail each worker cannot cross, and sizes the container for
78
78
  #: footprint x workers plus the supervisor's share.
79
79
  DEFAULT_WORKER_FOOTPRINT_MB: int | None = None
80
- #: Largest file a worker may write (its session databases), in MiB.
80
+ #: Largest file a worker may write (its session databases), in MiB, unless ``WORLDS_WORKER_FILE_MB`` says otherwise.
81
81
  DEFAULT_WORKER_FILE_MB = 4096
82
82
  #: Open files per worker: one per live session plus the sockets serving them.
83
83
  DEFAULT_WORKER_NOFILE = 4096
@@ -355,6 +355,7 @@ def worker_environment(
355
355
  home: Path,
356
356
  worlds_domain: str,
357
357
  memory_mb: int,
358
+ file_mb: int = DEFAULT_WORKER_FILE_MB,
358
359
  source: Mapping[str, str] | None = None,
359
360
  ) -> dict[str, str]:
360
361
  """The environment a worker is started with: the interpreter's own needs,
@@ -366,6 +367,7 @@ def worker_environment(
366
367
  HOME=str(home),
367
368
  WORLDS_WORKER_SECRET=secret,
368
369
  WORLDS_WORKER_MEMORY_MB=str(memory_mb),
370
+ WORLDS_WORKER_FILE_MB=str(file_mb),
369
371
  WORLDS_INGRESS_DOMAIN=worlds_domain,
370
372
  )
371
373
  return env
@@ -601,7 +603,10 @@ class WorkerPool:
601
603
  footprint_mb: int | None = DEFAULT_WORKER_FOOTPRINT_MB,
602
604
  idle_s: float = DEFAULT_WORKER_IDLE_S,
603
605
  python: str = sys.executable,
606
+ file_mb: int = DEFAULT_WORKER_FILE_MB,
604
607
  ):
608
+ if file_mb <= 0:
609
+ raise ValueError(f"a worker's file cap ({file_mb} MiB) must be at least 1 MiB (WORLDS_WORKER_FILE_MB)")
605
610
  if footprint_mb is None:
606
611
  footprint_mb = memory_mb
607
612
  if footprint_mb <= 0 or footprint_mb > memory_mb:
@@ -630,6 +635,7 @@ class WorkerPool:
630
635
  self.memory_mb = memory_mb
631
636
  self.budget_mb = budget_mb
632
637
  self.footprint_mb = footprint_mb
638
+ self.file_mb = file_mb
633
639
  self.max_workers = budget_mb // footprint_mb
634
640
  self.idle_s = idle_s
635
641
  self.python = python
@@ -752,6 +758,7 @@ class WorkerPool:
752
758
  home=home,
753
759
  worlds_domain=self.worlds_domain,
754
760
  memory_mb=self.memory_mb,
761
+ file_mb=self.file_mb,
755
762
  ),
756
763
  cwd=str(home),
757
764
  stdin=subprocess.DEVNULL,
@@ -16,22 +16,24 @@ 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
23
  from .host_handoff import OUTCOMES
24
24
  from .host_loops import swept
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
30
+ from .host_versions import DEFAULT_MAX_BUNDLE_MB, CachedVersion, DataKey, VersionCache
31
31
  from .host_workers import CALL_TIMEOUT_S, EXPORT_TIMEOUT_S, LOST, 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
36
+ from .webhooks import WebhookPoll
35
37
  from .runtime import WorldRuntime
36
38
  from .session_files import (
37
39
  RECOVERED_DIR,
@@ -39,9 +41,11 @@ from .session_files import (
39
41
  RecoveredSession,
40
42
  SessionExport,
41
43
  real_dir,
44
+ restore_vouches_pages,
42
45
  )
43
46
  from .session_move import PENDING_LEASE_S, Forwarding, platform_close
44
47
  from .tasks import TaskSpec, parse_task_spec
48
+ from .ui_interactions import RECORDER_ANSWER
45
49
  from .tools_world import DependencyWorld
46
50
  from .validation import fail
47
51
  from .verbs import SESSION_VERBS
@@ -132,6 +136,7 @@ class WorldHost:
132
136
  pending: bool = False,
133
137
  auth: str | None = None,
134
138
  ledger_source: str | None = None,
139
+ parameters: dict[str, str] | None = None,
135
140
  ) -> dict:
136
141
  """Open ``session_id`` on ``version_id``, either on the bundled ``task``
137
142
  or on ``task_spec``, a session task of its own (:mod:`tasks`); exactly
@@ -149,6 +154,7 @@ class WorldHost:
149
154
  fail("host", "task is the bundled task's name")
150
155
  spec = parse_task_spec(task_spec) if task_spec is not None else None
151
156
  deps = parse_dependency_refs(dependencies)
157
+ knobs = parse_run_parameters(parameters)
152
158
  life = LedgerLife.of(ledger_source)
153
159
  self._replace_pending(session_id, restore, browser, pending)
154
160
  with self._lock:
@@ -161,11 +167,12 @@ class WorldHost:
161
167
  self._refuse_closing(session_id)
162
168
  self._admit(session_id)
163
169
  if existing is not None:
164
- wanted = (version_id, (task, spec.raw if spec is not None else None), token)
170
+ data = DataKey.of(version_id, snapshot).sha256
171
+ wanted = (version_id, data, knobs, (task, spec.raw if spec is not None else None), token)
165
172
  return self._reopened(existing, wanted, restore, pending, auth)
166
173
  try:
167
174
  session = self._open(
168
- session_id, version_id, bundle_url, task, spec, token, snapshot, browser, restore, deps, pending, auth
175
+ session_id, version_id, bundle_url, task, spec, token, snapshot, browser, restore, deps, pending, auth, knobs
169
176
  )
170
177
  session.life = life
171
178
  self._register(session)
@@ -204,8 +211,9 @@ class WorldHost:
204
211
  this host is another host's to open, and one opened from another export or auth is refused."""
205
212
  if existing.move.leaving:
206
213
  fail("draining", f"session {existing.session_id} is moving to another host; place it elsewhere")
207
- if (existing.version_id, existing.task_key, existing.token) != wanted or auth not in (None, existing.auth):
208
- fail("host", f"session {existing.session_id} is already open as another version, task, token or auth")
214
+ identity = (existing.version_id, existing.snapshot_sha256, existing.parameters, existing.task_key, existing.token)
215
+ if identity != wanted or auth not in (None, existing.auth):
216
+ fail("host", f"session {existing.session_id} is already open as another version, data, task, token or auth")
209
217
  if restore and restore_sha256(restore) != existing.restore_sha256:
210
218
  fail("host", f"session {existing.session_id} is already open from another export")
211
219
  if not pending:
@@ -244,8 +252,10 @@ class WorldHost:
244
252
  deps: list[DependencyRef],
245
253
  pending: bool,
246
254
  auth: str | None = None,
255
+ knobs: dict[str, str] | None = None,
247
256
  ) -> Session:
248
257
  cached = self.cache.ensure(version_id, *self._trusted_version(bundle_url, snapshot))
258
+ data = DataKey.of(version_id, snapshot).sha256
249
259
  mode = session_mode(auth, token)
250
260
  dependencies = self._dependency_worlds(cached, deps)
251
261
  if spec is not None:
@@ -253,7 +263,7 @@ class WorldHost:
253
263
  relay = BrowserRelay.parse(browser)
254
264
  if cached.needs_worker and not self.run_handlers:
255
265
  return self._open_on_worker(
256
- cached, session_id, bundle_url, task, spec, token, relay, restore, deps, pending, mode
266
+ cached, session_id, bundle_url, task, spec, token, relay, restore, deps, pending, mode, snapshot, knobs
257
267
  )
258
268
  session_dir = self.sessions_root / session_id
259
269
  with self._opens.turn(version_id):
@@ -265,7 +275,9 @@ class WorldHost:
265
275
  token=token,
266
276
  dependencies=dependencies,
267
277
  restore=lambda load: self._restore_into(restore, session_dir, load, cached),
278
+ pages_vouched=restore_vouches_pages(restore),
268
279
  journaled=self.run_handlers,
280
+ parameters=knobs,
269
281
  )
270
282
  runtime.calls.outbox.on_pressure = lambda: self.ledger.wake(session_id)
271
283
  session = Session(
@@ -286,6 +298,8 @@ class WorldHost:
286
298
  task_spec=spec,
287
299
  settings=cached.settings,
288
300
  restore_sha256=restore_sha256(restore),
301
+ snapshot_sha256=data,
302
+ parameters=dict(knobs or {}),
289
303
  pending=pending,
290
304
  auth=mode,
291
305
  )
@@ -304,6 +318,8 @@ class WorldHost:
304
318
  deps: list[DependencyRef],
305
319
  pending: bool,
306
320
  mode: str = VENDOR_MODE,
321
+ snapshot: dict[str, str] | None = None,
322
+ knobs: dict[str, str] | None = None,
307
323
  ) -> Session:
308
324
  """Place the session on the version's worker (:class:`VersionWorkers`), which opens it from the bundle
309
325
  this process cached; the supervisor keeps the ui's files and the browser tunnel, relays the ui's api
@@ -322,7 +338,9 @@ class WorldHost:
322
338
  "task": task,
323
339
  "taskSpec": spec.raw if spec is not None else None,
324
340
  "token": token,
325
- "dependencies": [dep.raw for dep in deps],
341
+ "dependencies": [dep.for_worker for dep in deps],
342
+ "snapshot": worker_snapshot(snapshot),
343
+ "parameters": dict(knobs or {}),
326
344
  "auth": mode,
327
345
  }
328
346
  fetch = functools.partial(self._restore_source, restore)
@@ -346,6 +364,8 @@ class WorldHost:
346
364
  placement=body,
347
365
  settings=cached.settings,
348
366
  restore_sha256=restore_sha256(restore),
367
+ snapshot_sha256=DataKey.of(cached.version_id, snapshot).sha256,
368
+ parameters=dict(knobs or {}),
349
369
  pending=pending,
350
370
  auth=mode,
351
371
  )
@@ -389,7 +409,7 @@ class WorldHost:
389
409
  if not isinstance(url, str) or not isinstance(sha256, str) or len(sha256) != 64:
390
410
  fail("host", "restore must be {url: <presigned export url>, sha256: <hex digest>}")
391
411
  check_object_store_url(url, self.object_store, "restore.url")
392
- return ExportFile(download_verified(url, sha256, session_dir / "restore.db"), sha256)
412
+ return ExportFile(download_verified(url, sha256, session_dir / "restore.db"), sha256, restore.get("recorder"))
393
413
 
394
414
  def _recovered_source(self, directory: Path) -> RecoveredSession:
395
415
  root = self.sessions_root.parent / RECOVERED_DIR
@@ -409,7 +429,7 @@ class WorldHost:
409
429
 
410
430
  def _trusted_version(self, bundle_url: str, snapshot: dict[str, str] | None) -> tuple[str, dict[str, str] | None]:
411
431
  check_object_store_url(bundle_url, self.object_store, "bundleUrl")
412
- if snapshot:
432
+ if snapshot and snapshot.get("url") is not None:
413
433
  check_object_store_url(snapshot.get("url"), self.object_store, "snapshot.url")
414
434
  return bundle_url, snapshot
415
435
 
@@ -460,6 +480,15 @@ class WorldHost:
460
480
  return {"closed": True, "openedAt": None, "sessionSeconds": 0.0}
461
481
  return {"closed": True, "openedAt": session.opened_at, "sessionSeconds": session.seconds}
462
482
 
483
+ def browser_hosts(self, session_id: str, domain: str) -> list[str]:
484
+ with self._lock:
485
+ session = self._sessions.get(session_id)
486
+ if session is None:
487
+ fail(UNKNOWN_SESSION, f"no session {session_id} on this host")
488
+ if session.browser is None:
489
+ fail("host", f"session {session_id} was opened without a browser surface")
490
+ return session.browser_hosts(domain)
491
+
463
492
  def set_browser(self, session_id: str, browser: Any) -> dict:
464
493
  """Point the session's browser surface at another pool relay: the one
465
494
  it had died and the platform leased a replacement. Connections open
@@ -503,12 +532,12 @@ class WorldHost:
503
532
  with self._lock:
504
533
  session.export = None
505
534
  self._counters["exports_unchanged"] += 1
506
- return {"exportId": None, "sha256": sha256, "bytes": size, "unchanged": True}
535
+ return {"exportId": None, "sha256": sha256, "bytes": size, "unchanged": True, **RECORDER_ANSWER}
507
536
  export = Export(export_id=path.stem, path=path, sha256=sha256, bytes=size, content_type=engine.content_type)
508
537
  with self._lock:
509
538
  session.export = export
510
539
  self._counters["exports"] += 1
511
- described = export.describe()
540
+ described = {**export.describe(), **RECORDER_ANSWER}
512
541
  if self.run_handlers:
513
542
  described["path"] = str(path)
514
543
  return described
@@ -668,7 +697,7 @@ class WorldHost:
668
697
  """Cache a version before any session asks for it, so the first open
669
698
  pays nothing. Idempotent: a version already here is reported, not
670
699
  rebuilt."""
671
- already = self.cache.has(version_id)
700
+ already = self.cache.has(version_id, snapshot)
672
701
  if not already:
673
702
  self.cache.ensure(version_id, *self._trusted_version(bundle_url, snapshot))
674
703
  return {"versionId": version_id, "cached": True, "alreadyCached": already}
@@ -699,6 +728,7 @@ class WorldHost:
699
728
  "maxWorkers": self.workers.max_workers if self.workers is not None else 0,
700
729
  "versions": self.cache.version_ids(),
701
730
  "versionsInUse": versions_in_use,
731
+ "cloneMode": self.cache.clone_mode,
702
732
  "uptimeSeconds": time.time() - self.started_at,
703
733
  "startedAt": self.started_at,
704
734
  "build": self.build,
@@ -706,7 +736,7 @@ class WorldHost:
706
736
  "sessionSeconds": session_seconds,
707
737
  "pid": os.getpid(),
708
738
  "limits": self.limits,
709
- "features": [OPEN_DOOR_FEATURE],
739
+ "features": [OPEN_DOOR_FEATURE, WORLD_STATES_FEATURE],
710
740
  }
711
741
 
712
742
  def metrics_text(self) -> str:
@@ -848,12 +878,21 @@ class WorldHost:
848
878
  def _owner_now(self, session_id: str) -> str | None:
849
879
  return self.owners.current(session_id) if self.owners is not None else self.advertise_url
850
880
 
851
- def _verb(self, session_id: str, method: str, verb: str, body: dict | None, local: Callable[[Any], dict]) -> dict:
881
+ def _verb(
882
+ self,
883
+ session_id: str,
884
+ method: str,
885
+ verb: str,
886
+ body: dict | None,
887
+ local: Callable[[Any], dict],
888
+ *,
889
+ touch: bool = True,
890
+ ) -> dict:
852
891
  """One session verb, the platform's: never held while the session moves (:meth:`SessionMove.verb`),
853
892
  admitted on its version, forwarded to the session's worker when it has one, else answered by its
854
- in-process runtime through ``local``."""
893
+ in-process runtime through ``local``; ``touch`` off for a reader that must not keep it busy."""
855
894
  with (
856
- self.using(session_id, confirm=True) as session,
895
+ self.using(session_id, confirm=True, touch=touch) as session,
857
896
  session.move.verb(),
858
897
  self.admission.turn(session.version_id, session.session_id),
859
898
  ):
@@ -923,6 +962,12 @@ class WorldHost:
923
962
  session_id, "POST", "grade", body, lambda runtime: runtime.grade(report, context, parsed, grader)
924
963
  )
925
964
 
965
+ def webhooks(self, session_id: str, poll: WebhookPoll = WebhookPoll()) -> dict:
966
+ """The world's subscriptions and a page of the deliveries it sent, a forwarder's answers kept
967
+ first; a poll that does not count as the session being used."""
968
+ body = poll.as_json()
969
+ return self._verb(session_id, "POST", "webhooks", body, lambda runtime: runtime.webhooks(poll), touch=False)
970
+
926
971
  def flush(self, session_id: str) -> dict:
927
972
  with self.using(session_id, touch=False, ledger=True) as session:
928
973
  return self.ledger.barrier(session)
@@ -941,6 +986,7 @@ HOSTED_OPERATIONS: dict[str, Callable[..., dict]] = {
941
986
  "GET evidence": WorldHost.evidence,
942
987
  "POST requests": WorldHost.requests,
943
988
  "POST flush": WorldHost.flush,
989
+ "POST webhooks": WorldHost.webhooks,
944
990
  "POST grade": WorldHost.grade,
945
991
  "POST reset": WorldHost.reset,
946
992
  "POST seed": WorldHost.seed,
@@ -108,6 +108,20 @@ class CaseResult:
108
108
  problems: list[str] = field(default_factory=list)
109
109
 
110
110
 
111
+ @dataclass
112
+ class PythonCase:
113
+ name: str
114
+ file: str
115
+ group: str
116
+ status: str
117
+ problems: list[str] = field(default_factory=list)
118
+
119
+ @classmethod
120
+ def of(cls, case, root: Path) -> "PythonCase":
121
+ file = _case_file(case, root)
122
+ return cls(name=_readable(case.get("name") or ""), file=file, group=file, status=_case_status(case), problems=_case_problems(case))
123
+
124
+
111
125
  @dataclass
112
126
  class PythonResult:
113
127
  status: str
@@ -119,6 +133,8 @@ class PythonResult:
119
133
  reason: str | None = None
120
134
  output: str = ""
121
135
  interpreter: str | None = None
136
+ cases: list[PythonCase] = field(default_factory=list)
137
+ cases_omitted: int = 0
122
138
 
123
139
  @property
124
140
  def ran_nothing(self) -> bool:
@@ -138,6 +154,7 @@ class Report:
138
154
  failed = sum(1 for c in self.cases if c.status != "passed")
139
155
  if self.python.status == "failed":
140
156
  failed += max(1, self.python.failures + self.python.errors)
157
+ passed += max(0, self.python.tests - self.python.failures - self.python.errors - self.python.skipped)
141
158
  if self.python.status == "passed":
142
159
  passed += self.python.tests - self.python.skipped
143
160
  return {
@@ -514,6 +531,7 @@ def _run_python(root: Path, files: list[Path], session: LocalSession) -> PythonR
514
531
  reason = "pytest wrote no junit report"
515
532
  return PythonResult(status="failed", files=names, reason=reason, output=output, interpreter=interpreter)
516
533
  tests, failures, errors, skipped = counts
534
+ cases, omitted = _bounded(_junit_cases(junit, root))
517
535
  if proc.returncode == PYTEST_NO_TESTS_COLLECTED:
518
536
  reason = "no tests collected"
519
537
  return PythonResult(status="none", files=names, reason=reason, output=output, interpreter=interpreter)
@@ -527,6 +545,8 @@ def _run_python(root: Path, files: list[Path], session: LocalSession) -> PythonR
527
545
  reason=reason,
528
546
  output=output,
529
547
  interpreter=interpreter,
548
+ cases=cases,
549
+ cases_omitted=omitted,
530
550
  )
531
551
  status = "passed" if proc.returncode == 0 else "failed"
532
552
  return PythonResult(
@@ -538,9 +558,63 @@ def _run_python(root: Path, files: list[Path], session: LocalSession) -> PythonR
538
558
  skipped=skipped,
539
559
  output=output,
540
560
  interpreter=interpreter,
561
+ cases=cases,
562
+ cases_omitted=omitted,
541
563
  )
542
564
 
543
565
 
566
+ PROBLEM_LIMIT = 1000
567
+ MAX_PYTHON_CASES = 500
568
+
569
+
570
+ def _junit_cases(path: Path, root: Path) -> list[PythonCase]:
571
+ import xml.etree.ElementTree as ET
572
+
573
+ return [PythonCase.of(case, root) for case in ET.parse(path).iter("testcase") if case.get("name")]
574
+
575
+
576
+ def _bounded(cases: list[PythonCase]) -> tuple[list[PythonCase], int]:
577
+ ordered = sorted(cases, key=lambda case: case.status == "passed")
578
+ return ordered[:MAX_PYTHON_CASES], max(0, len(ordered) - MAX_PYTHON_CASES)
579
+
580
+
581
+ def _readable(name: str) -> str:
582
+ base, bracket, params = name.partition("[")
583
+ words = base.removeprefix("test_").replace("_", " ").strip()
584
+ return f"{words} [{params}" if bracket else words
585
+
586
+
587
+ def _case_file(case, root: Path) -> str:
588
+ declared = case.get("file")
589
+ if declared:
590
+ return declared
591
+ module = (case.get("classname") or "").split(".")
592
+ index = next((at for at in range(len(module) - 1, -1, -1) if module[at].startswith("test_") or module[at].endswith("_test")), len(module) - 1)
593
+ dotted = "/".join(module[: index + 1]) + ".py"
594
+ if (root / dotted).is_file():
595
+ return dotted
596
+ found = sorted((root / TESTS_DIR).rglob(f"{module[index]}.py"))
597
+ return str(found[0].relative_to(root)) if found else f"{TESTS_DIR}/{module[index]}.py"
598
+
599
+
600
+ def _case_status(case) -> str:
601
+ outcomes = {child.tag: child for child in case}
602
+ skipped = outcomes.get("skipped")
603
+ if "failure" in outcomes or "error" in outcomes:
604
+ return "failed"
605
+ if skipped is not None and skipped.get("type") == "pytest.xfail":
606
+ return "passed"
607
+ return "skipped" if skipped is not None else "passed"
608
+
609
+
610
+ def _case_problems(case) -> list[str]:
611
+ return [
612
+ (child.get("message") or child.text or child.tag).strip()[:PROBLEM_LIMIT]
613
+ for child in case
614
+ if child.tag in ("failure", "error")
615
+ ]
616
+
617
+
544
618
  def _junit_counts(path: Path) -> tuple[int, int, int, int] | None:
545
619
  if not path.is_file():
546
620
  return None
@@ -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
  ]