@withgateway/sdk 0.6.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 (119) 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 +5019 -1599
  10. package/dist/cli.js.map +1 -1
  11. package/dist/cli.mjs +5003 -1584
  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 +2689 -401
  28. package/dist/index.js.map +1 -1
  29. package/dist/index.mjs +2650 -394
  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 +1983 -1745
  48. package/dist/worlds/index.d.ts +1983 -1745
  49. package/dist/worlds/index.js +1295 -226
  50. package/dist/worlds/index.js.map +1 -1
  51. package/dist/worlds/index.mjs +1290 -222
  52. package/dist/worlds/index.mjs.map +1 -1
  53. package/package.json +6 -1
  54. package/runtime/gatewaysdk/environment/bundle_manifest.py +243 -0
  55. package/runtime/gatewaysdk/environment/schema/__main__.py +2 -2
  56. package/runtime/gatewaysdk/environment/schema/_slack_fidelity.py +8 -23
  57. package/runtime/gatewaysdk/environment/schema/api.py +3 -4
  58. package/runtime/gatewaysdk/environment/schema/assertions.py +7 -1
  59. package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +1 -0
  60. package/runtime/gatewaysdk/environment/schema/call_log.py +20 -0
  61. package/runtime/gatewaysdk/environment/schema/database/base.py +2 -2
  62. package/runtime/gatewaysdk/environment/schema/host.py +74 -11
  63. package/runtime/gatewaysdk/environment/schema/host_browser.py +48 -0
  64. package/runtime/gatewaysdk/environment/schema/host_control.py +33 -2
  65. package/runtime/gatewaysdk/environment/schema/host_handoff.py +4 -1
  66. package/runtime/gatewaysdk/environment/schema/host_requests.py +14 -0
  67. package/runtime/gatewaysdk/environment/schema/host_session.py +13 -2
  68. package/runtime/gatewaysdk/environment/schema/host_surfaces.py +6 -0
  69. package/runtime/gatewaysdk/environment/schema/host_versions.py +96 -19
  70. package/runtime/gatewaysdk/environment/schema/journal.py +7 -2
  71. package/runtime/gatewaysdk/environment/schema/local.py +32 -7
  72. package/runtime/gatewaysdk/environment/schema/page_checks.py +123 -0
  73. package/runtime/gatewaysdk/environment/schema/platform.py +23 -267
  74. package/runtime/gatewaysdk/environment/schema/platform_templates.py +332 -0
  75. package/runtime/gatewaysdk/environment/schema/request_ledger.py +4 -1
  76. package/runtime/gatewaysdk/environment/schema/run_parameters.py +25 -0
  77. package/runtime/gatewaysdk/environment/schema/runtime.py +43 -5
  78. package/runtime/gatewaysdk/environment/schema/scaffold.py +367 -217
  79. package/runtime/gatewaysdk/environment/schema/session_files.py +13 -2
  80. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +1 -1
  81. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +1 -2
  82. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +4 -2
  83. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +7 -7
  84. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +32 -2
  85. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +6 -6
  86. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +17 -2
  87. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/new-world-sandbox.md +1 -1
  88. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/ui-map.md +3 -2
  89. package/runtime/gatewaysdk/environment/schema/slack.py +55 -10
  90. package/runtime/gatewaysdk/environment/schema/snapshot.py +28 -2
  91. package/runtime/gatewaysdk/environment/schema/tasks.py +25 -2
  92. package/runtime/gatewaysdk/environment/schema/template_record.py +131 -0
  93. package/runtime/gatewaysdk/environment/schema/tools_world.py +7 -5
  94. package/runtime/gatewaysdk/environment/schema/ui.py +54 -33
  95. package/runtime/gatewaysdk/environment/schema/ui_interactions.py +419 -0
  96. package/runtime/gatewaysdk/environment/schema/ui_recorder.js +895 -0
  97. package/runtime/gatewaysdk/environment/schema/ui_replay.py +366 -0
  98. package/runtime/gatewaysdk/environment/schema/ui_replay_record.LICENSE +25 -0
  99. package/runtime/gatewaysdk/environment/schema/ui_replay_record.js +109 -0
  100. package/runtime/gatewaysdk/environment/schema/validation.py +10 -1
  101. package/runtime/gatewaysdk/environment/schema/worker.py +5 -1
  102. package/runtime/gatewaysdk/environment/schema/workers.py +8 -1
  103. package/runtime/gatewaysdk/environment/schema/world_host.py +44 -15
  104. package/runtime/gatewaysdk/environment/secret_values.py +1 -1
  105. package/runtime/gatewaysdk/environment/world.py +34 -43
  106. package/runtime/gatewaysdk/environment/world_session_contract.py +7 -34
  107. package/skills/benchmarks-getting-started/SKILL.md +1 -1
  108. package/skills/connector-schema-authoring/SKILL.md +1 -2
  109. package/skills/connector-schema-authoring/connector-worlds.md +2 -2
  110. package/skills/connector-schema-authoring/world-schema.md +29 -23
  111. package/skills/world-data-ingestion/SKILL.md +4 -2
  112. package/skills/worlds-getting-started/SKILL.md +7 -7
  113. package/skills/worlds-getting-started/references/cli-mcp-map.md +32 -2
  114. package/skills/worlds-getting-started/references/gotchas.md +6 -6
  115. package/skills/worlds-getting-started/references/journal-checks.md +17 -2
  116. package/skills/worlds-getting-started/references/new-world-sandbox.md +1 -1
  117. package/skills/worlds-getting-started/references/ui-map.md +3 -2
  118. package/dist/media-BIApiPzS.d.mts +0 -102
  119. package/dist/media-BIApiPzS.d.ts +0 -102
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@withgateway/sdk",
3
- "version": "0.6.0",
3
+ "version": "0.9.1",
4
4
  "description": "Gateway SDK for TypeScript - A/B experiments, tracing, and observability",
