@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
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@withgateway/sdk",
3
- "version": "0.4.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",
@@ -18,6 +18,7 @@ import importlib.util
18
18
  import inspect
19
19
  import sys
20
20
  import uuid
21
+ from contextlib import ExitStack
21
22
  from dataclasses import dataclass, field
22
23
  from pathlib import Path
23
24
  from typing import Any, Callable, Dict, List, Optional
@@ -124,8 +125,8 @@ def load_handlers(bundle_path: Path, manifest: EnvManifest) -> Dict[str, Callabl
124
125
  handler_files = sorted(tools_dir.glob("*.py")) if tools_dir.is_dir() else []
125
126
  load_token = runtime._load_registry.set(registry)
126
127
  strict_token = runtime._strict_registration.set(contract is not None)
127
- saved = sys.modules.get("gateway_env")
128
- sys.modules["gateway_env"] = runtime
128
+ installed = ExitStack()
129
+ installed.enter_context(runtime.installed(runtime))
129
130
  # Generated bundles use intra-bundle imports ("from tools._db import …"),
130
131
  # so the bundle root must be importable for the load's dynamic extent.
131
132
  bundle_root = str(bundle_path)
@@ -158,10 +159,7 @@ def load_handlers(bundle_path: Path, manifest: EnvManifest) -> Dict[str, Callabl
158
159
  modules.append(module)
159
160
  modules_by_stem[handler_file.stem] = module
160
161
  finally:
161
- if saved is not None:
162
- sys.modules["gateway_env"] = saved
163
- else:
164
- sys.modules.pop("gateway_env", None)
162
+ installed.close()
165
163
  if path_added:
166
164
  try:
167
165
  sys.path.remove(bundle_root)
@@ -20,6 +20,7 @@ if TYPE_CHECKING: # pragma: no cover
20
20
  from .core import Environment
21
21
  from .schema.journal import JournalUse, WorldJournal
22
22
  from .schema.session_files import ProvenTemplate, SessionExport
23
+ from .schema.webhooks import WebhookOutbox, Webhooks
23
24
 
24
25
 
25
26
  @dataclass
@@ -120,6 +121,7 @@ class World:
120
121
  self.contract = template.contract if template is not None else self._bundle_contract()
121
122
  source, audit = (Path(snapshot), True) if snapshot is not None else self._seed()
122
123
  self._backing = WorldBacking.branch(source, self.db_path, self.contract, audit=audit)
124
+ self.webhooks = self._webhook_outbox(None)
123
125
 
124
126
  @staticmethod
125
127
  def database_file(directory: Path, world_id: str) -> Path:
@@ -133,6 +135,24 @@ class World:
133
135
 
134
136
  return ProvenTemplate.required(template)
135
137
 
138
+ def serve_webhooks(self, webhooks: "Webhooks | None") -> None:
139
+ """Deliveries this world's tools stage go to the subscriptions ``webhooks`` declares."""
140
+ if webhooks is not None and self.contract is not None:
141
+ webhooks.check_contract(self.contract.entities)
142
+ self.webhooks = self._webhook_outbox(webhooks if self.contract is not None else None)
143
+
144
+ def _webhook_outbox(self, webhooks: "Webhooks | None") -> "WebhookOutbox":
145
+ from .schema.api import ApiContext
146
+ from .schema.primary_key import PrimaryKey
147
+ from .schema.webhooks import WebhookOutbox
148
+
149
+ return WebhookOutbox(
150
+ webhooks,
151
+ lambda entity: list(self.store.list(entity)),
152
+ lambda entity, row: PrimaryKey.in_contract(self.contract, entity).key(row),
153
+ ApiContext.clock,
154
+ )
155
+
136
156
  def _bundle_contract(self) -> Any:
137
157
  from .schema import bundle_mode, check_bundle
138
158
 
@@ -156,7 +176,7 @@ class World:
156
176
  raise ToolRouteError(f"tool '{tool_name}' has no declared env handler")
157
177
  supplied = ({} if self.contract else None) if tool_input is _NO_INPUT else tool_input
158
178
  started = time.perf_counter()
159
- with self._backing.transaction():
179
+ with self.webhooks.transaction(), self._backing.transaction():
160
180
  if self.contract is not None:
161
181
  validate(
162
182
  self.contract.tools[tool_name]["input_schema"],
@@ -165,6 +185,7 @@ class World:
165
185
  )
166
186
  token = runtime._active_connection.set(self._backing.handler_connection())
167
187
  store_token = runtime._active_store.set(self.store)
188
+ webhooks_token = runtime._active_webhooks.set(self.webhooks)
168
189
  try:
169
190
  if isinstance(supplied, Mapping):
170
191
  result = handler(**supplied)
@@ -181,6 +202,7 @@ class World:
181
202
  finally:
182
203
  runtime._active_connection.reset(token)
183
204
  runtime._active_store.reset(store_token)
205
+ runtime._active_webhooks.reset(webhooks_token)
184
206
  duration_ms = (time.perf_counter() - started) * 1000.0
185
207
  self.call_log.append({"tool": tool_name, "match": "env", "input": supplied})
186
208
  self.env._record_route(tool_name, "env", duration_ms, self.id)
@@ -234,6 +256,7 @@ class World:
234
256
  self._refuse_a_changed_contract()
235
257
  source, audit = self._seed()
236
258
  self._relay(source, audit=audit)
259
+ self.webhooks.clear()
237
260
 
238
261
  def _refuse_a_changed_contract(self) -> None:
239
262
  """An environment's bundle can change under a live world; a version's cannot."""
@@ -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
+ ]
@@ -24,12 +24,16 @@ falls back to discovery by function name == served tool name.
24
24
  from __future__ import annotations
25
25
 
26
26
  import re
27
+ import sys
28
+ from contextlib import contextmanager
27
29
  from contextvars import ContextVar
28
- from typing import Any, Callable, Dict, Optional
30
+ from types import ModuleType
31
+ from typing import Any, Callable, Dict, Iterator, Optional
29
32
 
33
+ from .schema.handler_errors import Refusal
30
34
  from .schema.store_contract import STORE_METHOD_NAMES, unknown_store_method_detail
31
35
 
32
- __all__ = ["tool", "db", "store"]
36
+ __all__ = ["tool", "db", "store", "webhooks", "Refusal"]
33
37
 
34
38
  _active_connection: ContextVar[Optional[Any]] = ContextVar("gateway_env_active_connection", default=None)
35
39
 
@@ -38,6 +42,7 @@ _load_registry: ContextVar[Optional[Dict[str, Callable[..., Any]]]] = ContextVar
38
42
  )
