@withgateway/sdk 0.3.1 → 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 (176) hide show
  1. package/README.md +8 -6
  2. package/dist/cli.js +4372 -2265
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +4362 -2256
  5. package/dist/cli.mjs.map +1 -1
  6. package/dist/files/index.d.mts +1 -1
  7. package/dist/files/index.d.ts +1 -1
  8. package/dist/files/index.js +259 -58
  9. package/dist/files/index.js.map +1 -1
  10. package/dist/files/index.mjs +249 -50
  11. package/dist/files/index.mjs.map +1 -1
  12. package/dist/hooks/index.d.mts +1 -1
  13. package/dist/hooks/index.d.ts +1 -1
  14. package/dist/hooks/index.js +124 -11
  15. package/dist/hooks/index.js.map +1 -1
  16. package/dist/hooks/index.mjs +124 -11
  17. package/dist/hooks/index.mjs.map +1 -1
  18. package/dist/{index-C3UzD0G3.d.mts → index-CDPQBsU5.d.mts} +19 -3
  19. package/dist/{index-C3UzD0G3.d.ts → index-CDPQBsU5.d.ts} +19 -3
  20. package/dist/{index-CBqbB_0J.d.ts → index-DUHmS74p.d.ts} +1 -1
  21. package/dist/{index-D-AMnAMa.d.mts → index-mJhG3vZU.d.mts} +1 -1
  22. package/dist/index.d.mts +5 -5
  23. package/dist/index.d.ts +5 -5
  24. package/dist/index.js +2240 -789
  25. package/dist/index.js.map +1 -1
  26. package/dist/index.mjs +2150 -739
  27. package/dist/index.mjs.map +1 -1
  28. package/dist/{media-CbcAfQvd.d.mts → media-BIApiPzS.d.mts} +21 -2
  29. package/dist/{media-CbcAfQvd.d.ts → media-BIApiPzS.d.ts} +21 -2
  30. package/dist/traces/index.d.mts +1 -1
  31. package/dist/traces/index.d.ts +1 -1
  32. package/dist/traces/index.js +253 -52
  33. package/dist/traces/index.js.map +1 -1
  34. package/dist/traces/index.mjs +243 -44
  35. package/dist/traces/index.mjs.map +1 -1
  36. package/dist/tracing/index.d.mts +2 -2
  37. package/dist/tracing/index.d.ts +2 -2
  38. package/dist/tracing/index.js +75 -13
  39. package/dist/tracing/index.js.map +1 -1
  40. package/dist/tracing/index.mjs +75 -13
  41. package/dist/tracing/index.mjs.map +1 -1
  42. package/dist/worlds/index.d.mts +893 -482
  43. package/dist/worlds/index.d.ts +893 -482
  44. package/dist/worlds/index.js +1968 -669
  45. package/dist/worlds/index.js.map +1 -1
  46. package/dist/worlds/index.mjs +1960 -662
  47. package/dist/worlds/index.mjs.map +1 -1
  48. package/package.json +1 -1
  49. package/runtime/gatewaysdk/environment/_bundle.py +2 -27
  50. package/runtime/gatewaysdk/environment/_materialize.py +48 -88
  51. package/runtime/gatewaysdk/environment/_world.py +155 -237
  52. package/runtime/gatewaysdk/environment/backing.py +133 -0
  53. package/runtime/gatewaysdk/environment/core.py +2 -17
  54. package/runtime/gatewaysdk/environment/legacy_sqlite.py +288 -0
  55. package/runtime/gatewaysdk/environment/reward_keys.py +25 -0
  56. package/runtime/gatewaysdk/environment/runtime.py +8 -13
  57. package/runtime/gatewaysdk/environment/schema/__init__.py +4 -4
  58. package/runtime/gatewaysdk/environment/schema/admin_routes.py +86 -0
  59. package/runtime/gatewaysdk/environment/schema/admission.py +174 -0
  60. package/runtime/gatewaysdk/environment/schema/api.py +347 -892
  61. package/runtime/gatewaysdk/environment/schema/assertions.py +458 -0
  62. package/runtime/gatewaysdk/environment/schema/batch.py +44 -39
  63. package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +17 -5
  64. package/runtime/gatewaysdk/environment/schema/cache_layout.py +5 -0
  65. package/runtime/gatewaysdk/environment/schema/call_capture.py +309 -0
  66. package/runtime/gatewaysdk/environment/schema/call_log.py +503 -0
  67. package/runtime/gatewaysdk/environment/schema/call_redaction.py +526 -0
  68. package/runtime/gatewaysdk/environment/schema/cast.py +15 -35
  69. package/runtime/gatewaysdk/environment/schema/compiler.py +334 -158
  70. package/runtime/gatewaysdk/environment/schema/conform.py +14 -39
  71. package/runtime/gatewaysdk/environment/schema/connector.py +113 -211
  72. package/runtime/gatewaysdk/environment/schema/connectors/confluence/connector.toml +1 -12
  73. package/runtime/gatewaysdk/environment/schema/connectors/github/connector.toml +1 -0
  74. package/runtime/gatewaysdk/environment/schema/connectors/servicenow/connector.toml +2 -5
  75. package/runtime/gatewaysdk/environment/schema/cors.py +54 -0
  76. package/runtime/gatewaysdk/environment/schema/credentials.py +313 -8
  77. package/runtime/gatewaysdk/environment/schema/data.py +60 -216
  78. package/runtime/gatewaysdk/environment/schema/database/__init__.py +24 -0
  79. package/runtime/gatewaysdk/environment/schema/database/audit.py +121 -0
  80. package/runtime/gatewaysdk/environment/schema/database/base.py +936 -0
  81. package/runtime/gatewaysdk/environment/schema/database/budget.py +33 -0
  82. package/runtime/gatewaysdk/environment/schema/database/connections.py +101 -0
  83. package/runtime/gatewaysdk/environment/schema/database/engines.py +8 -0
  84. package/runtime/gatewaysdk/environment/schema/database/guard.py +215 -0
  85. package/runtime/gatewaysdk/environment/schema/database/ingest.py +154 -0
  86. package/runtime/gatewaysdk/environment/schema/database/matching.py +58 -0
  87. package/runtime/gatewaysdk/environment/schema/database/provenance.py +30 -0
  88. package/runtime/gatewaysdk/environment/schema/database/reads.py +169 -0
  89. package/runtime/gatewaysdk/environment/schema/database/rows.py +53 -0
  90. package/runtime/gatewaysdk/environment/schema/database/runtime_rows.py +39 -0
  91. package/runtime/gatewaysdk/environment/schema/database/sqlite.py +393 -0
  92. package/runtime/gatewaysdk/environment/schema/declared_routes.py +210 -0
  93. package/runtime/gatewaysdk/environment/schema/domain_migration.py +236 -0
  94. package/runtime/gatewaysdk/environment/schema/door.py +899 -0
  95. package/runtime/gatewaysdk/environment/schema/envelope.py +227 -0
  96. package/runtime/gatewaysdk/environment/schema/extract.py +6 -13
  97. package/runtime/gatewaysdk/environment/schema/grading.py +90 -103
  98. package/runtime/gatewaysdk/environment/schema/handler_errors.py +163 -12
  99. package/runtime/gatewaysdk/environment/schema/host.py +237 -1795
  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 +437 -0
  112. package/runtime/gatewaysdk/environment/schema/lanes.py +53 -0
  113. package/runtime/gatewaysdk/environment/schema/ledger_spill.py +828 -0
  114. package/runtime/gatewaysdk/environment/schema/local.py +58 -170
  115. package/runtime/gatewaysdk/environment/schema/mapping.py +5 -25
  116. package/runtime/gatewaysdk/environment/schema/openapi_import.py +112 -73
  117. package/runtime/gatewaysdk/environment/schema/openapi_paging.py +147 -0
  118. package/runtime/gatewaysdk/environment/schema/openapi_payloads.py +288 -0
  119. package/runtime/gatewaysdk/environment/schema/openapi_routes.py +97 -102
  120. package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +113 -30
  121. package/runtime/gatewaysdk/environment/schema/platform.py +137 -187
  122. package/runtime/gatewaysdk/environment/schema/platform_import.py +2 -3
  123. package/runtime/gatewaysdk/environment/schema/platform_query.py +61 -5
  124. package/runtime/gatewaysdk/environment/schema/primary_key.py +61 -0
  125. package/runtime/gatewaysdk/environment/schema/proof.py +19 -12
  126. package/runtime/gatewaysdk/environment/schema/request_body.py +238 -0
  127. package/runtime/gatewaysdk/environment/schema/request_ledger.py +958 -0
  128. package/runtime/gatewaysdk/environment/schema/route_bindings.py +25 -3
  129. package/runtime/gatewaysdk/environment/schema/route_miss.py +54 -0
  130. package/runtime/gatewaysdk/environment/schema/runtime.py +178 -308
  131. package/runtime/gatewaysdk/environment/schema/served_names.py +58 -0
  132. package/runtime/gatewaysdk/environment/schema/session_files.py +275 -0
  133. package/runtime/gatewaysdk/environment/schema/session_move.py +275 -0
  134. package/runtime/gatewaysdk/environment/schema/skills/agents/connector-template-author.md +5 -1
  135. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +10 -11
  136. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +49 -16
  137. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +39 -9
  138. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +27 -27
  139. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +33 -33
  140. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +13 -7
  141. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +49 -1
  142. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +182 -0
  143. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/openapi-import.md +50 -21
  144. package/runtime/gatewaysdk/environment/schema/slack.py +4 -8
  145. package/runtime/gatewaysdk/environment/schema/snapshot.py +516 -140
  146. package/runtime/gatewaysdk/environment/schema/spill_files.py +228 -0
  147. package/runtime/gatewaysdk/environment/schema/store_contract.py +8 -14
  148. package/runtime/gatewaysdk/environment/schema/tasks.py +267 -276
  149. package/runtime/gatewaysdk/environment/schema/tools_world.py +146 -242
  150. package/runtime/gatewaysdk/environment/schema/ui.py +24 -5
  151. package/runtime/gatewaysdk/environment/schema/ui_static/app.js +100 -130
  152. package/runtime/gatewaysdk/environment/schema/ui_static/index.html +1 -8
  153. package/runtime/gatewaysdk/environment/schema/validation.py +235 -41
  154. package/runtime/gatewaysdk/environment/schema/verbs.py +32 -36
  155. package/runtime/gatewaysdk/environment/schema/worker.py +6 -4
  156. package/runtime/gatewaysdk/environment/schema/workers.py +345 -96
  157. package/runtime/gatewaysdk/environment/schema/world_host.py +953 -0
  158. package/runtime/gatewaysdk/environment/schema/world_sql.py +81 -0
  159. package/runtime/gatewaysdk/environment/schema/world_tests.py +80 -50
  160. package/runtime/gatewaysdk/environment/score.py +57 -0
  161. package/runtime/gatewaysdk/environment/secret_values.py +36 -0
  162. package/runtime/gatewaysdk/environment/world.py +43 -4
  163. package/runtime/gatewaysdk/environment/world_session_contract.py +46 -5
  164. package/skills/agents/connector-template-author.md +5 -1
  165. package/skills/benchmarks-getting-started/SKILL.md +10 -11
  166. package/skills/connector-schema-authoring/SKILL.md +49 -16
  167. package/skills/connector-schema-authoring/connector-worlds.md +142 -11
  168. package/skills/connector-schema-authoring/world-schema.md +103 -51
  169. package/skills/world-data-ingestion/ROWS.md +39 -9
  170. package/skills/world-data-ingestion/SKILL.md +27 -27
  171. package/skills/worlds-getting-started/SKILL.md +33 -33
  172. package/skills/worlds-getting-started/references/cli-mcp-map.md +13 -7
  173. package/skills/worlds-getting-started/references/gotchas.md +49 -1
  174. package/skills/worlds-getting-started/references/journal-checks.md +182 -0
  175. package/skills/worlds-getting-started/references/openapi-import.md +50 -21
  176. package/runtime/gatewaysdk/environment/schema/store.py +0 -1013
