@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
@@ -19,7 +19,7 @@ What `open` does and does not do:
19
19
  - The slug goes through the one world slug validator and must be free in the project. A taken
20
20
  slug is a 409 `world_exists`; the sandbox never renames it (pick another slug).
21
21
  - `--from custom` seeds the working tree with exactly what `gateway worlds schema init <slug>`
22
- writes; `--from <template>` with a shipped template (`gateway worlds schema templates`,
22
+ writes; `--from <template>` with an official template (`gateway worlds schema templates`,
23
23
  `GET /api/public/worlds/templates`). An unknown template is a 400 that names the list.
24
24
  - No world, container or version is created at open. `open`/`status` say so:
25
25
  `containerId: null`, `baseVersionId: null`, `baseContentHash: null`, `branch: "main"`,
@@ -5,8 +5,9 @@ is the world's container.
5
5
 
6
6
  | Thing | Where |
7
7
  | --- | --- |
8
- | Connectors, shipped and workspace, with Create world / Clone; New connector | Connectors page `/project/{projectId}/connectors` |
9
- | One connector: Overview (verdict + schema), API (served routes, tools), Worlds (built from it, Cancel/Retry) | `/project/{projectId}/connectors/{slug}` |
8
+ | Public worlds of every organization, then connectors, shipped and workspace, with Create world / Clone; New connector | WorldHub `/project/{projectId}/worldhub` (`/connectors` redirects) |
9
+ | One connector: Overview (verdict + schema), API (served routes, tools), Worlds (built from it, Cancel/Retry), UI | `/project/{projectId}/worldhub/{slug}` |
10
+ | A public world as another organization sees it: Overview (schema of `main`), API, History (code changes only) | `/project/{projectId}/worldhub/worlds/{containerId}` |
10
11
  | A world: tabs Overview, Scenarios, Schema, Results, Evals, History | `/project/{projectId}/world?env={containerId}&tab=<tab>` |
11
12
  | Schema tab: entities, tool schemas, the pin back to the connector, and the Redaction tile (per-field hash / preserve / round / drop, salt = connector slug) | `...&tab=schema` |
12
13
  | Overview: provenance (type, "Created from <connector> <version>", author), then Relationships — Links picture, Uses (pin → resolved version, entity mappings with transform chains), Used by; unresolved pins shown, never omitted | `...&tab=overview` |
@@ -11,16 +11,19 @@ import hashlib
11
11
  from pathlib import Path
12
12
  import shutil
13
13
  import tempfile
14
+ from typing import Mapping
14
15
 
15
16
  from .compiler import Contract, check_bundle
16
- from .scaffold import init_bundle
17
+ from .scaffold import TemplateWorld
18
+ from .template_record import TemplateRecord
17
19
  from .database import WorldDatabase
18
20
  from .validation import encoded, fail, read_json
19
- from ._slack_fidelity import fidelity_report, load_capabilities, slack_template_digest
21
+ from ._slack_fidelity import fidelity_report, load_capabilities
20
22
  from ._slack_scenario import write_scenario
21
23
 
22
24
  FORMAT = "gateway-slack-evidence/1"
23
25
  MAPPING = {"id": "slack-evidence", "version": "1"}
26
+ PUBLISHED_CAPABILITIES = "schema/capabilities.json"
24
27
 
25
28
 
26
29
  def _merge(old, patch):
@@ -657,12 +660,21 @@ def synthetic_slack_evidence() -> dict:
657
660
  }
658
661
 
659
662
 
660
- def build_slack_bundle(destination: str | Path, *, evidence: dict | None = None, name: str | None = None) -> Contract:
661
- """Create a populated executable Slack bundle in a new/empty directory."""
663
+ def build_slack_bundle(
664
+ destination: str | Path,
665
+ *,
666
+ template: Mapping[str, bytes],
667
+ evidence: dict | None = None,
668
+ name: str | None = None,
669
+ ) -> Contract:
670
+ """Create a populated executable Slack bundle in a new/empty directory from the
671
+ official Slack world's files (the world the platform serves for the Slack template)."""
662
672
  evidence = synthetic_slack_evidence() if evidence is None else evidence
663
673
  workspace, principal = _envelope(evidence)
664
674
  destination = Path(destination)
665
- contract = init_bundle(destination, connector="slack", name=name or "slack-world")
675
+ official = TemplateWorld(template, location="/template")
676
+ contract = official.write(destination, name=name or "slack-world")
677
+ capabilities = load_capabilities(official.files, PUBLISHED_CAPABILITIES)
666
678
  try:
667
679
  diagnostics = {}
668
680
  batch = map_slack_evidence(evidence, contract, diagnostics=diagnostics)
@@ -677,22 +689,43 @@ def build_slack_bundle(destination: str | Path, *, evidence: dict | None = None,
677
689
  encoded({"workspace_id": workspace["id"], "user_id": principal["user_id"]})
678
690
  )
679
691
  (destination / "fidelity.json").write_bytes(
680
- encoded(fidelity_report(contract, evidence, batch, diagnostics, mapping=MAPPING))
692
+ encoded(
693
+ fidelity_report(
694
+ contract,
695
+ evidence,
696
+ batch,
697
+ diagnostics,
698
+ mapping=MAPPING,
699
+ capabilities=capabilities,
700
+ template_digest=official.digest,
701
+ )
702
+ )
681
703
  )
682
- (destination / "capabilities.json").write_bytes(encoded(load_capabilities()))
704
+ (destination / "capabilities.json").write_bytes(encoded(capabilities))
683
705
  write_scenario(destination, evidence, batch, entities=contract.entities)
684
706
  (destination / "slack-imports.json").write_bytes(
685
707
  encoded({batch["id"]: hashlib.sha256(encoded(evidence)).hexdigest()})
686
708
  )
687
709
  check_bundle(destination)
710
+ TemplateRecord.of_world(destination, connector=official.record.connector, digest=official.digest).write(
711
+ destination
712
+ )
688
713
  return contract
689
714
  except BaseException:
690
715
  shutil.rmtree(destination)
691
716
  raise
692
717
 
693
718
 
