@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
@@ -1,40 +1,4 @@
1
- """A schema world's tools on the World Host.
2
-
3
- A schema-backed mock-tools bundle (``gateway-env.toml`` with ``[schema]`` at its
4
- root, ``tools/*.py`` handlers, ``verifiers/*.sql``) is reached through the
5
- ``tools`` surface, the platform's ``call``/``grade``/``reset``/``seed``
6
- rendezvous. On the pod engine that rendezvous is a runner sidecar and
7
- ``deploy/benchmark-runner/engines/schema_session.py``; on the host it is this
8
- module, driven by :class:`~gatewaysdk.environment.schema.host.WorldHost`.
9
-
10
- ONE SESSION, BOTH SURFACES. When the tree also carries ``connector.toml`` — the
11
- routes the served vendor API answers — the same session serves its HTTP surface
12
- too: :class:`ToolsWorldState` presents the :class:`ToolsWorld`'s store to the
13
- api runtime's :class:`~gatewaysdk.environment.schema.api.WorldApp`, so a row a
14
- tool writes is the row a route lists, and a route's create is what the SQL
15
- verifiers grade. This is the schema world stored as itself (the supported
16
- shape), not packaged as an api bundle; nothing has to be packaged to get HTTP.
17
-
18
- The session contract is the runner's: ``call`` executes a handler through the
19
- schema contract, ``grade`` runs the task's verifiers, ``reset`` copies the
20
- template back and re-arms the task context, ``seed`` lands rows through the
21
- contract. The handlers are world-authored code, so a tools version always
22
- lives in a version worker; the supervisor only detects the kind.
23
-
24
- DEPENDENCY WORLDS. A world whose manifest declares ``[dependencies]``
25
- (:mod:`dependencies`) opens beside them: one :class:`ToolsWorld` holds the
26
- root world and one isolated store per dependency, each under its alias. A
27
- dependency's tools are served as ``<alias>.<tool>`` (Relay calls
28
- ``slack.post_message`` and ``list_messages`` from one session), its verifiers
29
- grade as ``<alias>/<verifier>``, its rows are reported under
30
- ``worlds.<alias>`` and seeded as ``<alias>.<entity>``. The root's verifiers
31
- read every dependency's store as ``<alias>.<table>`` (attached read-only), so
32
- a cross-world check — the WhatsApp escalation that must land a Slack message —
33
- is one SQL file in the root world. A dependency's ``task`` names the scenario
34
- it starts in (``scenarios/<task>/`` of its tree): the overlay is laid on the
35
- dependency's template at open and again at reset, as ``--scenario`` lays the
36
- root's.
37
- """
1
+ """Twin of deploy/benchmark-runner/engines/schema_session.py: the runner's session contract on the World Host."""
38
2
 
39
3
  from __future__ import annotations
40
4
 
@@ -50,7 +14,7 @@ from typing import Any
50
14
 
51
15
  from .. import _bundle
52
16
  from .._toml import tomllib
53
- from .._world import World
17
+ from .._world import VerifierResult, World
54
18
  from ..errors import VerifierError, WorldStartError
55
19
  from ..world import World as WorldDetector
56
20
  from . import snapshot as snapshots
@@ -64,46 +28,33 @@ from .database import WorldDatabase
64
28
  from .dependencies import Dependency, parse_dependencies
65
29
  from .grading import Grade, world_state
66
30
  from .handler_errors import failure_answer
31
+ from .journal import LINKED_JOURNAL, WorldJournal
32
+ from .route_bindings import RouteBindings
67
33
  from .served_names import ServedNames
68
- from .session_files import ProvenTemplate, SessionExport
34
+ from .session_files import ProvenTemplate, SessionExport, real_dir
69
35
  from .tasks import TaskSpec
70
36
 
71
37
  Handler = Callable[..., Any]
72
38
 
73
- #: The reward key the scalar goes under; a verifier may not claim it.
74
39
  REWARD = "reward"
40
+ SESSION_WORLD = "session"
75
41
 
76
42
 
77
43
  @dataclass(frozen=True)
78
44
  class ToolsTask:
79
- """One task of a mock-tools bundle: the prompt and the checks that grade it.
80
- Mirrors the runner's ``MockTask`` minus the user-simulation fields, which
81
- a session does not run."""
45
+ """Mirrors the runner's ``MockTask`` minus the user-simulation fields, which a session does not run."""
82
46
 
83
47
  id: str
84
48
  prompt: str
85
49
  verifier: str | None = None
86
50
  verifiers: tuple[str, ...] = ()
87
51
  metadata: dict[str, Any] = field(default_factory=dict)
88
- #: Dependency verifiers the task grades with, by alias (``"worlds": {"slack":
89
- #: ["message_posted"]}``). An alias absent here grades with none of its
90
- #: verifiers; ``None`` (a task that names no worlds) grades with all of every
91
- #: dependency's, the way it grades with all of the root's.
92
52
  worlds: dict[str, tuple[str, ...]] | None = None
93
- #: An authored ``scenarios/<id>/`` task: its seed overlay replaces whole
94
- #: entities of the template at open and reset (None: the template alone).
95
53
  scenario: dict[str, list] | None = None
96
- #: The scenario's ``checks/verify.py``, when it grades by one instead of
97
- #: the world's SQL verifiers (the runtime's :class:`TaskGrader` runs it).
98
54
  verify: Path | None = None
99
- #: Whether the world's verifiers grade this task at all. A bundled task's
100
- #: do (all of them when it names none); a session task's never do — it
101
- #: grades by its own grader or is ungraded (the platform's ``no grader``).
102
55
  graded_by_world: bool = True
103
56
 
104
57
  def selected(self, all_verifiers: list[str]) -> list[str]:
105
- """The verifiers this task grades with: its own list, else the
106
- primary one, else every verifier the bundle ships."""
107
58
  if not self.graded_by_world:
108
59
  return []
109
60
  if self.verifiers:
@@ -113,7 +64,6 @@ class ToolsTask:
113
64
  return list(all_verifiers)
114
65
 
115
66
  def selected_of(self, alias: str, all_verifiers: list[str]) -> list[str]:
116
- """The verifiers of dependency ``alias`` this task grades with."""
117
67
  if not self.graded_by_world:
118
68
  return []
119
69
  if self.worlds is None:
@@ -125,12 +75,7 @@ INLINE_TASK_ID = "session"
125
75
 
126
76
 
127
77
  def inline_task(spec: TaskSpec) -> ToolsTask:
128
- """A session task (:mod:`tasks`) as a schema-world task: the spec's
129
- instruction as the prompt. It grades by its own grader (assertions,
130
- python, rubric) the way an api world's session task does, over
131
- :meth:`ToolsWorld.grader_state`; without one it is ungraded — the
132
- bundle's verifiers were written for the bundle's tasks, not this one.
133
- The seed is applied by :class:`ToolsWorld` once the template copy exists."""
78
+ """Never graded by the bundle's verifiers: they were written for the bundle's tasks, not this one."""
134
79
  return ToolsTask(
135
80
  id=spec.name or INLINE_TASK_ID, prompt=spec.instruction, metadata=dict(spec.metadata), graded_by_world=False
136
81
  )
@@ -138,42 +83,28 @@ def inline_task(spec: TaskSpec) -> ToolsTask:
138
83
 
139
84
  @dataclass
140
85
  class ToolsVersion:
141
- """A mock-tools version as the host caches it: the bundle, its tasks and
142
- verifiers, the proven template every session copies, and (in a worker)
143
- the loaded handlers."""
144
-
145
86
  bundle: Path
146
87
  manifest: _bundle.EnvManifest
147
88
  verifiers: list[str]
148
89
  tasks: dict[str, ToolsTask]
149
90
  template: ProvenTemplate
150
91
  engine: type[WorldDatabase]
151
- #: The tools the version serves, by name: the loaded handlers' in a
152
- #: worker, the contract's in the supervisor (which imports no handler but
153
- #: still checks a session task's allow-list against what is served).
92
+ #: The handlers' names in a worker, the contract's in the supervisor, which imports no world-authored code.
154
93
  tool_names: list[str] = field(default_factory=list)