@@ -1,62 +1,44 @@
1
- """The one engine a session runs on. :class:`WorldRuntime` is what the World
2
- Host holds for a session opened in its process: the store, the task's
3
- starting state, the HTTP surface when the tree declares one, and every
4
- control verb (reset, seed, state, grade, call, export, restore, close). The
5
- host asks the runtime; it never asks what shape the version was stored as.
6
-
7
- Two runtimes exist because two stored shapes still do:
8
-
9
- - :class:`TreeRuntime` — a schema world stored as itself (``gateway-env.toml``
10
- with a ``[schema]`` table): a copy of the version's materialized template,
11
- executed through its handlers, beside a copy of each dependency world, its
12
- routes (``connector.toml``) over the same store. This is the runtime every
13
- new push opens on.
14
- - :class:`SnapshotRuntime` — an api bundle (``gateway-api-world.toml`` over
15
- ``server/world``): a clone of the version's compiled snapshot behind its
16
- routes. **READ PATH, marked for deletion**: it exists so the worlds the
17
- platform already stores as bundles keep opening until the migration
18
- (handoff step 5) has rewritten them as schema worlds; nothing new is
19
- stored in this shape. Delete it, ``CachedVersion.snapshot`` and the
20
- api-bundle arm of ``VersionCache._build`` together (step 6).
21
-
22
- The shape is chosen once, in :meth:`WorldRuntime.open`, from what the version
23
- cache loaded; from there the host sees one interface."""
24
-
25
1
  from __future__ import annotations
