@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
@@ -0,0 +1,332 @@
1
+ """The bridge's template commands: ``templates``, ``template-summary``, ``describe``,
2
+ ``init-template``, ``init-template-files``, ``init-world-files``, ``build-slack`` and ``refresh-slack``.
3
+
4
+ A vendor template is an official world on the platform, a schema world built from it, and
5
+ arrives as that world's files (``[{path, content}]``, base64); only the blank ``custom``
6
+ scaffold is read from code. None of these runs a template's Python.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import json
12
+ import tempfile
13
+ from pathlib import Path
14
+ from typing import TYPE_CHECKING, Any, Callable
15
+
16
+ from .cast import world_fields
17
+ from .scaffold import (
18
+ CUSTOM,
19
+ TEMPLATE_SLUG,
20
+ CustomScaffold,
21
+ TemplateWorld,
22
+ init_bundle,
23
+ init_bundle_from_files,
24
+ init_bundle_from_world,
25
+ refuse_official,
26
+ request_files,
27
+ template_digest,
28
+ )
29
+ from .validation import ContractError, fail
30
+
31
+ if TYPE_CHECKING:
32
+ from .connector import Spec
33
+ from .redaction import RedactPolicy
34
+
35
+ COMPILED_MARKERS = ("schema/world.json", "tool-schemas.json")
36
+ DESCRIBE_PATHS = (
37
+ "schema/world.json",
38
+ "tool-schemas.json",
39
+ "connector.toml",
40
+ "gateway-env.toml",
41
+ "api/handlers.py",
42
+ )
43
+
44
+
45
+ def templates(request: dict) -> dict:
46
+ """A summary of each official world the caller sends, in its order, then ``custom``. A world whose
47
+ own files cannot be summarized is answered under ``refused`` and the others still list; a
48
+ request of the wrong shape is refused whole."""
49
+ listed = request.get("templates")
50
+ listed = [] if listed is None else listed
51
+ if not isinstance(listed, list):
52
+ fail("input", "Expected templates as [{slug, files: [{path, content}]}]", "/templates")
53
+ summaries: list[dict] = []
54
+ refused: list[dict] = []
55
+ seen: set[str] = set()
56
+ for index, entry in enumerate(listed):
57
+ location = f"/templates/{index}"
58
+ slug = _official_slug(entry, location)
59
+ if slug in seen:
60
+ fail("input", f"{slug} is sent twice", f"{location}/slug")
61
+ seen.add(slug)
62
+ template = TemplateWorld(request_files(entry, location=f"{location}/files"), location=f"{location}/files")
63
+ try:
64
+ summaries.append(template.summary(slug))
65
+ except ContractError as error:
66
+ refused.append({"slug": slug, "error": error.detail})
67
+ return {"status": "ok", "templates": [*summaries, CustomScaffold().summary(CUSTOM)], "refused": refused}
68
+
69
+
70
+ def _official_slug(entry: Any, location: str) -> str:
71
+ slug = entry.get("slug") if isinstance(entry, dict) else None
72
+ if not isinstance(slug, str) or not TEMPLATE_SLUG.fullmatch(slug):
73
+ fail(
74
+ "input", "Each template is {slug, files} with a slug of lowercase letters, digits and -", f"{location}/slug"
75
+ )
76
+ if slug == CUSTOM:
77
+ fail(
78
+ "input",
79
+ "custom is the runtime's own scaffold and is always listed last; send official templates only",
80
+ f"{location}/slug",
81
+ )
82
+ return slug
83
+
84
+
85
+ def init_template(request: dict, root: Path) -> None:
86
+ connector = request.get("connector", CUSTOM)
87
+ name = request.get("name")
88
+ if not isinstance(connector, str) or (name is not None and not isinstance(name, str)):
89
+ fail("input", "Expected a connector template slug and an optional name")
90
+ refuse_official(connector, "init-template-files")
91
+ init_bundle(root, connector=CUSTOM, name=name, with_example_tool=request.get("with_example_tool") is True)
92
+
93
+
94
+ def init_template_files(request: dict, root: Path) -> None:
95
+ """The template arrives as files, never as a path the request chose."""
96
+ connector = request.get("connector")
97
+ name = request.get("name")
98
+ if not isinstance(connector, str) or (name is not None and not isinstance(name, str)):
99
+ fail("input", "Expected the connector slug and an optional name")
100
+ init_bundle_from_files(root, request_files(request), connector=connector, name=name)
101
+
102
+
103
+ def init_world_files(request: dict, root: Path) -> None:
104
+ """An official world's files, copied under ``name`` and compiled."""
105
+ name = request.get("name")
106
+ if not isinstance(name, str):
107
+ fail("input", "Expected the new world's name")
108
+ init_bundle_from_world(root, request_files(request), name=name)
109
+
110
+
111
+ def build_slack(request: dict, root: Path) -> None:
112
+ from .slack import build_slack_bundle
113
+
114
+ template = request_files(request, "template")
115
+ build_slack_bundle(root, template=template, evidence=request.get("evidence"), name=request.get("name"))
116
+
117
+
118
+ def refresh_slack(request: dict, root: Path) -> None:
119
+ from .slack import refresh_slack_bundle
120
+
121
+ template = request_files(request, "template")
122
+ refresh_slack_bundle(root, request.get("evidence"), template=template, batch_id=request.get("batch_id"))
123
+
124
+
125
+ WRITERS: dict[str, Callable[[dict, Path], None]] = {
126
+ "init-template": init_template,
127
+ "init-template-files": init_template_files,
128
+ "init-world-files": init_world_files,
129
+ "build-slack": build_slack,
130
+ "refresh-slack": refresh_slack,
131
+ }
132
+
133
+
134
+ def _redact_summary(spec: "Spec | RedactPolicy") -> dict:
135
+ """``slug`` is the salt ``_digest`` hashes under: the connector's slug, not the platform world slug."""
136
+ return {
137
+ "slug": spec.slug,
138
+ "hash": sorted(spec.hash_fields),
139
+ "drop": sorted(spec.drop_fields),
140
+ "preserve": sorted(spec.preserve_fields),
141
+ "round": dict(spec.round_fields),
142
+ }
143
+
144
+
145
+ def _annotate_redaction(entities: list[dict], spec: "Spec | RedactPolicy | None") -> None:
146
+ from .connector import redaction_of
147
+
148
+ for entity in entities:
149
+ for field in entity["fields"]:
150
+ field["redaction"] = redaction_of(spec, field["name"]) if spec else None
151
+
152
+
153
+ def _operations(spec: "Spec") -> list[dict]:
154
+ return [
155
+ {
156
+ "name": op.name,
157
+ "method": op.method,
158
+ "path": op.path,
159
+ "params": list(op.params),
160
+ "entity": op.entity,
161
+ "results": op.results,
162
+ }
163
+ for op in spec.operations.values()
164
+ ]
165
+
166
+
167
+ def _served_operations(spec: "Spec", settings: Any) -> list[dict]:
168
+ operations = _operations(spec)
169
+ for operation in operations:
170
+ served = settings.for_operation(operation["name"]) if settings else None
171
+ operation["action"] = served.action if served else None
172
+ operation["status"] = served.status if served else None
173
+ return operations
174
+
175
+
176
+ def template_summary(files: dict[str, bytes]) -> dict:
177
+ """Never runs the template's Python."""
178
+ from .connector import bind_spec, parse_spec
179
+ from .redaction import parse_env_policy
180
+
181
+ world_path = next((path for path in ("world.json", "schema/world.json") if path in files), None)
182
+ if world_path is None:
183
+ fail(
184
+ "template",
185
+ "No world.json (template) or schema/world.json (world) among the files",
186
+ )
187
+ try:
188
+ world = json.loads(files[world_path].decode("utf-8"))
189
+ except (UnicodeDecodeError, json.JSONDecodeError) as error:
190
+ fail("template", f"{world_path} is not valid JSON: {error}")
191
+ gateway = world.get("x-gateway") if isinstance(world, dict) else None
192
+ if not isinstance(gateway, dict):
193
+ fail("template", f"{world_path} is not a gateway-world document")
194
+ spec = bind_spec(parse_spec(files["connector.toml"].decode("utf-8")), world) if "connector.toml" in files else None
195
+ policy = spec
196
+ if policy is None and "gateway-env.toml" in files:
197
+ policy = parse_env_policy(files["gateway-env.toml"].decode("utf-8"))
198
+ entities = []
199
+ fields_by_entity = world_fields(world)
200
+ for name, entity in sorted((gateway.get("entities") or {}).items()):
201
+ entities.append(
202
+ {
203
+ "name": name,
204
+ "primaryKey": list(entity.get("primary_key") or []) if isinstance(entity, dict) else [],
205
+ "unique": list(entity.get("unique") or []) if isinstance(entity, dict) else [],
206
+ "relationships": list(entity.get("relationships") or []) if isinstance(entity, dict) else [],
207
+ "fields": [field.describe() for field in fields_by_entity.get(name, [])],
208
+ }
209
+ )
210
+ _annotate_redaction(entities, policy)
211
+ connection = None
212
+ if spec is not None:
213
+ connection = {
214
+ "slug": spec.slug,
215
+ "baseUrl": spec.base_url,
216
+ "auth": spec.scheme,
217
+ "redact": _redact_summary(spec),
218
+ "operations": _operations(spec),
219
+ }
220
+ package = gateway.get("package") or {}
221
+ return {
222
+ "status": "ok",
223
+ "summary": {
224
+ "packageVersion": package.get("version"),
225
+ "domainVersion": gateway.get("domain_version"),
226
+ "domainId": world.get("$id"),
227
+ "digest": template_digest(files),
228
+ "entities": entities,
229
+ "connection": connection,
230
+ "redact": _redact_summary(policy) if policy is not None else None,
231
+ "tools": sorted((gateway.get("tools") or {}).keys()),
232
+ "files": sorted(files),
233
+ },
234
+ }
235
+
236
+
237
+ def describe(request: dict) -> dict:
238
+ """``connector`` (``custom`` only) or the ``files`` of a template or a compiled world."""
239
+ from .platform import describe_dependencies
240
+ from .ui import ui_kind
241
+
242
+ with tempfile.TemporaryDirectory(prefix="gateway-schema-") as directory:
243
+ root = Path(directory) / "bundle"
244
+ authored = _described_tree(request, root)
245
+ summary = template_summary({"world.json": (root / "schema/world.json").read_bytes()})["summary"]
246
+ summary["digest"] = template_digest(authored)
247
+ summary["files"] = sorted(authored)
248
+ summary["ui"] = ui_kind(root)
249
+ summary["tools"] = _tool_schemas(root)
250
+ summary["connection"] = None
251
+ summary["openapi"] = None
252
+ _describe_surface(root, summary)
253
+ summary["dependencies"] = describe_dependencies(root) if (root / "gateway-env.toml").is_file() else []
254
+ return {"status": "ok", "description": summary}
255
+
256
+
257
+ def _described_tree(request: dict, root: Path) -> dict[str, bytes]:
258
+ from .connector import parse_spec
259
+
260
+ connector = request.get("connector")
261
+ if connector is not None:
262
+ return _custom_tree(connector, root)
263
+ authored = request_files(request)
264
+ if all(marker in authored for marker in COMPILED_MARKERS):
265
+ _write_compiled(authored, root)
266
+ return authored
267
+ slug = request.get("slug") if isinstance(request.get("slug"), str) else None
268
+ if slug is None and "connector.toml" in authored:
269
+ slug = parse_spec(authored["connector.toml"].decode("utf-8")).slug
270
+ init_bundle_from_files(root, authored, connector=slug or CUSTOM)
271
+ return authored
272
+
273
+
274
+ def _custom_tree(connector: Any, root: Path) -> dict[str, bytes]:
275
+ if not isinstance(connector, str):
276
+ fail("input", "Expected a connector template slug", "/connector")
277
+ refuse_official(connector, "describe", "/connector")
278
+ scaffold = CustomScaffold()
279
+ scaffold.write(root, connector=CUSTOM)
280
+ return scaffold.files
281
+
282
+
283
+ def _write_compiled(authored: dict[str, bytes], root: Path) -> None:
284
+ root.mkdir()
285
+ for path, data in authored.items():
286
+ if path in DESCRIBE_PATHS:
287
+ target = root / path
288
+ target.parent.mkdir(parents=True, exist_ok=True)
289
+ target.write_bytes(data)
290
+
291
+
292
+ def _tool_schemas(root: Path) -> list[dict]:
293
+ tool_schemas = {}
294
+ if (root / "tool-schemas.json").is_file():
295
+ tool_schemas = json.loads((root / "tool-schemas.json").read_text(encoding="utf-8")).get("tools") or {}
296
+ return [
297
+ {
298
+ "name": name,
299
+ "description": str(entry.get("description") or ""),
300
+ "inputSchema": entry.get("input_schema"),
301
+ "outputSchema": entry.get("output_schema"),
302
+ }
303
+ for name, entry in sorted(tool_schemas.items())
304
+ ]
305
+
306
+
307
+ def _describe_surface(root: Path, summary: dict) -> None:
308
+ from .api import load_api_settings, openapi_document
309
+ from .connector import load_spec
310
+ from .redaction import env_policy
311
+
312
+ if not (root / "connector.toml").is_file():
313
+ policy = env_policy(root / "gateway-env.toml")
314
+ _annotate_redaction(summary["entities"], policy)
315
+ summary["redact"] = _redact_summary(policy) if policy else None
316
+ return
317
+ spec = load_spec(root)
318
+ try:
319
+ settings = load_api_settings(root, spec)
320
+ except ContractError:
321
+ # A template without its handlers still has a shape worth showing.
322
+ settings = None
323
+ _annotate_redaction(summary["entities"], spec)
324
+ summary["connection"] = {
325
+ "slug": spec.slug,
326
+ "baseUrl": spec.base_url,
327
+ "auth": spec.scheme,
328
+ "redact": _redact_summary(spec),
329
+ "operations": _served_operations(spec, settings),
330
+ }
331
+ summary["openapi"] = openapi_document(spec, summary.get("domainId") or spec.slug, settings)
332
+ summary["redact"] = summary["connection"]["redact"]
@@ -434,11 +434,14 @@ class _Unredirected(urllib.request.HTTPRedirectHandler):
434
434
  return None
