@withgateway/sdk 0.3.3 → 0.4.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 (123) hide show
  1. package/README.md +4 -3
  2. package/dist/cli.js +2221 -962
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +2212 -953
  5. package/dist/cli.mjs.map +1 -1
  6. package/dist/files/index.js +81 -19
  7. package/dist/files/index.js.map +1 -1
  8. package/dist/files/index.mjs +79 -17
  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.d.mts +2 -2
  19. package/dist/index.d.ts +2 -2
  20. package/dist/index.js +903 -221
  21. package/dist/index.js.map +1 -1
  22. package/dist/index.mjs +868 -212
  23. package/dist/index.mjs.map +1 -1
  24. package/dist/traces/index.js +78 -16
  25. package/dist/traces/index.js.map +1 -1
  26. package/dist/traces/index.mjs +76 -14
  27. package/dist/traces/index.mjs.map +1 -1
  28. package/dist/tracing/index.js +7 -1
  29. package/dist/tracing/index.js.map +1 -1
  30. package/dist/tracing/index.mjs +7 -1
  31. package/dist/tracing/index.mjs.map +1 -1
  32. package/dist/worlds/index.d.mts +692 -410
  33. package/dist/worlds/index.d.ts +692 -410
  34. package/dist/worlds/index.js +740 -197
  35. package/dist/worlds/index.js.map +1 -1
  36. package/dist/worlds/index.mjs +736 -193
  37. package/dist/worlds/index.mjs.map +1 -1
  38. package/package.json +1 -1
  39. package/runtime/gatewaysdk/environment/_materialize.py +5 -25
  40. package/runtime/gatewaysdk/environment/_world.py +58 -65
  41. package/runtime/gatewaysdk/environment/backing.py +20 -24
  42. package/runtime/gatewaysdk/environment/core.py +1 -16
  43. package/runtime/gatewaysdk/environment/legacy_sqlite.py +14 -27
  44. package/runtime/gatewaysdk/environment/schema/admission.py +174 -0
  45. package/runtime/gatewaysdk/environment/schema/api.py +174 -471
  46. package/runtime/gatewaysdk/environment/schema/assertions.py +458 -0
  47. package/runtime/gatewaysdk/environment/schema/batch.py +3 -3
  48. package/runtime/gatewaysdk/environment/schema/cache_layout.py +5 -0
  49. package/runtime/gatewaysdk/environment/schema/call_capture.py +309 -0
  50. package/runtime/gatewaysdk/environment/schema/call_log.py +230 -18
  51. package/runtime/gatewaysdk/environment/schema/call_redaction.py +201 -19
  52. package/runtime/gatewaysdk/environment/schema/cast.py +15 -35
  53. package/runtime/gatewaysdk/environment/schema/conform.py +6 -27
  54. package/runtime/gatewaysdk/environment/schema/connector.py +89 -152
  55. package/runtime/gatewaysdk/environment/schema/connectors/confluence/connector.toml +1 -12
  56. package/runtime/gatewaysdk/environment/schema/connectors/github/connector.toml +1 -0
  57. package/runtime/gatewaysdk/environment/schema/connectors/servicenow/connector.toml +2 -5
  58. package/runtime/gatewaysdk/environment/schema/cors.py +54 -0
  59. package/runtime/gatewaysdk/environment/schema/credentials.py +313 -8
  60. package/runtime/gatewaysdk/environment/schema/data.py +14 -13
  61. package/runtime/gatewaysdk/environment/schema/database/base.py +106 -165
  62. package/runtime/gatewaysdk/environment/schema/database/guard.py +43 -36
  63. package/runtime/gatewaysdk/environment/schema/database/reads.py +169 -0
  64. package/runtime/gatewaysdk/environment/schema/database/sqlite.py +57 -31
  65. package/runtime/gatewaysdk/environment/schema/declared_routes.py +210 -0
  66. package/runtime/gatewaysdk/environment/schema/door.py +899 -0
  67. package/runtime/gatewaysdk/environment/schema/envelope.py +86 -28
  68. package/runtime/gatewaysdk/environment/schema/grading.py +58 -86
  69. package/runtime/gatewaysdk/environment/schema/handler_errors.py +25 -4
  70. package/runtime/gatewaysdk/environment/schema/host.py +229 -1695
  71. package/runtime/gatewaysdk/environment/schema/host_control.py +144 -0
  72. package/runtime/gatewaysdk/environment/schema/host_handoff.py +370 -0
  73. package/runtime/gatewaysdk/environment/schema/host_loops.py +97 -0
  74. package/runtime/gatewaysdk/environment/schema/host_owners.py +121 -0
  75. package/runtime/gatewaysdk/environment/schema/host_proxy.py +111 -0
  76. package/runtime/gatewaysdk/environment/schema/host_requests.py +6 -0
  77. package/runtime/gatewaysdk/environment/schema/host_session.py +126 -0
  78. package/runtime/gatewaysdk/environment/schema/host_surfaces.py +79 -21
  79. package/runtime/gatewaysdk/environment/schema/host_transfers.py +127 -0
  80. package/runtime/gatewaysdk/environment/schema/host_versions.py +242 -0
  81. package/runtime/gatewaysdk/environment/schema/host_workers.py +577 -0
  82. package/runtime/gatewaysdk/environment/schema/journal.py +437 -0
  83. package/runtime/gatewaysdk/environment/schema/ledger_spill.py +828 -0
  84. package/runtime/gatewaysdk/environment/schema/local.py +31 -116
  85. package/runtime/gatewaysdk/environment/schema/platform.py +15 -17
  86. package/runtime/gatewaysdk/environment/schema/request_body.py +238 -0
  87. package/runtime/gatewaysdk/environment/schema/request_ledger.py +958 -0
  88. package/runtime/gatewaysdk/environment/schema/route_bindings.py +25 -3
  89. package/runtime/gatewaysdk/environment/schema/route_miss.py +54 -0
  90. package/runtime/gatewaysdk/environment/schema/runtime.py +129 -176
  91. package/runtime/gatewaysdk/environment/schema/session_files.py +133 -24
  92. package/runtime/gatewaysdk/environment/schema/session_move.py +275 -0
  93. package/runtime/gatewaysdk/environment/schema/skills/agents/connector-template-author.md +5 -1
  94. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +8 -9
  95. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +31 -6
  96. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +12 -8
  97. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +13 -13
  98. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +23 -23
  99. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +11 -6
  100. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +35 -2
  101. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +182 -0
  102. package/runtime/gatewaysdk/environment/schema/snapshot.py +149 -29
  103. package/runtime/gatewaysdk/environment/schema/spill_files.py +228 -0
  104. package/runtime/gatewaysdk/environment/schema/tasks.py +229 -323
  105. package/runtime/gatewaysdk/environment/schema/tools_world.py +84 -203
  106. package/runtime/gatewaysdk/environment/schema/validation.py +69 -1
  107. package/runtime/gatewaysdk/environment/schema/verbs.py +32 -36
  108. package/runtime/gatewaysdk/environment/schema/worker.py +6 -4
  109. package/runtime/gatewaysdk/environment/schema/workers.py +203 -39
  110. package/runtime/gatewaysdk/environment/schema/world_host.py +953 -0
  111. package/runtime/gatewaysdk/environment/schema/world_tests.py +9 -11
  112. package/runtime/gatewaysdk/environment/world.py +1 -1
  113. package/runtime/gatewaysdk/environment/world_session_contract.py +14 -0
  114. package/skills/agents/connector-template-author.md +5 -1
  115. package/skills/benchmarks-getting-started/SKILL.md +8 -9
  116. package/skills/connector-schema-authoring/SKILL.md +31 -6
  117. package/skills/connector-schema-authoring/connector-worlds.md +129 -7
  118. package/skills/world-data-ingestion/ROWS.md +12 -8
  119. package/skills/world-data-ingestion/SKILL.md +13 -13
  120. package/skills/worlds-getting-started/SKILL.md +23 -23
  121. package/skills/worlds-getting-started/references/cli-mcp-map.md +11 -6
  122. package/skills/worlds-getting-started/references/gotchas.md +35 -2
  123. 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,46 @@ 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:
502
394
  host = _EnvHost(version, directory)
503
- return World(host, world_id=uuid.uuid4().hex, template=version.template) # type: ignore[arg-type]
395
+ # _EnvHost is what a World reads of an Environment.
396
+ return World(host, world_id=SESSION_WORLD, template=version.template) # type: ignore[arg-type]
397
+
398
+ @staticmethod
399
+ def live_state(session_dir: Path) -> Path:
400
+ return World.database_file(session_dir, SESSION_WORLD)
401
+
402
+ @staticmethod
403
+ def dependency_states(session_dir: Path) -> dict[str, Path]:
404
+ """Each dependency's store, reached through no link (path confinement)."""
405
+ worlds = Path(session_dir) / "worlds"
406
+ homes = [alias for alias in sorted(worlds.glob("*")) if real_dir(alias)] if real_dir(worlds) else []
407
+ stores = {alias.name: World.database_file(alias, SESSION_WORLD) for alias in homes}
408
+ return {alias: store for alias, store in stores.items() if store.is_file() and not store.is_symlink()}
504
409
 
505
410
  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
411
  if self.task.scenario is not None:
510
412
  self.seed({"rows": self.task.scenario, "mode": "replace"})
511
413
  if self._task_seed is not None:
512
414
  self.seed({"rows": self._task_seed["rows"], "mode": self._task_seed["mode"]})
