@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
@@ -1,25 +1,33 @@
1
- """Initialize a schema world from a connector template or the custom template.
1
+ """Initialize a schema world from a connector template's files, or from the blank ``custom`` scaffold.
2
2
 
3
- Templates are authored ``gateway-world/1`` contracts shipped with the SDK, one
4
- directory per connector under ``connectors/``. Initializing copies the authored
5
- files, compiles them, and writes an empty initial batch; the world starts with
6
- no records and is filled by ingestion or by hand-authored fixture batches.
3
+ Vendor templates are official worlds on the platform: each is a schema world built from its
4
+ template (:func:`init_bundle_from_files`), and a world made from one is that world copied under
5
+ its own name and compiled again (:func:`init_bundle_from_world`), never a vendor directory.
6
+ ``custom`` is the one template that ships in code. Initializing places the authored files,
7
+ compiles them and writes an empty initial batch; the world starts with no records.
7
8
  """
8
9
 
9
10
  from __future__ import annotations
10
11
 
11
12
  import base64
12
13
  import binascii
14
+ import hashlib
13
15
  import json
16
+ import re
14
17
  import shutil
15
18
  from pathlib import Path
19
+ from typing import Any, Callable, Mapping
16
20
 
17
- from .compiler import Contract, compile_bundle
21
+ from .._toml import tomllib
22
+ from .compiler import CompilePlan, Contract, compile_bundle, retarget_journals
18
23
  from .store_contract import describe_store
19
- from .validation import ContractError, encoded, fail, read_json
24
+ from .template_record import RECORD as TEMPLATE_RECORD, TemplateRecord
25
+ from .ui import UiDeclaration
26
+ from .validation import ContractError, encoded, fail, parse_json, tree_path
20
27
 
21
28
  TEMPLATES = Path(__file__).resolve().parent / "connectors"
22
29
  CUSTOM = "custom"
30
+ TEMPLATE_SLUG = re.compile(r"[a-z][a-z0-9-]*")
23
31
  MANIFEST = """[environment]
24
32
  name = "{name}"
25
33
  kind = "schema"
@@ -67,8 +75,6 @@ and body as the vendor's refusal; any other exception is answered 500 {error: "e
67
75
  """
68
76
  '''
69
77
 
70
-
71
- #: Where the template module's docstring ends and its example tools begin.
72
78
  _DOCSTRING_END = '\n"""\n'
73
79
 
74
80
 
@@ -94,10 +100,26 @@ def custom_handlers_source(template_handlers: bytes, with_example_tool: bool) ->
94
100
  return (doc + end).encode("utf-8")
95
101
 
96
102
 
103
+ SUPPORTING_SUFFIXES = {".json", ".md", ".toml"}
104
+ GENERATED_NAMES = {"base.json", "runtime.json", "lock.json", "README.md", "tool-schemas.json", "template.json"}
105
+ #: Template subdirectories copied verbatim to the world root: the connection's
106
+ #: Python (``api/handlers.py``), its served scenarios (``scenarios/…``), the
107
+ #: tests it ships for its tools (``tests/…``, run by ``gateway worlds test``) and its ``ui/``.
108
+ TEMPLATE_DIRECTORIES = {"api", "scenarios", "tests", "ui"}
109
+ #: Template files compile does not lay out, copied to the world root after it, so a world keeps every
110
+ #: file its template brought: the twin of ``splitCarriedTemplateFiles``
111
+ #: (gateway/packages/shared/src/domain/worldSchema.ts).
112
+ CARRIED_DIRECTORIES = {"verifiers", "openapi", "readers", "evidence", "reports"}
113
+ CARRIED_FILES = {"tasks.json"}
114
+ SCHEMA_CONTRACT = "schema/world.json"
115
+ WORLD_MANIFEST = "gateway-env.toml"
116
+ HANDLER_PATHS = ("handlers.py", "tools/handlers.py")
117
+ PLACED_ELSEWHERE = {"world.json", *HANDLER_PATHS}
118
+
119
+
97
120
  def list_templates() -> list[str]:
98
- """Connector slugs that ``init_bundle`` accepts, custom last."""
99
- slugs = sorted(p.name for p in TEMPLATES.iterdir() if (p / "world.json").is_file())
100
- return [s for s in slugs if s != CUSTOM] + [CUSTOM]
121
+ """The templates this runtime holds: the blank ``custom`` scaffold. Vendor templates live on the platform."""
122
+ return [CUSTOM]
101
123
 