26
2
 
27
- import fcntl
28
3
  import json
29
4
  import shutil
30
5
  import uuid
31
6
  from abc import ABC, abstractmethod
32
- from collections.abc import Callable, Iterable
7
+ from collections.abc import Callable
33
8
  from pathlib import Path
34
9
  from typing import TYPE_CHECKING, Any, Optional
35
10
 
36
11
  from . import snapshot as snapshots
37
- from .api import Via, WorldApp, WorldState, operation_request, vendor_credential, with_query
12
+ from .api import WorldApp, WorldState
13
+ from .call_log import CallJournal, CallLog
14
+ from .database import WorldDatabase
38
15
  from .dependencies import Dependency
39
16
  from .grading import Grade, GraderError, TaskGrader
17
+ from .journal import CallsView, WorldJournal
18
+ from .request_ledger import RequestOutbox
19
+ from .served_names import ServedNames
20
+ from .session_files import CALLS_JOURNAL, LEDGER_JOURNAL, SessionExport
40
21
  from .snapshot import SCENARIOS
41
- from .tasks import TASK_DIR, TaskSpec, unknown_task_entities, verifier_source, write_task_dir
22
+ from .tasks import (
23
+ TASK_DIR,
24
+ TaskSpec,
25
+ _parse_grader,
26
+ parse_task_spec,
27
+ unknown_task_entities,
28
+ verifier_source,
29
+ write_task_dir,
30
+ )
42
31
  from .tools_world import DependencyWorld, ToolsWorld, ToolsWorldState, inline_task, served_with_dependencies
43
32
  from .validation import fail
44
33
  from .workers import ConfinedVerifierSandbox
45
34
 
46
35
  if TYPE_CHECKING:
47
- from .host import CachedVersion
48
-
49
- #: The token an api world is handed when the session was opened without one:
50
- #: the router still authorizes by it, so the host's own calls carry it.
51
- WORLD_AUTH_SENTINEL = "gateway-session"
36
+ from .host_versions import CachedVersion
52
37
 
53
- Restorer = Callable[[Callable[[Path], None]], bool]
38
+ Restorer = Callable[[Callable[[SessionExport], None]], bool]
54
39
 
55
40
 
56
41
  class WorldRuntime(ABC):
57
- """One session's world, in process. Built by :meth:`open`; the host keeps
58
- it on the session and calls nothing else of the world's."""
59
-
60
42
  def __init__(
61
43
  self,
62
44
  cached: CachedVersion,
@@ -65,40 +47,40 @@ class WorldRuntime(ABC):
65
47
  task: str | None,
66
48
  spec: TaskSpec | None,
67
49
  token: str | None,
50
+ journaled: bool = False,
68
51
  ) -> None:
69
52
  self.cached = cached
70
53
  self.session_dir = Path(session_dir)
71
54
  self.task = task
72
55
  self.task_spec = spec
73
56
  self.token = token
74
- #: The routes of connector.toml over the session's store, when the
75
- #: tree declares any; None for a world of tools alone.
76
57
  self.app: WorldApp | None = None
77
- #: An ``oauth2`` world's client-credentials grant the host minted for
78
- #: itself, so a caller the session token admits is presented to the
79
- #: world as a granted client.
80
- self.grant: str | None = None
58
+ journal = CallJournal(self.session_dir / CALLS_JOURNAL) if journaled else None
59
+ outbox = RequestOutbox(CallJournal(self.session_dir / LEDGER_JOURNAL) if journaled else None)
60
+ spec = cached.spec
61
+ self.calls = CallLog.for_spec(spec, journal, outbox, token)
81
62
  self.restored = False
82
63
 
83
- # -- what the shape knows before a session opens ------------------------ #
84
-
85
64
  @classmethod
86
65
  @abstractmethod
87
- def served_by(cls, cached: CachedVersion, dependencies: dict[str, DependencyWorld]) -> list[str]:
88
- """Every name a session task on ``cached`` may allow."""
66
+ def served_by(cls, cached: CachedVersion, dependencies: dict[str, DependencyWorld]) -> list[str]: ...
89
67
 
90
68
  @classmethod
91
69
  @abstractmethod
92
70
  def authored_code(cls, cached: CachedVersion) -> str | None:
93
- """What world-authored code ``cached`` runs (so only a worker may open
94
- it), None when it runs none."""
71
+ """World-authored code ``cached`` runs, so only a version worker may open it; None when it runs none."""
95
72
 
96
73
  @classmethod
97
74
  def declared_dependencies(cls, cached: CachedVersion) -> dict[str, Dependency]:
98
- """The ``[dependencies]`` the version's manifest declares, by alias."""
99
75
  return {}
100
76
 
101
- # -- construction ------------------------------------------------------ #
77
+ @staticmethod
78
+ @abstractmethod
79
+ def live_state(session_dir: Path) -> Path: ...
80
+
81
+ @staticmethod
82
+ def dependency_states(session_dir: Path) -> dict[str, Path]:
83
+ return {}
102
84
 
103
85
  @classmethod
104
86
  def open(
@@ -111,16 +93,14 @@ class WorldRuntime(ABC):
111
93
  token: str | None,
112
94
  dependencies: dict[str, DependencyWorld],
113
95
  restore: Restorer,
96
+ journaled: bool = False,
114
97
  ) -> WorldRuntime:
115
- """The runtime for ``cached``, started in its task's state, an export
116
- restored into it when the platform names one, its HTTP surface
117
- attached. A start that fails leaves no session directory behind."""
118
- runtime = cached.runtime_class(cached, session_dir, task=task, spec=spec, token=token)
98
+ """``journaled`` keeps the calls on disk, so a version worker that dies leaves them to the next one."""
99
+ runtime = cached.runtime_class(cached, session_dir, task=task, spec=spec, token=token, journaled=journaled)
119
100
  runtime._start(dependencies)