513
415
 
514
416
  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
417
  for alias, dep in self.dependencies.items():
518
418
  if dep.scenario:
519
419
  rows = {f"{alias}.{entity}": entity_rows for entity, entity_rows in dep.scenario.items()}
520
420
  self.seed({"rows": rows, "mode": "replace"})
521
421
 
522
422
  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
423
  scenario_id = str(self.task.metadata.get("scenario_id") or self.task.id)
527
424
  for world in (self.world, *self.worlds.values()):
528
425
  world.set_task_context(scenario_id)
529
426
  self._attach()
530
427
 
531
428
  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."""
429
+ """Redone after a reset or restore, which reconnect."""
534
430
  store = self.world.store
535
431
  if store is None:
536
432
  return
@@ -540,9 +436,6 @@ class ToolsWorld:
540
436
  store.attach(alias, world.db_path, world.contract.entities)
541
437
 
542
438
  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
439
  alias, dot, local = tool.partition(".")
547
440
  if dot and alias in self.dependencies:
548
441
  dep = self.dependencies[alias]
@@ -554,23 +447,16 @@ class ToolsWorld:
554
447
 
555
448
  @property
556
449
  def names(self) -> ServedNames:
557
- """The tools this session serves, beside the root's routes it refuses by name."""
558
450
  return ServedNames.of(self.served, self.version.spec)
559
451
 
560
452
  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
- )
453
+ """Answers as the handler's HTTP twin would; a contract refusal raised mid-call is logged as its 400."""
454
+ try:
455
+ world, local = self._admitted(tool)
456
+ except ContractError as refusal:
457
+ if self.calls is not None:
458
+ self.calls.refused_tool(tool, args, refusal.detail)
459
+ raise
574
460
  started = time.monotonic()
575
461
  status, body = 400, None
576
462
  try:
@@ -579,6 +465,15 @@ class ToolsWorld:
579
465
  self._log(tool, args, status, body, time.monotonic() - started)
580
466
  return {"status": status, "body": body}
581
467
 
468
+ def _admitted(self, tool: str) -> tuple[World, str]:
469
+ routed = self._route(tool)
470
+ if self.allowed is not None and tool not in self.allowed:
471
+ fail(
472
+ "tool_not_allowed",
473
+ f"tool '{tool}' is not allowed by this session's task; it allows: {', '.join(sorted(self.allowed))}",
474
+ )
475
+ return routed
476
+
582
477
  @staticmethod
583
478
  def _run(world: World, local: str, args: dict) -> tuple[int, Any]:
584
479
  try:
@@ -592,34 +487,32 @@ class ToolsWorld:
592
487
  if self.calls is not None:
593
488
  self.calls.record_tool(tool, args, status, body, elapsed_s)
594
489
 
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."""
490
+ def grade(self, journal: WorldJournal | None = None) -> dict:
491
+ """``reward`` is null when no verifier answered a number, never 0; a dependency's verifier that reads the
492
+ journal fails closed, as the journal is the root world's."""
602
493
  try:
603
- rewards = self._verifier_scores()
494
+ results = self._verifier_results(journal)
604
495
  except VerifierError as error:
605
496
  fail("verifier", str(error))
606
- if not rewards:
497
+ if not results:
607
498
  return Grade.ungraded().as_dict()
499
+ rewards = {name: result.score for name, result in results.items()}
608
500
  if self.task.verifier is not None and self.task.verifier in rewards:
609
501
  reward = rewards[self.task.verifier]
610
502
  else:
611
503
  numeric = [s for s in rewards.values() if isinstance(s, (int, float))]
612
504
  reward = sum(numeric) / len(numeric) if numeric else None
613
- return {REWARD: reward, "rewards": rewards}
505
+ reasons = {name: result.closed for name, result in results.items() if result.closed is not None}
506
+ return {REWARD: reward, "rewards": rewards, **({"reasons": reasons} if reasons else {})}
614
507
 
615
- def _verifier_scores(self) -> dict[str, float | None]:
616
- rewards: dict[str, float | None] = {}
508
+ def _verifier_results(self, journal: WorldJournal | None) -> dict[str, VerifierResult]:
509
+ results: dict[str, VerifierResult] = {}
617
510
  for name in self.task.selected(self.version.verifiers):