39
43
 
40
44
  _active_store: ContextVar[Any] = ContextVar("gateway_env_active_store", default=None)
45
+ _active_webhooks: ContextVar[Any] = ContextVar("gateway_env_active_webhooks", default=None)
41
46
  _strict_registration: ContextVar[bool] = ContextVar("gateway_env_strict_registration", default=False)
42
47
 
43
48
 
@@ -59,6 +64,21 @@ class _Store:
59
64
 
60
65
  store = _Store()
61
66
 
67
+
68
+ class _Webhooks:
69
+ """``deliver`` binds to the world whose tool is executing (:class:`~.schema.webhooks.WebhookOutbox`)."""
70
+
71
+ def deliver(
72
+ self, event_type: str, body: Any, scope: Optional[Dict[str, Any]] = None, event_id: Optional[str] = None
73
+ ) -> list[str]:
74
+ active = _active_webhooks.get()
75
+ if active is None:
76
+ raise RuntimeError("gateway_env.webhooks.deliver requires an executing tool in a schema-backed world")
77
+ return active.deliver(event_type, body, scope, event_id)
78
+
79
+
80
+ webhooks = _Webhooks()
81
+
62
82
  _IDENTIFIER_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
63
83
 
64
84
 
@@ -147,3 +167,26 @@ def tool(fn: Optional[Callable[..., Any]] = None, *, name: Optional[str] = None)
147
167
  return register(handler, name or handler.__name__)