102
124
 
103
125
  def _slug(value: str, location: str) -> str:
@@ -106,44 +128,33 @@ def _slug(value: str, location: str) -> str:
106
128
  return value
107
129
 
108
130
 
131
+ def refuse_official(connector: str, door: str, location: str = "/init/connector") -> str:
132
+ """``connector`` when it names the ``custom`` scaffold; any other slug is an official
133
+ template this runtime does not hold, refused naming the ``door`` that takes its files."""
134
+ slug = _slug(connector, location)
135
+ if slug != CUSTOM:
136
+ fail("template", f"{slug} is an official template on the platform: send its files with {door}", location)
137
+ return slug
138
+
139
+
109
140
  def _resource(path: Path) -> Path:
110
141
  if path.is_symlink() or path.parent.is_symlink() or not path.is_file():
111
142
  fail("template", "Template resources must be regular files, not symlinks", str(path))
112
143
  return path
113
144
 
114
145
 
115
- SUPPORTING_SUFFIXES = {".json", ".md", ".toml"}
116
- GENERATED_NAMES = {"base.json", "runtime.json", "lock.json", "README.md", "tool-schemas.json"}
117
- #: Template files that are not schema artifacts but travel with a workspace connector.
118
- TEMPLATE_CODE = {"handlers.py", "api/handlers.py"}
119
- #: Template subdirectories copied verbatim to the world root: the connection's
120
- #: Python (``api/handlers.py``), its served scenarios (``scenarios/…``) and the
121
- #: tests it ships for its tools (``tests/…``, run by ``gateway worlds test``).
122
- TEMPLATE_DIRECTORIES = {"api", "scenarios", "tests", "ui"}
123
- #: Template subdirectories that stay with the connector package and never enter a
124
- #: world: authoring evidence, fidelity reports, and ``readers/`` — how the platform
125
- #: fills a world on this contract from a live connection (``readers/merge.toml``
126
- #: names the tools to pull, ``readers/merge.ingest.toml`` maps their payloads).
127
- CONNECTOR_ONLY_DIRECTORIES = {"evidence", "reports", "readers"}
128
-
129
-
130
146
  def _template_directory_files(directory: Path) -> list[Path]:
131
- files = []
132
- for path in sorted(directory.rglob("*")):
133
- if "__pycache__" in path.parts:
134
- continue
135
- if path.is_dir() and not path.is_symlink():
136
- continue
137
- files.append(_resource(path))
138
- return files
139
-
147
+ paths = sorted(directory.rglob("*"))
148
+ link = next((path for path in paths if path.is_symlink() or path.parent.is_symlink()), None)
149
+ if link is not None:
150
+ fail("template", "Template resources must be regular files, not symlinks", str(link))
151
+ return [path for path in paths if path.is_file() and "__pycache__" not in path.parts]
140
152
 
141
- def template_digest(files: dict[str, bytes]) -> str:
142
- """The same digest the platform computes over an installed template directory:
143
- sha256 over sorted ``path\0bytes\0``. A workspace connector's commit and an
144
- installed template with identical files therefore pin identically."""
145
- import hashlib
146
153
 
154
+ def template_digest(files: Mapping[str, bytes]) -> str:
155
+ """The same digest the platform computes over a template's files: sha256 over sorted
156
+ ``path\0bytes\0``. A workspace connector's commit and an official template with
157
+ identical files therefore pin identically."""
147
158
  digest = hashlib.sha256()
148
159
  for path in sorted(files):
149
160
  digest.update(path.encode("utf-8"))
@@ -153,65 +164,150 @@ def template_digest(files: dict[str, bytes]) -> str:
153
164
  return digest.hexdigest()
154
165
 
155
166
 