694
- def refresh_slack_bundle(destination: str | Path, evidence: dict | None = None, *, batch_id: str | None = None) -> dict:
719
+ def refresh_slack_bundle(
720
+ destination: str | Path,
721
+ evidence: dict | None = None,
722
+ *,
723
+ template: Mapping[str, bytes],
724
+ batch_id: str | None = None,
725
+ ) -> dict:
695
726
  """Validate then append one refresh batch; preserve original batch and lineage.
727
+ ``template`` is the official Slack world's files: a world built from another template
728
+ version is refused.
696
729
 
697
730
  Call this only on an isolated copy while constructing a new immutable version.
698
731
  The publisher owns expected-parent CAS and immutable version promotion.
@@ -705,7 +738,9 @@ def refresh_slack_bundle(destination: str | Path, evidence: dict | None = None,
705
738
  fail("slack_evidence", "Refresh cannot change the bound workspace or principal", "/evidence/principal")
706
739
  contract = check_bundle(destination)
707
740
  previous_report = read_json(destination / "fidelity.json")
708
- if previous_report.get("template_digest") != slack_template_digest():
741
+ official = TemplateWorld(template, location="/template")
742
+ official.record.verify(official.files, "/template")
743
+ if previous_report.get("template_digest") != official.digest:
709
744
  fail(
710
745
  "slack_template_mismatch",
711
746
  "Refresh requires the original template package; create a new world with the current template",
@@ -747,7 +782,17 @@ def refresh_slack_bundle(destination: str | Path, evidence: dict | None = None,
747
782
  imports[batch_id] = digest
748
783
  (destination / "slack-imports.json").write_bytes(encoded(imports))
749
784
  (destination / "fidelity.json").write_bytes(
750
- encoded(fidelity_report(contract, evidence, batch, diagnostics, mapping=MAPPING))
785
+ encoded(
786
+ fidelity_report(
787
+ contract,
788
+ evidence,
789
+ batch,
790
+ diagnostics,
791
+ mapping=MAPPING,
792
+ capabilities=load_capabilities(official.files, PUBLISHED_CAPABILITIES),
793
+ template_digest=official.digest,
794
+ )
795
+ )
751
796
  )
752
797
  write_scenario(destination, evidence, state, entities=contract.entities)
753
798
  return result
@@ -37,7 +37,7 @@ the **pin** (:class:`SnapshotPin`): the hosted snapshot's ``batchDigest`` (and s
37
37
  fields), which replaces the data files as the default batch. The tree's ``data/*.json``
38
38
  then no longer describes the world's data — only that snapshot does — so a pinned tree
39
39
  is never rebuilt from, nor served from, its data files; the platform hands the file
40
- down (``load_world_to_sandbox``, the pod's ``WORLD_SNAPSHOT_*``). Where the file is not
40
+ down (``gateway worlds sandbox open``, the pod's ``WORLD_SNAPSHOT_*``). Where the file is not
41
41
  handed down (a sandbox), the pin itself proves which domain the hosted rows were stored
42
42
  under, so the contract still compiles and checks.
43
43
 
@@ -66,6 +66,7 @@ from .domain_migration import DomainMigration
66
66
  from .validation import ContractError, canonical, fail, read_json
67
67
 
68
68
  SIDECAR = "state.json"
69
+ SNAPSHOT_OUTPUTS = frozenset({*(engine.snapshot_name for engine in WorldDatabase.engines()), SIDECAR})
69
70
  PIN = "snapshot.json"
70
71
  DEFAULT_DIR = "db"
71
72
  SCENARIOS = "scenarios"
@@ -330,7 +331,7 @@ class SnapshotStore:
330
331
  """How a refusal of a pinned snapshot neither the tree nor this store holds ends."""
331
332
  if self.root is None:
332
333
  return (
333
- ": run the world on the platform (`gateway worlds session open <slug>`, load_world_to_sandbox), "
334
+ ": run the world on the platform (`gateway worlds session open <slug>`, `gateway worlds sandbox open <slug>`), "
334
335
  f"which serves that snapshot, or remove {DEFAULT_DIR}/{PIN} to rebuild from the data files"
335
336
  )
336
337
  return (
@@ -406,9 +407,29 @@ def scenario_dirs(world: str | Path) -> dict[str, Path]:
406
407
  return out
407
408
 
408
409
 
409
- def scenario_seed_files(scenario: Path) -> list[Path]:
410
+ SCENARIO_GRADERS = "checks"
411
+
412
+
413
+ def scenario_seed_dir(scenario: Path) -> Path:
414
+ """Where a scenario's rows live: a directory inside the scenario, neither the scenario itself
415
+ (its built snapshot sits there) nor its graders, so a copy that keeps a scenario's code and
416
+ drops its data can tell the two apart by path."""
410
417
  table = tomllib.loads((scenario / "scenario.toml").read_text(encoding="utf-8"))
411
- seed_dir = scenario / str(table.get("seed") or "seed")
418
+ name = str(table.get("seed") or "seed")
419
+ root = scenario.resolve()
420
+ seed_dir = (scenario / name).resolve()
421
+ inside = seed_dir != root and seed_dir.is_relative_to(root)
422
+ if not inside or seed_dir.is_relative_to(root / SCENARIO_GRADERS):
423
+ fail(
424
+ "scenario",
425
+ f"{scenario.name}/scenario.toml seed {name!r} must name a directory inside the scenario, not the scenario itself or {SCENARIO_GRADERS}/",
426
+ f"/{SCENARIOS}/{scenario.name}",
427
+ )
428
+ return seed_dir
429
+
430
+
431
+ def scenario_seed_files(scenario: Path) -> list[Path]:
432
+ seed_dir = scenario_seed_dir(scenario)
412
433
  return sorted(seed_dir.glob("*.json")) if seed_dir.is_dir() else []
413
434
 
414
435
 
@@ -527,6 +548,11 @@ def verify(snapshot: Path, contract: Contract, remedy: str = REBUILD_REMEDY) ->
527
548
  return sidecar
528
549
 
529
550
 
551
+ def is_snapshot_output(path: str) -> bool:
552
+ """A built snapshot or its sidecar: an output of a tree, never a source. Twin of ``isWorldSnapshotOutput``."""
553
+ return path.rsplit("/", 1)[-1] in SNAPSHOT_OUTPUTS
554
+
555
+
530
556
  def snapshot_name(contract: Contract) -> str:
531
557
  """The file name the contract's engine writes a snapshot to."""
532
558
  return WorldDatabase.for_contract(contract).snapshot_name
@@ -76,12 +76,14 @@ class TaskSpec:
76
76
  def allows_tool(self, tool: str) -> bool:
77
77
  return self.tools is None or tool in self.tools
78
78
 
79
+ def grader_checks(self) -> list[dict]:
80
+ return list(self.grader["checks"]) if self.grader is not None and self.grader["kind"] == "assertions" else []
81
+
79
82
  def entities(self) -> list[str]:
80
83
  named: list[str] = []
