@withgateway/sdk 0.3.3 → 0.6.0

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 (158) hide show
  1. package/README.md +4 -3
  2. package/dist/cli.js +3005 -1401
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +2996 -1392
  5. package/dist/cli.mjs.map +1 -1
  6. package/dist/files/index.js +128 -37
  7. package/dist/files/index.js.map +1 -1
  8. package/dist/files/index.mjs +126 -35
  9. package/dist/files/index.mjs.map +1 -1
  10. package/dist/hooks/index.d.mts +1 -1
  11. package/dist/hooks/index.d.ts +1 -1
  12. package/dist/hooks/index.js +124 -11
  13. package/dist/hooks/index.js.map +1 -1
  14. package/dist/hooks/index.mjs +124 -11
  15. package/dist/hooks/index.mjs.map +1 -1
  16. package/dist/{index-C3UzD0G3.d.mts → index-CDPQBsU5.d.mts} +19 -3
  17. package/dist/{index-C3UzD0G3.d.ts → index-CDPQBsU5.d.ts} +19 -3
  18. package/dist/{index-mJhG3vZU.d.mts → index-Di9nNqOY.d.mts} +26 -3
  19. package/dist/{index-DUHmS74p.d.ts → index-LA-PMRJT.d.ts} +26 -3
  20. package/dist/index.d.mts +4 -4
  21. package/dist/index.d.ts +4 -4
  22. package/dist/index.js +1078 -260
  23. package/dist/index.js.map +1 -1
  24. package/dist/index.mjs +1040 -251
  25. package/dist/index.mjs.map +1 -1
  26. package/dist/replay/index.d.mts +1 -1
  27. package/dist/replay/index.d.ts +1 -1
  28. package/dist/replay/index.js.map +1 -1
  29. package/dist/replay/index.mjs.map +1 -1
  30. package/dist/traces/index.js +125 -34
  31. package/dist/traces/index.js.map +1 -1
  32. package/dist/traces/index.mjs +123 -32
  33. package/dist/traces/index.mjs.map +1 -1
  34. package/dist/tracing/index.d.mts +1 -1
  35. package/dist/tracing/index.d.ts +1 -1
  36. package/dist/tracing/index.js +7 -1
  37. package/dist/tracing/index.js.map +1 -1
  38. package/dist/tracing/index.mjs +7 -1
  39. package/dist/tracing/index.mjs.map +1 -1
  40. package/dist/worlds/index.d.mts +819 -438
  41. package/dist/worlds/index.d.ts +819 -438
  42. package/dist/worlds/index.js +912 -236
  43. package/dist/worlds/index.js.map +1 -1
  44. package/dist/worlds/index.mjs +908 -232
  45. package/dist/worlds/index.mjs.map +1 -1
  46. package/package.json +1 -1
  47. package/runtime/gatewaysdk/environment/_bundle.py +4 -6
  48. package/runtime/gatewaysdk/environment/_materialize.py +5 -25
  49. package/runtime/gatewaysdk/environment/_world.py +82 -66
  50. package/runtime/gatewaysdk/environment/backing.py +20 -24
  51. package/runtime/gatewaysdk/environment/core.py +1 -16
  52. package/runtime/gatewaysdk/environment/legacy_sqlite.py +14 -27
  53. package/runtime/gatewaysdk/environment/runtime.py +45 -2
  54. package/runtime/gatewaysdk/environment/schema/admission.py +174 -0
  55. package/runtime/gatewaysdk/environment/schema/api.py +198 -474
  56. package/runtime/gatewaysdk/environment/schema/assertions.py +458 -0
  57. package/runtime/gatewaysdk/environment/schema/batch.py +3 -3
  58. package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +1 -0
  59. package/runtime/gatewaysdk/environment/schema/cache_layout.py +5 -0
  60. package/runtime/gatewaysdk/environment/schema/call_capture.py +321 -0
  61. package/runtime/gatewaysdk/environment/schema/call_log.py +276 -18
  62. package/runtime/gatewaysdk/environment/schema/call_redaction.py +207 -19
  63. package/runtime/gatewaysdk/environment/schema/cast.py +15 -35
  64. package/runtime/gatewaysdk/environment/schema/compiler.py +4 -1
  65. package/runtime/gatewaysdk/environment/schema/conform.py +38 -35
  66. package/runtime/gatewaysdk/environment/schema/connector.py +94 -152
  67. package/runtime/gatewaysdk/environment/schema/connectors/confluence/connector.toml +1 -12
  68. package/runtime/gatewaysdk/environment/schema/connectors/custom/handlers.py +2 -1
  69. package/runtime/gatewaysdk/environment/schema/connectors/github/api/handlers.py +217 -58
  70. package/runtime/gatewaysdk/environment/schema/connectors/github/connector.toml +10 -19
  71. package/runtime/gatewaysdk/environment/schema/connectors/github/scenarios/default/seed/github_webhooks.json +10 -2
  72. package/runtime/gatewaysdk/environment/schema/connectors/github/tests/webhooks.json +47 -0
  73. package/runtime/gatewaysdk/environment/schema/connectors/github/world.json +21 -0
  74. package/runtime/gatewaysdk/environment/schema/connectors/jamf/api/handlers.py +185 -18
  75. package/runtime/gatewaysdk/environment/schema/connectors/jamf/connector.toml +29 -14
  76. package/runtime/gatewaysdk/environment/schema/connectors/jamf/provenance.json +43 -12
  77. package/runtime/gatewaysdk/environment/schema/connectors/jamf/scenarios/default/seed/jamf_webhooks.json +2 -2
  78. package/runtime/gatewaysdk/environment/schema/connectors/jamf/scope.toml +4 -17
  79. package/runtime/gatewaysdk/environment/schema/connectors/jamf/tests/webhooks.json +107 -0
  80. package/runtime/gatewaysdk/environment/schema/connectors/jamf/vendor-openapi.json +1 -1
  81. package/runtime/gatewaysdk/environment/schema/connectors/linear/api/handlers.py +85 -1
  82. package/runtime/gatewaysdk/environment/schema/connectors/linear/connector.toml +19 -31
  83. package/runtime/gatewaysdk/environment/schema/connectors/linear/provenance.json +18 -8
  84. package/runtime/gatewaysdk/environment/schema/connectors/linear/scenarios/default/seed/webhooks.json +19 -3
  85. package/runtime/gatewaysdk/environment/schema/connectors/linear/tests/test_webhooks.py +71 -0
  86. package/runtime/gatewaysdk/environment/schema/connectors/servicenow/connector.toml +2 -5
  87. package/runtime/gatewaysdk/environment/schema/cors.py +54 -0
  88. package/runtime/gatewaysdk/environment/schema/credentials.py +313 -8
  89. package/runtime/gatewaysdk/environment/schema/data.py +14 -13
  90. package/runtime/gatewaysdk/environment/schema/database/base.py +106 -165
  91. package/runtime/gatewaysdk/environment/schema/database/guard.py +45 -37
  92. package/runtime/gatewaysdk/environment/schema/database/reads.py +169 -0
  93. package/runtime/gatewaysdk/environment/schema/database/sqlite.py +57 -31
  94. package/runtime/gatewaysdk/environment/schema/declared_routes.py +210 -0
  95. package/runtime/gatewaysdk/environment/schema/door.py +899 -0
  96. package/runtime/gatewaysdk/environment/schema/envelope.py +86 -28
  97. package/runtime/gatewaysdk/environment/schema/grading.py +58 -86
  98. package/runtime/gatewaysdk/environment/schema/handler_errors.py +52 -5
  99. package/runtime/gatewaysdk/environment/schema/host.py +229 -1695
  100. package/runtime/gatewaysdk/environment/schema/host_control.py +144 -0
  101. package/runtime/gatewaysdk/environment/schema/host_handoff.py +370 -0
  102. package/runtime/gatewaysdk/environment/schema/host_loops.py +97 -0
  103. package/runtime/gatewaysdk/environment/schema/host_owners.py +121 -0
  104. package/runtime/gatewaysdk/environment/schema/host_proxy.py +111 -0
  105. package/runtime/gatewaysdk/environment/schema/host_requests.py +6 -0
  106. package/runtime/gatewaysdk/environment/schema/host_session.py +126 -0
  107. package/runtime/gatewaysdk/environment/schema/host_surfaces.py +79 -21
  108. package/runtime/gatewaysdk/environment/schema/host_transfers.py +127 -0
  109. package/runtime/gatewaysdk/environment/schema/host_versions.py +242 -0
  110. package/runtime/gatewaysdk/environment/schema/host_workers.py +577 -0
  111. package/runtime/gatewaysdk/environment/schema/journal.py +438 -0
  112. package/runtime/gatewaysdk/environment/schema/ledger_spill.py +828 -0
  113. package/runtime/gatewaysdk/environment/schema/local.py +32 -116
  114. package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +20 -5
  115. package/runtime/gatewaysdk/environment/schema/platform.py +29 -234
  116. package/runtime/gatewaysdk/environment/schema/request_body.py +238 -0
  117. package/runtime/gatewaysdk/environment/schema/request_ledger.py +958 -0
  118. package/runtime/gatewaysdk/environment/schema/route_bindings.py +25 -3
  119. package/runtime/gatewaysdk/environment/schema/route_miss.py +54 -0
  120. package/runtime/gatewaysdk/environment/schema/runtime.py +136 -176
  121. package/runtime/gatewaysdk/environment/schema/scaffold.py +2 -1
  122. package/runtime/gatewaysdk/environment/schema/session_files.py +133 -24
  123. package/runtime/gatewaysdk/environment/schema/session_move.py +275 -0
  124. package/runtime/gatewaysdk/environment/schema/skills/agents/connector-template-author.md +5 -1
  125. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +8 -9
  126. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/CONNECTORS.md +3 -3
  127. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +50 -28
  128. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +12 -8
  129. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +20 -22
  130. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +25 -25
  131. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +24 -16
  132. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +71 -7
  133. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +182 -0
  134. package/runtime/gatewaysdk/environment/schema/snapshot.py +150 -30
  135. package/runtime/gatewaysdk/environment/schema/spill_files.py +228 -0
  136. package/runtime/gatewaysdk/environment/schema/tasks.py +229 -323
  137. package/runtime/gatewaysdk/environment/schema/tools_world.py +103 -203
  138. package/runtime/gatewaysdk/environment/schema/validation.py +69 -1
  139. package/runtime/gatewaysdk/environment/schema/verbs.py +38 -36
  140. package/runtime/gatewaysdk/environment/schema/webhooks.py +687 -0
  141. package/runtime/gatewaysdk/environment/schema/worker.py +6 -4
  142. package/runtime/gatewaysdk/environment/schema/workers.py +203 -39
  143. package/runtime/gatewaysdk/environment/schema/world_host.py +970 -0
  144. package/runtime/gatewaysdk/environment/schema/world_tests.py +83 -11
  145. package/runtime/gatewaysdk/environment/world.py +1 -1
  146. package/runtime/gatewaysdk/environment/world_session_contract.py +14 -0
  147. package/skills/agents/connector-template-author.md +5 -1
  148. package/skills/benchmarks-getting-started/SKILL.md +8 -9
  149. package/skills/connector-schema-authoring/CONNECTORS.md +3 -3
  150. package/skills/connector-schema-authoring/SKILL.md +50 -28
  151. package/skills/connector-schema-authoring/connector-worlds.md +282 -18
  152. package/skills/connector-schema-authoring/world-schema.md +7 -6
  153. package/skills/world-data-ingestion/ROWS.md +12 -8
  154. package/skills/world-data-ingestion/SKILL.md +20 -22
  155. package/skills/worlds-getting-started/SKILL.md +25 -25
  156. package/skills/worlds-getting-started/references/cli-mcp-map.md +24 -16
  157. package/skills/worlds-getting-started/references/gotchas.md +71 -7
  158. package/skills/worlds-getting-started/references/journal-checks.md +182 -0