156
- def init_bundle_from_files(
157
- destination: str | Path, files: dict[str, bytes], *, connector: str, name: str | None = None
158
- ) -> Contract:
159
- """Create and compile a schema world from a template held in memory: a workspace
160
- connector's files (``world.json``, ``connector.toml``, ``provenance.json``,
161
- ``scope.toml``, ``handlers.py``, ``api/handlers.py``, ``scenarios/…``, ``tests/…``), exactly
162
- what :func:`init_bundle` reads from an installed template directory.
163
-
164
- ``connector`` names the template for the manifest; ``name`` the world."""
165
- destination = Path(destination)
166
- connector = _slug(connector, "/init/connector")
167
- name = _slug(name if name is not None else f"{connector}-world", "/init/name")
168
- if destination.exists() and (not destination.is_dir() or any(destination.iterdir())):
169
- fail("state_exists", "Destination must be a new or empty directory", "/init")
170
- if "world.json" not in files:
171
- fail("template", "A connector template needs world.json", "/init/files")
172
- if not all(isinstance(k, str) and k and not k.startswith("/") and ".." not in k.split("/") for k in files):
173
- fail("template", "Template paths must be relative and stay inside the template", "/init/files")
174
- try:
175
- world = json.loads(files["world.json"].decode("utf-8"))
176
- except (UnicodeDecodeError, ValueError):
177
- fail("template", "world.json is not valid JSON", "/init/files/world.json")
178
- if not isinstance(world, dict) or not isinstance(world.get("x-gateway"), dict):
179
- fail("template", "world.json is not a gateway-world document", "/init/files/world.json")
180
- world["x-gateway"]["package"]["id"] = name
181
- tools = sorted(world["x-gateway"].get("tools", {}))
167
+ def template_json(files: Mapping[str, bytes], name: str, location: str = "/init/files") -> Any:
168
+ if name not in files:
169
+ fail("template", f"The template carries no {name}", f"{location}/{name}")
182
170
  try:
171
+ return parse_json(files[name].decode("utf-8"), name)
172
+ except ContractError:
173
+ raise
174
+ except ValueError:
175
+ fail("template", f"{name} is not valid JSON", f"{location}/{name}")
176
+
177
+
178
+ def _pretty(value) -> bytes:
179
+ return (json.dumps(value, indent=2) + "\n").encode("utf-8")
180
+
181
+
182
+ def _published_slack_capabilities(files: Mapping[str, bytes]) -> bytes:
183
+ from ._slack_fidelity import load_capabilities
184
+
185
+ return _pretty(load_capabilities(files, "capabilities.json"))
186
+
187
+
188
+ #: Authored files a template publishes in another form: Slack's capabilities are
189
+ #: expanded, so no reader of a world resolves the authoring defaults.
190
+ RENDERED: dict[tuple[str, str], Callable[[Mapping[str, bytes]], bytes]] = {
191
+ ("slack", "capabilities.json"): _published_slack_capabilities,
192
+ }
193
+
194
+
195
+ class WorldTemplate:
196
+ """A connector template held in memory, ``{template-relative path: bytes}``: what a world
197
+ is initialized from (``world.json``, ``connector.toml``, ``handlers.py``, ``provenance.json``,
198
+ ``scope.toml``, ``api/…``, ``scenarios/…``, ``tests/…``, ``ui/…``). ``location`` names the
199
+ files in refusals."""
200
+
201
+ def __init__(self, files: Mapping[str, bytes], location: str = "/init/files") -> None:
202
+ self.files = dict(files)
203
+ self.location = location
204
+
205
+ @property
206
+ def digest(self) -> str:
207
+ return template_digest(self.files)
208
+
209
+ def world(self) -> dict:
210
+ if "world.json" not in self.files:
211
+ fail("template", "A connector template needs world.json", self.location)
212
+ world = template_json(self.files, "world.json", self.location)
213
+ if not isinstance(world, dict) or not isinstance(world.get("x-gateway"), dict):
214
+ fail("template", "world.json is not a gateway-world document", f"{self.location}/world.json")
215
+ return world
216
+
217
+ def summary(self, slug: str) -> dict:
218
+ """What a template listing shows; never runs the template's Python."""
219
+ world = self.world()
220
+ gateway = world["x-gateway"]
221
+ return {
222
+ "slug": slug,
223
+ "name": world.get("title") if isinstance(world.get("title"), str) else None,
224
+ "description": world.get("description") if isinstance(world.get("description"), str) else None,
225
+ "entities": self._names(gateway, "entities"),
226
+ "tools": self._names(gateway, "tools"),
227
+ "hasConnection": "connector.toml" in self.files,
228
+ "ui": UiDeclaration.kind_of(self.files.get("connector.toml")),
229
+ }
230
+
231
+ def _names(self, gateway: dict, key: str) -> list[str]:
232
+ value = gateway.get(key) or {}
233
+ names = list(value) if isinstance(value, (dict, list)) else None
234
+ if names is None or not all(isinstance(name, str) for name in names):
235
+ fail(
236
+ "template",
237
+ f'"x-gateway".{key} must be an object or a list of names',
238
+ f"{self.location}/world.json",
239
+ )
240
+ return sorted(names)
241
+
242
+ def write(self, destination: str | Path, *, connector: str, name: str | None = None) -> Contract:
243
+ """Lay the template out as a world at ``destination`` (new or empty) and compile it.
244
+ ``connector`` names the template in the manifest; ``name`` the world and its package
245
+ id. The domain ``$id`` stays the template's, so worlds built from one template share
246
+ a domain identity."""
247
+ destination = _fresh(destination)
248
+ connector = _slug(connector, "/init/connector")
249
+ name = _slug(name if name is not None else f"{connector}-world", "/init/name")
250
+ world = self._named(self.world(), name)
251
+ placed = self._placed(connector)
252
+ if not world["x-gateway"].get("entities"):
253
+ fail("template", "world.json declares no entities", f"{self.location}/world.json")
254
+ try:
255
+ return self._lay_out(destination, world, placed, name=name, connector=connector)
256
+ except BaseException:
257
+ shutil.rmtree(destination, ignore_errors=True)
258
+ raise
259
+
260
+ def _named(self, world: dict, name: str) -> dict:
261
+ if not isinstance(world["x-gateway"].get("package"), dict):
262
+ fail("template", "world.json declares no x-gateway.package", f"{self.location}/world.json")
263
+ world["x-gateway"]["package"]["id"] = name
264
+ return world
265
+
266
+ def _handlers(self) -> bytes:
267
+ handlers = self.files.get("handlers.py") or self.files.get("tools/handlers.py")
268
+ return handlers if handlers is not None else b""
269
+
270
+ def _target(self, path: str) -> str | None:
271
+ """Where an authored file lands in the world; None when it stays with the template."""
272
+ parts = path.split("/")
273
+ if path in PLACED_ELSEWHERE or path in GENERATED_NAMES or "__pycache__" in parts:
274
+ return None
275
+ if path == "connector.toml" or _carried(path) or (parts[0] in TEMPLATE_DIRECTORIES and len(parts) > 1):
276
+ return path
277
+ if len(parts) == 1 and Path(path).suffix in SUPPORTING_SUFFIXES and path not in GENERATED_NAMES:
278
+ return f"schema/{path}"
279
+ fail("template", "Unsupported or generated template artifact", f"{self.location}/{path}")
280
+
281
+ def _placed(self, connector: str) -> dict[str, bytes]:
282
+ _confined(self.files, self.location)
283
+ placed = {}
284
+ for path in sorted(self.files):
285
+ target = self._target(path)
286
+ if target is not None:
287
+ placed[target] = self._content(connector, path)
288
+ return placed
289
+
290
+ def _content(self, connector: str, path: str) -> bytes:
291
+ render = RENDERED.get((connector, path))
292
+ return render(self.files) if render is not None else self.files[path]
293
+
294
+ def _lay_out(
295
+ self, destination: Path, world: dict, placed: dict[str, bytes], *, name: str, connector: str
296
+ ) -> Contract:
297
+ tools = sorted(world["x-gateway"].get("tools") or {})
298
+ entity = min(world["x-gateway"]["entities"])
183
299
  (destination / "schema").mkdir(parents=True)
184
300
  (destination / "schema/world.json").write_bytes(_pretty(world))
185
301
  shutil.copyfile(_resource(TEMPLATES / "base.json"), destination / "schema/base.json")
186
302
  (destination / "tools").mkdir()
187
- handlers = files.get("handlers.py") or files.get("tools/handlers.py")
188
- (destination / "tools/handlers.py").write_bytes(handlers if handlers is not None else b"")
189
- for path, content in sorted(files.items()):
190
- if path in {"world.json", "handlers.py", "tools/handlers.py"} or path.startswith("__pycache__"):
191
- continue
192
- if path == "connector.toml":
193
- target = destination / "connector.toml"
194
- elif path.startswith(("api/", "scenarios/", "tests/", "ui/")):
195
- target = destination / path
196
- elif path.split("/", 1)[0] in CONNECTOR_ONLY_DIRECTORIES:
197
- continue # evidence, reports and reader plans stay with the connector, not the world
198
- elif (
199
- Path(path).suffix in SUPPORTING_SUFFIXES and Path(path).name not in GENERATED_NAMES and "/" not in path
200
- ):
201
- target = destination / "schema" / path
202
- else:
203
- fail("template", "Unsupported or generated template artifact", f"/init/files/{path}")
204
- target.parent.mkdir(parents=True, exist_ok=True)
205
- target.write_bytes(content)
303
+ (destination / "tools/handlers.py").write_bytes(self._handlers())
304
+ _write(destination, {target: content for target, content in placed.items() if not _carried(target)})
206
305
  (destination / "gateway-env.toml").write_text(
207
306
  MANIFEST.format(name=name, connector=connector, serve=", ".join(f'"{t}"' for t in tools)),
208
307
  encoding="utf-8",
209
308
  )