155
94
  handlers: dict[str, Handler] | None = None
156
- #: The HTTP surface, when the tree carries ``connector.toml``: the routes
157
- #: and their served-API settings, and (in a worker) the ``api/handlers.py``
158
- #: module they name. None for a tree with tools only.
159
95
  spec: Spec | None = None
160
96
  settings: ApiSettings | None = None
161
97
  api_handlers: dict[str, Handler] | None = None
162
98
  dependencies: dict[str, Dependency] = field(default_factory=dict)
99
+ read_fields: list[tuple[str, tuple[str, ...]]] = field(default_factory=list)
163
100
 
164
101
  @property
165
102
  def served_names(self) -> list[str]:
166
- """Everything a session task may allow: the declared tools."""
167
103
  return sorted(self.tool_names)
168
104
 
169
105
 
170
106
  @dataclass(frozen=True)
171
107
  class DependencyWorld:
172
- """A dependency as a session opens it: the alias the root's manifest gave
173
- it, its cached version, the tools of it this session serves (the
174
- manifest's ``tools`` allow-list, else every tool the version has), and the
175
- seed overlay of the scenario its ``task`` names (None: its template alone)."""
176
-
177
108
  alias: str
178
109
  version: ToolsVersion
179
110
  tools: tuple[str, ...]
@@ -210,9 +141,6 @@ class DependencyWorld:
210
141
 
211
142
 
212
143
  def served_with_dependencies(version: ToolsVersion, dependencies: dict[str, DependencyWorld]) -> list[str]:
213
- """Every name a session on ``version`` beside ``dependencies`` serves: the
214
- root's tools, and ``<alias>.<tool>`` for each dependency. Refuses a root
215
- tool that reads as a dependency's (``slack.post_message``)."""
216
144
  declared = set(version.dependencies)
217
145
  missing = declared - set(dependencies)
218
146
  if missing:
@@ -231,8 +159,6 @@ def served_with_dependencies(version: ToolsVersion, dependencies: dict[str, Depe
231
159
 
232
160
 
233
161
  def is_tools_bundle(bundle: Path) -> bool:
234
- """The tree runs on the tools engine (a schema or legacy tools world stored
235
- as itself; an api bundle does not)."""
236
162
  return WorldDetector.from_dir(bundle).tools_engine
237
163
 
238
164
 
@@ -279,9 +205,6 @@ def _tasks_from_rows(rows: list) -> list[ToolsTask]:
279
205
 
280
206
 
281
207
  def _scenario_task(name: str, scenario: Path) -> ToolsTask:
282
- """A task from an authored scenario dir (what an api bundle carried and
283
- ``worlds migrate`` keeps): ``instruction.md`` or the toml's ``instruction``
284
- is the prompt, ``seed/*.json`` the overlay, ``checks/verify.py`` the grader."""
285
208
  table = tomllib.loads((scenario / "scenario.toml").read_text(encoding="utf-8"))
286
209
  instruction = scenario / "instruction.md"
287
210
  prompt = instruction.read_text(encoding="utf-8") if instruction.is_file() else str(table.get("instruction") or "")
@@ -296,17 +219,11 @@ def _scenario_task(name: str, scenario: Path) -> ToolsTask:
296
219
 
297
220
 
298
221
  def scenario_tasks(bundle: Path) -> list[ToolsTask]:
299
- """One task per ``scenarios/<name>/scenario.toml`` of the tree."""
300
222
  return [_scenario_task(name, path) for name, path in snapshots.scenario_dirs(bundle).items()]
301
223
 
302
224
 
303
225
  def load_tasks(bundle: Path, manifest: _bundle.EnvManifest, verifiers: list[str]) -> dict[str, ToolsTask]:
304
- """The bundle's tasks, in the runner's precedence: ``[[tasks]]`` in the
305
- manifest, else ``tasks.jsonl`` / ``tasks.json``, else one task per
306
- verifier; plus one per authored ``scenarios/<name>/`` the declared tasks
307
- do not already name. A bundle may have none: a session that carries its
308
- own task, or none (exploratory), still opens, and one that names a
309
- bundled task the world lacks is refused when it opens."""
226
+ """In the runner's precedence, so a bundle opens with the same tasks on the host as on the runner."""
310
227
  declared = manifest.raw.get("tasks")
311
228
  tasks = _tasks_from_rows(declared) if isinstance(declared, list) else []
312
229
  if not tasks:
@@ -349,9 +266,6 @@ def load_tools_version(
349
266
  *,
350
267
  run_handlers: bool,
351
268
  ) -> ToolsVersion:
352
- """Cache a mock-tools version: verify and pin its snapshot, build and prove
353
- the template once (:class:`ProvenTemplate`), read its tasks, and in a
354
- worker import its handlers."""
355
269
  if not is_tools_bundle(bundle):
356
270
  fail("host", f"{bundle} is not a mock-tools bundle (no gateway-env.toml)")
357
271
  manifest = _bundle.parse_manifest(bundle)
@@ -366,7 +280,13 @@ def load_tools_version(
366
280
  contract = check_bundle(bundle)
367
281
  if snapshot:
368
282
  snapshots.fetch(bundle, contract, snapshot["url"], snapshot["sha256"], snapshot["digest"])
369
- proven = ProvenTemplate.prove(bundle, template, contract, fetched=bool(snapshot))
283
+ # connector.toml is read as the api runtime reads it, so an unservable route is refused at cache time.
284
+ spec = settings = None
285
+ if (bundle / SPEC).is_file():
286
+ spec = load_spec(bundle)
287
+ settings = load_api_settings(bundle, spec)
288
+ read_fields = RouteBindings.served(spec, settings, contract)
289
+ proven = ProvenTemplate.prove(bundle, template, contract, fetched=bool(snapshot), read_fields=read_fields)
370
290
  verifiers = verifier_names(bundle)
371
291
  if REWARD in verifiers:
372
292
  fail("host", f"verifier name '{REWARD}' is reserved for the scalar grade")
@@ -387,13 +307,9 @@ def load_tools_version(
387
307
  handlers = _bundle.load_handlers(bundle, manifest)
388
308
  except WorldStartError as error:
389
309
  fail("host", str(error))
390
- # connector.toml is read as the api runtime reads it, so an unservable route is refused at cache time.
391
- spec = settings = api_handlers = None
392
- if (bundle / SPEC).is_file():
393
- spec = load_spec(bundle)
394
- settings = load_api_settings(bundle, spec)
395
- if run_handlers and settings.handlers is not None:
396
- api_handlers = load_api_handlers(settings)
310
+ api_handlers = None
311
+ if run_handlers and settings is not None and settings.handlers is not None:
312
+ api_handlers = load_api_handlers(settings)
397
313
  return ToolsVersion(
398
314
  bundle=bundle,
399
315
  manifest=manifest,
@@ -407,14 +323,11 @@ def load_tools_version(
407
323
  settings=settings,
408
324
  api_handlers=api_handlers,
409
325
  dependencies=dependencies,
326
+ read_fields=read_fields,
410
327
  )
411
328
 
412
329
 
413
330
  class _EnvHost:
414
- """What :class:`World` reads of an ``Environment`` beside the version's
415
- template: a scratch dir, the handlers, the bundle path, and always-``env``
416
- routing."""
417
-
418
331
  def __init__(self, version: ToolsVersion, worlds_dir: Path) -> None:
419
332
  self.bundle_path = version.bundle
420
333
  self._worlds_dir = worlds_dir
@@ -428,25 +341,6 @@ class _EnvHost:
428
341
 
429
342
 
430
343
  class ToolsWorld:
431
- """One session of a mock-tools version: a copy of the template in the
432
- session's own directory, executed through the bundle's handlers.
433
-
434
- ``task`` is the id of a task the bundle carries, or a :class:`ToolsTask`
435
- of the session's own (:func:`inline_task`). A session task may bring a
436
- ``seed`` (the spec's, ``{mode, rows}``), laid on the template copy at open
437
- and again on every reset — the way the host lays an api task's seed on
438
- its clone — and an ``allowed`` tool list, which ``call`` holds to.
439
-
440
- ``dependencies`` are the worlds the version's manifest declares, one
441
- :class:`DependencyWorld` per alias, every one of them required: each gets
442
- its own template copy under the session directory, and the root's store
443
- reads each as ``<alias>.<table>``.
444
-
445
- ``calls`` is the session's call log (its routes write it too when the tree
446
- carries connector.toml): every tool call that runs is an entry
447
- ``via: tool``, so a grader over ``calls`` sees what the agent did through
448
- tools."""
449
-
450
344
  def __init__(
451
345
  self,
452
346
  version: ToolsVersion,
@@ -483,7 +377,6 @@ class ToolsWorld:
483
377
  self._apply_dependency_scenarios()
484
378
  self._apply_task_seed()
485
379
  except BaseException:
486
- # A refused seed fails the open without leaking the session directory.
487
380
  self.close()
488
381
  raise
489
382
 
@@ -494,43 +387,52 @@ class ToolsWorld:
494
387
  selected = version.tasks.get(task)
495
388
  if selected is None:
496
389
  fail("host", f"no task '{task}' in this world; it has {', '.join(sorted(version.tasks)) or 'none'}")
497
- raise AssertionError # fail() never returns
498
390
  return selected
499
391
 
500
392
  @staticmethod
501
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:
502
400
  host = _EnvHost(version, directory)
503
- return World(host, world_id=uuid.uuid4().hex, template=version.template) # type: ignore[arg-type]
401
+ # _EnvHost is what a World reads of an Environment.
402
+ return World(host, world_id=SESSION_WORLD, template=version.template) # type: ignore[arg-type]
403
+
404
+ @staticmethod
405
+ def live_state(session_dir: Path) -> Path:
406
+ return World.database_file(session_dir, SESSION_WORLD)
407
+
408
+ @staticmethod
409
+ def dependency_states(session_dir: Path) -> dict[str, Path]:
410
+ """Each dependency's store, reached through no link (path confinement)."""
411
+ worlds = Path(session_dir) / "worlds"
412
+ homes = [alias for alias in sorted(worlds.glob("*")) if real_dir(alias)] if real_dir(worlds) else []
413
+ stores = {alias.name: World.database_file(alias, SESSION_WORLD) for alias in homes}
414
+ return {alias: store for alias, store in stores.items() if store.is_file() and not store.is_symlink()}
504
415
 
505
416
  def _apply_task_seed(self) -> None:
506
- """Start the session in its task's state: the template with the task's
507
- rows on top — a scenario task's overlay replacing whole entities, then
508
- the session task's seed. A task without either starts on the template."""
509
417
  if self.task.scenario is not None:
510
418
  self.seed({"rows": self.task.scenario, "mode": "replace"})
511
419
  if self._task_seed is not None:
512
420
  self.seed({"rows": self._task_seed["rows"], "mode": self._task_seed["mode"]})
513
421
 
514
422
  def _apply_dependency_scenarios(self) -> None:
515
- """Start each dependency in the scenario its ``task`` names: the overlay
516
- replaces whole entities on that dependency's template."""
517
423
  for alias, dep in self.dependencies.items():
518
424
  if dep.scenario:
519
425
  rows = {f"{alias}.{entity}": entity_rows for entity, entity_rows in dep.scenario.items()}
520
426
  self.seed({"rows": rows, "mode": "replace"})
521
427
 
522
428
  def _arm(self) -> None:
523
- """Write the active task into every world's opt-in context table, so
524
- SQL verifiers can key off the scenario without a tool that sets it, and
525
- attach each dependency's store to the root's for cross-world reads."""
526
429
  scenario_id = str(self.task.metadata.get("scenario_id") or self.task.id)
527
430
  for world in (self.world, *self.worlds.values()):
528
431
  world.set_task_context(scenario_id)
529
432
  self._attach()
530
433
 
531
434
  def _attach(self) -> None:
532
- """Every dependency's file, readable from the root's connection as
533
- ``<alias>.<table>``. Redone after a reset or restore, which reconnect."""
435
+ """Redone after a reset or restore, which reconnect."""
534
436
  store = self.world.store
535
437
  if store is None:
536
438
  return
@@ -540,9 +442,6 @@ class ToolsWorld:
540
442
  store.attach(alias, world.db_path, world.contract.entities)
541
443
 
542
444
  def _route(self, tool: str) -> tuple[World, str]:
543
- """The world that serves ``tool`` and its name there: a dependency's by
544
- ``<alias>.<tool>``, else the root's. A root route's name is refused
545
- with the api URL to call it over."""
546
445
  alias, dot, local = tool.partition(".")
547
446
  if dot and alias in self.dependencies:
548
447
  dep = self.dependencies[alias]
@@ -554,31 +453,34 @@ class ToolsWorld:
554
453
 
555
454
  @property
556
455
  def names(self) -> ServedNames:
557
- """The tools this session serves, beside the root's routes it refuses by name."""
558
456
  return ServedNames.of(self.served, self.version.spec)
559
457
 
560
458
  def call(self, tool: str, args: dict) -> dict:
561
- """Run ``tool`` and answer as the handler's HTTP twin would: 200 with
562
- the result, 400 when the handler itself is wrong (a name, attribute or
563
- type error is the author's bug, never the engine's), 500 when anything
564
- else fails inside the handler. Both failure bodies are structured
565
- ``{error, detail, handler}`` — never a bare exception string. A call
566
- that runs is logged in :attr:`calls`, a contract refusal as its 400;
567
- an unknown or disallowed name runs nothing and is not a call."""
568
- world, local = self._route(tool)
569
- if self.allowed is not None and tool not in self.allowed:
570
- fail(
571
- "tool_not_allowed",
572
- f"tool '{tool}' is not allowed by this session's task; it allows: {', '.join(sorted(self.allowed))}",
573
- )
459
+ """Answers as the handler's HTTP twin would; a contract refusal raised mid-call is logged as its 400."""
460
+ try:
461
+ world, local = self._admitted(tool)
462
+ except ContractError as refusal:
463
+ if self.calls is not None:
464
+ self.calls.refused_tool(tool, args, refusal.detail)
465
+ raise
574
466
  started = time.monotonic()
575
467
  status, body = 400, None
576
468
  try:
577
469
  status, body = self._run(world, local, args)
578
470
  finally:
579
471
  self._log(tool, args, status, body, time.monotonic() - started)
472
+ self._log_webhooks(world)
580
473
  return {"status": status, "body": body}
581
474
 
475
+ def _admitted(self, tool: str) -> tuple[World, str]:
476
+ routed = self._route(tool)
477
+ if self.allowed is not None and tool not in self.allowed:
478
+ fail(
479
+ "tool_not_allowed",
480
+ f"tool '{tool}' is not allowed by this session's task; it allows: {', '.join(sorted(self.allowed))}",
481
+ )
482
+ return routed
483
+
582
484
  @staticmethod
583
485
  def _run(world: World, local: str, args: dict) -> tuple[int, Any]:
584
486
  try:
@@ -592,34 +494,37 @@ class ToolsWorld:
592
494
  if self.calls is not None:
593
495
  self.calls.record_tool(tool, args, status, body, elapsed_s)
594
496
 
595
- def grade(self) -> dict:
596
- """The task's verifiers, the root's by name and each dependency's as
597
- ``<alias>/<name>``; ``reward`` is the primary verifier's score when the
598
- task names one, else the mean of the numeric scores — null when no
599
- verifier answered a number (never 0). A task no verifier grades is
600
- ungraded, with the reason. A verifier that cannot score (bad SQL, a
601
- value that is not a number from 0 to 1) refuses the grade by name."""
497
+ def _log_webhooks(self, world: World) -> None:
498
+ delivered = world.webhooks.take()
499
+ if self.calls is not None:
500
+ self.calls.record_webhooks(delivered)
501
+
502
+ def grade(self, journal: WorldJournal | None = None) -> dict:
503
+ """``reward`` is null when no verifier answered a number, never 0; a dependency's verifier that reads the
504
+ journal fails closed, as the journal is the root world's."""
602
505
  try:
603
- rewards = self._verifier_scores()
506
+ results = self._verifier_results(journal)
604
507
  except VerifierError as error:
605
508
  fail("verifier", str(error))
606
- if not rewards:
509
+ if not results:
607
510
  return Grade.ungraded().as_dict()
511
+ rewards = {name: result.score for name, result in results.items()}
608
512
  if self.task.verifier is not None and self.task.verifier in rewards:
609
513
  reward = rewards[self.task.verifier]
610
514
  else:
611
515
  numeric = [s for s in rewards.values() if isinstance(s, (int, float))]
612
516
  reward = sum(numeric) / len(numeric) if numeric else None
613
- return {REWARD: reward, "rewards": rewards}
517
+ reasons = {name: result.closed for name, result in results.items() if result.closed is not None}
518
+ return {REWARD: reward, "rewards": rewards, **({"reasons": reasons} if reasons else {})}
614
519
 
615
- def _verifier_scores(self) -> dict[str, float | None]:
616
- rewards: dict[str, float | None] = {}
520
+ def _verifier_results(self, journal: WorldJournal | None) -> dict[str, VerifierResult]:
521
+ results: dict[str, VerifierResult] = {}
617
522
  for name in self.task.selected(self.version.verifiers):
618
- rewards[name] = self.world.verify(name).score
523
+ results[name] = self.world.verify(name, journal)
619
524
  for alias, dep in self.dependencies.items():
620
525
  for name in self.task.selected_of(alias, dep.version.verifiers):
621
- rewards[f"{alias}/{name}"] = self.worlds[alias].verify(name).score
622
- return rewards
526
+ results[f"{alias}/{name}"] = self.worlds[alias].verify(name, LINKED_JOURNAL)
527
+ return results
623
528
 
624
529
  def reset(self) -> dict:
625
530
  for world in self.worlds.values():
@@ -631,23 +536,25 @@ class ToolsWorld:
631
536
  return {"reset": True}
632
537
 
633
538
  def export(self, destination: Path) -> Path:
634
- """The session's state as one database file, taken consistently. A
635
- session beside dependency worlds exports the root's state; theirs is
636
- not in the file, so a restore starts them from their templates."""
539
+ """Holds the root's state only, so a restore from it starts dependency worlds from their templates."""
637
540
  return self.world.snapshot(destination)
638
541
 
639
542
  def restore(self, export: SessionExport) -> None:
640
- """Continue from an export this host verified: the root's rows as the
641
- export holds them, without a second row audit, and each dependency from
642
- its template."""
643
- for world in self.worlds.values():
644
- world.reset()
543
+ carried = export.worlds
544
+ for alias, world in self.worlds.items():
545
+ self._continue(world, carried.get(alias))
645
546
  self.world.resume(export)
646
547
  self._arm()
548
+ if self.world.store is not None:
549
+ self.world.store.index_reads(self.version.read_fields)
550
+
551
+ @staticmethod
552
+ def _continue(world: World, export: SessionExport | None) -> None:
553
+ if export is None:
554
+ return world.reset()
555
+ world.resume(export)
647
556
 
648
557
  def _world_of(self, entity: str) -> tuple[World, str]:
649
- """The world an entity name of a seed addresses: ``<alias>.<entity>``
650
- is a dependency's, a bare name the root's."""
651
558
  alias, dot, local = entity.partition(".")
652
559
  if dot and alias in self.worlds:
653
560
  return self.worlds[alias], local
@@ -673,7 +580,6 @@ class ToolsWorld:
673
580
  store, contract = world.store, world.contract
674
581
  if store is None or contract is None:
675
582
  fail("host", "seed needs a schema-backed world (gateway-world/1); this bundle has none")
676
- raise AssertionError # fail() never returns
677
583
  batch = seed_batch(store, contract, local_rows, mode, batch_id=f"host-seed-{uuid.uuid4().hex}")
678
584
  applied = store.apply_batch(batch)
679
585
  seeded += applied.get("applied", sum(len(v) for v in local_rows.values()))
@@ -688,14 +594,12 @@ class ToolsWorld:
688
594
  return self._dir
689
595
 
690
596
  def state(self) -> dict:
691
- """The root's rows by entity, and under ``worlds`` each dependency's."""
692
597
  out: dict[str, Any] = {"entities": _entities_of(self.world)}
693
598
  if self.worlds:
694
599
  out["worlds"] = {alias: {"entities": _entities_of(world)} for alias, world in self.worlds.items()}
695
600
  return out
696
601
 
697
602
  def entity_names(self) -> list[str]:
698
- """Every entity name :meth:`grader_state` reports, rows or not."""
699
603
  names = list(self.world.contract.entities) if self.world.contract is not None else []
700
604
  for alias, world in self.worlds.items():
701
605
  if world.contract is not None:
@@ -703,7 +607,6 @@ class ToolsWorld:
703
607
  return names
704
608
 
705
609
  def grader_state(self) -> dict:
706
- """The rows as a session task's grader reads them (:func:`world_state`)."""
707
610
  return world_state(self.world, self.worlds)
708
611
 
709
612
  def close(self) -> None:
@@ -723,19 +626,11 @@ def _entities_of(world: World) -> dict[str, list]:
723
626
 
724
627
 
725
628
  class ToolsWorldState(WorldState):
726
- """The api runtime's view of a :class:`ToolsWorld`: the SAME store the tools
727
- write, presented through the :class:`~gatewaysdk.environment.schema.api.WorldState`
728
- interface :class:`~gatewaysdk.environment.schema.api.WorldApp` and its
729
- handlers read. Nothing is copied: ``store`` resolves to the world's live
730
- store on every access, so a reset or a restore that swaps the file
731
- underneath is seen at once. The state owns no store of its own — the
732
- :class:`ToolsWorld` opens and closes it — so ``close`` here is a no-op and
733
- ``reset`` is the world's (template plus the task's seed, the context table
734
- re-armed), never a snapshot clone."""
629
+ """The tools world's live store, resolved on every access so a reset or restore that swaps the file is seen at
630
+ once; the ToolsWorld opens and closes it, so ``close`` here is a no-op."""
735
631
 
736
632
  def __init__(self, tools: ToolsWorld, tree: Path) -> None:
737
- # Deliberately not ``super().__init__``: that opens a temporary store
738
- # from the tree's snapshot, and this state has the tools world's.
633
+ # Not super().__init__: that opens a store from the tree's snapshot, and this state reads the tools world's.
739
634
  self.world = tree
740
635
  self._tools = tools
741
636
  contract = tools.world.contract
@@ -749,22 +644,27 @@ class ToolsWorldState(WorldState):
749
644
  self._clear_events()
750
645
 
751
646
  @property
752
- def store(self): # type: ignore[override]
647
+ def store(self): # type: ignore[override] # the tools world's live store, never one of its own
753
648
  return self._tools.world.store
754
649
 
755
650
  @store.setter
756
651
  def store(self, value) -> None: # WorldState.close assigns None; the world owns it.
757
652
  return None
758
653
 
654
+ @property
655
+ def webhooks(self): # type: ignore[override]
656
+ return self._tools.world.webhooks
657
+
658
+ def serve_webhooks(self, webhooks) -> None:
659
+ return None
660
+
759
661
  def reset(self, *, initial: bool = True) -> None:
760
662
  self._tools.reset()
761
663
  self._clear_events()
762
664
 
763
665
  def seed(self, body: Any) -> dict:
764
- """The runner's legacy whole-state seed, over the template: the named
765
- entities hold exactly the rows given (a replace), the rest keep the
766
- template's. An overlay body is refused as it is on any world without a
767
- snapshot digest (``base_mismatch``)."""
666
+ """The runner's legacy whole-state seed; an overlay body is refused (``base_mismatch``), as on any world
667
+ without a snapshot digest."""
768
668
  if isinstance(body, dict) and isinstance(body.get("base"), str) and isinstance(body.get("rows"), dict):
769
669
  return self._seed_overlay(body)
770
670
  if not isinstance(body, dict):