81
84
  if self.seed is not None:
82
85
  named.extend(self.seed["rows"])
83
- if self.grader is not None and self.grader["kind"] == "assertions":
84
- named.extend(check["entity"] for check in self.grader["checks"])
86
+ named.extend(check["entity"] for check in self.grader_checks())
85
87
  # A session task is named for its alias: only checks under it name this world's entities.
86
88
  own = f"{self.name}."
87
89
  for verifier in self.verifiers:
@@ -96,6 +98,27 @@ JOURNAL = "gateway_requests"
96
98
  JOURNAL_META = "gateway_journal"
97
99
  RESERVED_STATE_KEYS = frozenset({CALL_LOG, "snapshot", JOURNAL})
98
100
  DOOR_FIELD = "via"
101
+ PAGE_DOOR = "page"
102
+ PAGE_SERVED = "ui.served"
103
+ PAGE_RECORDING = "ui.recording"
104
+ PAGE_UNRECORDED_LIFE = "ui.unrecorded"
105
+ PAGE_NOTES = frozenset({PAGE_SERVED, PAGE_RECORDING, PAGE_UNRECORDED_LIFE})
106
+ PAGE_UNJOURNALED = (
107
+ "a check on the page's interactions is decided from the session's journal, which shows whether its pages "
108
+ "were recorded; this grade has none (a cross-world check, or a grade off the platform): ungraded"
109
+ )
110
+ PAGE_UNRECORDED = (
111
+ "no World Host noted that it recorded every part of this session's pages (a host from before the page "
112
+ "recorder served some of them), so a check on the page's interactions cannot be decided: ungraded"
113
+ )
114
+ PAGE_UNHEARD = (
115
+ "the session served its ui's pages but no page reported an interaction (a page that never ran the "
116
+ "recorder), so a check on the page's interactions cannot be decided: ungraded"
117
+ )
118
+ PAGE_GAP = (
119
+ "the page numbered {missing} interactions it never reported (a report lost on the way), so a check "
120
+ "on the page's interactions cannot be decided: ungraded"
121
+ )
99
122
  WITHHELD_FIELD = "withheld"
100
123
  ROW_FIELDS = ("found", "rows")
101
124
  ORDER_KEYS = ("before", "after")
