@withgateway/sdk 0.2.4 → 0.2.6
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.
- package/dist/cli.js +4304 -2381
- package/dist/cli.js.map +1 -1
- package/dist/cli.mjs +4266 -2343
- package/dist/cli.mjs.map +1 -1
- package/dist/files/index.js +56 -31
- package/dist/files/index.js.map +1 -1
- package/dist/files/index.mjs +52 -27
- package/dist/files/index.mjs.map +1 -1
- package/dist/hooks/index.d.mts +1 -1
- package/dist/hooks/index.d.ts +1 -1
- package/dist/hooks/index.js +280 -8
- package/dist/hooks/index.js.map +1 -1
- package/dist/hooks/index.mjs +272 -8
- package/dist/hooks/index.mjs.map +1 -1
- package/dist/{index-1xnxt0Cc.d.ts → index-BO2SNSgy.d.ts} +12 -1
- package/dist/{index-B0R3IgsV.d.mts → index-BaKu5ZSU.d.mts} +124 -2
- package/dist/{index-B0R3IgsV.d.ts → index-BaKu5ZSU.d.ts} +124 -2
- package/dist/{index-C1wDEwH4.d.mts → index-Cz8Q6Keo.d.mts} +12 -1
- package/dist/index.d.mts +4 -4
- package/dist/index.d.ts +4 -4
- package/dist/index.js +1100 -438
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +1079 -424
- package/dist/index.mjs.map +1 -1
- package/dist/traces/index.js +45 -20
- package/dist/traces/index.js.map +1 -1
- package/dist/traces/index.mjs +41 -16
- package/dist/traces/index.mjs.map +1 -1
- package/dist/tracing/index.d.mts +1 -1
- package/dist/tracing/index.d.ts +1 -1
- package/dist/tracing/index.js +98 -61
- package/dist/tracing/index.js.map +1 -1
- package/dist/tracing/index.mjs +98 -61
- package/dist/tracing/index.mjs.map +1 -1
- package/dist/worlds/index.d.mts +179 -25
- package/dist/worlds/index.d.ts +179 -25
- package/dist/worlds/index.js +639 -284
- package/dist/worlds/index.js.map +1 -1
- package/dist/worlds/index.mjs +631 -276
- package/dist/worlds/index.mjs.map +1 -1
- package/package.json +2 -1
- package/runtime/gatewaysdk/environment/_bundle.py +15 -25
- package/runtime/gatewaysdk/environment/_materialize.py +53 -9
- package/runtime/gatewaysdk/environment/_toml.py +13 -0
- package/runtime/gatewaysdk/environment/schema/api.py +40 -25
- package/runtime/gatewaysdk/environment/schema/batch.py +15 -11
- package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +24 -0
- package/runtime/gatewaysdk/environment/schema/compiler.py +60 -28
- package/runtime/gatewaysdk/environment/schema/conform.py +1 -1
- package/runtime/gatewaysdk/environment/schema/connector.py +1 -1
- package/runtime/gatewaysdk/environment/schema/connectors/google-drive/readers/merge.ingest.toml +25 -0
- package/runtime/gatewaysdk/environment/schema/connectors/google-drive/readers/merge.toml +17 -0
- package/runtime/gatewaysdk/environment/schema/data.py +21 -19
- package/runtime/gatewaysdk/environment/schema/extract.py +1 -5
- package/runtime/gatewaysdk/environment/schema/grading.py +225 -0
- package/runtime/gatewaysdk/environment/schema/host.py +156 -546
- package/runtime/gatewaysdk/environment/schema/host_surfaces.py +1 -5
- package/runtime/gatewaysdk/environment/schema/ingest.py +3 -11
- package/runtime/gatewaysdk/environment/schema/local.py +32 -126
- package/runtime/gatewaysdk/environment/schema/mapping.py +1 -1
- package/runtime/gatewaysdk/environment/schema/platform.py +30 -26
- package/runtime/gatewaysdk/environment/schema/proof.py +237 -0
- package/runtime/gatewaysdk/environment/schema/redaction.py +1 -1
- package/runtime/gatewaysdk/environment/schema/runtime.py +686 -0
- package/runtime/gatewaysdk/environment/schema/scaffold.py +9 -2
- package/runtime/gatewaysdk/environment/schema/skill.py +1 -0
- package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +67 -9
- package/runtime/gatewaysdk/environment/schema/skills/hooks-getting-started/SKILL.md +67 -6
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +4 -1
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +11 -11
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +17 -1
- package/runtime/gatewaysdk/environment/schema/snapshot.py +1 -5
- package/runtime/gatewaysdk/environment/schema/tools_world.py +71 -23
- package/runtime/gatewaysdk/environment/schema/ui.py +1 -5
- package/runtime/gatewaysdk/environment/schema/verbs.py +136 -0
- package/runtime/gatewaysdk/environment/schema/workers.py +14 -0
- package/runtime/gatewaysdk/environment/schema/world_tests.py +1 -1
- package/runtime/gatewaysdk/environment/world.py +507 -0
- package/skills/benchmarks-getting-started/SKILL.md +67 -9
- package/skills/connector-schema-authoring/connector-worlds.md +8 -1
- package/skills/connector-schema-authoring/world-schema.md +1 -1
- package/skills/hooks-getting-started/SKILL.md +67 -6
- package/skills/world-data-ingestion/SKILL.md +4 -1
- package/skills/worlds-getting-started/SKILL.md +11 -11
- package/skills/worlds-getting-started/references/cli-mcp-map.md +17 -1
|
@@ -0,0 +1,686 @@
|
|
|
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
|
+
from __future__ import annotations
|
|
26
|
+
|
|
27
|
+
import fcntl
|
|
28
|
+
import json
|
|
29
|
+
import shutil
|
|
30
|
+
import uuid
|
|
31
|
+
from abc import ABC, abstractmethod
|
|
32
|
+
from collections.abc import Callable, Iterable
|
|
33
|
+
from pathlib import Path
|
|
34
|
+
from typing import TYPE_CHECKING, Any, Optional
|
|
35
|
+
|
|
36
|
+
from . import snapshot as snapshots
|
|
37
|
+
from .api import WorldApp, WorldState, operation_request, vendor_credential, with_query
|
|
38
|
+
from .dependencies import Dependency
|
|
39
|
+
from .grading import Grade, GraderError, TaskGrader
|
|
40
|
+
from .snapshot import SCENARIOS
|
|
41
|
+
from .tasks import TASK_DIR, TaskSpec, unknown_task_entities, write_task_dir
|
|
42
|
+
from .tools_world import DependencyWorld, ToolsWorld, ToolsWorldState, inline_task, served_with_dependencies
|
|
43
|
+
from .validation import fail
|
|
44
|
+
from .workers import ConfinedVerifierSandbox
|
|
45
|
+
|
|
46
|
+
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"
|
|
52
|
+
|
|
53
|
+
Restorer = Callable[[Callable[[Path], None]], bool]
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
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
|
+
def __init__(
|
|
61
|
+
self,
|
|
62
|
+
cached: CachedVersion,
|
|
63
|
+
session_dir: Path,
|
|
64
|
+
*,
|
|
65
|
+
task: str | None,
|
|
66
|
+
spec: TaskSpec | None,
|
|
67
|
+
token: str | None,
|
|
68
|
+
) -> None:
|
|
69
|
+
self.cached = cached
|
|
70
|
+
self.session_dir = Path(session_dir)
|
|
71
|
+
self.task = task
|
|
72
|
+
self.task_spec = spec
|
|
73
|
+
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
|
+
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
|
|
81
|
+
self.restored = False
|
|
82
|
+
|
|
83
|
+
# -- what the shape knows before a session opens ------------------------ #
|
|
84
|
+
|
|
85
|
+
@classmethod
|
|
86
|
+
@abstractmethod
|
|
87
|
+
def served_by(cls, cached: CachedVersion, dependencies: dict[str, DependencyWorld]) -> list[str]:
|
|
88
|
+
"""Every name a session task on ``cached`` may allow."""
|
|
89
|
+
|
|
90
|
+
@classmethod
|
|
91
|
+
@abstractmethod
|
|
92
|
+
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."""
|
|
95
|
+
|
|
96
|
+
@classmethod
|
|
97
|
+
def declared_dependencies(cls, cached: CachedVersion) -> dict[str, Dependency]:
|
|
98
|
+
"""The ``[dependencies]`` the version's manifest declares, by alias."""
|
|
99
|
+
return {}
|
|
100
|
+
|
|
101
|
+
# -- construction ------------------------------------------------------ #
|
|
102
|
+
|
|
103
|
+
@classmethod
|
|
104
|
+
def open(
|
|
105
|
+
cls,
|
|
106
|
+
cached: CachedVersion,
|
|
107
|
+
session_dir: Path,
|
|
108
|
+
*,
|
|
109
|
+
task: str | None,
|
|
110
|
+
spec: TaskSpec | None,
|
|
111
|
+
token: str | None,
|
|
112
|
+
dependencies: dict[str, DependencyWorld],
|
|
113
|
+
restore: Restorer,
|
|
114
|
+
) -> 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)
|
|
119
|
+
runtime._start(dependencies)
|
|
120
|
+
try:
|
|
121
|
+
if spec is not None:
|
|
122
|
+
runtime._check_task_entities(spec)
|
|
123
|
+
# Under the session, where a grade and a restart find the task.
|
|
124
|
+
write_task_dir(spec, runtime.session_dir)
|
|
125
|
+
runtime._to_start()
|
|
126
|
+
runtime.restored = restore(runtime.restore)
|
|
127
|
+
runtime._attach_app()
|
|
128
|
+
except BaseException:
|
|
129
|
+
runtime.close()
|
|
130
|
+
raise
|
|
131
|
+
return runtime
|
|
132
|
+
|
|
133
|
+
def _attach_app(self) -> None:
|
|
134
|
+
cached = self.cached
|
|
135
|
+
if cached.spec is None:
|
|
136
|
+
return
|
|
137
|
+
# ``handlers={}`` for a code-free world: WorldApp would otherwise
|
|
138
|
+
# import the module itself, and only a worker may do that.
|
|
139
|
+
self.app = WorldApp(
|
|
140
|
+
self._app_state(),
|
|
141
|
+
cached.router(),
|
|
142
|
+
self.token,
|
|
143
|
+
handlers=cached.handlers or {},
|
|
144
|
+
allowed=self.allowed,
|
|
145
|
+
)
|
|
146
|
+
self.grant = client_grant(self.app, self.token)
|
|
147
|
+
|
|
148
|
+
@property
|
|
149
|
+
def allowed(self) -> frozenset[str] | None:
|
|
150
|
+
spec = self.task_spec
|
|
151
|
+
return frozenset(spec.tools) if spec is not None and spec.tools is not None else None
|
|
152
|
+
|
|
153
|
+
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."""
|
|
158
|
+
defined = self.entity_names()
|
|
159
|
+
unknown = unknown_task_entities(spec, defined)
|
|
160
|
+
if unknown:
|
|
161
|
+
fail(
|
|
162
|
+
"task",
|
|
163
|
+
f"the task names {', '.join(unknown)}, which this world does not define; "
|
|
164
|
+
f"its entities are {', '.join(sorted(defined)) or 'none'}",
|
|
165
|
+
"/task",
|
|
166
|
+
)
|
|
167
|
+
|
|
168
|
+
# -- what a subclass supplies ------------------------------------------ #
|
|
169
|
+
|
|
170
|
+
@abstractmethod
|
|
171
|
+
def _start(self, dependencies: dict[str, DependencyWorld]) -> None:
|
|
172
|
+
"""Bring the store up. A failure here leaves nothing to close."""
|
|
173
|
+
|
|
174
|
+
def _to_start(self) -> None:
|
|
175
|
+
"""Lay the task's starting state on the store, when :meth:`_start` did not."""
|
|
176
|
+
|
|
177
|
+
@abstractmethod
|
|
178
|
+
def _app_state(self) -> Any:
|
|
179
|
+
"""The :class:`api.WorldState` the routes read and write."""
|
|
180
|
+
|
|
181
|
+
@abstractmethod
|
|
182
|
+
def entity_names(self) -> list[str]:
|
|
183
|
+
"""Every entity a grader may name (a dependency's as ``alias.entity``)."""
|
|
184
|
+
|
|
185
|
+
@abstractmethod
|
|
186
|
+
def served(self) -> list[str]:
|
|
187
|
+
"""Every name :meth:`call` answers: tools, operations, a dependency's ``alias.tool``."""
|
|
188
|
+
|
|
189
|
+
@abstractmethod
|
|
190
|
+
def reset(self) -> dict: ...
|
|
191
|
+
|
|
192
|
+
@abstractmethod
|
|
193
|
+
def seed(self, rows: dict, mode: str, redact: str) -> dict: ...
|
|
194
|
+
|
|
195
|
+
@abstractmethod
|
|
196
|
+
def _rows(self) -> dict:
|
|
197
|
+
"""The state without the calls: rows by entity, and what the store started from."""
|
|
198
|
+
|
|
199
|
+
@abstractmethod
|
|
200
|
+
def _grader_rows(self) -> dict:
|
|
201
|
+
"""The rows as a session task's grader reads them (keyed by primary key)."""
|
|
202
|
+
|
|
203
|
+
@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."""
|
|
208
|
+
|
|
209
|
+
@abstractmethod
|
|
210
|
+
def _bundled_verifier(self) -> Path | None:
|
|
211
|
+
"""The ``verify.py`` of the bundled task, when the version carries one."""
|
|
212
|
+
|
|
213
|
+
@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."""
|
|
216
|
+
|
|
217
|
+
@abstractmethod
|
|
218
|
+
def export(self, destination: Path) -> Path: ...
|
|
219
|
+
|
|
220
|
+
@abstractmethod
|
|
221
|
+
def restore(self, source: Path) -> None: ...
|
|
222
|
+
|
|
223
|
+
@abstractmethod
|
|
224
|
+
def close(self) -> None: ...
|
|
225
|
+
|
|
226
|
+
@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
|
|
236
|
+
|
|
237
|
+
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())
|
|
247
|
+
if report is not None:
|
|
248
|
+
state["report"] = report
|
|
249
|
+
return state
|
|
250
|
+
|
|
251
|
+
def grade(self, report: Optional[str] = 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
|
+
spec = self.task_spec
|
|
259
|
+
if spec is None or spec.grader is None:
|
|
260
|
+
bundled = self.bundled_grade()
|
|
261
|
+
if bundled is not None:
|
|
262
|
+
return bundled
|
|
263
|
+
grader = self._task_grader(spec)
|
|
264
|
+
if grader is None:
|
|
265
|
+
return Grade(None).as_dict()
|
|
266
|
+
try:
|
|
267
|
+
return grader.grade(self.grader_state(report)).as_dict()
|
|
268
|
+
except GraderError as error:
|
|
269
|
+
fail("host", str(error))
|
|
270
|
+
raise AssertionError # fail() never returns
|
|
271
|
+
|
|
272
|
+
def _task_grader(self, spec: Optional[TaskSpec]) -> Optional[TaskGrader]:
|
|
273
|
+
"""The session's grader: the spec's, with its verify.py where
|
|
274
|
+
:func:`write_task_dir` put it; else the bundled task's verify.py; else
|
|
275
|
+
none (an ungraded task grades null)."""
|
|
276
|
+
sandbox = ConfinedVerifierSandbox()
|
|
277
|
+
home = self.session_dir / "verify"
|
|
278
|
+
if spec is not None:
|
|
279
|
+
if spec.grader is None:
|
|
280
|
+
return None
|
|
281
|
+
verify = self.session_dir / TASK_DIR / "checks" / "verify.py"
|
|
282
|
+
return TaskGrader(spec.grader, verify=verify, sandbox=sandbox, home=home)
|
|
283
|
+
verify = self._bundled_verifier()
|
|
284
|
+
if verify is None or not verify.is_file():
|
|
285
|
+
return None
|
|
286
|
+
return TaskGrader.for_verifier(verify, sandbox=sandbox, home=home)
|
|
287
|
+
|
|
288
|
+
def call(self, tool: str, args: dict) -> dict:
|
|
289
|
+
"""One name of what the session serves: a tool by name (a dependency's
|
|
290
|
+
as ``alias.tool``); on a tree with connector.toml, an operation by name
|
|
291
|
+
too, answered by its route over the same store, ``{status, body}`` the
|
|
292
|
+
route's own. A name that is both is the tool's."""
|
|
293
|
+
answer = self._call_tool(tool, args)
|
|
294
|
+
if answer is not None:
|
|
295
|
+
return answer
|
|
296
|
+
if self.app is None:
|
|
297
|
+
fail("host", f"unknown tool '{tool}'; this world serves: {', '.join(sorted(self.served())) or '(none)'}")
|
|
298
|
+
raise AssertionError # fail() never returns
|
|
299
|
+
return call_operation(
|
|
300
|
+
self.app, tool, args, self.token or WORLD_AUTH_SENTINEL, allowed=self.allowed, grant=self.grant
|
|
301
|
+
)
|
|
302
|
+
|
|
303
|
+
def credential(self) -> tuple[dict[str, str], dict[str, str]]:
|
|
304
|
+
"""(headers, query) carrying the world's own credential for this
|
|
305
|
+
session: the session token in the vendor's shape, or for an oauth2
|
|
306
|
+
world the grant the host minted for itself."""
|
|
307
|
+
assert self.app is not None, "a world of tools alone has no http surface to present a credential on"
|
|
308
|
+
return vendor_credential(self.app.router.spec, self.token or WORLD_AUTH_SENTINEL, grant=self.grant)
|
|
309
|
+
|
|
310
|
+
|
|
311
|
+
class TreeRuntime(WorldRuntime):
|
|
312
|
+
"""A schema world stored as itself: :class:`ToolsWorld` over a copy of the
|
|
313
|
+
version's template, beside a copy of each dependency's, graded by the
|
|
314
|
+
version's SQL verifiers unless the session's own task brings a grader."""
|
|
315
|
+
|
|
316
|
+
world: ToolsWorld
|
|
317
|
+
|
|
318
|
+
@classmethod
|
|
319
|
+
def served_by(cls, cached: CachedVersion, dependencies: dict[str, DependencyWorld]) -> list[str]:
|
|
320
|
+
assert cached.tools is not None
|
|
321
|
+
return served_with_dependencies(cached.tools, dependencies)
|
|
322
|
+
|
|
323
|
+
@classmethod
|
|
324
|
+
def authored_code(cls, cached: CachedVersion) -> str:
|
|
325
|
+
return "schema world handlers" # its tools ARE handlers
|
|
326
|
+
|
|
327
|
+
@classmethod
|
|
328
|
+
def declared_dependencies(cls, cached: CachedVersion) -> dict[str, Dependency]:
|
|
329
|
+
assert cached.tools is not None
|
|
330
|
+
return cached.tools.dependencies
|
|
331
|
+
|
|
332
|
+
def _start(self, dependencies: dict[str, DependencyWorld]) -> None:
|
|
333
|
+
tools = self.cached.tools
|
|
334
|
+
assert tools is not None
|
|
335
|
+
spec = self.task_spec
|
|
336
|
+
if spec is not None:
|
|
337
|
+
self.world = ToolsWorld(
|
|
338
|
+
tools,
|
|
339
|
+
self.session_dir,
|
|
340
|
+
inline_task(spec),
|
|
341
|
+
seed=spec.seed,
|
|
342
|
+
allowed=self.allowed,
|
|
343
|
+
dependencies=dependencies,
|
|
344
|
+
)
|
|
345
|
+
return
|
|
346
|
+
assert self.task is not None
|
|
347
|
+
self.world = ToolsWorld(tools, self.session_dir, self.task, dependencies=dependencies)
|
|
348
|
+
|
|
349
|
+
def _app_state(self) -> ToolsWorldState:
|
|
350
|
+
return ToolsWorldState(self.world, self.cached.tree)
|
|
351
|
+
|
|
352
|
+
def entity_names(self) -> list[str]:
|
|
353
|
+
return self.world.entity_names()
|
|
354
|
+
|
|
355
|
+
def served(self) -> list[str]:
|
|
356
|
+
return list(self.world.served)
|
|
357
|
+
|
|
358
|
+
def reset(self) -> dict:
|
|
359
|
+
return self.world.reset()
|
|
360
|
+
|
|
361
|
+
def seed(self, rows: dict, mode: str, redact: str) -> dict:
|
|
362
|
+
if redact != "off":
|
|
363
|
+
fail("host", "a schema world has no [redact] policy; seed it with redact=off")
|
|
364
|
+
return self.world.seed({"rows": rows, "mode": mode})
|
|
365
|
+
|
|
366
|
+
def _rows(self) -> dict:
|
|
367
|
+
return self.world.state()
|
|
368
|
+
|
|
369
|
+
def _grader_rows(self) -> dict:
|
|
370
|
+
return self.world.grader_state()
|
|
371
|
+
|
|
372
|
+
def bundled_grade(self) -> dict | None:
|
|
373
|
+
return None if self.world.task.verify is not None else self.world.grade()
|
|
374
|
+
|
|
375
|
+
def _bundled_verifier(self) -> Path | None:
|
|
376
|
+
return self.world.task.verify
|
|
377
|
+
|
|
378
|
+
def _call_tool(self, tool: str, args: dict) -> dict | None:
|
|
379
|
+
version = self.world.version
|
|
380
|
+
if self.app is not None and tool not in version.tool_names and tool in self.app.router.spec.operations:
|
|
381
|
+
return None
|
|
382
|
+
return self.world.call(tool, args)
|
|
383
|
+
|
|
384
|
+
def export(self, destination: Path) -> Path:
|
|
385
|
+
return self.world.export(destination)
|
|
386
|
+
|
|
387
|
+
def restore(self, source: Path) -> None:
|
|
388
|
+
self.world.restore(source)
|
|
389
|
+
|
|
390
|
+
def close(self) -> None:
|
|
391
|
+
self.world.close()
|
|
392
|
+
|
|
393
|
+
def task_card(self) -> dict:
|
|
394
|
+
return task_card(self.world)
|
|
395
|
+
|
|
396
|
+
|
|
397
|
+
# --------------------------------------------------------------------------- #
|
|
398
|
+
# READ PATH, marked for deletion (handoff step 6): the api-bundle runtime and
|
|
399
|
+
# the reflink-cloned store under it. Nothing new is stored in this shape.
|
|
400
|
+
# --------------------------------------------------------------------------- #
|
|
401
|
+
|
|
402
|
+
_FICLONE = 0x40049409 # ioctl: clone one file's extents into another (btrfs/XFS)
|
|
403
|
+
|
|
404
|
+
|
|
405
|
+
def clone_file(src: Path, dst: Path) -> None:
|
|
406
|
+
"""Copy ``src`` to ``dst`` cheaply. A reflink (``FICLONE``) shares the
|
|
407
|
+
version snapshot's blocks copy-on-write, so opening a session costs the
|
|
408
|
+
same whatever the snapshot's size; a filesystem without reflink falls back
|
|
409
|
+
to a plain copy, which is what the pod engine does today."""
|
|
410
|
+
dst.parent.mkdir(parents=True, exist_ok=True)
|
|
411
|
+
try:
|
|
412
|
+
with open(src, "rb") as s, open(dst, "wb") as d:
|
|
413
|
+
fcntl.ioctl(d.fileno(), _FICLONE, s.fileno())
|
|
414
|
+
return
|
|
415
|
+
except OSError:
|
|
416
|
+
pass # not supported here (tmpfs, ext4, cross-device) — copy instead
|
|
417
|
+
shutil.copyfile(src, dst)
|
|
418
|
+
|
|
419
|
+
|
|
420
|
+
def scenario_dir(bundle: Path, tree: Path, task: str) -> Path | None:
|
|
421
|
+
"""A bundled task's scenario directory, checked at the bundle root first
|
|
422
|
+
(where ``build_api_bundle`` writes them) then in the tree."""
|
|
423
|
+
for root in (bundle / SCENARIOS / task, tree / SCENARIOS / task):
|
|
424
|
+
if (root / "scenario.toml").is_file():
|
|
425
|
+
return root
|
|
426
|
+
return None
|
|
427
|
+
|
|
428
|
+
|
|
429
|
+
class HostWorldState(WorldState):
|
|
430
|
+
"""A session's world, opened by cloning the version's cached snapshot into a
|
|
431
|
+
file on the host's own volume — the reflink is the whole per-session cost.
|
|
432
|
+
Otherwise a plain :class:`WorldState`."""
|
|
433
|
+
|
|
434
|
+
def __init__(self, cached: CachedVersion, session_dir: Path):
|
|
435
|
+
self._session_dir = Path(session_dir)
|
|
436
|
+
self._session_dir.mkdir(parents=True, exist_ok=True)
|
|
437
|
+
self._cached = cached
|
|
438
|
+
self._database: Path | None = None
|
|
439
|
+
super().__init__(cached.tree)
|
|
440
|
+
|
|
441
|
+
@property
|
|
442
|
+
def session_dir(self) -> Path:
|
|
443
|
+
return self._session_dir
|
|
444
|
+
|
|
445
|
+
def _open(self, snapshot: Path | None, *, initial: bool = True) -> None:
|
|
446
|
+
# A snapshot start is a clone of the version's cached snapshot into this
|
|
447
|
+
# session's file; the legacy no-snapshot path stays as the base class runs it.
|
|
448
|
+
if snapshot is None:
|
|
449
|
+
return super()._open(None, initial=initial)
|
|
450
|
+
if self.store is not None:
|
|
451
|
+
self.store.close()
|
|
452
|
+
if self._database is not None:
|
|
453
|
+
self._database.unlink(missing_ok=True)
|
|
454
|
+
database = self._session_dir / f"{uuid.uuid4().hex}.db"
|
|
455
|
+
clone_file(snapshot, database)
|
|
456
|
+
self.store = snapshots.SQLiteStore.open(database, self.contract, audit=False)
|
|
457
|
+
self._database = database
|
|
458
|
+
|
|
459
|
+
def export(self, destination: Path) -> Path:
|
|
460
|
+
"""The session's state as one sqlite file: the store's own audited
|
|
461
|
+
online backup, consistent while requests keep writing."""
|
|
462
|
+
assert self.store is not None
|
|
463
|
+
with self._lock:
|
|
464
|
+
return self.store.snapshot(destination)
|
|
465
|
+
|
|
466
|
+
def restore(self, source: Path) -> None:
|
|
467
|
+
"""Continue from a file :meth:`export` wrote. The file is audited row by
|
|
468
|
+
row on open: it came over the network, not from this store."""
|
|
469
|
+
with self._lock:
|
|
470
|
+
if self.store is not None:
|
|
471
|
+
self.store.close()
|
|
472
|
+
if self._database is not None:
|
|
473
|
+
self._database.unlink(missing_ok=True)
|
|
474
|
+
database = self._session_dir / f"{uuid.uuid4().hex}.db"
|
|
475
|
+
clone_file(source, database)
|
|
476
|
+
self.store = snapshots.SQLiteStore.open(database, self.contract, audit=True)
|
|
477
|
+
self._database = database
|
|
478
|
+
|
|
479
|
+
def close(self) -> None:
|
|
480
|
+
super().close()
|
|
481
|
+
shutil.rmtree(self._session_dir, ignore_errors=True)
|
|
482
|
+
|
|
483
|
+
|
|
484
|
+
class SnapshotRuntime(WorldRuntime):
|
|
485
|
+
"""An api bundle: :class:`HostWorldState` cloned from the version's compiled
|
|
486
|
+
snapshot, the bundled task's scenario overlay (or the session task's seed)
|
|
487
|
+
on top, graded by the scenario's ``verify.py``. READ PATH — see above."""
|
|
488
|
+
|
|
489
|
+
state_: HostWorldState
|
|
490
|
+
|
|
491
|
+
@classmethod
|
|
492
|
+
def served_by(cls, cached: CachedVersion, dependencies: dict[str, DependencyWorld]) -> list[str]:
|
|
493
|
+
assert cached.spec is not None
|
|
494
|
+
return list(cached.spec.operations)
|
|
495
|
+
|
|
496
|
+
@classmethod
|
|
497
|
+
def authored_code(cls, cached: CachedVersion) -> str | None:
|
|
498
|
+
if cached.settings is None or cached.settings.handlers is None:
|
|
499
|
+
return None
|
|
500
|
+
return f"api handlers module {cached.settings.handlers.name}"
|
|
501
|
+
|
|
502
|
+
def _start(self, dependencies: dict[str, DependencyWorld]) -> None:
|
|
503
|
+
if dependencies:
|
|
504
|
+
fail(
|
|
505
|
+
"host",
|
|
506
|
+
f"version {self.cached.version_id} is an api bundle; only a schema world opens beside dependencies",
|
|
507
|
+
)
|
|
508
|
+
assert self.cached.snapshot is not None
|
|
509
|
+
self.state_ = HostWorldState(self.cached, self.session_dir)
|
|
510
|
+
|
|
511
|
+
def _to_start(self) -> None:
|
|
512
|
+
"""The task's starting state on a fresh clone: the session task's seed,
|
|
513
|
+
else the bundled task's scenario overlay. The compiled snapshot the
|
|
514
|
+
session is cloned from IS the base state, so a scenario with no seed
|
|
515
|
+
overlay (the synthesized ``default``) needs nothing."""
|
|
516
|
+
spec = self.task_spec
|
|
517
|
+
if spec is not None:
|
|
518
|
+
if spec.seed is not None:
|
|
519
|
+
self.state_.seed_live(spec.seed["rows"], spec.seed["mode"], spec.seed.get("redact", "off"))
|
|
520
|
+
return
|
|
521
|
+
assert self.task is not None
|
|
522
|
+
scenario = scenario_dir(self.cached.bundle, self.cached.tree, self.task)
|
|
523
|
+
if scenario is None:
|
|
524
|
+
if self.task in self.state_.scenarios():
|
|
525
|
+
self.state_.apply_scenario(self.task) # a tree-authored scenario
|
|
526
|
+
return
|
|
527
|
+
fail(
|
|
528
|
+
"host",
|
|
529
|
+
f"no scenario '{self.task}' in this world; it has {', '.join(self.state_.scenarios()) or 'default'}",
|
|
530
|
+
)
|
|
531
|
+
overlay = snapshots.scenario_overlay(scenario)
|
|
532
|
+
if not overlay:
|
|
533
|
+
return # base state; the cloned snapshot already holds it
|
|
534
|
+
digest = self.state_.digest
|
|
535
|
+
if digest is None:
|
|
536
|
+
fail("host", "a scenario overlay needs a compiled snapshot to apply against")
|
|
537
|
+
self.state_.seed({"base": digest, "rows": overlay, "mode": "replace"})
|
|
538
|
+
|
|
539
|
+
def _app_state(self) -> HostWorldState:
|
|
540
|
+
return self.state_
|
|
541
|
+
|
|
542
|
+
def entity_names(self) -> list[str]:
|
|
543
|
+
return list(self.state_.contract.entities)
|
|
544
|
+
|
|
545
|
+
def served(self) -> list[str]:
|
|
546
|
+
spec = self.cached.spec
|
|
547
|
+
return sorted(spec.operations) if spec is not None else []
|
|
548
|
+
|
|
549
|
+
def reset(self) -> dict:
|
|
550
|
+
# Back to the task's starting state: re-clone the snapshot, then
|
|
551
|
+
# re-apply the task's seed or the scenario overlay if it had one.
|
|
552
|
+
self.state_.reset()
|
|
553
|
+
self._to_start()
|
|
554
|
+
return {"reset": True}
|
|
555
|
+
|
|
556
|
+
def seed(self, rows: dict, mode: str, redact: str) -> dict:
|
|
557
|
+
# Onto the live state, the way the runner's session seed lands: an
|
|
558
|
+
# append upserts by key, a replace swaps the named entities.
|
|
559
|
+
self.state_.seed_live(rows, mode, redact)
|
|
560
|
+
return {
|
|
561
|
+
"seeded": sum(len(v) for v in rows.values()),
|
|
562
|
+
"mode": mode,
|
|
563
|
+
**({"redact": redact} if redact != "off" else {}),
|
|
564
|
+
"entity_counts": {
|
|
565
|
+
entity: len(self.state_.rows(entity)) for entity in rows if entity in self.state_.contract.entities
|
|
566
|
+
},
|
|
567
|
+
}
|
|
568
|
+
|
|
569
|
+
def _rows(self) -> dict:
|
|
570
|
+
return {**self.state_.dump(), "snapshot": self.state_.describe_snapshot()}
|
|
571
|
+
|
|
572
|
+
def _grader_rows(self) -> dict:
|
|
573
|
+
return self._rows()
|
|
574
|
+
|
|
575
|
+
def bundled_grade(self) -> dict | None:
|
|
576
|
+
return None
|
|
577
|
+
|
|
578
|
+
def _bundled_verifier(self) -> Path | None:
|
|
579
|
+
assert self.task is not None
|
|
580
|
+
scenario = scenario_dir(self.cached.bundle, self.cached.tree, self.task)
|
|
581
|
+
return scenario / "checks" / "verify.py" if scenario else None
|
|
582
|
+
|
|
583
|
+
def _call_tool(self, tool: str, args: dict) -> dict | None:
|
|
584
|
+
return None
|
|
585
|
+
|
|
586
|
+
def export(self, destination: Path) -> Path:
|
|
587
|
+
return self.state_.export(destination)
|
|
588
|
+
|
|
589
|
+
def restore(self, source: Path) -> None:
|
|
590
|
+
self.state_.restore(source)
|
|
591
|
+
|
|
592
|
+
def close(self) -> None:
|
|
593
|
+
self.state_.close()
|
|
594
|
+
|
|
595
|
+
def task_card(self) -> dict:
|
|
596
|
+
spec = self.task_spec
|
|
597
|
+
return {
|
|
598
|
+
"task": self.task if spec is None else spec.name,
|
|
599
|
+
"prompt": spec.instruction if spec is not None else None,
|
|
600
|
+
"tools": self.served(),
|
|
601
|
+
"contracts": {},
|
|
602
|
+
"verifiers": [],
|
|
603
|
+
"worlds": {},
|
|
604
|
+
"metadata": {},
|
|
605
|
+
}
|
|
606
|
+
|
|
607
|
+
|
|
608
|
+
# --------------------------------------------------------------------------- #
|
|
609
|
+
# Shared by the runtimes and the local session: an operation by name, the
|
|
610
|
+
# client grant, the task card.
|
|
611
|
+
# --------------------------------------------------------------------------- #
|
|
612
|
+
|
|
613
|
+
|
|
614
|
+
def client_grant(app: WorldApp | None, credential: str | None) -> str | None:
|
|
615
|
+
"""The bearer an ``oauth2`` world's routes take when the session itself
|
|
616
|
+
calls them (the page's api prefix, an operation by name); None for any
|
|
617
|
+
other scheme, or when the world refuses the client-credentials grant."""
|
|
618
|
+
if app is None or app.router.spec.scheme != "oauth2":
|
|
619
|
+
return None
|
|
620
|
+
issued = app.router.issue_token({"grant_type": "client_credentials", "client_secret": credential or ""}, credential)
|
|
621
|
+
return issued["access_token"] if issued else None
|
|
622
|
+
|
|
623
|
+
|
|
624
|
+
def call_operation(
|
|
625
|
+
app: WorldApp,
|
|
626
|
+
name: str,
|
|
627
|
+
args: dict,
|
|
628
|
+
credential: str,
|
|
629
|
+
*,
|
|
630
|
+
allowed: Iterable[str] | None = None,
|
|
631
|
+
grant: str | None = None,
|
|
632
|
+
) -> dict:
|
|
633
|
+
"""An operation of connector.toml called by name (:func:`operation_request`
|
|
634
|
+
reads the args: ``path``/``query``/``body``, or leftover top-level keys as
|
|
635
|
+
the body); the world's own credential is presented, as the host presents a
|
|
636
|
+
session's. The answer is the route's ``{status, body}``."""
|
|
637
|
+
spec = app.router.spec
|
|
638
|
+
operation = spec.operations.get(name)
|
|
639
|
+
if operation is None:
|
|
640
|
+
known = ", ".join(sorted(spec.operations)) or "(none)"
|
|
641
|
+
fail("host", f"unknown tool '{name}'; this world serves: {known}")
|
|
642
|
+
if allowed is not None and name not in allowed:
|
|
643
|
+
fail(
|
|
644
|
+
"tool_not_allowed",
|
|
645
|
+
f"tool '{name}' is not allowed by this session's task; it allows: {', '.join(sorted(allowed))}",
|
|
646
|
+
)
|
|
647
|
+
method, target, raw = operation_request(spec, operation, args)
|
|
648
|
+
headers, credential_query = vendor_credential(spec, credential, grant=grant)
|
|
649
|
+
status, answer, _ = app.handle(
|
|
650
|
+
method, with_query(target, credential_query), {"content-type": "application/json", **headers}, raw, "127.0.0.1"
|
|
651
|
+
)
|
|
652
|
+
return {"status": status, "body": answer}
|
|
653
|
+
|
|
654
|
+
|
|
655
|
+
def tool_contracts(bundle: Path, prefix: str = "") -> dict[str, dict]:
|
|
656
|
+
"""Each compiled tool's ``{description, input}`` from the bundle's
|
|
657
|
+
``tool-schemas.json`` (refs inlined by the compiler), keyed by served name."""
|
|
658
|
+
path = bundle / "tool-schemas.json"
|
|
659
|
+
if not path.is_file():
|
|
660
|
+
return {}
|
|
661
|
+
tools = json.loads(path.read_text(encoding="utf-8")).get("tools") or {}
|
|
662
|
+
return {
|
|
663
|
+
f"{prefix}{name}": {"description": str(entry.get("description") or ""), "input": entry.get("input_schema")}
|
|
664
|
+
for name, entry in tools.items()
|
|
665
|
+
}
|
|
666
|
+
|
|
667
|
+
|
|
668
|
+
def task_card(world: ToolsWorld) -> dict:
|
|
669
|
+
"""What an outside agent is handed about the session's task: ``{task,
|
|
670
|
+
prompt, tools, contracts, verifiers, worlds}`` — ``tools`` the served names,
|
|
671
|
+
``contracts`` each one's description and input schema, ``verifiers`` the
|
|
672
|
+
root's that grade, ``worlds`` each dependency alias to the verifiers of its
|
|
673
|
+
own that grade (``slack/message_posted`` in the grade's ``rewards``)."""
|
|
674
|
+
task = world.task
|
|
675
|
+
contracts = tool_contracts(world.version.bundle)
|
|
676
|
+
for alias, dep in world.dependencies.items():
|
|
677
|
+
contracts.update(tool_contracts(dep.version.bundle, f"{alias}."))
|
|
678
|
+
return {
|
|
679
|
+
"task": task.id,
|
|
680
|
+
"prompt": task.prompt,
|
|
681
|
+
"tools": list(world.served),
|
|
682
|
+
"contracts": {name: contracts[name] for name in world.served if name in contracts},
|
|
683
|
+
"verifiers": task.selected(world.version.verifiers),
|
|
684
|
+
"worlds": {alias: task.selected_of(alias, dep.version.verifiers) for alias, dep in world.dependencies.items()},
|
|
685
|
+
"metadata": dict(task.metadata),
|
|
686
|
+
}
|