120
101
  try:
121
102
  if spec is not None:
122
103
  runtime._check_task_entities(spec)
123
- # Under the session, where a grade and a restart find the task.
124
104
  write_task_dir(spec, runtime.session_dir)
125
105
  runtime._to_start()
126
106
  runtime.restored = restore(runtime.restore)
@@ -134,16 +114,15 @@ class WorldRuntime(ABC):
134
114
  cached = self.cached
135
115
  if cached.spec is None:
136
116
  return
137
- # ``handlers={}`` for a code-free world: WorldApp would otherwise
138
- # import the module itself, and only a worker may do that.
117
+ # A code-free world gets ``handlers={}``: WorldApp would otherwise import the module, and only a worker may.
139
118
  self.app = WorldApp(
140
119
  self._app_state(),
141
120
  cached.router(),
142
121
  self.token,
143
122
  handlers=cached.handlers or {},
144
- allowed=self.allowed,
123
+ routes_closed=self.allowed is not None,
124
+ calls=self.calls,
145
125
  )
146
- self.grant = client_grant(self.app, self.token)
147
126
 
148
127
  @property
149
128
  def allowed(self) -> frozenset[str] | None:
@@ -151,10 +130,7 @@ class WorldRuntime(ABC):
151
130
  return frozenset(spec.tools) if spec is not None and spec.tools is not None else None
152
131
 
153
132
  def _check_task_entities(self, spec: TaskSpec) -> None:
154
- """A task is refused for a world that does not define every entity it
155
- names. The seed would fail on its own; an assertion over an unknown
156
- entity would not, selecting no rows, so ``absent`` or ``count: eq 0``
157
- checks would pass on a typo and grade a task that can never be graded."""
133
+ """A check over an unknown entity selects no rows: ``absent`` or ``count: eq 0`` would pass on a typo."""
158
134
  defined = self.entity_names()
159
135
  unknown = unknown_task_entities(spec, defined)
160
136
  if unknown:
@@ -165,26 +141,21 @@ class WorldRuntime(ABC):
165
141
  "/task",
166
142
  )
167
143
 
168
- # -- what a subclass supplies ------------------------------------------ #
169
-
170
144
  @abstractmethod
171
145
  def _start(self, dependencies: dict[str, DependencyWorld]) -> None:
172
- """Bring the store up. A failure here leaves nothing to close."""
146
+ """A failure here leaves nothing to close: :meth:`open` runs it outside its cleanup."""
173
147
 
174
148
  def _to_start(self) -> None:
175
149
  """Lay the task's starting state on the store, when :meth:`_start` did not."""
176
150
 
177
151
  @abstractmethod
178
- def _app_state(self) -> Any:
179
- """The :class:`api.WorldState` the routes read and write."""
152
+ def _app_state(self) -> Any: ...
180
153
 
181
154
  @abstractmethod
182
- def entity_names(self) -> list[str]:
183
- """Every entity a grader may name (a dependency's as ``alias.entity``)."""
155
+ def entity_names(self) -> list[str]: ...
184
156
 
185
157
  @abstractmethod
186
- def served(self) -> list[str]:
187
- """Every name :meth:`call` answers: tools, operations, a dependency's ``alias.tool``."""
158
+ def served(self) -> list[str]: ...
188
159
 
189
160
  @abstractmethod
190
161
  def reset(self) -> dict: ...
@@ -193,77 +164,79 @@ class WorldRuntime(ABC):
193
164
  def seed(self, rows: dict, mode: str, redact: str) -> dict: ...
194
165
 
195
166
  @abstractmethod
196
- def _rows(self) -> dict:
197
- """The state without the calls: rows by entity, and what the store started from."""
167
+ def _rows(self) -> dict: ...
198
168
 
199
169
  @abstractmethod
200
- def _grader_rows(self) -> dict:
201
- """The rows as a session task's grader reads them (keyed by primary key)."""
170
+ def _grader_rows(self) -> dict: ...
202
171
 
203
172
  @abstractmethod
204
- def bundled_grade(self) -> dict | None:
205
- """The grade of the version's own task by the version's own graders
206
- (a schema world's SQL verifiers), or None when the version grades a
207
- bundled task through a ``verify.py`` the :class:`TaskGrader` runs."""
173
+ def bundled_grade(self, journal: WorldJournal | None = None) -> dict | None:
174
+ """None means the bundled task grades by its ``verify.py`` (:class:`TaskGrader`), not that it is ungraded."""
208
175
 
209
176
  @abstractmethod
210
- def _bundled_verifier(self) -> Path | None:
211
- """The ``verify.py`` of the bundled task, when the version carries one."""
177
+ def _bundled_verifier(self) -> Path | None: ...
212
178
 
213
179
  @abstractmethod
214
- def _call_tool(self, tool: str, args: dict) -> dict | None:
215
- """A tool by name, or None when ``tool`` is an operation of the routes."""
180
+ def call(self, tool: str, args: dict) -> dict:
181
+ """A route's name is refused with the api URL to call it over: routes are never tools."""
216
182
 
217
183
  @abstractmethod
218
- def export(self, destination: Path) -> Path: ...
184
+ def _export_state(self, destination: Path) -> Path: ...
219
185
 
220
186
  @abstractmethod
221
- def restore(self, source: Path) -> None: ...
187
+ def _restore_state(self, export: SessionExport) -> None:
188
+ """The session's store laid from a verified export, without a row audit."""
189
+
190
+ def export(self, destination: Path) -> Path:
191
+ path = self._export_state(destination)
192
+ SessionExport.carry_calls(path, self.calls.describe()["calls"], self.cached.engine)
193
+ return path
194
+
195
+ def restore(self, export: SessionExport) -> None:
196
+ self._restore_state(export)
197
+ self.calls.resume(export.calls)
198
+ self.calls.outbox.resume(export.unsent)
222
199
 
223
200
  @abstractmethod
224
201
  def close(self) -> None: ...
225
202
 
226
203
  @abstractmethod
227
- def task_card(self) -> dict:
228
- """What an outside agent is handed about the session's task."""
229
-
230
- # -- the control verbs, shared ----------------------------------------- #
231
-
232
- def _with_calls(self, state: dict) -> dict:
233
- if self.app is not None:
234
- state["calls"] = self.app.calls.describe()["calls"]
235
- return state
204
+ def task_card(self) -> dict: ...
236
205
 
237
206
  def state(self) -> dict:
238
- return self._with_calls(self._rows())
239
-
240
- def grader_state(self, report: Optional[str] = None) -> dict:
241
- """The evidence a grader reads: the rows keyed by primary key (a
242
- dependency's as ``<alias>.<entity>``), the snapshot in use, the calls
243
- the agent made (a read-only investigation writes nothing) and, under
244
- ``report``, the agent's own claim. Reserved keys: no world entity may
245
- be named ``calls``, ``snapshot`` or ``report``."""
246
- state = self._with_calls(self._grader_rows())
207
+ return self.calls.into_state(self._rows())
208
+
209
+ def grader_state(self, report: Optional[str] = None, journal: Optional[WorldJournal] = None) -> dict:
210
+ """Keys beside the rows (``calls``, ``snapshot``, ``report``, ``gateway_*``) are reserved from entity names."""
211
+ state = self.calls.into_state(self._grader_rows())
212
+ if journal is not None:
213
+ state = journal.into_state(state, self._calls_view().rows(journal))
247
214
  if report is not None:
248
215
  state["report"] = report
249
216
  return state
250
217
 
251
- def grade(self, report: Optional[str] = None, context: Optional[dict] = None) -> dict:
252
- """One grader path. The session's own task grades by its grader —
253
- assertions in process, verify.py confined like a worker, a rubric
254
- pending on the platform (the host has no model, no key and no business
255
- calling one from a tenant's session) — over the same state dump
256
- whatever the world's shape. A bundled task grades by the version's own
257
- graders.
258
-
259
- The task's cross-world verifiers anchored here grade next, each over
260
- :meth:`TaskGrader.evidence` of this state and ``context`` (the other
261
- scoped worlds' states, ``{alias: state}``, gathered by the platform),
262
- and answer under ``verifiers`` by name — apart from the world's own
263
- ``reward``, so a task aggregate counts each once. A verifier that
264
- cannot grade (evidence missing, verify.py failed) answers null with
265
- its ``error``; the world's own grade still stands."""
266
- own = self._own_grade(report)
218
+ def _calls_view(self) -> CallsView:
219
+ """A tool call the door refused before it ran (a name not served or not allowed) is not a call."""
220
+ served = frozenset(self.served())
221
+ allowed = self.allowed
222
+ return CallsView(
223
+ self.cached.spec,
224
+ self.calls.redaction,
225
+ lambda tool: tool in served and (allowed is None or tool in allowed),
226
+ )
227
+
228
+ def grade(
229
+ self,
230
+ report: Optional[str] = None,
231
+ context: Optional[dict] = None,
232
+ journal: Optional[WorldJournal] = None,
233
+ grader: Optional[dict] = None,
234
+ ) -> dict:
235
+ """A rubric stays pending: the host has no model, no key and no business calling one from a tenant's session.
236
+ Cross-world verifiers answer under ``verifiers``, apart from ``reward``, so an aggregate counts each once."""
237
+ if grader is not None:
238
+ return self.trial(grader, report, journal)
239
+ own = self._own_grade(report, journal)
267
240
  verifiers = self._verifiers()
268
241
  if not verifiers:
269
242
  return own
@@ -271,22 +244,38 @@ class WorldRuntime(ABC):
271
244
  graded = {grader.name: self._verifier_grade(grader, state, context or {}) for grader in verifiers}
272
245
  return {**own, "verifiers": graded}
273
246
 
274
- def _own_grade(self, report: Optional[str]) -> dict:
275
- """The session task's grade by its own grader, or null with the reason
276
- when it has none; a bundled task's by the version's own graders."""
247
+ def _own_grade(self, report: Optional[str], journal: Optional[WorldJournal]) -> dict:
277
248
  spec = self.task_spec
278
- if spec is None:
279
- bundled = self.bundled_grade()
280
- if bundled is not None:
281
- return bundled
249
+ bundled = self.bundled_grade(journal) if spec is None else None
250
+ if bundled is not None:
251
+ return bundled
282
252
  grader = self._task_grader(spec)
283
253
  if grader is None:
284
254
  return Grade.ungraded().as_dict()
255
+ return self._graded(grader, report, journal)
256
+
257
+ def _graded(self, grader: TaskGrader, report: Optional[str], journal: Optional[WorldJournal]) -> dict:
285
258
  try:
286
- return grader.grade(self.grader_state(report)).as_dict()
259
+ return grader.grade(self.grader_state(report, journal if grader.reads_journal else None)).as_dict()
287
260
  except GraderError as error:
288
261
  fail("host", str(error))
289
- raise AssertionError # fail() never returns
262
+ raise AssertionError
263
+
264
+ def trial(self, table: dict, report: Optional[str], journal: Optional[WorldJournal]) -> dict:
265
+ parsed = _parse_grader(table, "/grader")
266
+ if parsed is None or parsed["kind"] == "rubric":
267
+ fail("host", "a candidate grader grades by assertions or python; a rubric is judged by the platform")
268
+ self._check_task_entities(parse_task_spec({"instruction": "try", "grader": table}))
269
+ sandbox, home = self._sandbox()
270
+ scratch = self.session_dir / "trial" / uuid.uuid4().hex
271
+ try:
272
+ verify = scratch / "verify.py"
273
+ scratch.mkdir(parents=True)
274
+ verify.write_text(parsed.get("source", ""), encoding="utf-8")
275
+ grader = TaskGrader(parsed, verify=verify, sandbox=sandbox, home=scratch / "home", explain=True)
276
+ return self._graded(grader, report, journal)
277
+ finally:
278
+ shutil.rmtree(scratch, ignore_errors=True)
290
279
 
291
280
  @staticmethod
292
281
  def _verifier_grade(grader: TaskGrader, state: dict, context: dict) -> dict:
@@ -299,24 +288,21 @@ class WorldRuntime(ABC):
299
288
  return ConfinedVerifierSandbox(), self.session_dir / "verify"
300
289
 
301
290
  def _task_grader(self, spec: Optional[TaskSpec]) -> Optional[TaskGrader]:
302
- """The session's grader: the spec's, with its verify.py where
303
- :func:`write_task_dir` put it; else the bundled task's verify.py; else
304
- none (an ungraded task grades null)."""
305
291
  sandbox, home = self._sandbox()
306
292
  if spec is not None:
307
- if spec.grader is None:
308
- return None
309
- verify = self.session_dir / TASK_DIR / "checks" / "verify.py"
310
- return TaskGrader(spec.grader, verify=verify, sandbox=sandbox, home=home)
293
+ return self._spec_grader(spec, sandbox, home)
311
294
  verify = self._bundled_verifier()
