@withgateway/sdk 0.3.0 → 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.
Files changed (130) hide show
  1. package/README.md +6 -1
  2. package/dist/cli.js +3971 -2338
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +3950 -2318
  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 +214 -41
  9. package/dist/files/index.js.map +1 -1
  10. package/dist/files/index.mjs +206 -35
  11. package/dist/files/index.mjs.map +1 -1
  12. package/dist/{index-DAb-FCMg.d.ts → index-DUHmS74p.d.ts} +3 -13
  13. package/dist/{index-D6oi1TWE.d.mts → index-mJhG3vZU.d.mts} +3 -13
  14. package/dist/index.d.mts +4 -4
  15. package/dist/index.d.ts +4 -4
  16. package/dist/index.js +1456 -564
  17. package/dist/index.js.map +1 -1
  18. package/dist/index.mjs +1433 -557
  19. package/dist/index.mjs.map +1 -1
  20. package/dist/{media-CbcAfQvd.d.mts → media-BIApiPzS.d.mts} +21 -2
  21. package/dist/{media-CbcAfQvd.d.ts → media-BIApiPzS.d.ts} +21 -2
  22. package/dist/traces/index.d.mts +1 -1
  23. package/dist/traces/index.d.ts +1 -1
  24. package/dist/traces/index.js +211 -38
  25. package/dist/traces/index.js.map +1 -1
  26. package/dist/traces/index.mjs +203 -32
  27. package/dist/traces/index.mjs.map +1 -1
  28. package/dist/tracing/index.d.mts +2 -2
  29. package/dist/tracing/index.d.ts +2 -2
  30. package/dist/tracing/index.js +96 -21
  31. package/dist/tracing/index.js.map +1 -1
  32. package/dist/tracing/index.mjs +96 -21
  33. package/dist/tracing/index.mjs.map +1 -1
  34. package/dist/worlds/index.d.mts +300 -123
  35. package/dist/worlds/index.d.ts +300 -123
  36. package/dist/worlds/index.js +1385 -508
  37. package/dist/worlds/index.js.map +1 -1
  38. package/dist/worlds/index.mjs +1377 -501
  39. package/dist/worlds/index.mjs.map +1 -1
  40. package/package.json +1 -1
  41. package/runtime/gatewaysdk/environment/_bundle.py +2 -27
  42. package/runtime/gatewaysdk/environment/_materialize.py +49 -69
  43. package/runtime/gatewaysdk/environment/_world.py +122 -197
  44. package/runtime/gatewaysdk/environment/backing.py +137 -0
  45. package/runtime/gatewaysdk/environment/core.py +1 -1
  46. package/runtime/gatewaysdk/environment/legacy_sqlite.py +301 -0
  47. package/runtime/gatewaysdk/environment/reward_keys.py +25 -0
  48. package/runtime/gatewaysdk/environment/runtime.py +8 -13
  49. package/runtime/gatewaysdk/environment/schema/__init__.py +4 -4
  50. package/runtime/gatewaysdk/environment/schema/admin_routes.py +86 -0
  51. package/runtime/gatewaysdk/environment/schema/api.py +266 -515
  52. package/runtime/gatewaysdk/environment/schema/batch.py +42 -37
  53. package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +17 -5
  54. package/runtime/gatewaysdk/environment/schema/call_log.py +291 -0
  55. package/runtime/gatewaysdk/environment/schema/call_redaction.py +344 -0
  56. package/runtime/gatewaysdk/environment/schema/cast.py +31 -4
  57. package/runtime/gatewaysdk/environment/schema/compiler.py +334 -158
  58. package/runtime/gatewaysdk/environment/schema/conform.py +8 -12
  59. package/runtime/gatewaysdk/environment/schema/connector.py +27 -62
  60. package/runtime/gatewaysdk/environment/schema/data.py +50 -207
  61. package/runtime/gatewaysdk/environment/schema/database/__init__.py +24 -0
  62. package/runtime/gatewaysdk/environment/schema/database/audit.py +121 -0
  63. package/runtime/gatewaysdk/environment/schema/database/base.py +995 -0
  64. package/runtime/gatewaysdk/environment/schema/database/budget.py +33 -0
  65. package/runtime/gatewaysdk/environment/schema/database/connections.py +101 -0
  66. package/runtime/gatewaysdk/environment/schema/database/engines.py +8 -0
  67. package/runtime/gatewaysdk/environment/schema/database/guard.py +208 -0
  68. package/runtime/gatewaysdk/environment/schema/database/ingest.py +154 -0
  69. package/runtime/gatewaysdk/environment/schema/database/matching.py +58 -0
  70. package/runtime/gatewaysdk/environment/schema/database/provenance.py +30 -0
  71. package/runtime/gatewaysdk/environment/schema/database/rows.py +53 -0
  72. package/runtime/gatewaysdk/environment/schema/database/runtime_rows.py +39 -0
  73. package/runtime/gatewaysdk/environment/schema/database/sqlite.py +367 -0
  74. package/runtime/gatewaysdk/environment/schema/domain_migration.py +236 -0
  75. package/runtime/gatewaysdk/environment/schema/envelope.py +169 -0
  76. package/runtime/gatewaysdk/environment/schema/extract.py +6 -13
  77. package/runtime/gatewaysdk/environment/schema/grading.py +45 -30
  78. package/runtime/gatewaysdk/environment/schema/handler_errors.py +142 -12
  79. package/runtime/gatewaysdk/environment/schema/host.py +158 -250
  80. package/runtime/gatewaysdk/environment/schema/lanes.py +53 -0
  81. package/runtime/gatewaysdk/environment/schema/local.py +44 -71
  82. package/runtime/gatewaysdk/environment/schema/mapping.py +5 -25
  83. package/runtime/gatewaysdk/environment/schema/openapi_import.py +112 -73
  84. package/runtime/gatewaysdk/environment/schema/openapi_paging.py +147 -0
  85. package/runtime/gatewaysdk/environment/schema/openapi_payloads.py +288 -0
  86. package/runtime/gatewaysdk/environment/schema/openapi_routes.py +97 -102
  87. package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +113 -30
  88. package/runtime/gatewaysdk/environment/schema/platform.py +124 -178
  89. package/runtime/gatewaysdk/environment/schema/platform_import.py +2 -3
  90. package/runtime/gatewaysdk/environment/schema/platform_query.py +61 -5
  91. package/runtime/gatewaysdk/environment/schema/primary_key.py +61 -0
  92. package/runtime/gatewaysdk/environment/schema/proof.py +19 -12
  93. package/runtime/gatewaysdk/environment/schema/runtime.py +77 -160
  94. package/runtime/gatewaysdk/environment/schema/served_names.py +58 -0
  95. package/runtime/gatewaysdk/environment/schema/session_files.py +166 -0
  96. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +2 -2
  97. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +22 -14
  98. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +29 -3
  99. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +16 -16
  100. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +18 -18
  101. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +3 -2
  102. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +15 -0
  103. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/openapi-import.md +50 -21
  104. package/runtime/gatewaysdk/environment/schema/slack.py +4 -8
  105. package/runtime/gatewaysdk/environment/schema/snapshot.py +385 -129
  106. package/runtime/gatewaysdk/environment/schema/store_contract.py +8 -14
  107. package/runtime/gatewaysdk/environment/schema/tasks.py +140 -55
  108. package/runtime/gatewaysdk/environment/schema/tools_world.py +110 -87
  109. package/runtime/gatewaysdk/environment/schema/ui.py +24 -5
  110. package/runtime/gatewaysdk/environment/schema/ui_static/app.js +100 -130
  111. package/runtime/gatewaysdk/environment/schema/ui_static/index.html +1 -8
  112. package/runtime/gatewaysdk/environment/schema/validation.py +166 -40
  113. package/runtime/gatewaysdk/environment/schema/workers.py +142 -57
  114. package/runtime/gatewaysdk/environment/schema/world_sql.py +81 -0
  115. package/runtime/gatewaysdk/environment/schema/world_tests.py +71 -39
  116. package/runtime/gatewaysdk/environment/score.py +57 -0
  117. package/runtime/gatewaysdk/environment/secret_values.py +36 -0
  118. package/runtime/gatewaysdk/environment/world.py +42 -3
  119. package/runtime/gatewaysdk/environment/world_session_contract.py +32 -5
  120. package/skills/benchmarks-getting-started/SKILL.md +2 -2
  121. package/skills/connector-schema-authoring/SKILL.md +22 -14
  122. package/skills/connector-schema-authoring/connector-worlds.md +26 -10
  123. package/skills/connector-schema-authoring/world-schema.md +111 -51
  124. package/skills/world-data-ingestion/ROWS.md +29 -3
  125. package/skills/world-data-ingestion/SKILL.md +16 -16
  126. package/skills/worlds-getting-started/SKILL.md +18 -18
  127. package/skills/worlds-getting-started/references/cli-mcp-map.md +3 -2
  128. package/skills/worlds-getting-started/references/gotchas.md +15 -0
  129. package/skills/worlds-getting-started/references/openapi-import.md +50 -21
  130. 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 materialized template,
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, Iterable
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 Via, WorldApp, WorldState, operation_request, vendor_credential, with_query
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
- #: 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.
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[[Path], None]], bool]
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
- #: 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.
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 name a session task on ``cached`` may allow."""
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={}`` for a code-free world: WorldApp would otherwise
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
- allowed=self.allowed,
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, operations, a dependency's ``alias.tool``."""
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 _call_tool(self, tool: str, args: dict) -> dict | None:
215
- """A tool by name, or None when ``tool`` is an operation of the routes."""
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 export(self, destination: Path) -> Path: ...
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 restore(self, source: Path) -> None: ...
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._with_calls(self._rows())
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._with_calls(self._grader_rows())
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 # fail() never returns
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" # its tools ARE 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 _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
417
+ def call(self, tool: str, args: dict) -> dict:
431
418
  return self.world.call(tool, args)