@@ -0,0 +1,131 @@
1
+ """``schema/template.json``: the template a world was built from, the template's digest, the compiler outputs the
2
+ build produced, and the sha256 of every other file the built world holds. A reader trusts the digest only while the
3
+ world still holds exactly those files (twin: ``TemplateRecord`` in gateway/packages/shared/src/world/templateRecord.ts;
4
+ the outputs a record may name are pinned by conformance/template-record.json)."""
5
+
6
+ from __future__ import annotations
7
+
8
+ import hashlib
9
+ import json
10
+ from dataclasses import dataclass
11
+ from pathlib import Path, PurePosixPath
12
+ from typing import Any, Mapping
13
+
14
+ from ..world import WorldTree
15
+ from .compiler import GENERATED, LOCK
16
+ from .snapshot import is_snapshot_output
17
+ from .ui import GENERATED_FILES, is_generated, read_ui_declaration
18
+ from .validation import fail, tree_path
19
+
20
+ RECORD = "schema/template.json"
21
+ COMPILED_OUTPUTS = (*GENERATED, LOCK)
22
+ _SHA256 = frozenset("0123456789abcdef")
23
+
24
+
25
+ def is_template_output(path: str) -> bool:
26
+ return path in COMPILED_OUTPUTS or PurePosixPath(path).name in GENERATED_FILES
27
+
28
+
29
+ @dataclass(frozen=True)
30
+ class TemplateRecord:
31
+ connector: str
32
+ digest: str
33
+ outputs: tuple[str, ...]
34
+ sources: Mapping[str, str]
35
+
36
+ @classmethod
37
+ def of_world(cls, root: Path, *, connector: str, digest: str) -> "TemplateRecord":
38
+ outputs = tuple(sorted(_compiled_outputs(root)))
39
+ sources = {
40
+ path: hashlib.sha256((root / path).read_bytes()).hexdigest()
41
+ for path in WorldTree.from_dir(root).hashed_paths()
42
+ if _covered(path, outputs)
43
+ }
44
+ return cls(connector, digest, outputs, sources)
45
+
46
+ @classmethod
47
+ def parse(cls, files: Mapping[str, bytes], location: str) -> "TemplateRecord":
48
+ where = f"{location}/{RECORD}"
49
+ try:
50
+ raw = json.loads(files[RECORD].decode("utf-8")) if RECORD in files else None
51
+ except (UnicodeDecodeError, ValueError):
52
+ raw = None
53
+ if not isinstance(raw, dict):
54
+ fail("template", f"The world carries no readable {RECORD}", where)
55
+ return cls(
56
+ _text(raw.get("connector"), "connector", where),
57
+ _sha256(raw.get("digest"), "digest", where),
58
+ _outputs(raw.get("outputs"), where),
59
+ _sources(raw.get("sources"), where),
60
+ )
61
+
62
+ def verify(self, files: Mapping[str, bytes], location: str) -> None:
63
+ """Refuse a world that no longer holds, byte for byte, every file it was built with: an edit in place."""
64
+ held = {path for path in files if _covered(path, self.outputs)}
65
+ changed = sorted(
66
+ path
67
+ for path in held | set(self.sources)
68
+ if path not in held
69
+ or path not in self.sources
70
+ or hashlib.sha256(files[path]).hexdigest() != self.sources[path]
71
+ )
72
+ if changed:
73
+ fail(
74
+ "template",
75
+ f"The world no longer holds the files it was built with from its template ({', '.join(changed[:5])}); "
76
+ "rebuild it from its template",
77
+ location,
78
+ )
79
+
80
+ def write(self, root: Path) -> None:
81
+ document = {
82
+ "connector": self.connector,
83
+ "digest": self.digest,
84
+ "outputs": list(self.outputs),
85
+ "sources": dict(sorted(self.sources.items())),
86
+ }
87
+ (root / RECORD).write_bytes((json.dumps(document, indent=2) + "\n").encode("utf-8"))
88
+
89
+
90
+ def _covered(path: str, outputs: tuple[str, ...]) -> bool:
91
+ return path != RECORD and path not in outputs and not is_snapshot_output(path)
92
+
93
+
94
+ def _compiled_outputs(root: Path) -> list[str]:
95
+ outputs = [path for path in COMPILED_OUTPUTS if (root / path).is_file()]
96
+ ui = read_ui_declaration(root)
97
+ static = PurePosixPath(ui.static).as_posix() if ui is not None else None
98
+ if static is None or ui.generated is not True or not is_generated(root / static / "index.html"):
99
+ return outputs
100
+ return [*outputs, *(f"{static}/{name}" for name in GENERATED_FILES if (root / static / name).is_file())]
101
+
102
+
103
+ def _text(value: Any, field: str, where: str) -> str:
104
+ if not isinstance(value, str) or not value:
105
+ fail("template", f"{RECORD} names no {field}", where)
106
+ return value
107
+
108
+
109
+ def _sha256(value: Any, field: str, where: str) -> str:
110
+ if not isinstance(value, str) or len(value) != 64 or not set(value) <= _SHA256:
111
+ fail("template", f"{RECORD} {field} is not a sha256 hex digest", where)
112
+ return value
113
+
114
+
115
+ def _outputs(value: Any, where: str) -> tuple[str, ...]:
116
+ if not isinstance(value, list) or not all(isinstance(path, str) for path in value):
117
+ fail("template", f"{RECORD} names no outputs list", where)
118
+ for path in value:
119
+ tree_path(path, where)
120
+ if not is_template_output(path):
121
+ fail("template", f"{RECORD} names {path} as an output; only compiler outputs are", where)
122
+ return tuple(value)
123
+
124
+
125
+ def _sources(value: Any, where: str) -> dict[str, str]:
126
+ if not isinstance(value, dict) or not value:
127
+ fail("template", f"{RECORD} names no source files", where)
128
+ for path, digest in value.items():
129
+ tree_path(path, where)
130
+ _sha256(digest, f"source {path}", where)
131
+ return dict(value)
@@ -208,7 +208,7 @@ def _scenario_task(name: str, scenario: Path) -> ToolsTask:
208
208
  table = tomllib.loads((scenario / "scenario.toml").read_text(encoding="utf-8"))
209
209
  instruction = scenario / "instruction.md"
210
210
  prompt = instruction.read_text(encoding="utf-8") if instruction.is_file() else str(table.get("instruction") or "")