312
295
  if verify is None or not verify.is_file():
313
296
  return None
314
297
  return TaskGrader.for_verifier(verify, sandbox=sandbox, home=home)
315
298
 
299
+ def _spec_grader(self, spec: TaskSpec, sandbox: ConfinedVerifierSandbox, home: Path) -> Optional[TaskGrader]:
300
+ if spec.grader is None:
301
+ return None
302
+ verify = self.session_dir / TASK_DIR / "checks" / "verify.py"
303
+ return TaskGrader(spec.grader, verify=verify, sandbox=sandbox, home=home)
304
+
316
305
  def _verifiers(self) -> list[TaskGrader]:
317
- """The task's cross-world verifiers anchored on this session, each a
318
- scoped :class:`TaskGrader` with its verify.py where
319
- :func:`write_task_dir` put it."""
320
306
  spec = self.task_spec
321
307
  if spec is None:
322
308
  return []
@@ -334,34 +320,8 @@ class WorldRuntime(ABC):
334
320
  for row in spec.verifiers
335
321
  ]
336
322
 
337
- def call(self, tool: str, args: dict) -> dict:
338
- """One name of what the session serves: a tool by name (a dependency's
339
- as ``alias.tool``); on a tree with connector.toml, an operation by name
340
- too, answered by its route over the same store, ``{status, body}`` the
341
- route's own. A name that is both is the tool's."""
342
- answer = self._call_tool(tool, args)
343
- if answer is not None:
344
- return answer
345
- if self.app is None:
346
- fail("host", f"unknown tool '{tool}'; this world serves: {', '.join(sorted(self.served())) or '(none)'}")
347
- raise AssertionError # fail() never returns
348
- return call_operation(
349
- self.app, tool, args, self.token or WORLD_AUTH_SENTINEL, allowed=self.allowed, grant=self.grant
350
- )
351
-
352
- def credential(self) -> tuple[dict[str, str], dict[str, str]]:
353
- """(headers, query) carrying the world's own credential for this
354
- session: the session token in the vendor's shape, or for an oauth2
355
- world the grant the host minted for itself."""
356
- assert self.app is not None, "a world of tools alone has no http surface to present a credential on"
357
- return vendor_credential(self.app.router.spec, self.token or WORLD_AUTH_SENTINEL, grant=self.grant)
358
-
359
323
 
360
324
  class TreeRuntime(WorldRuntime):
361
- """A schema world stored as itself: :class:`ToolsWorld` over a copy of the
362
- version's template, beside a copy of each dependency's, graded by the
363
- version's SQL verifiers unless the session's own task brings a grader."""
364
-
365
325
  world: ToolsWorld
366
326
 
367
327
  @classmethod
@@ -371,13 +331,21 @@ class TreeRuntime(WorldRuntime):
371
331
 
372
332
  @classmethod
373
333
  def authored_code(cls, cached: CachedVersion) -> str:
374
- return "schema world handlers" # its tools ARE handlers
334
+ return "schema world handlers"
375
335
 
376
336
  @classmethod
377
337
  def declared_dependencies(cls, cached: CachedVersion) -> dict[str, Dependency]:
378
338
  assert cached.tools is not None
379
339
  return cached.tools.dependencies
380
340
 
341
+ @staticmethod
342
+ def live_state(session_dir: Path) -> Path:
343
+ return ToolsWorld.live_state(session_dir)
344
+
345
+ @staticmethod
346
+ def dependency_states(session_dir: Path) -> dict[str, Path]:
347
+ return ToolsWorld.dependency_states(session_dir)
348
+
381
349
  def _start(self, dependencies: dict[str, DependencyWorld]) -> None:
382
350
  tools = self.cached.tools
383
351
  assert tools is not None
@@ -390,10 +358,11 @@ class TreeRuntime(WorldRuntime):
390
358
  seed=spec.seed,
391
359
  allowed=self.allowed,
392
360
  dependencies=dependencies,
361
+ calls=self.calls,
393
362
  )
394
363
  return
395
364
  assert self.task is not None
396
- self.world = ToolsWorld(tools, self.session_dir, self.task, dependencies=dependencies)
365
+ self.world = ToolsWorld(tools, self.session_dir, self.task, dependencies=dependencies, calls=self.calls)
397
366
 
398
367
  def _app_state(self) -> ToolsWorldState:
399
368
  return ToolsWorldState(self.world, self.cached.tree)
@@ -418,23 +387,20 @@ class TreeRuntime(WorldRuntime):
418
387
  def _grader_rows(self) -> dict:
419
388
  return self.world.grader_state()
420
389
 
421
- def bundled_grade(self) -> dict | None:
422
- return None if self.world.task.verify is not None else self.world.grade()
390
+ def bundled_grade(self, journal: WorldJournal | None = None) -> dict | None:
391
+ return None if self.world.task.verify is not None else self.world.grade(journal)
423
392
 
424
393
  def _bundled_verifier(self) -> Path | None:
425
394
  return self.world.task.verify
426
395
 
427
- def _call_tool(self, tool: str, args: dict) -> dict | None:
428
- version = self.world.version
429
- if self.app is not None and tool not in version.tool_names and tool in self.app.router.spec.operations:
430
- return None
396
+ def call(self, tool: str, args: dict) -> dict:
431
397
  return self.world.call(tool, args)
432
398
 
433
- def export(self, destination: Path) -> Path:
399
+ def _export_state(self, destination: Path) -> Path:
434
400
  return self.world.export(destination)
435
401
 
436
- def restore(self, source: Path) -> None:
437
- self.world.restore(source)
402
+ def _restore_state(self, export: SessionExport) -> None:
403
+ self.world.restore(export)
438
404
 
439
405
  def close(self) -> None:
440
406
  self.world.close()
@@ -443,32 +409,8 @@ class TreeRuntime(WorldRuntime):
443
409
  return task_card(self.world)
444
410
 
445
411
 