432
419
 
433
- def export(self, destination: Path) -> Path:
420
+ def _export_state(self, destination: Path) -> Path:
434
421
  return self.world.export(destination)
435
422
 
436
- def restore(self, source: Path) -> None:
437
- self.world.restore(source)
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
- clone_file(snapshot, database)
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 sqlite file: the store's own audited
510
- online backup, consistent while requests keep writing."""
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
- return self.store.snapshot(destination)
478
+ store = self.store
479
+ assert store is not None
480
+ return store.snapshot(destination)
514
481
 
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."""
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
- 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
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
- assert cached.spec is not None
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) # a tree-authored scenario
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 # base state; the cloned snapshot already holds it
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
- spec = self.cached.spec
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 _call_tool(self, tool: str, args: dict) -> dict | None:
633
- return None
586
+ def call(self, tool: str, args: dict) -> dict:
587
+ ServedNames.of((), self.cached.spec).refuse(tool)
634
588
 
635
- def export(self, destination: Path) -> Path:
589
+ def _export_state(self, destination: Path) -> Path:
636
590
  return self.state_.export(destination)
637
591
 
638
- def restore(self, source: Path) -> None:
639
- self.state_.restore(source)
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, an operation by name); None for any
660
- other scheme, or when the world refuses the client-credentials grant."""
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
+ )