618
- rewards[name] = self.world.verify(name).score
511
+ results[name] = self.world.verify(name, journal)
619
512
  for alias, dep in self.dependencies.items():
620
513
  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
514
+ results[f"{alias}/{name}"] = self.worlds[alias].verify(name, LINKED_JOURNAL)
515
+ return results
623
516
 
624
517
  def reset(self) -> dict:
625
518
  for world in self.worlds.values():
@@ -631,23 +524,25 @@ class ToolsWorld:
631
524
  return {"reset": True}
632
525
 
633
526
  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."""
527
+ """Holds the root's state only, so a restore from it starts dependency worlds from their templates."""
637
528
  return self.world.snapshot(destination)
638
529
 
639
530
  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()
531
+ carried = export.worlds
532
+ for alias, world in self.worlds.items():
533
+ self._continue(world, carried.get(alias))
645
534
  self.world.resume(export)
646
535
  self._arm()
536
+ if self.world.store is not None:
537
+ self.world.store.index_reads(self.version.read_fields)
538
+
539
+ @staticmethod
540
+ def _continue(world: World, export: SessionExport | None) -> None:
541
+ if export is None:
542
+ return world.reset()
543
+ world.resume(export)
647
544
 
648
545
  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
546
  alias, dot, local = entity.partition(".")
652
547
  if dot and alias in self.worlds:
653
548
  return self.worlds[alias], local
@@ -673,7 +568,6 @@ class ToolsWorld:
673
568
  store, contract = world.store, world.contract
674
569
  if store is None or contract is None:
675
570
  fail("host", "seed needs a schema-backed world (gateway-world/1); this bundle has none")
676
- raise AssertionError # fail() never returns
677
571
  batch = seed_batch(store, contract, local_rows, mode, batch_id=f"host-seed-{uuid.uuid4().hex}")
678
572
  applied = store.apply_batch(batch)
679
573
  seeded += applied.get("applied", sum(len(v) for v in local_rows.values()))
@@ -688,14 +582,12 @@ class ToolsWorld:
688
582
  return self._dir
689
583
 
690
584
  def state(self) -> dict:
691
- """The root's rows by entity, and under ``worlds`` each dependency's."""
692
585
  out: dict[str, Any] = {"entities": _entities_of(self.world)}
693
586
  if self.worlds:
694
587
  out["worlds"] = {alias: {"entities": _entities_of(world)} for alias, world in self.worlds.items()}
695
588
  return out
696
589
 
697
590
  def entity_names(self) -> list[str]:
698
- """Every entity name :meth:`grader_state` reports, rows or not."""
699
591
  names = list(self.world.contract.entities) if self.world.contract is not None else []
700
592
  for alias, world in self.worlds.items():
701
593
  if world.contract is not None:
@@ -703,7 +595,6 @@ class ToolsWorld:
703
595
  return names
704
596
 
705
597
  def grader_state(self) -> dict:
706
- """The rows as a session task's grader reads them (:func:`world_state`)."""
707
598
  return world_state(self.world, self.worlds)
708
599
 
709
600
  def close(self) -> None:
@@ -723,19 +614,11 @@ def _entities_of(world: World) -> dict[str, list]:
723
614
 
724
615
 
725
616
  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."""
617
+ """The tools world's live store, resolved on every access so a reset or restore that swaps the file is seen at
618
+ once; the ToolsWorld opens and closes it, so ``close`` here is a no-op."""
735
619
 
736
620
  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.
621
+ # Not super().__init__: that opens a store from the tree's snapshot, and this state reads the tools world's.
739
622
  self.world = tree
740
623
  self._tools = tools
741
624
  contract = tools.world.contract
@@ -749,7 +632,7 @@ class ToolsWorldState(WorldState):
749
632
  self._clear_events()
750
633
 
751
634
  @property
752
- def store(self): # type: ignore[override]
635
+ def store(self): # type: ignore[override] # the tools world's live store, never one of its own
753
636
  return self._tools.world.store
754
637
 
755
638
  @store.setter
@@ -761,10 +644,8 @@ class ToolsWorldState(WorldState):
761
644
  self._clear_events()
762
645
 
763
646
  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``)."""
647
+ """The runner's legacy whole-state seed; an overlay body is refused (``base_mismatch``), as on any world
648
+ without a snapshot digest."""
768
649
  if isinstance(body, dict) and isinstance(body.get("base"), str) and isinstance(body.get("rows"), dict):
769
650
  return self._seed_overlay(body)
770
651
  if not isinstance(body, dict):