210
- entities = sorted(world["x-gateway"].get("entities", {}))
211
- if not entities:
212
- fail("template", "world.json declares no entities", "/init/files/world.json")
213
- (destination / "verifiers").mkdir()
214
- (destination / "verifiers/state_present.sql").write_text(VERIFIER.format(entity=entities[0]), encoding="utf-8")
309
+ (destination / "verifiers").mkdir(exist_ok=True)
310
+ (destination / "verifiers/state_present.sql").write_text(VERIFIER.format(entity=entity), encoding="utf-8")
215
311
  contract = compile_bundle(destination)
216
312
  (destination / "data").mkdir()
217
313
  (destination / "data/initial.json").write_bytes(
@@ -225,10 +321,151 @@ def init_bundle_from_files(
225
321
  }
226
322
  )
227
323
  )
228
- except BaseException:
229
- shutil.rmtree(destination, ignore_errors=True)
230
- raise
231
- return contract
324
+ _write(destination, {target: content for target, content in placed.items() if _carried(target)})
325
+ TemplateRecord.of_world(destination, connector=connector, digest=self.digest).write(destination)
326
+ return contract
327
+
328
+
329
+ class TemplateWorld(WorldTemplate):
330
+ """An official world's head as stored: a schema world built from a connector template, whose
331
+ ``schema/template.json`` (``TemplateRecord``) names the template's digest and the sha256 of every
332
+ file the world holds besides the compiler's outputs. A world made from it is a copy of every file
333
+ it holds under the new world's name, compiled again, so nothing is rebuilt from the template and
334
+ the digest its worlds pin is the one recorded when it was built."""
335
+
336
+ def world(self) -> dict:
337
+ world = template_json(self.files, SCHEMA_CONTRACT, self.location)
338
+ if not isinstance(world, dict) or not isinstance(world.get("x-gateway"), dict):
339
+ fail("template", f"{SCHEMA_CONTRACT} is not a gateway-world document", f"{self.location}/{SCHEMA_CONTRACT}")
340
+ return world
341
+
342
+ @property
343
+ def record(self) -> TemplateRecord:
344
+ return TemplateRecord.parse(self.files, self.location)
345
+
346
+ @property
347
+ def digest(self) -> str:
348
+ return self.record.digest
349
+
350
+ def write(self, destination: str | Path, *, connector: str | None = None, name: str | None = None) -> Contract:
351
+ """Copy the world to ``destination`` (new or empty) as ``name`` and compile it there; its data follows
352
+ the renamed contract. Built snapshots are outputs of the official world, not part of the copy."""
353
+ from .snapshot import is_snapshot_output
354
+
355
+ _confined(self.files, self.location)
356
+ record = self.record
357
+ record.verify(self.files, self.location)
358
+ destination = _fresh(destination)
359
+ connector = _slug(connector if connector is not None else record.connector, "/init/connector")
360
+ name = _slug(name if name is not None else f"{connector}-world", "/init/name")
361
+ files = {
362
+ **{path: data for path, data in self.files.items() if not is_snapshot_output(path)},
363
+ SCHEMA_CONTRACT: _pretty(self._named(self.world(), name)),
364
+ WORLD_MANIFEST: self._renamed_manifest(name),
365
+ }
366
+ try:
367
+ _write(destination, files)
368
+ plan = CompilePlan.of(destination)
369
+ retarget_journals(destination, plan.contract)
370
+ contract = plan.write()
371
+ TemplateRecord.of_world(destination, connector=record.connector, digest=record.digest).write(destination)
372
+ return contract
373
+ except BaseException:
374
+ shutil.rmtree(destination, ignore_errors=True)
375
+ raise
376
+
377
+ def _renamed_manifest(self, name: str) -> bytes:
378
+ location = f"{self.location}/{WORLD_MANIFEST}"
379
+ if WORLD_MANIFEST not in self.files:
380
+ fail("template", f"The world carries no {WORLD_MANIFEST}", location)
381
+ text = self.files[WORLD_MANIFEST].decode("utf-8")
382
+ current = tomllib.loads(text).get("environment", {}).get("name")
383
+ line = f'name = "{current}"\n'
384
+ if not isinstance(current, str) or text.count(line) != 1:
385
+ fail("template", "The manifest must name its world once, as [environment] name", location)
386
+ return text.replace(line, f'name = "{name}"\n').encode("utf-8")
387
+
388
+
389
+ def _fresh(destination: str | Path) -> Path:
390
+ destination = Path(destination)
391
+ if destination.exists() and (not destination.is_dir() or any(destination.iterdir())):
392
+ fail("state_exists", "Destination must be a new or empty directory", "/init")
393
+ return destination
394
+
395
+
396
+ def _carried(path: str) -> bool:
397
+ parts = path.split("/")
398
+ return path in CARRIED_FILES or (parts[0] in CARRIED_DIRECTORIES and len(parts) > 1)
399
+
400
+
401
+ def _confined(files: Mapping[str, bytes], location: str) -> None:
402
+ for path in files:
403
+ tree_path(path, location)
404
+
405
+
406
+ def _write(destination: Path, files: Mapping[str, bytes]) -> None:
407
+ for target, content in files.items():
408
+ written = destination.joinpath(*tree_path(target).parts)
409
+ written.parent.mkdir(parents=True, exist_ok=True)
410
+ written.write_bytes(content)
411
+
412
+
413
+ class CustomScaffold(WorldTemplate):
414
+ """The blank page, read from code: not a shared vendor model, so its ``$id`` is the
415
+ world's own name (``urn:gateway:connector:<name>``), and its example tools, with the
416
+ tests that call them, enter the world only when ``with_example_tool`` asks."""
417
+
418
+ def __init__(self, with_example_tool: bool = False) -> None:
419
+ directory = TEMPLATES / CUSTOM
420
+ files = {
421
+ path.relative_to(directory).as_posix(): path.read_bytes() for path in _template_directory_files(directory)
422
+ }
423
+ super().__init__(files)
424
+ self.with_example_tool = with_example_tool
425
+
426
+ def _named(self, world: dict, name: str) -> dict:
427
+ world = super()._named(world, name)
428
+ world["$id"] = f"urn:gateway:connector:{name}"
429
+ if not self.with_example_tool:
430
+ world["x-gateway"]["tools"] = {}
431
+ return world
432
+
433
+ def _handlers(self) -> bytes:
434
+ return custom_handlers_source(super()._handlers(), self.with_example_tool)
435
+
436
+ def _target(self, path: str) -> str | None:
437
+ if path in GENERATED_NAMES:
438
+ fail("template", "Unsupported or generated template artifact", f"{self.location}/{path}")
439
+ if path.startswith("tests/") and not self.with_example_tool:
440
+ return None
441
+ return super()._target(path)
442
+
443
+
444
+ def init_bundle_from_files(
445
+ destination: str | Path, files: Mapping[str, bytes], *, connector: str, name: str | None = None
446
+ ) -> Contract:
447
+ """Create and compile a schema world from a template's files: an official template the
448
+ platform serves, a workspace connector, or a document an importer rendered.
449
+
450
+ ``connector`` names the template for the manifest; ``name`` the world."""
451
+ return WorldTemplate(files).write(destination, connector=connector, name=name)
452
+
453
+
454
+ def init_official_world(destination: str | Path, template_directory: str | Path) -> Contract:
455
+ """The schema world the official organization stores for a template directory: the template built under its
456
+ own slug. A push leaves its checkout record under ``.gateway/``; no dot entry, at any depth, is a template file."""
457
+ directory = Path(template_directory)
458
+ files = {
459
+ path.relative_to(directory).as_posix(): path.read_bytes()
460
+ for path in _template_directory_files(directory)
461
+ if not any(part.startswith(".") for part in path.relative_to(directory).parts)
462
+ }
463
+ return init_bundle_from_files(destination, files, connector=directory.name, name=directory.name)
464
+
465
+
466
+ def init_bundle_from_world(destination: str | Path, files: Mapping[str, bytes], *, name: str | None = None) -> Contract:
467
+ """Create and compile a world from an official world's files: a copy under ``name``."""
468
+ return TemplateWorld(files).write(destination, name=name)
232
469
 
