@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
@@ -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,10 +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
20
  from .served_names import ServedNames
20
21
  from .session_files import CALLS_JOURNAL, LEDGER_JOURNAL, SessionExport
21
- from .snapshot import SCENARIOS
22
+ from .snapshot import SCENARIO_GRADERS, SCENARIOS
22
23
  from .tasks import (
23
24
  TASK_DIR,
24
25
  TaskSpec,
@@ -29,7 +30,9 @@ from .tasks import (
29
30
  write_task_dir,
30
31
  )
31
32
  from .tools_world import DependencyWorld, ToolsWorld, ToolsWorldState, inline_task, served_with_dependencies
33
+ from .ui_interactions import UiRecorder
32
34
  from .validation import fail
35
+ from .webhooks import WebhookPoll
33
36
  from .workers import ConfinedVerifierSandbox
34
37
 
35
38
  if TYPE_CHECKING:
@@ -39,6 +42,8 @@ Restorer = Callable[[Callable[[SessionExport], None]], bool]
39
42
 
40
43
 
41
44
  class WorldRuntime(ABC):
45
+ takes_parameters = False
46
+
42
47
  def __init__(
43
48
  self,
44
49
  cached: CachedVersion,
@@ -48,8 +53,10 @@ class WorldRuntime(ABC):
48
53
  spec: TaskSpec | None,
49
54
  token: str | None,
50
55
  journaled: bool = False,
56
+ parameters: dict[str, str] | None = None,
51
57
  ) -> None:
52
58
  self.cached = cached
59
+ self.parameters = dict(parameters or {})
53
60
  self.session_dir = Path(session_dir)
54
61
  self.task = task
55
62
  self.task_spec = spec
@@ -93,23 +100,38 @@ class WorldRuntime(ABC):
93
100
  token: str | None,
94
101
  dependencies: dict[str, DependencyWorld],
95
102
  restore: Restorer,
103
+ pages_vouched: bool,
96
104
  journaled: bool = False,
105
+ parameters: dict[str, str] | None = None,
97
106
  ) -> WorldRuntime:
98
107
  """``journaled`` keeps the calls on disk, so a version worker that dies leaves them to the next one."""
99
- 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
+ )
100
113
  runtime._start(dependencies)
101
114
  try:
102
115
  if spec is not None:
103
116
  runtime._check_task_entities(spec)
117
+ runtime._check_page_checks(spec)
104
118
  write_task_dir(spec, runtime.session_dir)
105
119
  runtime._to_start()
106
120
  runtime.restored = restore(runtime.restore)
121
+ runtime._note_pages(pages_vouched)
107
122
  runtime._attach_app()
108
123
  except BaseException:
109
124
  runtime.close()
110
125
  raise
111
126
  return runtime
112
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
+
113
135
  def _attach_app(self) -> None:
114
136
  cached = self.cached
115
137
  if cached.spec is None:
@@ -141,6 +163,18 @@ class WorldRuntime(ABC):
141
163
  "/task",
142
164
  )
143
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
+
144
178
  @abstractmethod
145
179
  def _start(self, dependencies: dict[str, DependencyWorld]) -> None:
146
180
  """A failure here leaves nothing to close: :meth:`open` runs it outside its cleanup."""
@@ -206,6 +240,12 @@ class WorldRuntime(ABC):
206
240
  def state(self) -> dict:
207
241
  return self.calls.into_state(self._rows())
208
242
 
243
+ def webhooks(self, poll: WebhookPoll) -> dict:
244
+ """The subscriptions the world's ``[webhooks]`` finds (none declared: ``declared`` false), a page
245
+ of deliveries, and how many of the poll's answers the ledger kept."""
246
+ outbox = self.app.state.webhooks if self.app is not None else None
247
+ return self.calls.webhook_page(outbox, poll)
248
+
209
249
  def grader_state(self, report: Optional[str] = None, journal: Optional[WorldJournal] = None) -> dict:
210
250
  """Keys beside the rows (``calls``, ``snapshot``, ``report``, ``gateway_*``) are reserved from entity names."""
211
251
  state = self.calls.into_state(self._grader_rows())
@@ -322,6 +362,8 @@ class WorldRuntime(ABC):
322
362
 
323
363
 
324
364
  class TreeRuntime(WorldRuntime):
365
+ takes_parameters = True
366
+
325
367
  world: ToolsWorld
326
368
 
327
369
  @classmethod
@@ -359,10 +401,13 @@ class TreeRuntime(WorldRuntime):
359
401
  allowed=self.allowed,
360
402
  dependencies=dependencies,
361
403
  calls=self.calls,
404
+ parameters=self.parameters,
362
405
  )
363
406
  return
364
407
  assert self.task is not None
365
- 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
+ )
366
411
 
367
412
  def _app_state(self) -> ToolsWorldState:
368
413
  return ToolsWorldState(self.world, self.cached.tree)
@@ -551,7 +596,7 @@ class SnapshotRuntime(WorldRuntime):
551
596
  def _bundled_verifier(self) -> Path | None:
552
597
  assert self.task is not None
553
598
  scenario = scenario_dir(self.cached.bundle, self.cached.tree, self.task)
554
- return scenario / "checks" / "verify.py" if scenario else None
599
+ return scenario / SCENARIO_GRADERS / "verify.py" if scenario else None
555
600
 
556
601
  def call(self, tool: str, args: dict) -> dict:
557
602
  ServedNames.of((), self.cached.spec).refuse(tool)