5
5
  "main": "./dist/index.js",
6
6
  "module": "./dist/index.mjs",
@@ -81,6 +81,11 @@
81
81
  "import": "./dist/hooks/index.mjs",
82
82
  "require": "./dist/hooks/index.js"
83
83
  },
84
+ "./agents": {
85
+ "types": "./dist/agents/index.d.ts",
86
+ "import": "./dist/agents/index.mjs",
87
+ "require": "./dist/agents/index.js"
88
+ },
84
89
  "./cli": {
85
90
  "types": "./dist/cli.d.ts",
86
91
  "import": "./dist/cli.mjs",
@@ -0,0 +1,243 @@
1
+ """Stdlib only: the runner vendors this package."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import re
7
+ from dataclasses import dataclass, field
8
+ from typing import Any
9
+
10
+ from ._toml import tomllib
11
+
12
+ BUNDLE_MANIFEST = "gateway-bundle.toml"
13
+ MIN_BUNDLE_MEMBERS = 2
14
+ MAX_BUNDLE_MEMBERS = 48
15
+ BUNDLE_NOT_A_WORLD = (
16
+ "A world bundle is not itself a world, its members are: drop gateway-env.toml from the bundle, or push it "
17
+ "as its own world."
18
+ )
19
+ BUNDLE_PUSH_ACTIONS = ("tests",)
20
+ BUNDLE_RESERVED_TABLES = ("identities", "references", "integrations")
21
+
22
+ _TABLES = ("bundle", "members", "actions", *BUNDLE_RESERVED_TABLES)
23
+ _BUNDLE_KEYS = ("name", "test_state")
24
+ _MEMBER_ALIAS = re.compile(r"^[a-z][a-z0-9_]{0,31}$")
25
+ _RESERVED_ALIASES = ("constructor", "prototype")
26
+ _MEMBER_PIN = re.compile(r"^(?:([^/@]+)/)?([^/@]+)@([^/@]+)$")
27
+ _MEMBER_REF = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$")
28
+ _WORLD_SLUG = re.compile(r"^(?!(?:migrate|runtime|templates)$)[a-z0-9][a-z0-9\-_]*$")
29
+ _MAX_SLUG_LENGTH = 128
30
+ _MAX_TEST_STATE_LENGTH = 120
31
+
32
+
33
+ def _utf16_length(value: str) -> int:
34
+ return len(value.encode("utf-16-le")) // 2
35
+
36
+
37
+ def _world_slug(value: str) -> bool:
38
+ return len(value) <= _MAX_SLUG_LENGTH and _WORLD_SLUG.fullmatch(value) is not None
39
+
40
+
41
+ @dataclass(frozen=True)
42
+ class BundleMember:
43
+ alias: str
44
+ slug: str
45
+ ref: str
46
+
47
+ def to_json(self) -> dict[str, str]:
48
+ return {"alias": self.alias, "slug": self.slug, "ref": self.ref}
49
+
50
+
51
+ @dataclass(frozen=True)
52
+ class BundleManifest:
53
+ name: str
54
+ test_state: str | None
55
+ members: tuple[BundleMember, ...]
56
+ on_push: tuple[str, ...] = ()
57
+ reserved: tuple[str, ...] = field(default_factory=tuple)
58
+
59
+ @classmethod
60
+ def read(cls, text: str) -> BundleManifest | list[str]:
61
+ """The manifest, or the list of issues that refuse it."""
62
+ try:
63
+ root = tomllib.loads(text.replace("\r\n", "\n"))
64
+ except tomllib.TOMLDecodeError as error:
65
+ return [f"gateway-bundle.toml is not valid TOML: {error}"]
66
+ return _Reader(root).read()
67
+
68
+ @staticmethod
69
+ def compose(
70
+ name: str,
71
+ members: list[BundleMember],
72
+ test_state: str | None = None,
73
+ on_push: tuple[str, ...] = (),
74
+ ) -> str:
75
+ def quoted(value: object) -> str:
76
+ return json.dumps(value, ensure_ascii=False, separators=(",", ":"))
77
+
78
+ lines = ["[bundle]", f"name = {quoted(name)}"]
79
+ if test_state:
80
+ lines.append(f"test_state = {quoted(test_state)}")
81
+ if on_push:
82
+ lines += ["", "[actions]", f"on_push = {quoted(list(on_push))}"]
83
+ for member in sorted(members, key=lambda m: m.alias):
84
+ lines += ["", f"[members.{member.alias}]", f"pin = {quoted(f'{member.slug}@{member.ref}')}"]
85
+ return "\n".join(lines) + "\n"
86
+
87
+ def to_json(self) -> dict[str, Any]:
88
+ return {
89
+ "name": self.name,
90
+ "testState": self.test_state,
91
+ "members": [member.to_json() for member in sorted(self.members, key=lambda m: m.alias)],
92
+ "onPush": list(self.on_push),
93
+ "reserved": list(self.reserved),
94
+ }
95
+
96
+
97
+ class _Reader:
98
+ def __init__(self, root: dict[str, Any]) -> None:
99
+ self.root = root
100
+ self.issues: list[str] = []
101
+ self.members: list[BundleMember] = []
102
+
103
+ def read(self) -> BundleManifest | list[str]:
104
+ self._unknown_tables()
105
+ bundle = self._bundle()
106
+ self._member_tables()
107
+ on_push = self._actions()
108
+ if self.issues or bundle is None:
109
+ return self.issues
110
+ return BundleManifest(
111
+ name=bundle[0],
112
+ test_state=bundle[1],
113
+ members=tuple(self.members),
114
+ on_push=tuple(on_push),
115
+ reserved=tuple(sorted(t for t in BUNDLE_RESERVED_TABLES if t in self.root)),
116
+ )
117
+
118
+ def _unknown_tables(self) -> None:
119
+ for key in sorted(self.root):
120
+ if key not in _TABLES:
121
+ self.issues.append(
122
+ f"gateway-bundle.toml has no table `{key}`; it takes bundle, members, actions, identities, "
123
+ "references and integrations."
124
+ )
125
+
126
+ def _bundle(self) -> tuple[str, str | None] | None:
127
+ bundle = self.root.get("bundle")
128
+ if not isinstance(bundle, dict):
129
+ self.issues.append("gateway-bundle.toml needs a [bundle] table with the bundle's name.")
130
+ return None
131
+ for key in sorted(bundle):
132
+ if key not in _BUNDLE_KEYS:
133
+ self.issues.append(f"[bundle] has no key `{key}`; it takes name and test_state.")
134
+ name = bundle.get("name")
135
+ named = isinstance(name, str) and _world_slug(name)
136
+ if not named:
137
+ self.issues.append("[bundle] name must be a world slug: lowercase letters, digits, '-' or '_'.")
138
+ test_state = bundle.get("test_state")
139
+ stated = test_state is None or (
140
+ isinstance(test_state, str) and 1 <= _utf16_length(test_state) <= _MAX_TEST_STATE_LENGTH
141
+ )
142
+ if not stated:
143
+ self.issues.append(
144
+ "[bundle] test_state names a world state of every member: a name of 1 to "
145
+ f"{_MAX_TEST_STATE_LENGTH} characters."
146
+ )
147
+ if not named or not stated:
148
+ return None
149
+ return str(name), test_state
150
+
151
+ def _member_tables(self) -> None:
152
+ members = self.root.get("members")
153
+ if not isinstance(members, dict):
154
+ self.issues.append("gateway-bundle.toml needs [members.<alias>] tables, one per member world.")
155
+ return
156
+ count = len(members)
157
+ if count < MIN_BUNDLE_MEMBERS:
158
+ plural = "" if count == 1 else "s"
159
+ self.issues.append(
160
+ f"gateway-bundle.toml names {count} member{plural}; a bundle needs at least {MIN_BUNDLE_MEMBERS} "
161
+ "(one world is a world, not a bundle)."
162
+ )
163
+ if count > MAX_BUNDLE_MEMBERS:
164
+ self.issues.append(f"gateway-bundle.toml names {count} members; a bundle holds at most {MAX_BUNDLE_MEMBERS}.")
165
+ pinned_by: dict[str, str] = {}
166
+ for alias in sorted(members):
167
+ self._member(alias, members[alias], pinned_by)
168
+
169
+ def _member(self, alias: str, table: Any, pinned_by: dict[str, str]) -> None:
170
+ if alias in _RESERVED_ALIASES:
171
+ self.issues.append(f"member alias `{alias}` is reserved; name the member another way.")
172
+ return
173
+ if not _MEMBER_ALIAS.fullmatch(alias):
174
+ self.issues.append(
175
+ f"member alias `{alias}` must be lowercase letters, digits or '_', start with a letter and be at "
176
+ "most 32 characters."
177
+ )
178
+ if not isinstance(table, dict):
179
+ self.issues.append(f"[members.{alias}] must be a table with a pin.")
180
+ return
181
+ for key in sorted(table):
182
+ if key != "pin":
183
+ self.issues.append(f"[members.{alias}] has no key `{key}`; it takes pin.")
184
+ member = self._pin(alias, table.get("pin"))
185
+ if member is None:
186
+ return
187
+ first = pinned_by.get(member.slug)
188
+ if first is not None:
189
+ self.issues.append(
190
+ f"[members.{alias}] pins {member.slug}, which [members.{first}] already pins; a world is a member once."
191
+ )
192
+ return
193
+ pinned_by[member.slug] = alias
194
+ self.members.append(member)
195
+
196
+ def _pin(self, alias: str, pin: Any) -> BundleMember | None:
197
+ parsed = _MEMBER_PIN.fullmatch(pin.strip(" \t")) if isinstance(pin, str) else None
198
+ if parsed is None or not _MEMBER_REF.fullmatch(parsed.group(3)):
199
+ self.issues.append(f"[members.{alias}] pin must be `<slug>@<ref>`.")
200
+ return None
201
+ project, slug, ref = parsed.groups()
202
+ if project is not None:
203
+ self.issues.append(
204
+ f"[members.{alias}] pin names a project; a member is a world of the bundle's own project, so drop "
205
+ f"the `{project}/` prefix."
206
+ )
207
+ return None
208
+ if not _world_slug(slug):
209
+ self.issues.append(
210
+ f"[members.{alias}] pin's slug `{slug}` must be a world slug: lowercase letters, digits, '-' or '_'."
211
+ )
212
+ return None
213
+ return BundleMember(alias, slug, ref)
214
+
215
+ def _actions(self) -> list[str]:
216
+ actions = self.root.get("actions")
217
+ if actions is None:
218
+ return []
219
+ if not isinstance(actions, dict):
220
+ self.issues.append("[actions] must be a table.")
221
+ return []
222
+ for key in sorted(actions):
223
+ if key != "on_push":
224
+ self.issues.append(f"[actions] has no key `{key}`; it takes on_push.")
225
+ on_push = actions.get("on_push", [])
226
+ known = isinstance(on_push, list) and all(
227
+ isinstance(action, str) and action in BUNDLE_PUSH_ACTIONS for action in on_push
228
+ )
229
+ if not known:
230
+ self.issues.append(f"[actions] on_push lists what runs on push: {', '.join(BUNDLE_PUSH_ACTIONS)}.")
231
+ return []
232
+ return list(on_push)
233
+
234
+
235
+ __all__ = [
236
+ "BUNDLE_MANIFEST",
237
+ "BUNDLE_PUSH_ACTIONS",
238
+ "BUNDLE_RESERVED_TABLES",
239
+ "MAX_BUNDLE_MEMBERS",
240
+ "MIN_BUNDLE_MEMBERS",
241
+ "BundleManifest",
242
+ "BundleMember",
243
+ ]
@@ -146,8 +146,8 @@ def main(argv=None):
146
146
  "--connector",
147
147
  default="custom",
148
148
  type=_installed_connector,
149
- choices=list_templates(),
150
- help="init only: connector template to start from (default: custom)",
149
+ help="init only: the blank custom scaffold (the default); a vendor template lives on the platform, "
150
+ "`gateway worlds schema init PATH --connector <slug>` fetches it",
151
151
  )
152
152
  parser.add_argument("--name", default=None, help="init only: environment name and package id")
153
153
  parser.add_argument(
@@ -6,11 +6,10 @@ so consumers never implement inheritance or infer collection from vendor URLs.
6
6
 
7
7
  from copy import deepcopy
8
8
  import hashlib
9
- from pathlib import Path
9
+ from typing import Mapping
10
10
 
11
- from .validation import encoded, fail, read_json
12
-
13
- TEMPLATE = Path(__file__).with_name("connectors") / "slack"
11
+ from .scaffold import template_json
12
+ from .validation import encoded, fail
14
13
 
15
14
 
16
15
  def expand_capabilities(document: dict) -> dict:
@@ -41,27 +40,13 @@ def expand_capabilities(document: dict) -> dict:
41
40
  return result
42
41
 
43
42
 
44
- def load_capabilities() -> dict:
45
- return expand_capabilities(read_json(TEMPLATE / "capabilities.json"))
46
-
47
-
48
- def slack_template_digest() -> str:
49
- """Match the platform's path-NUL-bytes-NUL hash over shipped Slack files."""
50
- root = TEMPLATE
51
- digest = hashlib.sha256()
52
- for path in sorted(root.rglob("*"), key=lambda p: p.relative_to(root).as_posix()):
53
- if not path.is_file() or path.is_symlink() or "__pycache__" in path.parts:
54
- continue
55
- digest.update(path.relative_to(root).as_posix().encode("utf-8"))
56
- digest.update(b"\0")
57
- digest.update(path.read_bytes())
58
- digest.update(b"\0")
59
- return digest.hexdigest()
43
+ def load_capabilities(files: Mapping[str, bytes], path: str) -> dict:
44
+ """The capabilities document at ``path`` (the template's authored one, or the world's published one), expanded."""
45
+ return expand_capabilities(template_json(files, path, "/template"))
60
46
 
61
47
 
62
- def fidelity_report(contract, evidence, batch, diagnostics=None, *, mapping):
48
+ def fidelity_report(contract, evidence, batch, diagnostics=None, *, mapping, capabilities: dict, template_digest: str):
63
49
  synthetic = evidence.get("synthetic") is True
64
- capabilities = load_capabilities()
65
50
  counts = {entity: 0 for entity in contract.entities}
66
51
  for mutation in batch["mutations"]:
67
52
  counts[mutation["entity"]] += 1
@@ -70,7 +55,7 @@ def fidelity_report(contract, evidence, batch, diagnostics=None, *, mapping):
70
55
  "shape": "base",
71
56
  "label": "synthetic" if synthetic else "subset",
72
57
  "source_hash": hashlib.sha256(encoded(evidence)).hexdigest(),
73
- "template_digest": slack_template_digest(),
58
+ "template_digest": template_digest,
74
59
  "contract_target": contract.target,
75
60
  "package": contract.lock["package"],
76
61
  "lock_digest": hashlib.sha256(encoded(contract.lock)).hexdigest(),
@@ -131,6 +131,7 @@ from .handler_errors import handled_answer, handler_bug_body, log_contract_refus
131
131
  from .primary_key import PrimaryKey
132
132
  from .request_body import RequestBody, Upload, json_value
133
133
  from .route_miss import RouteMiss, served_methods
134
+ from .ui import checked_api_path
134
135
  from .validation import ContractError, fail, read_json
135
136
 
136
137
  EVENT_LOG_SIZE = 500
@@ -435,10 +436,8 @@ def _ui_settings(raw: dict, world: Path) -> UiSettings | None:
435
436
  entry = ui.get("entry", "/")
436
437
  if not isinstance(entry, str) or not entry.startswith("/"):
437
438
  fail("spec", "ui.entry is the path the agent lands on, starting with /", "/ui/entry")
438
- api_path = ui.get("api_path", "/__world-api")
439
- if not isinstance(api_path, str) or not api_path.startswith("/") or api_path == "/":
440
- fail("spec", "ui.api_path is the same-origin prefix the ui calls the api at", "/ui/api_path")
441
- return UiSettings(static=static.rstrip("/"), entry=entry, api_path=api_path.rstrip("/"))
439
+ api_path = checked_api_path(ui.get("api_path", "/__world-api"))
440
+ return UiSettings(static=static.rstrip("/"), entry=entry, api_path=api_path)
442
441
 
443
442
 
444
443
  def load_api_settings(world: Path, spec: Spec) -> ApiSettings:
@@ -10,6 +10,7 @@ from dataclasses import dataclass
10
10
  from typing import Any, Mapping
11
11
 
12
12
  from .journal import NOT_RECORDED
13
+ from .page_checks import PageCheck, PageReport, page_rows
13
14
  from .tasks import (
14
15
  CALL_LOG,
15
16
  DOOR_FIELD,
@@ -302,7 +303,12 @@ class Selection(ABC):
302
303
  entity = check["entity"]
303
304
  meta = _journal_meta(state, entity)
304
305
  kind = KINDS[(_log_of(entity), meta is not None)]
305
- return kind.read(check, state, meta)
306
+ selection = kind.read(check, state, meta)
307
+ refusal = PageReport.of(state, entity).refusal() if PageCheck(check).names_the_page else None
308
+ if refusal is not None:
309
+ raise GraderError(refusal)
310
+ selection.rows = page_rows(check, selection.rows)
311
+ return selection
306
312
 
307
313
  @classmethod
308
314
  @abstractmethod
@@ -10,6 +10,7 @@ ENVIRONMENT_PACKAGE = SCHEMA_PACKAGE.parent
10
10
  SIBLING_MODULES = (
11
11
  "_toml.py",
12
12
  "backing.py",
13
+ "bundle_manifest.py",
13
14
  "errors.py",
14
15
  "legacy_sqlite.py",
15
16
  "reward_keys.py",
@@ -34,6 +34,7 @@ LINE_BOUNDS = {"method": METHOD_CHARS, "operation": OPERATION_CHARS, "path": PAT
34
34
  DEFAULT_CALL_LOG_MAX = 5000
35
35
  DEFAULT_CALL_LOG_VALUES = 200_000
36
36
  DEFAULT_CALL_LOG_CHARS = 8 << 20
37
+ INTERACTION_STATUS = 204
37
38
  WITHHELD_ROUTE = {
38
39
  "args": REDACTED,
39
40
  "query": {},
@@ -133,6 +134,7 @@ class Via(StrEnum):
133
134
  UI = "ui"
134
135
  TOOL = "tool"
135
136
  WEBHOOK = "webhook"
137
+ PAGE = "page"
136
138
 
137
139
 
138
140
  @dataclass(frozen=True)
@@ -428,6 +430,24 @@ class CallLog:
428
430
  request, budget = dict(WITHHELD_TOOL), RequestBudget()
429
431
  self._append({**heading, **request, "via": str(Via.TOOL)}, answered, budget)
430
432
 
433
+ def record_interaction(self, operation: str, page: str, summary: dict, detail: dict, graded: bool = True) -> None:
434
+ """One interaction on a UI world's page (:mod:`.ui_interactions`): a ``via`` page call named
435
+ ``operation`` at ``page`` with no method, ``summary`` as its query and ``detail`` as what was
436
+ asked, kept by the request ledger and, ``graded``, by the grader's log."""
437
+ secret = self.redaction.secret
438
+ heading = {"operation": operation, "method": None, "path": self.redaction.raw_path(page, secret)}
439
+ query = self.redaction.value(summary)
440
+ answered = _answered(INTERACTION_STATUS, None, 0.0)
441
+ exchange = partial(Exchange.of_tool, detail, INTERACTION_STATUS, None, self.redaction)
442
+ self._send({**heading, "query": query, "via": str(Via.PAGE)}, answered, exchange)
443
+ if self.maximum == 0 or not graded:
444
+ return
445
+ try:
446
+ request, budget = self._tool_request(detail)
447
+ except (RecursionError, RequestTooLarge):
448
+ request, budget = dict(WITHHELD_TOOL), RequestBudget()
449
+ self._append({**heading, **request, "query": query, "via": str(Via.PAGE)}, answered, budget)
450
+
431
451
  def record_webhooks(self, deliveries: Iterable[Delivery]) -> None:
432
452
  """Each delivery the world sent, kept by the request ledger with ``via`` webhook and no
433
453
  answer yet (status 0); the grader's call log keeps only what the agent called."""
@@ -53,7 +53,7 @@ CREATE TABLE benchmark_conversation_events (scenario_id TEXT NOT NULL, user_turn
53
53
  _FICLONE = 0x40049409
54
54
 
55
55
 
56
- def _reflink(source: Path, destination: Path) -> bool:
56
+ def reflink(source: Path, destination: Path) -> bool:
57
57
  try:
58
58
  import fcntl
59
59
 
@@ -175,7 +175,7 @@ class WorldDatabase(ABC):
175
175
  destination.parent.mkdir(parents=True, exist_ok=True)
176
176
  if destination.exists() and destination.samefile(source):
177
177
  raise shutil.SameFileError(f"{source} and {destination} are the same file")
178
- if not _reflink(source, destination):
178
+ if not reflink(source, destination):
179
179
  shutil.copyfile(source, destination)
180
180
 
181
181
  @classmethod
@@ -50,15 +50,18 @@ import signal
50
50
  import sys
51
51
  import threading
52
52
  import urllib.parse
53
+ from functools import partial
53
54
  from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
54
55
  from pathlib import Path
55
56
  from typing import Any
56
57
 
57
58
  from .api import Via, with_query
58
59
  from .call_capture import JSON_TYPE, send_response
60
+ from .call_redaction import CallRedaction
59
61
  from .credentials import BearerAuth
60
62
  from .door import PLATFORM_HEADER, Entry
61
63
  from .handler_errors import log_request_failure, request_failure_body
64
+ from .host_browser import RelayNavigation, log_relay
62
65
  from .host_control import ControlPlane
63
66
  from .host_handoff import DrainHandoff, HandoffDoor, PlatformHandoff
64
67
  from .host_loops import HEARTBEAT_S, Heartbeat, start_lease_sweeper
@@ -90,9 +93,12 @@ from .host_versions import DEFAULT_MAX_BUNDLE_MB
90
93
  from .host_workers import UNKNOWN_SESSION, refusal
91
94
  from .request_ledger import LedgerFlusher, LedgerSpill, NoLedger, PlatformLedger
92
95
  from .session_move import SessionMoved
96
+ from .ui_interactions import RECORDER_PATH, UiRecorder
97
+ from .ui_replay import REPLAY_PATH, REPLAY_SCRIPT_PATH, REPLAY_STOP_S, ReplayShipper, UiReplay
93
98
  from .validation import ContractError
94
99
  from .workers import (
95
100
  DEFAULT_WORKER_BUDGET_MB,
101
+ DEFAULT_WORKER_FILE_MB,
96
102
  DEFAULT_WORKER_FOOTPRINT_MB,
97
103
  DEFAULT_WORKER_MEMORY_MB,
98
104
  WorkerPool,
@@ -127,13 +133,15 @@ def make_host_handler(
127
133
  *,
128
134
  max_body_mb: int = DEFAULT_MAX_BODY_MB,
129
135
  secure_cookies: bool = True,
136
+ navigation: RelayNavigation | None = None,
137
+ replays: ReplayShipper | None = None,
130
138
  ):
131
139
  """The request handler class for one host; its control plane is :class:`ControlPlane`, which
132
140
  refuses an empty ``secret`` or ``worlds_domain``. ``secure_cookies`` is off
133
141
  only for a host whose public surface is reached over plain http (a dev
134
142
  host); it is the deployment's word, not the request's, since a client
135
143
  writes the forwarding headers a request arrives with."""
136
- control = ControlPlane(host, secret, HOSTED_OPERATIONS, worlds_domain)
144
+ control = ControlPlane(host, secret, HOSTED_OPERATIONS, worlds_domain, navigation)
137
145
  if max_body_mb <= 0:
138
146
  raise ValueError(f"the request body cap must be positive (WORLDS_HOST_MAX_BODY_MB={max_body_mb})")
139
147
  max_body_bytes = max_body_mb * (1 << 20)
@@ -318,12 +326,23 @@ def make_host_handler(
318
326
  ):
319
327
  return self._reply(401, {"error": "invalid session token"})
320
328
  route = api_target(ui, url.path)
321
- if route is None:
322
- return self._serve_static(ui, method, url, opened)
329
+ if url.path == RECORDER_PATH:
330
+ return self._serve_file(method, opened, UiRecorder.script)
331
+ if url.path == REPLAY_SCRIPT_PATH:
332
+ return self._serve_file(method, opened, partial(UiReplay.script, replays))
333
+ static = route is None and not UiRecorder.serves(url.path)
334
+ if static and session.worker is not None and UiRecorder.is_page(url.path):
335
+ return self._on_worker(session, method, headers)
336
+ if static:
337
+ return self._serve_static(session, ui, method, url, opened)
323
338
  if cross_site(headers, lambda origin: urllib.parse.urlsplit(origin).netloc == headers.get("host")):
324
339
  return self._reply(403, {"error": "the ui's api prefix answers its own page, not another site"})
340
+ if url.path == REPLAY_PATH:
341
+ return self._record_replay(session, method)
325
342
  if session.worker is not None:
326
343
  return self._on_worker(session, method, headers)
344
+ if route is None:
345
+ return self._record_interactions(session, method, url, headers)
327
346
  target = urllib.parse.urlunsplit(("", "", route, url.query, ""))
328
347
  api_headers = {k: v for k, v in headers.items() if k not in ("cookie", "authorization")}
329
348
  api_headers["host"] = session.api_host(worlds_domain, opened)
@@ -334,20 +353,49 @@ def make_host_handler(
334
353
  cookie = session_cookie(token, secure=secure_cookies, max_age_s=host.lease_s)
335
354
  self._reply(303, {"location": landing}, {"Location": landing, "Set-Cookie": cookie})
336
355
 
337
- def _serve_static(self, ui: UiSurface, method: str, url, opened: bool) -> None:
338
- """A file of the ui; on a capability host with no ``Referer``, so a page that
339
- loads another site's resource never hands it the capability."""
356
+ def _serve_static(self, session: Session, ui: UiSurface, method: str, url, opened: bool) -> None:
357
+ """A file of the ui; a page carries the recorder and is noted as served, a note for the
358
+ ledger alone (no grader reads it), so a page is never held by the move fence."""
340
359
  if method != "GET":
341
360
  return self._reply(405, {"error": "the static ui answers GET only"})
342
- status, static_headers, payload = static_file(ui, url.path)
343
- sealed = {**static_headers, **(NO_REFERRER if opened else {})}
361
+ status, file_headers, payload = static_file(ui, url.path)
362
+ page = UiRecorder.page(status, file_headers, payload)
363
+ if page is not None and session.runtime is not None:
364
+ UiRecorder.served(url.path, session.runtime.calls)
365
+ self._send_file(opened, status, file_headers, payload if page is None else page)
366
+
367
+ def _serve_file(self, method: str, opened: bool, answer) -> None:
368
+ if method != "GET":
369
+ return self._reply(405, {"error": "the static ui answers GET only"})
370
+ self._send_file(opened, *answer())
371
+
372
+ def _send_file(self, opened: bool, status: int, headers: dict[str, str], payload: bytes) -> None:
373
+ """On a capability host with no ``Referer``, so a page that loads another site's
374
+ resource never hands it the capability."""
375
+ sealed = {**headers, **(NO_REFERRER if opened else {})}
344
376
  self._relay(status, sealed.items(), payload, drop=FRAMING_HEADERS)
345
377
 
378
+ def _record_interactions(self, session: Session, method: str, url, headers: dict[str, str]) -> None:
379
+ if session.runtime is None:
380
+ return self._reply(404, {"error": "this session's world is not served here"})
381
+ raw = self._read()
382
+ with host.admitted(session, HOP_HEADER in headers):
383
+ answer = UiRecorder.record(method, url.path, raw, session.runtime.calls)
384
+ self._reply(*answer)
385
+
386
+ def _record_replay(self, session: Session, method: str) -> None:
387
+ """The host that holds the session keeps its page's recording, a worker's session too, scrubbed
388
+ as the call log scrubs (:class:`CallRedaction`)."""
389
+ scrub = CallRedaction.of(session.spec, session.token).scrub
390
+ self._reply(*UiReplay.take(method, self._read(), session.session_id, scrub, replays))
391
+
346
392
  def _serve_browser(self, session: Session, url, headers: dict[str, str]) -> None:
347
393
  """``/cdp/<session token>`` and ``/live/<grant>`` on the session's
348
394
  cdp host: check the credential against the SESSION, then tunnel
349
395
  the websocket to the leased relay with the POOL credential the
350
- relay knows. The relay's token never leaves the host."""
396
+ relay knows. The relay's token never leaves the host. The relay is
397
+ bound to the session's hosts first, so one that restarted and lost
398
+ its binding is never reached unbound."""
351
399
  relay = session.browser
352
400
  if relay is None:
353
401
  return self._reply(404, {"error": "this session has no browser surface"})
@@ -368,11 +416,16 @@ def make_host_handler(
368
416
  upstream_path = f"/live/{mint_live_grant(relay.token, LIVE_RELAY_GRANT_MS, scope)}"
369
417
  if headers.get("upgrade", "").lower() != "websocket":
370
418
  return self._reply(400, {"error": "the browser surface is a websocket"})
419
+ try:
420
+ control.navigation.bind(relay, session.browser_hosts(control.domain))
421
+ except ContractError as error:
422
+ return self._reply(502, {"error": "browser unbound", "detail": str(error)})
371
423
  self.close_connection = True
372
424
  try:
373
425
  tunnel(self.connection, relay.url, upstream_path, headers)
374
426
  except OSError as error:
375
- self._reply(502, {"error": "browser unreachable", "detail": str(error)})
427
+ log_relay("browser relay unreachable", relay, error=str(error))
428
+ self._reply(502, {"error": "browser unreachable"})
376
429
 
377
430
  return Handler
378
431
 
@@ -397,12 +450,14 @@ class HostServer(ThreadingHTTPServer):
397
450
  drain_s: float = DEFAULT_DRAIN_S,
398
451
  ledger: LedgerFlusher | None = None,
399
452
  handoff: HandoffDoor | None = None,
453
+ replays: ReplayShipper | None = None,
400
454
  ):
401
455
  super().__init__(address, handler)
402
456
  self.world_host = world_host
403
457
  self.lease_sweeper = start_lease_sweeper(world_host)
404
458
  self.heartbeat = Heartbeat(world_host, *heartbeat, interval_s=heartbeat_s).start() if heartbeat else None
405
459
  world_host.ledger = ledger.start() if ledger else NoLedger()
460
+ self.replays = replays.start() if replays else None
406
461
  self.handoff = DrainHandoff(world_host, handoff, drain_s)
407
462
  self._answering = 0
408
463
  self._draining = False
@@ -457,6 +512,7 @@ def serve(cache_root: str | Path, *, port: int = 8080, host_addr: str = "0.0.0.0
457
512
  ``WORLDS_WORKER_MEMORY_MB`` caps each version worker's address space, ``WORLDS_WORKER_BUDGET_MB`` is the memory
458
513
  all of them together are held to and ``WORLDS_WORKER_FOOTPRINT_MB`` what each is counted at against it (unset,
459
514
  its whole address-space cap; their count is the quotient, and one more version answers 503 ``at_capacity``),
515
+ ``WORLDS_WORKER_FILE_MB`` is the largest file a worker may write (a session's database, so a world state's data),
460
516
  ``WORLDS_HOST_OBJECT_STORE`` is where every presigned URL it is handed may point (required; ``any`` for a dev
461
517
  host), ``WORLDS_HOST_MAX_BUNDLE_MB`` is the largest version bundle the cache accepts,
462
518
  ``WORLDS_HOST_MAX_BODY_MB`` the largest request body it reads, ``WORLDS_HOST_LEDGER_SPILL_DIR`` (under the cache
@@ -491,6 +547,7 @@ def serve(cache_root: str | Path, *, port: int = 8080, host_addr: str = "0.0.0.0
491
547
  memory_mb=int(os.environ.get("WORLDS_WORKER_MEMORY_MB") or DEFAULT_WORKER_MEMORY_MB),
492
548
  budget_mb=int(os.environ.get("WORLDS_WORKER_BUDGET_MB") or DEFAULT_WORKER_BUDGET_MB),
493
549
  footprint_mb=int(footprint) if footprint else DEFAULT_WORKER_FOOTPRINT_MB,
550
+ file_mb=int(os.environ.get("WORLDS_WORKER_FILE_MB") or DEFAULT_WORKER_FILE_MB),
494
551
  )
495
552
  owners = PlatformOwners(platform_url, secret, advertise) if platform_url else None
496
553
  world_host = WorldHost(
@@ -504,6 +561,7 @@ def serve(cache_root: str | Path, *, port: int = 8080, host_addr: str = "0.0.0.0
504
561
  build=os.environ.get("WORLDS_HOST_BUILD") or None,
505
562
  owners=owners,
506
563
  )
564
+ replays = ReplayShipper(platform_url, secret) if platform_url else None
507
565
  handler = make_host_handler(
508
566
  world_host,
509
567
  secret=secret,
@@ -511,6 +569,7 @@ def serve(cache_root: str | Path, *, port: int = 8080, host_addr: str = "0.0.0.0
511
569
  owner_lookup=owners,
512
570
  max_body_mb=int(os.environ.get("WORLDS_HOST_MAX_BODY_MB") or DEFAULT_MAX_BODY_MB),
513
571
  secure_cookies=os.environ.get("WORLDS_HOST_PLAIN_HTTP", "0") != "1",
572
+ replays=replays,
514
573
  )
515
574
  sink = PlatformLedger(platform_url, secret, host_url=advertise) if platform_url else None
516
575
  return HostServer(
@@ -522,6 +581,7 @@ def serve(cache_root: str | Path, *, port: int = 8080, host_addr: str = "0.0.0.0
522
581
  heartbeat_s=float(os.environ.get("WORLDS_HOST_HEARTBEAT_S") or HEARTBEAT_S),
523
582
  drain_s=float(os.environ.get("WORLDS_HOST_DRAIN_S") or DEFAULT_DRAIN_S),
524
583
  handoff=PlatformHandoff(platform_url, secret) if platform_url and advertise else None,
584
+ replays=replays,
525
585
  )
526
586
 
527
587
 
@@ -534,7 +594,8 @@ def main(argv: list[str] | None = None) -> int:
534
594
  args = parser.parse_args(argv)
535
595
  server = serve(args.cache_root, port=args.port)
536
596
  print(
537
- f"world host listening on :{server.server_address[1]}, cache {args.cache_root}",
597
+ f"world host listening on :{server.server_address[1]}, cache {args.cache_root} "
598
+ f"(session copies: {server.world_host.cache.clone_mode})",
538
599
  file=sys.stderr,
539
600
  flush=True,
540
601
  )
@@ -543,6 +604,8 @@ def main(argv: list[str] | None = None) -> int:
543
604
  server.serve_forever()
544
605
  finally:
545
606
  server.world_host.ledger.stop(settle=server.world_host.finishing.settle)
607
+ if server.replays is not None:
608
+ server.replays.stop(REPLAY_STOP_S)
546
609
  server.lease_sweeper.set()
547
610
  if server.heartbeat is not None:
548
611
  server.heartbeat.stop()