211
- verify = scenario / "checks" / "verify.py"
211
+ verify = scenario / snapshots.SCENARIO_GRADERS / "verify.py"
212
212
  return ToolsTask(
213
213
  id=name,
214
214
  prompt=prompt.strip() or f"Drive the world into the state the scenario '{name}' checks.",
@@ -262,8 +262,8 @@ def load_tasks(bundle: Path, manifest: _bundle.EnvManifest, verifiers: list[str]
262
262
  def load_tools_version(
263
263
  bundle: Path,
264
264
  template: Path,
265
- snapshot: dict[str, str] | None,
266
265
  *,
266
+ fetched: bool,
267
267
  run_handlers: bool,
268
268
  ) -> ToolsVersion:
269
269
  if not is_tools_bundle(bundle):
@@ -278,15 +278,13 @@ def load_tools_version(
278
278
  "`gateway worlds schema init` starts one that does",
279
279
  )
280
280
  contract = check_bundle(bundle)
281
- if snapshot:
282
- snapshots.fetch(bundle, contract, snapshot["url"], snapshot["sha256"], snapshot["digest"])
283
281
  # connector.toml is read as the api runtime reads it, so an unservable route is refused at cache time.
284
282
  spec = settings = None
285
283
  if (bundle / SPEC).is_file():
286
284
  spec = load_spec(bundle)
287
285
  settings = load_api_settings(bundle, spec)
288
286
  read_fields = RouteBindings.served(spec, settings, contract)
289
- proven = ProvenTemplate.prove(bundle, template, contract, fetched=bool(snapshot), read_fields=read_fields)
287
+ proven = ProvenTemplate.prove(bundle, template, contract, fetched=fetched, read_fields=read_fields)
290
288
  verifiers = verifier_names(bundle)
291
289
  if REWARD in verifiers:
292
290
  fail("host", f"verifier name '{REWARD}' is reserved for the scalar grade")
@@ -351,6 +349,7 @@ class ToolsWorld:
351
349
  allowed: frozenset[str] | None = None,
352
350
  dependencies: dict[str, DependencyWorld] | None = None,
353
351
  calls: CallLog | None = None,
352
+ parameters: dict[str, str] | None = None,
354
353
  ) -> None:
355
354
  if version.handlers is None:
356
355
  fail("host", "a mock-tools session runs world-authored handlers; only a version worker opens one")
@@ -361,6 +360,7 @@ class ToolsWorld:
361
360
  self.task = self._task_of(version, task)
362
361
  self.allowed = allowed
363
362
  self.calls = calls
363
+ self.parameters = dict(parameters or {})
364
364
  self.dependencies = dict(dependencies or {})
365
365
  self.served = served_with_dependencies(version, self.dependencies)
366
366
  self._task_seed = seed
@@ -391,6 +391,12 @@ class ToolsWorld:
391
391
 
392
392
  @staticmethod
393
393
  def _open_world(version: ToolsVersion, directory: Path) -> World:
394
+ world = ToolsWorld._new_world(version, directory)
395
+ world.serve_webhooks(version.spec.webhooks if version.spec is not None else None)
396
+ return world
397
+
398
+ @staticmethod
399
+ def _new_world(version: ToolsVersion, directory: Path) -> World:
394
400
  host = _EnvHost(version, directory)
395
401
  # _EnvHost is what a World reads of an Environment.
396
402
  return World(host, world_id=SESSION_WORLD, template=version.template) # type: ignore[arg-type]
@@ -423,6 +429,8 @@ class ToolsWorld:
423
429
  scenario_id = str(self.task.metadata.get("scenario_id") or self.task.id)
424
430
  for world in (self.world, *self.worlds.values()):
425
431
  world.set_task_context(scenario_id)
432
+ if self.parameters:
433
+ self.world.set_run_parameters(self.parameters)
426
434
  self._attach()
427
435
 
428
436
  def _attach(self) -> None:
@@ -463,6 +471,7 @@ class ToolsWorld:
463
471
  status, body = self._run(world, local, args)
464
472
  finally:
465
473
  self._log(tool, args, status, body, time.monotonic() - started)
474
+ self._log_webhooks(world)
466
475
  return {"status": status, "body": body}
467
476
 
468
477
  def _admitted(self, tool: str) -> tuple[World, str]:
@@ -487,6 +496,11 @@ class ToolsWorld:
487
496
  if self.calls is not None:
488
497
  self.calls.record_tool(tool, args, status, body, elapsed_s)
489
498
 
499
+ def _log_webhooks(self, world: World) -> None:
500
+ delivered = world.webhooks.take()
501
+ if self.calls is not None:
502
+ self.calls.record_webhooks(delivered)
503
+
490
504
  def grade(self, journal: WorldJournal | None = None) -> dict:
491
505
  """``reward`` is null when no verifier answered a number, never 0; a dependency's verifier that reads the
492
506
  journal fails closed, as the journal is the root world's."""
@@ -639,6 +653,13 @@ class ToolsWorldState(WorldState):
639
653
  def store(self, value) -> None: # WorldState.close assigns None; the world owns it.
640
654
  return None
641
655
 
656
+ @property
657
+ def webhooks(self): # type: ignore[override]
658
+ return self._tools.world.webhooks
659
+
660
+ def serve_webhooks(self, webhooks) -> None:
661
+ return None
662
+
642
663
  def reset(self, *, initial: bool = True) -> None:
643
664
  self._tools.reset()
644
665
  self._clear_events()
@@ -40,6 +40,7 @@ STATIC_SOURCE = Path(__file__).with_name("ui_static")
40
40
  #: overwrites an index.html only when it carries it.
41
41
  GENERATED_MARK = "<!-- gateway-world-ui: generated -->"
42
42
  DEFAULT_ENTRY = "/"
43
+ UI_RESERVED = "/__world-ui"
43
44
  GENERATED_FILES = ("index.html", "app.js", "contract.json")
44
45
  #: What ``ui init`` adds to a connector.toml that declares no ui.
45
46
  UI_SECTION = """
@@ -54,6 +55,17 @@ generated = true
54
55
  """
55
56
 
56
57
 
58
+ def checked_api_path(api_path: Any) -> str:
59
+ """``[ui] api_path`` as both readers of ``[ui]`` keep it: a same-origin prefix, never the
60
+ root and never under :data:`UI_RESERVED`."""
61
+ if not isinstance(api_path, str) or not api_path.startswith("/") or api_path == "/":
62
+ fail("spec", "ui.api_path is the same-origin prefix the ui calls the api at", "/ui/api_path")
63
+ kept = api_path.rstrip("/")
64
+ if kept == UI_RESERVED or kept.startswith(f"{UI_RESERVED}/"):
65
+ fail("spec", f"ui.api_path is under {UI_RESERVED}, the prefix the ui origin keeps for itself", "/ui/api_path")
66
+ return kept
67
+
68
+
57
69
  @dataclass(frozen=True)
58
70
  class UiDeclaration:
59
71
  static: str
@@ -72,6 +84,44 @@ class UiDeclaration:
72
84
  contract at compile time). What the connector pages badge and label."""
73
85
  return "product" if self.generated is False else "generated"
74
86
 
87
+ @staticmethod
88
+ def kind_of(spec: bytes | None) -> str:
89
+ """The ui a connector.toml's bytes declare, as the connector pages show it:
90
+ ``product``, ``generated``, or ``none`` without the file or its ``[ui]``."""
91
+ declaration = UiDeclaration.parse(spec) if spec is not None else None
92
+ return declaration.kind if declaration is not None else "none"
93
+
94
+ @staticmethod
95
+ def parse(spec: bytes) -> UiDeclaration | None:
96
+ """``[ui]`` of a connector.toml, or None when it declares none. Read
97
+ without the api runtime's index.html check, which is what compile is
98
+ about to satisfy."""
99
+ try:
100
+ raw = tomllib.loads(spec.decode("utf-8"))
101
+ except ValueError as error:
102
+ fail("spec", f"Cannot parse connector.toml: {error}", "/connector.toml")
103
+ ui = raw.get("ui")
104
+ if ui is None:
105
+ return None
106
+ if not isinstance(ui, dict):
107
+ fail("spec", "[ui] must be a table", "/ui")
108
+ # No default here: api.py (the runtime that answers `[ui] api_path` requests)
109
+ # fails hard on a missing `static`, so this reader agrees rather than quietly
110
+ # picking a directory the api side would never have looked in.
111
+ static = ui.get("static")
112
+ if not isinstance(static, str) or not static or static.startswith("/") or ".." in static.split("/"):
113
+ fail("spec", "ui.static is a directory inside the world holding the ui", "/ui/static")
114
+ entry = ui.get("entry", DEFAULT_ENTRY)
115
+ # `//host` and `/\host` are paths only in form: a browser resolves them to
116
+ # another origin, which would carry the session token off the ui's own.
117
+ if not isinstance(entry, str) or not entry.startswith("/") or entry.startswith("//") or "\\" in entry:
118
+ fail("spec", "ui.entry is the path the agent lands on, starting with / on the ui's own origin", "/ui/entry")
119
+ api_path = checked_api_path(ui.get("api_path", "/__world-api"))
120
+ generated = ui.get("generated")
121
+ if generated is not None and not isinstance(generated, bool):
122
+ fail("spec", "ui.generated is true (compile writes the ui) or false (hand-written)", "/ui/generated")
123
+ return UiDeclaration(static=static.rstrip("/"), entry=entry, api_path=api_path, generated=generated)
124
+
75
125
 
76
126
  def ui_kind(world: Path) -> str:
77
127
  """The world's ui as the connector pages show it: ``product``,