@@ -26,22 +26,14 @@ from typing import TYPE_CHECKING, Any
26
26
 
27
27
  from .._materialize import materialize_template
28
28
  from ..world import WorldTree
29
- from . import ContractError, WorldDatabase, bundle_mode, check_bundle, compile_bundle, platform_import, platform_query
29
+ from . import ContractError, WorldDatabase, bundle_mode, check_bundle, platform_import, platform_query
30
30
  from . import snapshot as snapshots
31
31
  from .cast import world_fields
32
32
  from .compiler import CompilePlan, retarget_journals
33
33
  from .handler_scan import HandlerScan
34
34
  from .redaction import check_world_redaction
35
35
  from .scaffold import request_files
36
- from .validation import (
37
- digest,
38
- encoded,
39
- fail,
40
- journal_paths,
41
- members,
42
- nonempty,
43
- read_json,
44
- )
36
+ from .validation import encoded, fail
45
37
 
46
38
  if TYPE_CHECKING:
47
39
  from .compiler import Contract
@@ -60,7 +52,6 @@ COMMANDS = (
60
52
  "template-summary",
61
53
  "describe",
62
54
  "compile",
63
- "apply-batch",
64
55
  "build-slack",
65
56
  "refresh-slack",
66
57
  "capture",
@@ -84,7 +75,6 @@ COMMANDS = (
84
75
  "call",
85
76
  "dry-run",
86
77
  )
87
- PLATFORM_MAPPING = {"id": "platform-agent", "version": "1"}
88
78
 
89
79
 
90
80
  def compile_world(root: Path) -> dict:
@@ -131,78 +121,6 @@ def compile_world(root: Path) -> dict:
131
121
  return {"added": added, "retargeted": retargeted}
132
122
 
133
123
 
134
- def append_batch(root: Path, batch: dict, *, source: str | None = None) -> dict:
135
- """Validate then append one platform batch as an immutable refresh journal.
136
-
137
- ``target`` is filled from the compiled contract (a caller-supplied one must
138
- match); ``mapping`` and ``coverage`` default to the platform mapping and
139
- ``partial``. Mutations without ``source`` take ``{"record": "<source>#<n>"}``
140
- when a source prefix is given, otherwise provenance is required per mutation.
141
- Replaying every prior journal first makes a repeated batch id idempotent and
142
- a reused id with different content a conflict, exactly as in the store.
143
- """
144
- snapshots.refuse_pinned_rows(root)
145
- contract = check_bundle(root)
146
- members(
147
- batch,
148
- {"id", "target", "mapping", "coverage", "mutations"},
149
- {"id", "mutations"},
150
- "/batch",
151
- )
152
- nonempty(batch["id"], "/batch/id")
153
- if "target" in batch and not contract.targets(batch["target"]):
154
- fail(
155
- "batch_target",
156
- "Batch targets a different domain identity/version/hash",
157
- "/batch/target",
158
- )
159
- if not isinstance(batch["mutations"], list) or not batch["mutations"]:
160
- fail("batch", "mutations must be a non-empty array", "/batch/mutations")
161
- mutations = []
162
- for index, mutation in enumerate(batch["mutations"]):
163
- if not isinstance(mutation, dict):
164
- fail("batch", "Each mutation must be an object", f"/batch/mutations/{index}")
165
- if "source" not in mutation:
166
- if source is None:
167
- fail(
168
- "provenance",
169
- "Mutation has no source; pass a source prefix or a source.record per mutation",
170
- f"/batch/mutations/{index}/source",
171
- )
172
- mutation = {**mutation, "source": {"record": f"{source}#{index}"}}
173
- mutations.append(mutation)
174
- resolved = {
175
- "id": batch["id"],
176
- "target": contract.target,
177
- "mapping": batch.get("mapping", PLATFORM_MAPPING),
178
- "coverage": batch.get("coverage", "partial"),
179
- "mutations": mutations,
180
- }
181
- journals = journal_paths(root)
182
- with (
183
- tempfile.TemporaryDirectory(prefix="gateway-apply-batch-") as temporary,
184
- WorldDatabase.create(Path(temporary) / "world.db", contract) as store,
185
- ):
186
- for path in journals:
187
- store.apply_batch(read_json(path))
188
- result = store.apply_batch(resolved)
189
- store.audit()
190
- if result["status"] == "already_applied":
191
- return result
192
- batches = root / "data/batches"
193
- batches.mkdir(exist_ok=True)
194
- existing = len(journals) - 1
195
- target = batches / f"{existing + 1:06d}-{digest(batch['id'].encode())[:16]}.json"
196
- target.write_bytes(encoded(resolved))
197
- if snapshots.has_default_snapshot(root):
198
- # A snapshot built before this batch would be served over the grown journals.
199
- from .compiler import build
200
- from .snapshot import build_all
201
-
202
- build_all(root, build(root))
203
- return {**result, "journal": str(target.relative_to(root))}
204
-
205
-
206
124
  def validate_bundle(bundle: str | Path, *, execute: bool = False) -> dict:
207
125
  """Check a schema world: the contract, the handlers by syntax and by name, the
208
126
  initial state, every verifier over it, the tasks and the links. ``execute``
@@ -257,8 +175,6 @@ def validate_bundle(bundle: str | Path, *, execute: bool = False) -> dict:
257
175
 
258
176
 
259
177
  def _check_mappings(bundle: Path, contract: Contract) -> None:
260
- """Each ``[dependencies.<alias>.entities]`` mapping against this contract
261
- and, for a dependency whose ``path`` is here, against that contract too."""
262
178
  from .. import _bundle
263
179
  from .dependencies import check_mappings, parse_dependencies
264
180
 
@@ -278,12 +194,6 @@ def _field_map(contract: Contract) -> FieldMap:
278
194
 
279
195
 
280
196
  def _attach_dependencies(bundle: Path, store: WorldDatabase, staging: Path) -> dict[str, str]:
281
- """Each ``[dependencies]`` entry whose local ``path`` is on this machine,
282
- materialized beside the root's store and attached as ``<alias>.<table>``,
283
- so a cross-world verifier runs here the way it runs in a session. Returns
284
- the aliases left unattached, each with why: a pin without a path is the
285
- platform's to resolve; a path that is not here (the platform checking a
286
- pushed tree) resolves there too."""
287
197
  from .. import _bundle
288
198
  from .dependencies import parse_dependencies
289
199
 
@@ -310,13 +220,7 @@ def _attach_dependencies(bundle: Path, store: WorldDatabase, staging: Path) -> d
310
220
 
311
221
 
312
222
  def _check_verifiers(bundle: Path, store: WorldDatabase, unattached: dict[str, str], *, scored: bool) -> dict[str, Any]:
313
- """Every ``verifiers/*.sql`` run over the template through the store's
314
- read-only authorizer, the way a session grades. A verifier that names a
315
- table or column the contract lacks is refused here — at check — not at
316
- the first grade. ``scored`` reports the score over the initial state by
317
- the one :class:`SqlVerifier` rule a grade applies. A verifier that reads
318
- a dependency the check could not attach (a pin without a local path) is
319
- reported, not refused: it runs where the platform opens the link."""
223
+ """A verifier over a dependency the check could not attach is reported, not refused: it runs on the platform."""
320
224
  verifiers_dir = bundle / "verifiers"
321
225
  if not verifiers_dir.is_dir():
322
226
  return {}
@@ -350,8 +254,6 @@ def _check_verifier(path: Path, store: WorldDatabase, unattached: dict[str, str]
350
254
 
351
255
 
352
256
  def _refuse_verifier(path: Path, store: WorldDatabase, unattached: dict[str, str], error: ContractError) -> str:
353
- """The unattached dependency alias the failure names — the one refusal
354
- check reports rather than raises; every other failure is refused here."""
355
257
  reason = error.__cause__ if error.__cause__ is not None else error.detail["message"]
356
258
  missing = store.missing_table(reason)
357
259
  alias = _missing_dependency_alias(missing, unattached)
@@ -370,7 +272,6 @@ def _refuse_verifier(path: Path, store: WorldDatabase, unattached: dict[str, str
370
272
 
371
273
 
372
274
  def _missing_dependency_alias(table: str | None, unattached: dict[str, str]) -> str | None:
373
- """The alias of an unattached dependency a missing ``alias.table`` names, else ``None``."""
374
275
  alias, dot, _ = (table or "").partition(".")
375
276
  if dot and alias in unattached:
376
277
  return alias
@@ -378,8 +279,6 @@ def _missing_dependency_alias(table: str | None, unattached: dict[str, str]) ->
378
279
 
379
280
 
380
281
  def _check_tasks(bundle: Path, verifiers: list[str]) -> list[dict[str, Any]]:
381
- """The tasks the world declares (``[[tasks]]``, ``tasks.jsonl``/``.json``,
382
- else one per verifier), each checked to name verifiers the world has."""
383
282
  from .. import _bundle
384
283
  from .tools_world import load_tasks
385
284
 
@@ -448,14 +347,7 @@ def may_execute() -> bool:
448
347
 
449
348
 
450
349
  def _handler_execution(bundle: Path, execute: bool, declared: set[str], *, hosted: bool) -> dict[str, Any]:
451
- """Whether the handlers were run: imported, every declared tool bound, the
452
- ``[dependencies]`` opened from their paths — one session of the world,
453
- opened and closed. Only where authored code may run, and only over rows this
454
- tree holds (``hosted``: its data is a snapshot the platform keeps). ``tools`` is
455
- the declared handlers the session bound (the report's top-level ``tools``);
456
- ``served`` every name ``worlds call`` answers there — the handlers and a
457
- dependency's ``alias.tool``; a connector route answers over HTTP, never by
458
- name — so the two lists differ by design and say what each counts."""
350
+ """``tools`` counts bound declared handlers, ``served`` each name ``worlds call`` answers: they differ by design."""
459
351
  if not execute:
460
352
  return {
461
353
  "status": "not_run",
@@ -580,10 +472,7 @@ def _archive_files(encoded: str) -> list:
580
472
 
581
473
 
582
474
  def _capture(request: dict) -> dict:
583
- """``capture``: run one connection operation for the platform, from the pod whose
584
- egress the vendor allow-listed. The spec arrives as text, the credential as the
585
- environment variable it names (set by the caller, never in the request), and every
586
- recorded page comes back redacted the way the CLI would have written it."""
475
+ """The credential is the env variable the spec names, never in the request; pages come back redacted."""
587
476
  from .connector import CAPTURES, MANIFEST, capture, pairs_of, parse_spec
588
477
 
589
478
  spec_text = request.get("spec")
@@ -624,12 +513,7 @@ def _capture(request: dict) -> dict:
624
513
 
625
514
 
626
515
  def _redact_summary(spec: "Spec | RedactPolicy") -> dict:
627
- """The ``[redact]`` table as describe reports it, so a caller can compute a
628
- stored form from these lists without running Python. ``slug`` is the SALT —
629
- the connector's slug from connector.toml (``[environment].name`` for a tools-only
630
- world's gateway-env.toml), which is what ``_digest`` hashes under — and not the
631
- platform world slug, which may differ (``spycloud`` vs ``spycloud-world``); a caller
632
- that salts with the wrong one never matches a row."""
516
+ """``slug`` is the salt ``_digest`` hashes under: the connector's slug, not the platform world slug."""
633
517
  return {
634
518
  "slug": spec.slug,
635
519
  "hash": sorted(spec.hash_fields),
@@ -640,9 +524,6 @@ def _redact_summary(spec: "Spec | RedactPolicy") -> dict:
640
524
 
641
525
 
642
526
  def _annotate_redaction(entities: list[dict], spec: "Spec | RedactPolicy | None") -> None:
643
- """Stamp every field with the policy it is stored under (``hash``, ``drop``,
644
- ``preserve``, ``round:<n>`` or None), so a reader knows whether it can be looked
645
- up by plaintext, by digest, or not at all."""
646
527
  from .connector import redaction_of
647
528
 
648
529
  for entity in entities:
@@ -651,9 +532,7 @@ def _annotate_redaction(entities: list[dict], spec: "Spec | RedactPolicy | None"
651
532
 
652
533
 
653
534
  def _template_summary(files: dict[str, bytes]) -> dict:
654
- """What a workspace connector is, read from its files: the vendor connection
655
- (connector.toml) and the data model (world.json), plus the digest the platform
656
- pins worlds to. Never runs the template's Python."""
535
+ """Never runs the template's Python."""
657
536
  from .connector import bind_spec, parse_spec
658
537
  from .redaction import parse_env_policy
659
538
  from .scaffold import template_digest
@@ -735,14 +614,7 @@ DESCRIBE_PATHS = (
735
614
 
736
615
 
737
616
  def _describe(request: dict) -> dict:
738
- """One description for the connector page and a world's Schema tab: the data
739
- model, the tools with their schemas, and — when the connector declares a vendor
740
- connection — the OpenAPI document the served world answers to.
741
-
742
- The connector is compiled exactly as a world build compiles it (an installed
743
- template by slug, or a template's files), so the page shows what a world gets;
744
- a compiled world's own files (``schema/world.json`` + ``tool-schemas.json``) pass
745
- straight through. Never runs the connector's Python."""
617
+ """Never runs the connector's Python."""
746
618
  from .connector import load_spec, parse_spec
747
619
  from .redaction import env_policy
748
620
  from .scaffold import (
@@ -838,18 +710,7 @@ def _describe(request: dict) -> dict:
838
710
 
839
711
 
840
712
  def _ingest_calls(request: dict) -> dict:
841
- """``ingest-calls``: records into a world the platform holds as files — the twin
842
- of ``import-data`` for the record contract of :mod:`.ingest`. The tree arrives
843
- as ``[{path, content}]``, the records as a list, with ``redact`` (off by
844
- default), ``dry_run``, ``mode`` and optionally ``map`` — an ``ingest.toml``
845
- text or its parsed table (:mod:`.mapping`). Without ``map`` the world's own
846
- ``ingest.toml`` applies when it has one, else each record's tool resolves to
847
- an operation of ``connector.toml`` and its result is projected the way a
848
- capture is (:func:`ingest.ingest_records`). Transforms never run here: they
849
- are the agent's code and run where the agent is. The answer is the report
850
- plus the projected ``rows`` (``{entity: [row, …]}``, so a caller can push
851
- them through the batch lane itself) and, when the tree changed, every file
852
- of the updated tree the way ``import-data`` returns one."""
713
+ """Transforms never run here: they are the caller's code and run where the caller is."""
853
714
  from .data import KIND_SCHEMA, MODES
854
715
  from .ingest import ingest_records
855
716
  from .redaction import parse_mode
@@ -892,7 +753,6 @@ def _ingest_calls(request: dict) -> dict:
892
753
 
893
754
 
894
755
  def _workdir(request: dict) -> Path:
895
- """The absolute directory the caller prepared; every path in the request is under it."""
896
756
  workdir = request.get("workdir")
897
757
  if not isinstance(workdir, str) or not workdir or not Path(workdir).is_absolute() or not Path(workdir).is_dir():
898
758
  fail(
@@ -940,8 +800,6 @@ def _chunk_specs(workdir: Path, request: dict) -> list:
940
800
 
941
801
 
942
802
  def _tree(root: Path) -> list:
943
- """Every file under ``root`` as ``[{path, content}]``, the encoding ``init-template``
944
- returns, so the platform commits a version without knowing which file changed."""
945
803
  return [
946
804
  {
947
805
  "path": path.relative_to(root).as_posix(),
@@ -953,8 +811,7 @@ def _tree(root: Path) -> list:
953
811
 
954
812
 
955
813
  def _write_tree(workdir: Path, request: dict) -> Path:
956
- """The world tree from ``files``, written under ``workdir/tree`` and compiled (the
957
- contract alone is enough: generated artifacts are regenerated, snapshots are not)."""
814
+ """Compiled from the contract alone: generated artifacts are regenerated, snapshots are not."""
958
815
  from .compiler import compile_bundle
959
816
 
960
817
  root = workdir / "tree"
@@ -975,8 +832,6 @@ def _flag(request: dict, name: str, default: bool) -> bool:
975
832
 
976
833
 
977
834
  def _validate_rows(request: dict) -> dict:
978
- """``validate-rows``: shape-only validation of every row in the chunks (type, bounds,
979
- required, unknown property, primary key present); no reference checks."""
980
835
  from .batch import validate_chunks
981
836
  from .compiler import check_bundle
982
837
  from .data import MODES
@@ -990,7 +845,6 @@ def _validate_rows(request: dict) -> dict:
990
845
 
991
846
 
992
847
  def _redactor(root: Path, request: dict):
993
- """The batch's redaction hook from ``request.redact`` (off | apply | refuse)."""
994
848
  from .redaction import parse_mode, require_policy, row_redactor
995
849
 
996
850
  redact = parse_mode(request.get("redact"))
@@ -998,11 +852,6 @@ def _redactor(root: Path, request: dict):
998
852
 
999
853
 
1000
854
  def _snapshot_build(request: dict) -> dict:
1001
- """``snapshot-build``: the parent snapshot (or the tree's default), carried to the
1002
- tree's contract when that only adds to the domain its rows were stored under, with
1003
- the chunks applied in dependency order, one transaction (atomic) or one per chunk;
1004
- the new snapshot saved under workdir with its sidecar (its absolute path answered),
1005
- or nothing on dryRun or an atomic refusal."""
1006
855
  from .batch import build_batch
1007
856
  from .compiler import check_bundle
1008
857
  from .data import MERGES, MODES
@@ -1061,8 +910,6 @@ def _snapshot_build(request: dict) -> dict:
1061
910
 
1062
911
 
1063
912
  def _snapshot_default(request: dict) -> dict:
1064
- """``snapshot-default``: the tree's default snapshot and every scenario snapshot,
1065
- built under ``workdir/tree``; the sidecars come back with absolute paths."""
1066
913
  from .compiler import check_bundle
1067
914
  from .snapshot import build_all, build_default, default_snapshot, scenario_snapshot
1068
915
 
@@ -1084,8 +931,6 @@ def _snapshot_default(request: dict) -> dict:
1084
931
 
1085
932
 
1086
933
  def _api_bundle(request: dict) -> dict:
1087
- """The api-kind bundle that hosts a world's API, built from the world's files:
1088
- what `gateway worlds schema api-bundle` writes locally, for a CLI with no Python."""
1089
934
  from .api import build_api_bundle
1090
935
 
1091
936
  files = request_files(request)
@@ -1102,9 +947,7 @@ def _api_bundle(request: dict) -> dict:
1102
947
 
1103
948
 
1104
949
  def _ingest(request: dict) -> dict:
1105
- """``ingest``: the world's authored tree, its ``captures/`` and manifest included,
1106
- seeded from those captures through the contract exactly as the CLI does, and the
1107
- whole updated tree handed back. Runs no Python of the world's own."""
950
+ """Runs no Python of the world's own."""
1108
951
  from .connector import check, ingest
1109
952
 
1110
953
  batch_id = request.get("batch_id")
@@ -1124,9 +967,6 @@ def _ingest(request: dict) -> dict:
1124
967
 
1125
968
 
1126
969
  def _reconcile(request: dict) -> dict:
1127
- """``reconcile``: the world's contract against its captured rows (see
1128
- :mod:`reconcile`); the report of every change, and with ``write`` the updated
1129
- tree (``schema/world.json`` rewritten and recompiled)."""
1130
970
  from .reconcile import SOURCES, reconcile
1131
971
 
1132
972
  source = request.get("from", "captures")
@@ -1148,9 +988,7 @@ def _reconcile(request: dict) -> dict:
1148
988
 
1149
989
 
1150
990
  def _conform(request: dict) -> dict:
1151
- """``conform``: serve the world in the bridge and check every operation's answer
1152
- against the vendor's OpenAPI documents. The report is the one ``connector conform
1153
- --out`` writes; ``world`` names the bundle, never the bridge's scratch path."""
991
+ """``world`` names the bundle, never the bridge's scratch path."""
1154
992
  from .conform import conform
1155
993
 
1156
994
  documents = request.get("openapi")
@@ -1175,10 +1013,6 @@ def _conform(request: dict) -> dict:
1175
1013
 
1176
1014
 
1177
1015
  def _run_tests(request: dict) -> dict:
1178
- """``run-tests``: serve the world at these files in the bridge and run the tests it
1179
- ships under ``tests/`` (see :mod:`world_tests`). ``scenario`` starts the world in one
1180
- of its scenarios; ``snapshot`` ({url, sha256, digest}) lays a pinned data snapshot
1181
- into the tree first, so a data-only version is tested with its rows."""
1182
1016
  from .snapshot import fetch as fetch_snapshot
1183
1017
  from .world_tests import run
1184
1018
 
@@ -1200,10 +1034,7 @@ def _run_tests(request: dict) -> dict:
1200
1034
 
1201
1035
 
1202
1036
  def _prepared_tree(request: dict) -> Path:
1203
- """The tree the platform laid under a ``workdir`` it created — ``tree``, a
1204
- relative path under it, beside any snapshot it checked out — opened in place.
1205
- Every path is validated against the workdir (:func:`_under`); the workdir is
1206
- the caller's to remove."""
1037
+ """The workdir is the caller's to remove; Python never deletes it."""
1207
1038
  if request.get("files") is not None or request.get("world") is not None:
1208
1039
  fail("input", "a request opens its world through one of workdir, files or world")
1209
1040
  workdir = _workdir(request)
@@ -1214,34 +1045,26 @@ def _prepared_tree(request: dict) -> Path:
1214
1045
 
1215
1046
 
1216
1047
  def _world_for(request: dict, staging: Path) -> Path:
1217
- """The world a run-style command works on: ``files`` laid into ``staging``
1218
- (what the platform sends for a small tree), the tree under a ``workdir`` the
1219
- platform prepared (:func:`_prepared_tree`, for a large one), or — where this
1220
- runtime may run authored code — ``world``, an absolute directory on this
1221
- machine, opened in place so its ``[dependencies]`` paths resolve and nothing
1222
- is copied."""
1223
1048
  if request.get("workdir") is not None:
1224
1049
  return _prepared_tree(request)
1225
- world = request.get("world")
1226
- if world is None:
1050
+ if request.get("world") is None:
1227
1051
  root = staging / "world"
1228
1052
  root.mkdir()
1229
1053
  _write_files(root, request.get("files"))
1230
1054
  return world_root(root)
1055
+ return world_root(_local_tree(request))
1056
+
1057
+
1058
+ def _local_tree(request: dict) -> Path:
1059
+ world = request.get("world")
1231
1060
  if not may_execute():
1232
1061
  fail("input", "world is a local-runtime field; this runtime takes files")
1233
1062
  if not isinstance(world, str) or not Path(world).is_absolute() or not Path(world).is_dir():
1234
1063
  fail("input", "world must be an absolute path to a directory on this machine")
1235
- return world_root(Path(world).resolve())
1064
+ return Path(world).resolve()
1236
1065
 
1237
1066
 
1238
1067
  def _call(request: dict) -> dict:
1239
- """``call``: open the world at ``world`` (a local directory; ``files`` for a
1240
- tree without dependencies) as one session and call ``tool`` with ``args``,
1241
- the way the host would — root tools by name, a dependency's as
1242
- ``alias.tool``. The answer is the tool's ``{status, body}``, the state
1243
- afterwards when ``state`` is asked for, and the grade when ``grade`` is.
1244
- Only where this runtime may run a world's Python (:func:`may_execute`)."""
1245
1068
  from .local import open_world
1246
1069
 
1247
1070
  if not may_execute():
@@ -1280,15 +1103,6 @@ def _call(request: dict) -> dict:
1280
1103
 
1281
1104
 
1282
1105
  def _dry_run(request: dict) -> dict:
1283
- """``dry-run``: open the world at ``world`` under ``task`` exactly as a
1284
- hosted session would (the task's seed laid, its tools served), grade the
1285
- UNTOUCHED state with the task's verifiers, and close. The answer is the
1286
- task card (prompt, tools, verifiers), the state's rows per entity, and
1287
- ``grade`` — or, when a verifier cannot run (bad SQL, a missing entity),
1288
- ``grade: null`` and ``verifier_errors`` naming each verifier that failed
1289
- with the database engine's own words. That is the point of the dry run: a benchmark
1290
- whose grader dies is found here, not on the runner. Only where this
1291
- runtime may run a world's Python (:func:`may_execute`)."""
1292
1106
  from ..errors import VerifierError
1293
1107
  from .local import open_world
1294
1108
 
@@ -1346,9 +1160,7 @@ def _dry_run(request: dict) -> dict:
1346
1160
 
1347
1161
 
1348
1162
  def _templates(request: dict) -> dict:
1349
- """``templates``: every installed connector template, read from its ``world.json``
1350
- (name and description when the document carries them) and whether it declares a
1351
- vendor connection. Never runs a template's Python."""
1163
+ """Never runs a template's Python."""
1352
1164
  from .scaffold import TEMPLATES, list_templates
1353
1165
  from .ui import ui_kind
1354
1166
 
@@ -1373,7 +1185,6 @@ def _templates(request: dict) -> dict:
1373
1185
 
1374
1186
 
1375
1187
  def _answering_commands() -> dict:
1376
- """The commands that answer on their own, without the shared write-validate-return tree below."""
1377
1188
  return {
1378
1189
  "validate-rows": _validate_rows,
1379
1190
  "snapshot-build": _snapshot_build,
@@ -1402,10 +1213,7 @@ def _answering_commands() -> dict:
1402
1213
 
1403
1214
  def execute(request: dict) -> dict:
1404
1215
  if not isinstance(request, dict) or request.get("command") not in COMMANDS:
1405
- fail(
1406
- "command",
1407
- "Expected one of " + ", ".join(COMMANDS[:-1]) + " or " + COMMANDS[-1],
1408
- )
1216
+ fail("command", "Expected one of " + ", ".join(COMMANDS[:-1]) + " or " + COMMANDS[-1])
1409
1217
  handler = _answering_commands().get(request["command"])
1410
1218
  if handler is not None:
1411
1219
  return handler(request)
@@ -1418,33 +1226,20 @@ def execute(request: dict) -> dict:
1418
1226
  root = world_root(root)
1419
1227
  if bundle_mode(root) is None:
1420
1228
  return {"status": "ok", "mode": "legacy"}
1421
- if request["command"] == "validate" and request.get("world") is not None:
1422
- # Checked in place, so the ``[dependencies]`` paths beside it resolve.
1423
- root = _world_for(request, Path(directory))
1424
- elif request["command"] in (
1425
- "validate",
1426
- "compile",
1427
- "apply-batch",
1428
- "refresh-slack",
1429
- ):
1229
+ in_place = request["command"] in ("validate", "compile") and request.get("world") is not None
1230
+ if in_place:
1231
+ # In place, so the ``[dependencies]`` paths beside it resolve and its snapshots are compiled where they are.
1232
+ root = _local_tree(request)
1233
+ elif request["command"] in ("validate", "compile", "refresh-slack"):
1430
1234
  _write_files(root, request.get("files"))
1431
- # A schema world's api bundle keeps the world under server/world; the whole tree still travels back.
1432
1235
  world = world_root(root)
1433
1236
  if request["command"] == "compile":
1434
- # The agent authors schema/world.json; the trusted compiler owns every generated artifact.
1237
+ # The caller authors schema/world.json; the trusted compiler owns every generated artifact.
1435
1238
  extra["compile"] = compile_world(world)
1436
1239
  if world != root and (world / "data/initial.json").is_file():
1437
1240
  from .api import write_base_seed
1438
1241
 
1439
1242
  write_base_seed(world, root)
1440
- if request["command"] == "apply-batch":
1441
- batch, source = request.get("batch"), request.get("source")
1442
- if not isinstance(batch, dict) or (source is not None and not isinstance(source, str)):
1443
- fail(
1444
- "input",
1445
- "Expected a batch object and an optional source prefix string",
1446
- )
1447
- extra["batch"] = append_batch(world, batch, source=source)
1448
1243
  if request["command"] == "init-template":
1449
1244
  from .scaffold import init_bundle
1450
1245
 
@@ -1486,7 +1281,7 @@ def execute(request: dict) -> dict:
1486
1281
  **validate_bundle(world_root(root), execute=_flag(request, "execute", False)),
1487
1282
  **extra,
1488
1283
  }
1489
- if request["command"] not in ("validate", "validate-archive"):
1284
+ if request["command"] not in ("validate", "validate-archive") and not in_place:
1490
1285
  paths = [path for path in sorted(root.rglob("*")) if path.is_file()]
1491
1286
  if len(paths) > MAX_FILES:
1492
1287
  fail("size", f"The world tree has {len(paths)} files, over the {MAX_FILES} limit")