446
- # --------------------------------------------------------------------------- #
447
- # READ PATH, marked for deletion (handoff step 6): the api-bundle runtime and
448
- # the reflink-cloned store under it. Nothing new is stored in this shape.
449
- # --------------------------------------------------------------------------- #
450
-
451
- _FICLONE = 0x40049409 # ioctl: clone one file's extents into another (btrfs/XFS)
452
-
453
-
454
- def clone_file(src: Path, dst: Path) -> None:
455
- """Copy ``src`` to ``dst`` cheaply. A reflink (``FICLONE``) shares the
456
- version snapshot's blocks copy-on-write, so opening a session costs the
457
- same whatever the snapshot's size; a filesystem without reflink falls back
458
- to a plain copy, which is what the pod engine does today."""
459
- dst.parent.mkdir(parents=True, exist_ok=True)
460
- try:
461
- with open(src, "rb") as s, open(dst, "wb") as d:
462
- fcntl.ioctl(d.fileno(), _FICLONE, s.fileno())
463
- return
464
- except OSError:
465
- pass # not supported here (tmpfs, ext4, cross-device) — copy instead
466
- shutil.copyfile(src, dst)
467
-
468
-
469
412
  def scenario_dir(bundle: Path, tree: Path, task: str) -> Path | None:
470
- """A bundled task's scenario directory, checked at the bundle root first
471
- (where ``build_api_bundle`` writes them) then in the tree."""
413
+ """The bundle root first, where ``build_api_bundle`` writes the scenarios, then the tree."""
472
414
  for root in (bundle / SCENARIOS / task, tree / SCENARIOS / task):
473
415
  if (root / "scenario.toml").is_file():
474
416
  return root
@@ -476,54 +418,43 @@ def scenario_dir(bundle: Path, tree: Path, task: str) -> Path | None:
476
418
 
477
419
 
478
420
  class HostWorldState(WorldState):
479
- """A session's world, opened by cloning the version's cached snapshot into a
480
- file on the host's own volume — the reflink is the whole per-session cost.
481
- Otherwise a plain :class:`WorldState`."""
482
-
483
421
  def __init__(self, cached: CachedVersion, session_dir: Path):
484
422
  self._session_dir = Path(session_dir)
485
423
  self._session_dir.mkdir(parents=True, exist_ok=True)
486
424
  self._cached = cached
487
- self._database: Path | None = None
488
- super().__init__(cached.tree)
425
+ super().__init__(cached.tree, cached.served)
426
+
427
+ @staticmethod
428
+ def live_state(session_dir: Path) -> Path:
429
+ return Path(session_dir) / "state.db"
489
430
 
490
431
  @property
491
432
  def session_dir(self) -> Path:
492
433
  return self._session_dir
493
434
 
494
435
  def _open(self, snapshot: Path | None, *, initial: bool = True) -> None:
495
- # A snapshot start is a clone of the version's cached snapshot into this
496
- # session's file; the legacy no-snapshot path stays as the base class runs it.
497
436
  if snapshot is None:
498
437
  return super()._open(None, initial=initial)
438
+ self._lay(snapshot)
439
+
440
+ def _lay(self, source: Path) -> None:
499
441
  if self.store is not None:
500
442
  self.store.close()
501
- if self._database is not None:
502
- self._database.unlink(missing_ok=True)
503
- database = self._session_dir / f"{uuid.uuid4().hex}.db"
504
- clone_file(snapshot, database)
505
- self.store = snapshots.SQLiteStore.open(database, self.contract, audit=False)
506
- self._database = database
443
+ database = self.live_state(self._session_dir)
444
+ database.unlink(missing_ok=True)
445
+ self.store = WorldDatabase.open_copy(source, self.contract, database)
507
446
 
508
447
  def export(self, destination: Path) -> Path:
509
- """The session's state as one sqlite file: the store's own audited
510
- online backup, consistent while requests keep writing."""
511
- assert self.store is not None
448
+ """Copied outside the lock, so the session's requests keep landing."""
512
449
  with self._lock:
513
- return self.store.snapshot(destination)
450
+ store = self.store
451
+ assert store is not None
452
+ return store.snapshot(destination)
514
453
 
515
- def restore(self, source: Path) -> None:
516
- """Continue from a file :meth:`export` wrote. The file is audited row by
517
- row on open: it came over the network, not from this store."""
454
+ def restore(self, export: SessionExport) -> None:
455
+ path = SessionExport.required(export).path
518
456
  with self._lock:
519
- if self.store is not None:
520
- self.store.close()
521
- if self._database is not None:
522
- self._database.unlink(missing_ok=True)
523
- database = self._session_dir / f"{uuid.uuid4().hex}.db"
524
- clone_file(source, database)
525
- self.store = snapshots.SQLiteStore.open(database, self.contract, audit=True)
526
- self._database = database
457
+ self._lay(path)
527
458
 
528
459
  def close(self) -> None:
529
460
  super().close()
@@ -531,16 +462,14 @@ class HostWorldState(WorldState):
531
462
 
532
463
 
533
464
  class SnapshotRuntime(WorldRuntime):
534
- """An api bundle: :class:`HostWorldState` cloned from the version's compiled
535
- snapshot, the bundled task's scenario overlay (or the session task's seed)
536
- on top, graded by the scenario's ``verify.py``. READ PATH — see above."""
465
+ """Read path for worlds still stored as api bundles; nothing new is stored in this shape. Delete it with
466
+ ``CachedVersion.snapshot`` and the api-bundle arm of ``VersionCache._build``."""
537
467
 
538
468
  state_: HostWorldState
539
469
 
540
470
  @classmethod
541
471
  def served_by(cls, cached: CachedVersion, dependencies: dict[str, DependencyWorld]) -> list[str]:
542
- assert cached.spec is not None
543
- return list(cached.spec.operations)
472
+ return []
544
473
 
545
474
  @classmethod
546
475
  def authored_code(cls, cached: CachedVersion) -> str | None:
@@ -548,6 +477,10 @@ class SnapshotRuntime(WorldRuntime):
548
477
  return None
549
478
  return f"api handlers module {cached.settings.handlers.name}"
550
479
 
480
+ @staticmethod
481
+ def live_state(session_dir: Path) -> Path:
482
+ return HostWorldState.live_state(session_dir)
483
+
551
484
  def _start(self, dependencies: dict[str, DependencyWorld]) -> None:
552
485
  if dependencies:
553
486
  fail(
@@ -558,10 +491,6 @@ class SnapshotRuntime(WorldRuntime):
558
491
  self.state_ = HostWorldState(self.cached, self.session_dir)
559
492
 
560
493
  def _to_start(self) -> None:
561
- """The task's starting state on a fresh clone: the session task's seed,
562
- else the bundled task's scenario overlay. The compiled snapshot the
563
- session is cloned from IS the base state, so a scenario with no seed
564
- overlay (the synthesized ``default``) needs nothing."""
565
494
  spec = self.task_spec
566
495
  if spec is not None:
567
496
  if spec.seed is not None:
@@ -571,7 +500,7 @@ class SnapshotRuntime(WorldRuntime):
571
500
  scenario = scenario_dir(self.cached.bundle, self.cached.tree, self.task)
572
501
  if scenario is None:
573
502
  if self.task in self.state_.scenarios():
574
- self.state_.apply_scenario(self.task) # a tree-authored scenario
503
+ self.state_.apply_scenario(self.task)
575
504
  return
576
505
  fail(
577
506
  "host",
@@ -579,7 +508,7 @@ class SnapshotRuntime(WorldRuntime):
579
508
  )
580
509
  overlay = snapshots.scenario_overlay(scenario)
581
510
  if not overlay:
582
- return # base state; the cloned snapshot already holds it
511
+ return
583
512
  digest = self.state_.digest
584
513
  if digest is None:
585
514
  fail("host", "a scenario overlay needs a compiled snapshot to apply against")
@@ -592,19 +521,14 @@ class SnapshotRuntime(WorldRuntime):
592
521
  return list(self.state_.contract.entities)
593
522
 
594
523
  def served(self) -> list[str]:
595
- spec = self.cached.spec
596
- return sorted(spec.operations) if spec is not None else []
524
+ return []
597
525
 
598
526
  def reset(self) -> dict:
599
- # Back to the task's starting state: re-clone the snapshot, then
600
- # re-apply the task's seed or the scenario overlay if it had one.
601
527
  self.state_.reset()
602
528
  self._to_start()
603
529
  return {"reset": True}
604
530
 
605
531
  def seed(self, rows: dict, mode: str, redact: str) -> dict:
606
- # Onto the live state, the way the runner's session seed lands: an
607
- # append upserts by key, a replace swaps the named entities.
608
532
  self.state_.seed_live(rows, mode, redact)
609
533
  return {
610
534
  "seeded": sum(len(v) for v in rows.values()),
@@ -621,7 +545,7 @@ class SnapshotRuntime(WorldRuntime):
621
545
  def _grader_rows(self) -> dict:
622
546
  return self._rows()
623
547
 
624
- def bundled_grade(self) -> dict | None:
548
+ def bundled_grade(self, journal: WorldJournal | None = None) -> dict | None:
625
549
  return None
626
550
 
627
551
  def _bundled_verifier(self) -> Path | None:
@@ -629,14 +553,14 @@ class SnapshotRuntime(WorldRuntime):
629
553
  scenario = scenario_dir(self.cached.bundle, self.cached.tree, self.task)
630
554
  return scenario / "checks" / "verify.py" if scenario else None
631
555
 
632
- def _call_tool(self, tool: str, args: dict) -> dict | None:
633
- return None
556
+ def call(self, tool: str, args: dict) -> dict:
557
+ ServedNames.of((), self.cached.spec).refuse(tool)
634
558
 
635
- def export(self, destination: Path) -> Path:
559
+ def _export_state(self, destination: Path) -> Path:
636
560
  return self.state_.export(destination)
637
561
 
638
- def restore(self, source: Path) -> None:
639
- self.state_.restore(source)
562
+ def _restore_state(self, export: SessionExport) -> None:
563
+ self.state_.restore(export)
640
564
 
641
565
  def close(self) -> None:
642
566
  self.state_.close()
@@ -654,56 +578,7 @@ class SnapshotRuntime(WorldRuntime):
654
578
  }
655
579
 
656
580
 
657
- def client_grant(app: WorldApp | None, credential: str | None) -> str | None:
658
- """The bearer an ``oauth2`` world's routes take when the session itself
659
- calls them (the page's api prefix, an operation by name); None for any
660
- other scheme, or when the world refuses the client-credentials grant."""
661
- if app is None or app.router.spec.scheme != "oauth2":
662
- return None
663
- issued = app.router.issue_token({"grant_type": "client_credentials", "client_secret": credential or ""}, credential)
664
- return issued["access_token"] if issued else None
665
-
666
-
667
- def call_operation(
668
- app: WorldApp,
669
- name: str,
670
- args: dict,
671
- credential: str,
672
- *,
673
- allowed: Iterable[str] | None = None,
674
- grant: str | None = None,
675
- ) -> dict:
676
- """An operation of connector.toml called by name (:func:`operation_request`
677
- reads the args: ``path``/``query``/``body``, or leftover top-level keys as
678
- the body); the world's own credential is presented, as the host presents a
679
- session's. The call is logged ``via: tool``. The answer is the route's
680
- ``{status, body}``."""
681
- spec = app.router.spec
682
- operation = spec.operations.get(name)
683
- if operation is None:
684
- known = ", ".join(sorted(spec.operations)) or "(none)"
685
- fail("host", f"unknown tool '{name}'; this world serves: {known}")
686
- if allowed is not None and name not in allowed:
687
- fail(
688
- "tool_not_allowed",
689
- f"tool '{name}' is not allowed by this session's task; it allows: {', '.join(sorted(allowed))}",
690
- )
691
- method, target, raw = operation_request(spec, operation, args)
692
- headers, credential_query = vendor_credential(spec, credential, grant=grant)
693
- status, answer, _ = app.handle(
694
- method,
695
- with_query(target, credential_query),
696
- {"content-type": "application/json", **headers},
697
- raw,
698
- "127.0.0.1",
699
- via=Via.TOOL,
700
- )
701
- return {"status": status, "body": answer}
702
-
703
-
704
581
  def tool_contracts(bundle: Path, prefix: str = "") -> dict[str, dict]:
705
- """Each compiled tool's ``{description, input}`` from the bundle's
706
- ``tool-schemas.json`` (refs inlined by the compiler), keyed by served name."""
707
582
  path = bundle / "tool-schemas.json"
708
583
  if not path.is_file():
709
584
  return {}
@@ -715,11 +590,6 @@ def tool_contracts(bundle: Path, prefix: str = "") -> dict[str, dict]:
715
590
 
716
591
 
717
592
  def task_card(world: ToolsWorld) -> dict:
718
- """What an outside agent is handed about the session's task: ``{task,
719
- prompt, tools, contracts, verifiers, worlds}`` — ``tools`` the served names,
720
- ``contracts`` each one's description and input schema, ``verifiers`` the
721
- root's that grade, ``worlds`` each dependency alias to the verifiers of its
722
- own that grade (``slack/message_posted`` in the grade's ``rewards``)."""
723
593
  task = world.task
724
594
  contracts = tool_contracts(world.version.bundle)
725
595
  for alias, dep in world.dependencies.items():