@@ -82,38 +132,15 @@ def ui_kind(world: Path) -> str:
82
132
 
83
133
  def read_ui_declaration(world: Path) -> UiDeclaration | None:
84
134
  """``[ui]`` of the world's connector.toml, or None when the world declares
85
- none (no connector.toml, or no section). Read here without the api
86
- runtime's index.html check, which is what compile is about to satisfy."""
135
+ none (no connector.toml, or no section)."""
87
136
  path = world / "connector.toml"
88
137
  if not path.is_file():
89
138
  return None
90
139
  try:
91
- raw = tomllib.loads(path.read_text(encoding="utf-8"))
92
- except (OSError, ValueError) as error:
140
+ spec = path.read_bytes()
141
+ except OSError as error:
93
142
  fail("spec", f"Cannot parse connector.toml: {error}", "/connector.toml")
94
- ui = raw.get("ui")
95
- if ui is None:
96
- return None
97
- if not isinstance(ui, dict):
98
- fail("spec", "[ui] must be a table", "/ui")
99
- # No default here: api.py (the runtime that answers `[ui] api_path` requests)
100
- # fails hard on a missing `static`, so this reader agrees rather than quietly
101
- # picking a directory the api side would never have looked in.
102
- static = ui.get("static")
103
- if not isinstance(static, str) or not static or static.startswith("/") or ".." in static.split("/"):
104
- fail("spec", "ui.static is a directory inside the world holding the ui", "/ui/static")
105
- entry = ui.get("entry", DEFAULT_ENTRY)
106
- # `//host` and `/\host` are paths only in form: a browser resolves them to
107
- # another origin, which would carry the session token off the ui's own.
108
- if not isinstance(entry, str) or not entry.startswith("/") or entry.startswith("//") or "\\" in entry:
109
- fail("spec", "ui.entry is the path the agent lands on, starting with / on the ui's own origin", "/ui/entry")
110
- api_path = ui.get("api_path", "/__world-api")
111
- if not isinstance(api_path, str) or not api_path.startswith("/") or api_path == "/":
112
- fail("spec", "ui.api_path is the same-origin prefix the ui calls the api at", "/ui/api_path")
113
- generated = ui.get("generated")
114
- if generated is not None and not isinstance(generated, bool):
115
- fail("spec", "ui.generated is true (compile writes the ui) or false (hand-written)", "/ui/generated")
116
- return UiDeclaration(static=static.rstrip("/"), entry=entry, api_path=api_path.rstrip("/"), generated=generated)
143
+ return UiDeclaration.parse(spec)
117
144
 
118
145
 
119
146
  def is_generated(index: Path) -> bool:
@@ -187,8 +214,6 @@ def init_ui(world: str | Path) -> dict:
187
214
  if not declared:
188
215
  text = spec_path.read_text(encoding="utf-8")
189
216
  first_route = re.search(r"^\[\[operations\]\]", text, re.M)
190
- # Before the first route so the section reads with the other tables,
191
- # at the end when the file declares no routes yet.
192
217
  text = (
193
218
  text[: first_route.start()] + UI_SECTION.lstrip("\n") + "\n" + text[first_route.start() :]
194
219
  if first_route
@@ -208,10 +233,6 @@ def init_ui(world: str | Path) -> dict:
208
233
  }
209
234
 
210
235
 
211
- # --------------------------------------------------------------------------- #
212
- # contract.json: the world as the page renders it.
213
- # --------------------------------------------------------------------------- #
214
-
215
236
  VERBS = ("list", "get", "create", "update", "delete")
216
237
 
217
238