148
168
 
149
169
  return decorator
170
+
171
+
172
+ @contextmanager
173
+ def installed(module: ModuleType) -> Iterator[None]:
174
+ """``gateway_env`` names ``module`` for a handler load's dynamic extent, and whatever it named before after."""
175
+ saved = sys.modules.get("gateway_env")
176
+ sys.modules["gateway_env"] = module
177
+ try:
178
+ yield
179
+ finally:
180
+ if saved is None:
181
+ sys.modules.pop("gateway_env", None)
182
+ else:
183
+ sys.modules["gateway_env"] = saved
184
+
185
+
186
+ def route_module() -> ModuleType:
187
+ """What a route handler may import: ``Refusal`` alone; ``store``, ``db`` and ``tool`` belong to tools."""
188
+ module = ModuleType("gateway_env")
189
+ module.Refusal = Refusal
190
+ module.__all__ = ["Refusal"]
191
+ return module
192
+
@@ -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(),
@@ -117,6 +117,7 @@ from .admin_routes import ADMIN, RUNNER_PATHS, AdminToken
117
117
  from .bundle_runtime import stage_runtime_package
118
118
  from .call_capture import Served, WorldRequestHandler, send_response
119
119
  from .call_log import AnswerShape, CallLog, Via
120
+ from .webhooks import WebhookOutbox, Webhooks
120
121
  from .compiler import check_bundle, compile_bundle
121
122
  from .connector import SPEC, Operation, Spec, load_spec, stored_forms
122
123
  from .cors import Cors
@@ -130,6 +131,7 @@ from .handler_errors import handled_answer, handler_bug_body, log_contract_refus
130
131
  from .primary_key import PrimaryKey
131
132
  from .request_body import RequestBody, Upload, json_value
132
133
  from .route_miss import RouteMiss, served_methods
134
+ from .ui import checked_api_path
133
135
  from .validation import ContractError, fail, read_json
134
136
 
135
137
  EVENT_LOG_SIZE = 500
@@ -434,10 +436,8 @@ def _ui_settings(raw: dict, world: Path) -> UiSettings | None:
434
436
  entry = ui.get("entry", "/")
435
437
  if not isinstance(entry, str) or not entry.startswith("/"):
436
438
  fail("spec", "ui.entry is the path the agent lands on, starting with /", "/ui/entry")
437
- api_path = ui.get("api_path", "/__world-api")
438
- if not isinstance(api_path, str) or not api_path.startswith("/") or api_path == "/":
439
- fail("spec", "ui.api_path is the same-origin prefix the ui calls the api at", "/ui/api_path")
440
- 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)
441
441
 
442
442
 
443
443
  def load_api_settings(world: Path, spec: Spec) -> ApiSettings:
@@ -534,6 +534,7 @@ class WorldState:
534
534
  self._dir = tempfile.TemporaryDirectory(prefix="gateway-world-api-")
535
535
  self._lock = threading.RLock()
536
536
  self.store: WorldDatabase | None = None
537
+ self.webhooks = WebhookOutbox(None, self.rows, self.key_of, ApiContext.clock)
537
538
  self._clear_events()
538
539
  self.reset()
539
540
 
@@ -557,8 +558,15 @@ class WorldState:
557
558
  collide on every key)."""
558
559
  with self._lock:
559
560
  self._clear_events()
561
+ self.webhooks.clear()
560
562
  self._open(self._snapshot_path if initial and self.snapshot else None, initial=initial)
561
563
 
564
+ def serve_webhooks(self, webhooks: Webhooks | None) -> None:
565
+ """Deliveries this state's handlers stage go to the subscriptions ``webhooks`` declares."""
566
+ if webhooks is not None:
567
+ webhooks.check_contract(self.contract.entities)
568
+ self.webhooks = WebhookOutbox(webhooks, self.rows, self.key_of, ApiContext.clock)
569
+
562
570
  def _clear_events(self) -> None:
563
571
  self._events: list[dict] = []
564
572
  self.event_seq = 0
@@ -708,12 +716,12 @@ class WorldState:
708
716
 
709
717
  @contextmanager
710
718
  def transaction(self) -> Iterator[None]:
711
- """One route call: its writes and events all land, or none do."""
719
+ """One route call: its writes, events and deliveries all land, or none do."""
712
720
  with self._lock:
713
721
  assert self.store is not None
714
722
  events, seq = list(self._events), self.event_seq
715
723
  try:
716
- with self.store.transaction():
724
+ with self.webhooks.transaction(), self.store.transaction():
717
725
  yield
718
726
  except BaseException:
719
727
  self._events, self.event_seq = events, seq
@@ -858,6 +866,13 @@ class ApiContext:
858
866
  def events_since(self, seq: int) -> list[dict]:
859
867
  return self.state.events_since(seq)
860
868
 
869
+ def deliver(
870
+ self, event_type: str, body: Any, scope: dict[str, Any] | None = None, event_id: str | None = None
871
+ ) -> list[str]:
872
+ """Send ``body`` as ``event_type`` to every subscription ``[webhooks]`` finds for it
873
+ (:class:`~.webhooks.WebhookOutbox`); the delivery ids, none when no one subscribed."""
874
+ return self.state.webhooks.deliver(event_type, body, scope, event_id)
875
+
861
876
  def stored_forms(self, field: str, plaintext: Any) -> tuple[Any, ...]:
862
877
  """The values the store may hold for a plaintext under this world's ``[redact]``
863
878
  (see :func:`connector.stored_forms`); a world without a spec stores the clear value."""
@@ -944,10 +959,13 @@ def load_handlers(settings: ApiSettings) -> dict[str, Handler]:
944
959
  spec = importlib.util.spec_from_file_location(module_name, settings.handlers)
945
960
  if spec is None or spec.loader is None:
946
961
  fail("handlers", f"Could not load {settings.handlers}", "/api/handlers")
962
+ from .. import runtime
963
+
947
964
  module = importlib.util.module_from_spec(spec)
948
965
  sys.modules[module_name] = module
949
966
  try:
950
- spec.loader.exec_module(module)
967
+ with runtime.installed(runtime.route_module()):
968
+ spec.loader.exec_module(module)
951
969
  finally:
952
970
  sys.modules.pop(module_name, None)
953
971
  handlers: dict[str, Handler] = {}
@@ -1035,6 +1053,7 @@ class WorldApp:
1035
1053
  self.handlers = load_handlers(self.settings) if handlers is None else handlers
1036
1054
  self.routes_closed = routes_closed
1037
1055
  self.calls = calls if calls is not None else CallLog.for_spec(router.spec, secret=key)
1056
+ state.serve_webhooks(router.spec.webhooks)
1038
1057
 
1039
1058
  def handle(
1040
1059
  self,
@@ -1153,6 +1172,7 @@ class WorldApp:
1153
1172
  self.calls.record(
1154
1173
  operation, method, path, args, query_all, body, status, answer, elapsed, via, shape=shape, served=served
1155
1174
  )
1175
+ self.calls.record_webhooks(self.state.webhooks.take())
1156
1176
  return status, answer, settings.cors.carried(extra)
1157
1177
 
1158
1178
  def _answer_atomically(self, op, operation, *request) -> Response:
@@ -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,9 +10,11 @@ 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",
17
+ "runtime.py",
16
18
  "score.py",
17
19
  "secret_values.py",
18
20
  "world.py",