435
435
 
436
436
 
437
+ UNREDIRECTED = urllib.request.build_opener(_Unredirected)
438
+
439
+
437
440
  class PlatformLedger:
438
441
  """The platform's ledger door (:data:`LEDGER_ROUTE`), behind the control-plane secret; an answer that
439
442
  redirects the flush is not followed, so it reads as unavailable, never as stored."""
440
443
 
441
- _opener = urllib.request.build_opener(_Unredirected)
444
+ _opener = UNREDIRECTED
442
445
 
443
446
  def __init__(self, platform_url: str, secret: str, timeout_s: float = 30.0, host_url: str | None = None) -> None:
444
447
  self.url = f"{platform_url.rstrip('/')}{LEDGER_ROUTE}"
@@ -0,0 +1,25 @@
1
+ """The knob values a session opens with (a world state's bindings), as the World Host takes them."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from .validation import fail
6
+
7
+ MAX_RUN_PARAMETERS = 8
8
+ MAX_RUN_PARAMETER_VALUE_LENGTH = 64
9
+
10
+
11
+ def parse_run_parameters(raw: object) -> dict[str, str]:
12
+ if raw is None:
13
+ return {}
14
+ if not isinstance(raw, dict):
15
+ fail("host", "parameters is an object of parameter name to value")
16
+ if len(raw) > MAX_RUN_PARAMETERS:
17
+ fail("host", f"an open binds at most {MAX_RUN_PARAMETERS} parameters, not {len(raw)}")
18
+ for name, value in raw.items():
19
+ if not isinstance(name, str) or not name:
20
+ fail("host", "each parameter has a name")
21
+ if not isinstance(value, str):
22
+ fail("host", f"parameter '{name}' is bound to a string, not {type(value).__name__}")
23
+ if len(value) > MAX_RUN_PARAMETER_VALUE_LENGTH:
24
+ fail("host", f"parameter '{name}' is bound to at most {MAX_RUN_PARAMETER_VALUE_LENGTH} characters")
25
+ return dict(raw)
@@ -15,11 +15,11 @@ from .database import WorldDatabase
15
15
  from .dependencies import Dependency
16
16
  from .grading import Grade, GraderError, TaskGrader
17
17
  from .journal import CallsView, WorldJournal
18
+ from .page_checks import PageCheck
18
19
  from .request_ledger import RequestOutbox
19
- from .webhooks import WebhookPoll
20
20
  from .served_names import ServedNames
21
21
  from .session_files import CALLS_JOURNAL, LEDGER_JOURNAL, SessionExport
22
- from .snapshot import SCENARIOS
22
+ from .snapshot import SCENARIO_GRADERS, SCENARIOS
23
23
  from .tasks import (
24
24
  TASK_DIR,
25
25
  TaskSpec,
@@ -30,7 +30,9 @@ from .tasks import (
30
30
  write_task_dir,
31
31
  )
32
32
  from .tools_world import DependencyWorld, ToolsWorld, ToolsWorldState, inline_task, served_with_dependencies
33
+ from .ui_interactions import UiRecorder
33
34
  from .validation import fail
35
+ from .webhooks import WebhookPoll
34
36
  from .workers import ConfinedVerifierSandbox
35
37
 
36
38
  if TYPE_CHECKING:
@@ -40,6 +42,8 @@ Restorer = Callable[[Callable[[SessionExport], None]], bool]
40
42
 
41
43
 
42
44
  class WorldRuntime(ABC):
45
+ takes_parameters = False
46
+
43
47
  def __init__(
44
48
  self,
45
49
  cached: CachedVersion,
@@ -49,8 +53,10 @@ class WorldRuntime(ABC):
49
53
  spec: TaskSpec | None,
50
54
  token: str | None,
51
55
  journaled: bool = False,
56
+ parameters: dict[str, str] | None = None,
52
57
  ) -> None:
53
58
  self.cached = cached
59
+ self.parameters = dict(parameters or {})
54
60
  self.session_dir = Path(session_dir)
55
61
  self.task = task
56
62
  self.task_spec = spec
@@ -94,23 +100,38 @@ class WorldRuntime(ABC):
94
100
  token: str | None,
95
101
  dependencies: dict[str, DependencyWorld],
96
102
  restore: Restorer,
103
+ pages_vouched: bool,
97
104
  journaled: bool = False,
105
+ parameters: dict[str, str] | None = None,
98
106
  ) -> WorldRuntime:
99
107
  """``journaled`` keeps the calls on disk, so a version worker that dies leaves them to the next one."""
100
- runtime = cached.runtime_class(cached, session_dir, task=task, spec=spec, token=token, journaled=journaled)
108
+ if parameters and not cached.runtime_class.takes_parameters:
109
+ fail("host", f"version {cached.version_id} is an api bundle, which takes no runtime parameters")
110
+ runtime = cached.runtime_class(
111
+ cached, session_dir, task=task, spec=spec, token=token, journaled=journaled, parameters=parameters
112
+ )
101
113
  runtime._start(dependencies)
102
114
  try:
103
115
  if spec is not None:
104
116
  runtime._check_task_entities(spec)
117
+ runtime._check_page_checks(spec)
105
118
  write_task_dir(spec, runtime.session_dir)
106
119
  runtime._to_start()
107
120
  runtime.restored = restore(runtime.restore)
121
+ runtime._note_pages(pages_vouched)
108
122
  runtime._attach_app()
109
123
  except BaseException:
110
124
  runtime.close()
111
125
  raise
112
126
  return runtime
113
127
 
128
+ def _note_pages(self, vouched: bool) -> None:
129
+ """A first open notes that this host records the pages; a restore from an export no recording host took
130
+ notes that an earlier life may have gone unrecorded. A restore a recording host vouched for adds nothing."""
131
+ if self.cached.ui is None or (self.restored and vouched):
132
+ return
133
+ (UiRecorder.unrecorded if self.restored else UiRecorder.recording)(self.calls)
134
+
114
135
  def _attach_app(self) -> None:
115
136
  cached = self.cached
116
137
  if cached.spec is None:
@@ -142,6 +163,18 @@ class WorldRuntime(ABC):
142
163
  "/task",
143
164
  )
144
165
 
166
+ def _check_page_checks(self, spec: TaskSpec) -> None:
167
+ """A check on the page of a world that serves none could never be decided."""
168
+ named = [
169
+ check.get("id") or check["entity"] for check in spec.grader_checks() if PageCheck(check).names_the_page
170
+ ]
171
+ if named and self.cached.ui is None:
172
+ fail(
173
+ "task",
174
+ f"the task's checks {', '.join(named)} read the page, and this world serves none",
175
+ "/task/grader",
176
+ )
177
+
145
178
  @abstractmethod
146
179
  def _start(self, dependencies: dict[str, DependencyWorld]) -> None:
147
180
  """A failure here leaves nothing to close: :meth:`open` runs it outside its cleanup."""
@@ -329,6 +362,8 @@ class WorldRuntime(ABC):
329
362
 
330
363
 
331
364
  class TreeRuntime(WorldRuntime):
365
+ takes_parameters = True
366
+
332
367
  world: ToolsWorld
333
368
 
334
369
  @classmethod
@@ -366,10 +401,13 @@ class TreeRuntime(WorldRuntime):
366
401
  allowed=self.allowed,
367
402
  dependencies=dependencies,
368
403
  calls=self.calls,
404
+ parameters=self.parameters,
369
405
  )
370
406
  return
371
407
  assert self.task is not None
372
- self.world = ToolsWorld(tools, self.session_dir, self.task, dependencies=dependencies, calls=self.calls)
408
+ self.world = ToolsWorld(
409
+ tools, self.session_dir, self.task, dependencies=dependencies, calls=self.calls, parameters=self.parameters
410
+ )
373
411
 
374
412
  def _app_state(self) -> ToolsWorldState:
375
413
  return ToolsWorldState(self.world, self.cached.tree)
@@ -558,7 +596,7 @@ class SnapshotRuntime(WorldRuntime):
558
596
  def _bundled_verifier(self) -> Path | None:
559
597
  assert self.task is not None
560
598
  scenario = scenario_dir(self.cached.bundle, self.cached.tree, self.task)
561
- return scenario / "checks" / "verify.py" if scenario else None
599
+ return scenario / SCENARIO_GRADERS / "verify.py" if scenario else None
562
600
 
563
601
  def call(self, tool: str, args: dict) -> dict:
564
602
  ServedNames.of((), self.cached.spec).refuse(tool)