233
470
 
234
471
  def init_bundle(
@@ -238,131 +475,22 @@ def init_bundle(
238
475
  name: str | None = None,
239
476
  with_example_tool: bool = False,
240
477
  ) -> Contract:
241
- """Create and compile a schema world at ``destination`` from a template.
242
-
243
- The destination must not exist or must be an empty directory. ``name``
244
- becomes the environment name and package id; the domain ``$id`` stays the
245
- connector's so worlds built from one connector share a domain identity.
246
-
247
- The ``custom`` scaffold is the exception: it is a blank page, not a shared
248
- vendor model, so its ``$id`` is derived from the name
249
- (``urn:gateway:connector:<name>``) and its example tools are left out unless
250
- ``with_example_tool`` asks for them. Authors used to rewrite the ``$id`` and
251
- delete the placeholder tools by hand on every world (Brex retrospective).
252
- """
253
- destination = Path(destination)
254
- connector = _slug(connector, "/init/connector")
255
- if connector not in list_templates():
256
- fail(
257
- "template",
258
- f"Unknown connector template; choose one of {', '.join(list_templates())}",
259
- "/init/connector",
260
- )
261
- name = _slug(name if name is not None else f"{connector}-world", "/init/name")
262
- if destination.exists() and (not destination.is_dir() or any(destination.iterdir())):
263
- fail("state_exists", "Destination must be a new or empty directory", "/init")
264
- template = TEMPLATES / connector
265
- # Templates may carry sibling schema dependencies and model evidence. Keep
266
- # every authored artifact in initialized worlds; never silently drop files.
267
- supporting_files = []
268
- code_files = []
269
- for path in sorted(template.iterdir()):
270
- # pip compiles the shipped handler module during installation.
271
- if path.name == "__pycache__" and path.is_dir() and not path.is_symlink():
272
- continue
273
- if path.name in TEMPLATE_DIRECTORIES and path.is_dir() and not path.is_symlink():
274
- # The blank custom world has no tools for the shipped tests to call.
275
- if not (path.name == "tests" and connector == CUSTOM and not with_example_tool):
276
- code_files.extend(_template_directory_files(path))
277
- continue
278
- if path.name in CONNECTOR_ONLY_DIRECTORIES and path.is_dir() and not path.is_symlink():
279
- continue
280
- _resource(path)
281
- if path.name in {"world.json", "handlers.py"}:
282
- continue
283
- if path.suffix not in {".json", ".md", ".toml"} or path.name in {
284
- "base.json",
285
- "runtime.json",
286
- "lock.json",
287
- "README.md",
288
- "tool-schemas.json",
289
- }:
290
- fail("template", "Unsupported or generated template artifact", str(path))
291
- supporting_files.append(path)
292
- world = read_json(_resource(template / "world.json"))
293
- world["x-gateway"]["package"]["id"] = name
294
- handlers = _resource(template / "handlers.py").read_bytes()
295
- if connector == CUSTOM:
296
- world["$id"] = f"urn:gateway:connector:{name}"
297
- if not with_example_tool:
298
- world["x-gateway"]["tools"] = {}
299
- handlers = custom_handlers_source(handlers, with_example_tool)
300
- tools = sorted(world["x-gateway"]["tools"])
301
- try:
302
- (destination / "schema").mkdir(parents=True)
303
- (destination / "schema/world.json").write_bytes(_pretty(world))
304
- shutil.copyfile(_resource(TEMPLATES / "base.json"), destination / "schema/base.json")
305
- for path in supporting_files:
306
- # The connection spec sits at the world root, where `worlds connector` and
307
- # `worlds serve` look for it; everything else describes the schema.
308
- target = destination / path.name if path.name == "connector.toml" else destination / "schema" / path.name
309
- if connector == "slack" and path.name == "capabilities.json":
310
- from ._slack_fidelity import expand_capabilities
311
-
312
- target.write_bytes(_pretty(expand_capabilities(read_json(_resource(path)))))
313
- else:
314
- shutil.copyfile(_resource(path), target)
315
- for path in code_files:
316
- target = destination / path.relative_to(template)
317
- target.parent.mkdir(parents=True, exist_ok=True)
318
- shutil.copyfile(path, target)
319
- (destination / "tools").mkdir()
320
- (destination / "tools/handlers.py").write_bytes(handlers)
321
- (destination / "gateway-env.toml").write_text(
322
- MANIFEST.format(
323
- name=name,
324
- connector=connector,
325
- serve=", ".join(f'"{t}"' for t in tools),
326
- ),
327
- encoding="utf-8",
328
- )
329
- first_entity = sorted(world["x-gateway"]["entities"])[0]
330
- (destination / "verifiers").mkdir()
331
- (destination / "verifiers/state_present.sql").write_text(VERIFIER.format(entity=first_entity), encoding="utf-8")
332
- contract = compile_bundle(destination)
333
- # Only the journal: nothing reads a `data/records.json`, and an empty one
334
- # read as a leftover to clean up (Brex retrospective).
335
- (destination / "data").mkdir()
336
- (destination / "data/initial.json").write_bytes(
337
- encoded(
338
- {
339
- "id": f"{name}.initial.v1",
340
- "target": contract.target,
341
- "mapping": {"id": "empty", "version": "1"},
342
- "coverage": "partial",
343
- "mutations": [],
344
- }
345
- )
346
- )
347
- except BaseException:
348
- shutil.rmtree(destination, ignore_errors=True)
349
- raise
350
- return contract
351
-
352
-
353
- def _pretty(value) -> bytes:
354
- return (json.dumps(value, indent=2) + "\n").encode("utf-8")
478
+ """Create and compile the blank ``custom`` world at ``destination`` (new or empty).
355
479
 
480
+ ``name`` becomes the environment name and package id. Any other ``connector`` is an
481
+ official template on the platform: fetch its files and build with
482
+ :func:`init_bundle_from_files`."""
483
+ refuse_official(connector, "init_bundle_from_files")
484
+ return CustomScaffold(with_example_tool).write(destination, connector=CUSTOM, name=name)
356
485
 
357
- __all__ = ["CUSTOM", "TEMPLATES", "ContractError", "init_bundle", "list_templates"]
358
486
 
359
-
360
- def request_files(request: dict) -> dict[str, bytes]:
361
- """The ``files: [{path, content}]`` of a bridge request as ``{path: bytes}``:
487
+ def request_files(request: dict, key: str = "files", location: str | None = None) -> dict[str, bytes]:
488
+ """The ``[{path, content}]`` under ``key`` of a bridge request as ``{path: bytes}``:
362
489
  what ``init_bundle_from_files`` and the template readers consume."""
363
- listed = request.get("files")
490
+ where = location if location is not None else f"/{key}"
491
+ listed = request.get(key)
364
492
  if not isinstance(listed, list) or not listed:
365
- fail("input", "Expected the template's files as [{path, content}]")
493
+ fail("input", "Expected the template's files as [{path, content}]", where)
366
494
  files: dict[str, bytes] = {}
367
495
  for entry in listed:
368
496
  if (
@@ -370,9 +498,31 @@ def request_files(request: dict) -> dict[str, bytes]:
370
498
  or not isinstance(entry.get("path"), str)
371
499
  or not isinstance(entry.get("content"), str)
372
500
  ):
373
- fail("input", "Each template file is {path, content} with base64 content")
501
+ fail("input", "Each template file is {path, content} with base64 content", where)
502
+ tree_path(entry["path"], where)
503
+ if entry["path"] in files:
504
+ fail("path", f"{entry['path']} is sent twice", where)
374
505
  try:
375
506
  files[entry["path"]] = base64.b64decode(entry["content"], validate=True)
376
507
  except (ValueError, binascii.Error):
377
- fail("input", "Template file content must be base64")
508
+ fail("input", "Template file content must be base64", where)
378
509
  return files
510
+
511
+
512
+ __all__ = [
513
+ "CUSTOM",
514
+ "TEMPLATES",
515
+ "TEMPLATE_SLUG",
516
+ "ContractError",
517
+ "CustomScaffold",
518
+ "TemplateWorld",
519
+ "WorldTemplate",
520
+ "init_bundle",
521
+ "init_bundle_from_files",
522
+ "init_bundle_from_world",
523
+ "init_official_world",
524
+ "list_templates",
525
+ "refuse_official",
526
+ "request_files",
527
+ "template_digest",
528
+ ]