@withgateway/sdk 0.3.1 → 0.3.3
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/README.md +4 -3
- package/dist/cli.js +2880 -2032
- package/dist/cli.js.map +1 -1
- package/dist/cli.mjs +2982 -2135
- package/dist/cli.mjs.map +1 -1
- package/dist/files/index.d.mts +1 -1
- package/dist/files/index.d.ts +1 -1
- package/dist/files/index.js +180 -41
- package/dist/files/index.js.map +1 -1
- package/dist/files/index.mjs +172 -35
- package/dist/files/index.mjs.map +1 -1
- package/dist/{index-CBqbB_0J.d.ts → index-DUHmS74p.d.ts} +1 -1
- package/dist/{index-D-AMnAMa.d.mts → index-mJhG3vZU.d.mts} +1 -1
- package/dist/index.d.mts +4 -4
- package/dist/index.d.ts +4 -4
- package/dist/index.js +1309 -540
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +1287 -532
- package/dist/index.mjs.map +1 -1
- package/dist/{media-CbcAfQvd.d.mts → media-BIApiPzS.d.mts} +21 -2
- package/dist/{media-CbcAfQvd.d.ts → media-BIApiPzS.d.ts} +21 -2
- package/dist/traces/index.d.mts +1 -1
- package/dist/traces/index.d.ts +1 -1
- package/dist/traces/index.js +177 -38
- package/dist/traces/index.js.map +1 -1
- package/dist/traces/index.mjs +169 -32
- package/dist/traces/index.mjs.map +1 -1
- package/dist/tracing/index.d.mts +2 -2
- package/dist/tracing/index.d.ts +2 -2
- package/dist/tracing/index.js +69 -13
- package/dist/tracing/index.js.map +1 -1
- package/dist/tracing/index.mjs +69 -13
- package/dist/tracing/index.mjs.map +1 -1
- package/dist/worlds/index.d.mts +249 -120
- package/dist/worlds/index.d.ts +249 -120
- package/dist/worlds/index.js +1240 -484
- package/dist/worlds/index.js.map +1 -1
- package/dist/worlds/index.mjs +1231 -476
- package/dist/worlds/index.mjs.map +1 -1
- package/package.json +1 -1
- package/runtime/gatewaysdk/environment/_bundle.py +2 -27
- package/runtime/gatewaysdk/environment/_materialize.py +49 -69
- package/runtime/gatewaysdk/environment/_world.py +122 -197
- package/runtime/gatewaysdk/environment/backing.py +137 -0
- package/runtime/gatewaysdk/environment/core.py +1 -1
- package/runtime/gatewaysdk/environment/legacy_sqlite.py +301 -0
- package/runtime/gatewaysdk/environment/reward_keys.py +25 -0
- package/runtime/gatewaysdk/environment/runtime.py +8 -13
- package/runtime/gatewaysdk/environment/schema/__init__.py +4 -4
- package/runtime/gatewaysdk/environment/schema/admin_routes.py +86 -0
- package/runtime/gatewaysdk/environment/schema/api.py +266 -514
- package/runtime/gatewaysdk/environment/schema/batch.py +42 -37
- package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +17 -5
- package/runtime/gatewaysdk/environment/schema/call_log.py +291 -0
- package/runtime/gatewaysdk/environment/schema/call_redaction.py +344 -0
- package/runtime/gatewaysdk/environment/schema/compiler.py +334 -158
- package/runtime/gatewaysdk/environment/schema/conform.py +8 -12
- package/runtime/gatewaysdk/environment/schema/connector.py +27 -62
- package/runtime/gatewaysdk/environment/schema/data.py +50 -207
- package/runtime/gatewaysdk/environment/schema/database/__init__.py +24 -0
- package/runtime/gatewaysdk/environment/schema/database/audit.py +121 -0
- package/runtime/gatewaysdk/environment/schema/database/base.py +995 -0
- package/runtime/gatewaysdk/environment/schema/database/budget.py +33 -0
- package/runtime/gatewaysdk/environment/schema/database/connections.py +101 -0
- package/runtime/gatewaysdk/environment/schema/database/engines.py +8 -0
- package/runtime/gatewaysdk/environment/schema/database/guard.py +208 -0
- package/runtime/gatewaysdk/environment/schema/database/ingest.py +154 -0
- package/runtime/gatewaysdk/environment/schema/database/matching.py +58 -0
- package/runtime/gatewaysdk/environment/schema/database/provenance.py +30 -0
- package/runtime/gatewaysdk/environment/schema/database/rows.py +53 -0
- package/runtime/gatewaysdk/environment/schema/database/runtime_rows.py +39 -0
- package/runtime/gatewaysdk/environment/schema/database/sqlite.py +367 -0
- package/runtime/gatewaysdk/environment/schema/domain_migration.py +236 -0
- package/runtime/gatewaysdk/environment/schema/envelope.py +169 -0
- package/runtime/gatewaysdk/environment/schema/extract.py +6 -13
- package/runtime/gatewaysdk/environment/schema/grading.py +45 -30
- package/runtime/gatewaysdk/environment/schema/handler_errors.py +142 -12
- package/runtime/gatewaysdk/environment/schema/host.py +158 -250
- package/runtime/gatewaysdk/environment/schema/lanes.py +53 -0
- package/runtime/gatewaysdk/environment/schema/local.py +44 -71
- package/runtime/gatewaysdk/environment/schema/mapping.py +5 -25
- package/runtime/gatewaysdk/environment/schema/openapi_import.py +112 -73
- package/runtime/gatewaysdk/environment/schema/openapi_paging.py +147 -0
- package/runtime/gatewaysdk/environment/schema/openapi_payloads.py +288 -0
- package/runtime/gatewaysdk/environment/schema/openapi_routes.py +97 -102
- package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +113 -30
- package/runtime/gatewaysdk/environment/schema/platform.py +123 -171
- package/runtime/gatewaysdk/environment/schema/platform_import.py +2 -3
- package/runtime/gatewaysdk/environment/schema/platform_query.py +61 -5
- package/runtime/gatewaysdk/environment/schema/primary_key.py +61 -0
- package/runtime/gatewaysdk/environment/schema/proof.py +19 -12
- package/runtime/gatewaysdk/environment/schema/runtime.py +77 -160
- package/runtime/gatewaysdk/environment/schema/served_names.py +58 -0
- package/runtime/gatewaysdk/environment/schema/session_files.py +166 -0
- package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +2 -2
- package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +19 -11
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +29 -3
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +14 -14
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +12 -12
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +3 -2
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +15 -0
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/openapi-import.md +50 -21
- package/runtime/gatewaysdk/environment/schema/slack.py +4 -8
- package/runtime/gatewaysdk/environment/schema/snapshot.py +385 -129
- package/runtime/gatewaysdk/environment/schema/store_contract.py +8 -14
- package/runtime/gatewaysdk/environment/schema/tasks.py +140 -55
- package/runtime/gatewaysdk/environment/schema/tools_world.py +110 -87
- package/runtime/gatewaysdk/environment/schema/ui.py +24 -5
- package/runtime/gatewaysdk/environment/schema/ui_static/app.js +100 -130
- package/runtime/gatewaysdk/environment/schema/ui_static/index.html +1 -8
- package/runtime/gatewaysdk/environment/schema/validation.py +166 -40
- package/runtime/gatewaysdk/environment/schema/workers.py +142 -57
- package/runtime/gatewaysdk/environment/schema/world_sql.py +81 -0
- package/runtime/gatewaysdk/environment/schema/world_tests.py +71 -39
- package/runtime/gatewaysdk/environment/score.py +57 -0
- package/runtime/gatewaysdk/environment/secret_values.py +36 -0
- package/runtime/gatewaysdk/environment/world.py +42 -3
- package/runtime/gatewaysdk/environment/world_session_contract.py +32 -5
- package/skills/benchmarks-getting-started/SKILL.md +2 -2
- package/skills/connector-schema-authoring/SKILL.md +19 -11
- package/skills/connector-schema-authoring/connector-worlds.md +13 -4
- package/skills/connector-schema-authoring/world-schema.md +103 -51
- package/skills/world-data-ingestion/ROWS.md +29 -3
- package/skills/world-data-ingestion/SKILL.md +14 -14
- package/skills/worlds-getting-started/SKILL.md +12 -12
- package/skills/worlds-getting-started/references/cli-mcp-map.md +3 -2
- package/skills/worlds-getting-started/references/gotchas.md +15 -0
- package/skills/worlds-getting-started/references/openapi-import.md +50 -21
- package/runtime/gatewaysdk/environment/schema/store.py +0 -1013
|
@@ -7,7 +7,7 @@ host asks the runtime; it never asks what shape the version was stored as.
|
|
|
7
7
|
Two runtimes exist because two stored shapes still do:
|
|
8
8
|
|
|
9
9
|
- :class:`TreeRuntime` — a schema world stored as itself (``gateway-env.toml``
|
|
10
|
-
with a ``[schema]`` table): a copy of the version's
|
|
10
|
+
with a ``[schema]`` table): a copy of the version's proven template,
|
|
11
11
|
executed through its handlers, beside a copy of each dependency world, its
|
|
12
12
|
routes (``connector.toml``) over the same store. This is the runtime every
|
|
13
13
|
new push opens on.
|
|
@@ -24,19 +24,22 @@ cache loaded; from there the host sees one interface."""
|
|
|
24
24
|
|
|
25
25
|
from __future__ import annotations
|
|
26
26
|
|
|
27
|
-
import fcntl
|
|
28
27
|
import json
|
|
29
28
|
import shutil
|
|
30
29
|
import uuid
|
|
31
30
|
from abc import ABC, abstractmethod
|
|
32
|
-
from collections.abc import Callable
|
|
31
|
+
from collections.abc import Callable
|
|
33
32
|
from pathlib import Path
|
|
34
33
|
from typing import TYPE_CHECKING, Any, Optional
|
|
35
34
|
|
|
36
35
|
from . import snapshot as snapshots
|
|
37
|
-
from .api import
|
|
36
|
+
from .api import WorldApp, WorldState, vendor_credential
|
|
37
|
+
from .call_log import CallLog
|
|
38
|
+
from .database import WorldDatabase
|
|
38
39
|
from .dependencies import Dependency
|
|
39
40
|
from .grading import Grade, GraderError, TaskGrader
|
|
41
|
+
from .served_names import ServedNames
|
|
42
|
+
from .session_files import SessionExport
|
|
40
43
|
from .snapshot import SCENARIOS
|
|
41
44
|
from .tasks import TASK_DIR, TaskSpec, unknown_task_entities, verifier_source, write_task_dir
|
|
42
45
|
from .tools_world import DependencyWorld, ToolsWorld, ToolsWorldState, inline_task, served_with_dependencies
|
|
@@ -46,16 +49,20 @@ from .workers import ConfinedVerifierSandbox
|
|
|
46
49
|
if TYPE_CHECKING:
|
|
47
50
|
from .host import CachedVersion
|
|
48
51
|
|
|
49
|
-
|
|
50
|
-
#: the router still authorizes by it, so the host's own calls carry it.
|
|
52
|
+
# The router still authorizes by it, so the host's own calls carry it.
|
|
51
53
|
WORLD_AUTH_SENTINEL = "gateway-session"
|
|
52
54
|
|
|
53
|
-
Restorer = Callable[[Callable[[
|
|
55
|
+
Restorer = Callable[[Callable[[SessionExport], None]], bool]
|
|
54
56
|
|
|
55
57
|
|
|
56
58
|
class WorldRuntime(ABC):
|
|
57
59
|
"""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.
|
|
60
|
+
it on the session and calls nothing else of the world's. ``app`` is the
|
|
61
|
+
routes of connector.toml over the session's store, None for a world of
|
|
62
|
+
tools alone; ``calls`` is the one call log its routes and its tools write;
|
|
63
|
+
``grant`` is an ``oauth2`` world's client-credentials
|
|
64
|
+
grant the host minted for itself, so a caller the session token admits is
|
|
65
|
+
presented to the world as a granted client."""
|
|
59
66
|
|
|
60
67
|
def __init__(
|
|
61
68
|
self,
|
|
@@ -71,21 +78,15 @@ class WorldRuntime(ABC):
|
|
|
71
78
|
self.task = task
|
|
72
79
|
self.task_spec = spec
|
|
73
80
|
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
81
|
self.app: WorldApp | None = None
|
|
77
|
-
|
|
78
|
-
#: itself, so a caller the session token admits is presented to the
|
|
79
|
-
#: world as a granted client.
|
|
82
|
+
self.calls = CallLog.for_spec(cached.spec) if cached.spec is not None else CallLog()
|
|
80
83
|
self.grant: str | None = None
|
|
81
84
|
self.restored = False
|
|
82
85
|
|
|
83
|
-
# -- what the shape knows before a session opens ------------------------ #
|
|
84
|
-
|
|
85
86
|
@classmethod
|
|
86
87
|
@abstractmethod
|
|
87
88
|
def served_by(cls, cached: CachedVersion, dependencies: dict[str, DependencyWorld]) -> list[str]:
|
|
88
|
-
"""Every
|
|
89
|
+
"""Every tool a session task on ``cached`` may allow."""
|
|
89
90
|
|
|
90
91
|
@classmethod
|
|
91
92
|
@abstractmethod
|
|
@@ -98,8 +99,6 @@ class WorldRuntime(ABC):
|
|
|
98
99
|
"""The ``[dependencies]`` the version's manifest declares, by alias."""
|
|
99
100
|
return {}
|
|
100
101
|
|
|
101
|
-
# -- construction ------------------------------------------------------ #
|
|
102
|
-
|
|
103
102
|
@classmethod
|
|
104
103
|
def open(
|
|
105
104
|
cls,
|
|
@@ -120,7 +119,6 @@ class WorldRuntime(ABC):
|
|
|
120
119
|
try:
|
|
121
120
|
if spec is not None:
|
|
122
121
|
runtime._check_task_entities(spec)
|
|
123
|
-
# Under the session, where a grade and a restart find the task.
|
|
124
122
|
write_task_dir(spec, runtime.session_dir)
|
|
125
123
|
runtime._to_start()
|
|
126
124
|
runtime.restored = restore(runtime.restore)
|
|
@@ -134,14 +132,14 @@ class WorldRuntime(ABC):
|
|
|
134
132
|
cached = self.cached
|
|
135
133
|
if cached.spec is None:
|
|
136
134
|
return
|
|
137
|
-
# ``handlers={}
|
|
138
|
-
# import the module itself, and only a worker may do that.
|
|
135
|
+
# A code-free world gets ``handlers={}``: WorldApp would otherwise import the module, and only a worker may.
|
|
139
136
|
self.app = WorldApp(
|
|
140
137
|
self._app_state(),
|
|
141
138
|
cached.router(),
|
|
142
139
|
self.token,
|
|
143
140
|
handlers=cached.handlers or {},
|
|
144
|
-
|
|
141
|
+
routes_closed=self.allowed is not None,
|
|
142
|
+
calls=self.calls,
|
|
145
143
|
)
|
|
146
144
|
self.grant = client_grant(self.app, self.token)
|
|
147
145
|
|
|
@@ -165,8 +163,6 @@ class WorldRuntime(ABC):
|
|
|
165
163
|
"/task",
|
|
166
164
|
)
|
|
167
165
|
|
|
168
|
-
# -- what a subclass supplies ------------------------------------------ #
|
|
169
|
-
|
|
170
166
|
@abstractmethod
|
|
171
167
|
def _start(self, dependencies: dict[str, DependencyWorld]) -> None:
|
|
172
168
|
"""Bring the store up. A failure here leaves nothing to close."""
|
|
@@ -184,7 +180,7 @@ class WorldRuntime(ABC):
|
|
|
184
180
|
|
|
185
181
|
@abstractmethod
|
|
186
182
|
def served(self) -> list[str]:
|
|
187
|
-
"""Every name :meth:`call` answers: tools,
|
|
183
|
+
"""Every name :meth:`call` answers: the declared tools, a dependency's as ``alias.tool``."""
|
|
188
184
|
|
|
189
185
|
@abstractmethod
|
|
190
186
|
def reset(self) -> dict: ...
|
|
@@ -211,14 +207,29 @@ class WorldRuntime(ABC):
|
|
|
211
207
|
"""The ``verify.py`` of the bundled task, when the version carries one."""
|
|
212
208
|
|
|
213
209
|
@abstractmethod
|
|
214
|
-
def
|
|
215
|
-
"""A tool by name,
|
|
210
|
+
def call(self, tool: str, args: dict) -> dict:
|
|
211
|
+
"""A declared tool by name, its ``{status, body}``. A route's name is
|
|
212
|
+
refused with the api URL to call it over: routes are never tools."""
|
|
216
213
|
|
|
217
214
|
@abstractmethod
|
|
218
|
-
def
|
|
215
|
+
def _export_state(self, destination: Path) -> Path:
|
|
216
|
+
"""The store's copy of the session's state at ``destination``."""
|
|
219
217
|
|
|
220
218
|
@abstractmethod
|
|
221
|
-
def
|
|
219
|
+
def _restore_state(self, export: SessionExport) -> None:
|
|
220
|
+
"""The session's store laid from a verified export, without a row audit."""
|
|
221
|
+
|
|
222
|
+
def export(self, destination: Path) -> Path:
|
|
223
|
+
"""The session's state as one database file, with its call log in it, so a
|
|
224
|
+
reopen resumes both (:class:`SessionExport`)."""
|
|
225
|
+
path = self._export_state(destination)
|
|
226
|
+
SessionExport.carry_calls(path, self.calls.describe()["calls"], self.cached.engine)
|
|
227
|
+
return path
|
|
228
|
+
|
|
229
|
+
def restore(self, export: SessionExport) -> None:
|
|
230
|
+
"""Continue from an export this host verified, its call log with it."""
|
|
231
|
+
self._restore_state(export)
|
|
232
|
+
self.calls.resume(export.calls)
|
|
222
233
|
|
|
223
234
|
@abstractmethod
|
|
224
235
|
def close(self) -> None: ...
|
|
@@ -227,15 +238,8 @@ class WorldRuntime(ABC):
|
|
|
227
238
|
def task_card(self) -> dict:
|
|
228
239
|
"""What an outside agent is handed about the session's task."""
|
|
229
240
|
|
|
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
241
|
def state(self) -> dict:
|
|
238
|
-
return self.
|
|
242
|
+
return self.calls.into_state(self._rows())
|
|
239
243
|
|
|
240
244
|
def grader_state(self, report: Optional[str] = None) -> dict:
|
|
241
245
|
"""The evidence a grader reads: the rows keyed by primary key (a
|
|
@@ -243,7 +247,7 @@ class WorldRuntime(ABC):
|
|
|
243
247
|
the agent made (a read-only investigation writes nothing) and, under
|
|
244
248
|
``report``, the agent's own claim. Reserved keys: no world entity may
|
|
245
249
|
be named ``calls``, ``snapshot`` or ``report``."""
|
|
246
|
-
state = self.
|
|
250
|
+
state = self.calls.into_state(self._grader_rows())
|
|
247
251
|
if report is not None:
|
|
248
252
|
state["report"] = report
|
|
249
253
|
return state
|
|
@@ -286,7 +290,7 @@ class WorldRuntime(ABC):
|
|
|
286
290
|
return grader.grade(self.grader_state(report)).as_dict()
|
|
287
291
|
except GraderError as error:
|
|
288
292
|
fail("host", str(error))
|
|
289
|
-
raise AssertionError
|
|
293
|
+
raise AssertionError
|
|
290
294
|
|
|
291
295
|
@staticmethod
|
|
292
296
|
def _verifier_grade(grader: TaskGrader, state: dict, context: dict) -> dict:
|
|
@@ -334,21 +338,6 @@ class WorldRuntime(ABC):
|
|
|
334
338
|
for row in spec.verifiers
|
|
335
339
|
]
|
|
336
340
|
|
|
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
341
|
def credential(self) -> tuple[dict[str, str], dict[str, str]]:
|
|
353
342
|
"""(headers, query) carrying the world's own credential for this
|
|
354
343
|
session: the session token in the vendor's shape, or for an oauth2
|
|
@@ -371,7 +360,7 @@ class TreeRuntime(WorldRuntime):
|
|
|
371
360
|
|
|
372
361
|
@classmethod
|
|
373
362
|
def authored_code(cls, cached: CachedVersion) -> str:
|
|
374
|
-
return "schema world handlers"
|
|
363
|
+
return "schema world handlers"
|
|
375
364
|
|
|
376
365
|
@classmethod
|
|
377
366
|
def declared_dependencies(cls, cached: CachedVersion) -> dict[str, Dependency]:
|
|
@@ -390,10 +379,11 @@ class TreeRuntime(WorldRuntime):
|
|
|
390
379
|
seed=spec.seed,
|
|
391
380
|
allowed=self.allowed,
|
|
392
381
|
dependencies=dependencies,
|
|
382
|
+
calls=self.calls,
|
|
393
383
|
)
|
|
394
384
|
return
|
|
395
385
|
assert self.task is not None
|
|
396
|
-
self.world = ToolsWorld(tools, self.session_dir, self.task, dependencies=dependencies)
|
|
386
|
+
self.world = ToolsWorld(tools, self.session_dir, self.task, dependencies=dependencies, calls=self.calls)
|
|
397
387
|
|
|
398
388
|
def _app_state(self) -> ToolsWorldState:
|
|
399
389
|
return ToolsWorldState(self.world, self.cached.tree)
|
|
@@ -424,17 +414,14 @@ class TreeRuntime(WorldRuntime):
|
|
|
424
414
|
def _bundled_verifier(self) -> Path | None:
|
|
425
415
|
return self.world.task.verify
|
|
426
416
|
|
|
427
|
-
def
|
|
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
|
|
417
|
+
def call(self, tool: str, args: dict) -> dict:
|
|
431
418
|
return self.world.call(tool, args)
|
|
432
419
|
|
|
433
|
-
def
|
|
420
|
+
def _export_state(self, destination: Path) -> Path:
|
|
434
421
|
return self.world.export(destination)
|
|
435
422
|
|
|
436
|
-
def
|
|
437
|
-
self.world.restore(
|
|
423
|
+
def _restore_state(self, export: SessionExport) -> None:
|
|
424
|
+
self.world.restore(export)
|
|
438
425
|
|
|
439
426
|
def close(self) -> None:
|
|
440
427
|
self.world.close()
|
|
@@ -443,29 +430,6 @@ class TreeRuntime(WorldRuntime):
|
|
|
443
430
|
return task_card(self.world)
|
|
444
431
|
|
|
445
432
|
|
|
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
433
|
def scenario_dir(bundle: Path, tree: Path, task: str) -> Path | None:
|
|
470
434
|
"""A bundled task's scenario directory, checked at the bundle root first
|
|
471
435
|
(where ``build_api_bundle`` writes them) then in the tree."""
|
|
@@ -485,45 +449,41 @@ class HostWorldState(WorldState):
|
|
|
485
449
|
self._session_dir.mkdir(parents=True, exist_ok=True)
|
|
486
450
|
self._cached = cached
|
|
487
451
|
self._database: Path | None = None
|
|
488
|
-
super().__init__(cached.tree)
|
|
452
|
+
super().__init__(cached.tree, cached.served)
|
|
489
453
|
|
|
490
454
|
@property
|
|
491
455
|
def session_dir(self) -> Path:
|
|
492
456
|
return self._session_dir
|
|
493
457
|
|
|
494
458
|
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
459
|
if snapshot is None:
|
|
498
460
|
return super()._open(None, initial=initial)
|
|
461
|
+
self._lay(snapshot)
|
|
462
|
+
|
|
463
|
+
def _lay(self, source: Path) -> None:
|
|
464
|
+
"""A file of this session's own, cloned from the version's snapshot or a
|
|
465
|
+
verified export, and opened without the row audit."""
|
|
499
466
|
if self.store is not None:
|
|
500
467
|
self.store.close()
|
|
501
468
|
if self._database is not None:
|
|
502
469
|
self._database.unlink(missing_ok=True)
|
|
503
470
|
database = self._session_dir / f"{uuid.uuid4().hex}.db"
|
|
504
|
-
|
|
505
|
-
self.store = snapshots.SQLiteStore.open(database, self.contract, audit=False)
|
|
471
|
+
self.store = WorldDatabase.open_copy(source, self.contract, database)
|
|
506
472
|
self._database = database
|
|
507
473
|
|
|
508
474
|
def export(self, destination: Path) -> Path:
|
|
509
|
-
"""The session's state as one
|
|
510
|
-
|
|
511
|
-
assert self.store is not None
|
|
475
|
+
"""The session's state as one database file (:meth:`WorldDatabase.snapshot`),
|
|
476
|
+
copied without holding the session, so its requests keep landing."""
|
|
512
477
|
with self._lock:
|
|
513
|
-
|
|
478
|
+
store = self.store
|
|
479
|
+
assert store is not None
|
|
480
|
+
return store.snapshot(destination)
|
|
514
481
|
|
|
515
|
-
def restore(self,
|
|
516
|
-
"""Continue from
|
|
517
|
-
|
|
482
|
+
def restore(self, export: SessionExport) -> None:
|
|
483
|
+
"""Continue from an export this host verified (:class:`SessionExport`)."""
|
|
484
|
+
path = SessionExport.required(export).path
|
|
518
485
|
with self._lock:
|
|
519
|
-
|
|
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
|
|
486
|
+
self._lay(path)
|
|
527
487
|
|
|
528
488
|
def close(self) -> None:
|
|
529
489
|
super().close()
|
|
@@ -539,8 +499,7 @@ class SnapshotRuntime(WorldRuntime):
|
|
|
539
499
|
|
|
540
500
|
@classmethod
|
|
541
501
|
def served_by(cls, cached: CachedVersion, dependencies: dict[str, DependencyWorld]) -> list[str]:
|
|
542
|
-
|
|
543
|
-
return list(cached.spec.operations)
|
|
502
|
+
return []
|
|
544
503
|
|
|
545
504
|
@classmethod
|
|
546
505
|
def authored_code(cls, cached: CachedVersion) -> str | None:
|
|
@@ -571,7 +530,7 @@ class SnapshotRuntime(WorldRuntime):
|
|
|
571
530
|
scenario = scenario_dir(self.cached.bundle, self.cached.tree, self.task)
|
|
572
531
|
if scenario is None:
|
|
573
532
|
if self.task in self.state_.scenarios():
|
|
574
|
-
self.state_.apply_scenario(self.task)
|
|
533
|
+
self.state_.apply_scenario(self.task)
|
|
575
534
|
return
|
|
576
535
|
fail(
|
|
577
536
|
"host",
|
|
@@ -579,7 +538,7 @@ class SnapshotRuntime(WorldRuntime):
|
|
|
579
538
|
)
|
|
580
539
|
overlay = snapshots.scenario_overlay(scenario)
|
|
581
540
|
if not overlay:
|
|
582
|
-
return
|
|
541
|
+
return
|
|
583
542
|
digest = self.state_.digest
|
|
584
543
|
if digest is None:
|
|
585
544
|
fail("host", "a scenario overlay needs a compiled snapshot to apply against")
|
|
@@ -592,19 +551,14 @@ class SnapshotRuntime(WorldRuntime):
|
|
|
592
551
|
return list(self.state_.contract.entities)
|
|
593
552
|
|
|
594
553
|
def served(self) -> list[str]:
|
|
595
|
-
|
|
596
|
-
return sorted(spec.operations) if spec is not None else []
|
|
554
|
+
return []
|
|
597
555
|
|
|
598
556
|
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
557
|
self.state_.reset()
|
|
602
558
|
self._to_start()
|
|
603
559
|
return {"reset": True}
|
|
604
560
|
|
|
605
561
|
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
562
|
self.state_.seed_live(rows, mode, redact)
|
|
609
563
|
return {
|
|
610
564
|
"seeded": sum(len(v) for v in rows.values()),
|
|
@@ -629,14 +583,14 @@ class SnapshotRuntime(WorldRuntime):
|
|
|
629
583
|
scenario = scenario_dir(self.cached.bundle, self.cached.tree, self.task)
|
|
630
584
|
return scenario / "checks" / "verify.py" if scenario else None
|
|
631
585
|
|
|
632
|
-
def
|
|
633
|
-
|
|
586
|
+
def call(self, tool: str, args: dict) -> dict:
|
|
587
|
+
ServedNames.of((), self.cached.spec).refuse(tool)
|
|
634
588
|
|
|
635
|
-
def
|
|
589
|
+
def _export_state(self, destination: Path) -> Path:
|
|
636
590
|
return self.state_.export(destination)
|
|
637
591
|
|
|
638
|
-
def
|
|
639
|
-
self.state_.restore(
|
|
592
|
+
def _restore_state(self, export: SessionExport) -> None:
|
|
593
|
+
self.state_.restore(export)
|
|
640
594
|
|
|
641
595
|
def close(self) -> None:
|
|
642
596
|
self.state_.close()
|
|
@@ -656,51 +610,14 @@ class SnapshotRuntime(WorldRuntime):
|
|
|
656
610
|
|
|
657
611
|
def client_grant(app: WorldApp | None, credential: str | None) -> str | None:
|
|
658
612
|
"""The bearer an ``oauth2`` world's routes take when the session itself
|
|
659
|
-
calls them (the page's api prefix
|
|
660
|
-
|
|
613
|
+
calls them (the page's api prefix); None for any other scheme, or when the
|
|
614
|
+
world refuses the client-credentials grant."""
|
|
661
615
|
if app is None or app.router.spec.scheme != "oauth2":
|
|
662
616
|
return None
|
|
663
617
|
issued = app.router.issue_token({"grant_type": "client_credentials", "client_secret": credential or ""}, credential)
|
|
664
618
|
return issued["access_token"] if issued else None
|
|
665
619
|
|
|
666
620
|
|
|
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
621
|
def tool_contracts(bundle: Path, prefix: str = "") -> dict[str, dict]:
|
|
705
622
|
"""Each compiled tool's ``{description, input}`` from the bundle's
|
|
706
623
|
``tool-schemas.json`` (refs inlined by the compiler), keyed by served name."""
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
"""The names a world's tool door answers to: the tools it declares.
|
|
2
|
+
|
|
3
|
+
Its connector.toml operations are routes. A route answers over the world's
|
|
4
|
+
HTTP api, never through ``call``, so a call or a task naming one is refused
|
|
5
|
+
with :func:`~gatewaysdk.environment.world_session_contract.route_not_a_tool`.
|
|
6
|
+
A tool and an operation may share a name: the door runs the tool, the api the
|
|
7
|
+
route."""
|
|
8
|
+
|
|
9
|
+
from __future__ import annotations
|
|
10
|
+
|
|
11
|
+
from collections.abc import Iterable
|
|
12
|
+
from dataclasses import dataclass
|
|
13
|
+
from typing import NoReturn
|
|
14
|
+
|
|
15
|
+
from ..world_session_contract import NOT_A_TOOL, route_not_a_tool
|
|
16
|
+
from .connector import Spec
|
|
17
|
+
from .validation import fail
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
@dataclass(frozen=True)
|
|
21
|
+
class ServedNames:
|
|
22
|
+
tools: frozenset[str]
|
|
23
|
+
routes: frozenset[str]
|
|
24
|
+
|
|
25
|
+
@classmethod
|
|
26
|
+
def of(cls, tools: Iterable[str], spec: Spec | None) -> ServedNames:
|
|
27
|
+
return cls(frozenset(tools), frozenset(spec.operations) if spec is not None else frozenset())
|
|
28
|
+
|
|
29
|
+
@property
|
|
30
|
+
def served(self) -> list[str]:
|
|
31
|
+
return sorted(self.tools)
|
|
32
|
+
|
|
33
|
+
def is_route(self, name: str) -> bool:
|
|
34
|
+
return name in self.routes and name not in self.tools
|
|
35
|
+
|
|
36
|
+
def refuse(self, name: str) -> NoReturn:
|
|
37
|
+
"""``name`` is no tool here: a route's name is told the api URL, any
|
|
38
|
+
other name the tools this world serves."""
|
|
39
|
+
if self.is_route(name):
|
|
40
|
+
fail(NOT_A_TOOL, route_not_a_tool(name))
|
|
41
|
+
fail("host", f"unknown tool '{name}'; this world serves: {', '.join(self.served) or '(none)'}")
|
|
42
|
+
|
|
43
|
+
def check_allowed(self, allowed: Iterable[str] | None) -> None:
|
|
44
|
+
"""A task's allow-list names tools this world serves, every one of them:
|
|
45
|
+
a route is never a tool, and a misspelt name would narrow the list
|
|
46
|
+
without anyone noticing."""
|
|
47
|
+
listed = list(allowed or ())
|
|
48
|
+
routes = "; ".join(route_not_a_tool(name) for name in listed if self.is_route(name))
|
|
49
|
+
if routes:
|
|
50
|
+
fail("task", routes, "/task/tools")
|
|
51
|
+
unknown = [name for name in listed if name not in self.tools]
|
|
52
|
+
if unknown:
|
|
53
|
+
served = ", ".join(self.served) or "none"
|
|
54
|
+
fail(
|
|
55
|
+
"task",
|
|
56
|
+
f"the task allows {', '.join(unknown)}, which this world does not serve; its tools are {served}",
|
|
57
|
+
"/task/tools",
|
|
58
|
+
)
|