@withgateway/sdk 0.3.1 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (176) hide show
  1. package/README.md +8 -6
  2. package/dist/cli.js +4372 -2265
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +4362 -2256
  5. package/dist/cli.mjs.map +1 -1
  6. package/dist/files/index.d.mts +1 -1
  7. package/dist/files/index.d.ts +1 -1
  8. package/dist/files/index.js +259 -58
  9. package/dist/files/index.js.map +1 -1
  10. package/dist/files/index.mjs +249 -50
  11. package/dist/files/index.mjs.map +1 -1
  12. package/dist/hooks/index.d.mts +1 -1
  13. package/dist/hooks/index.d.ts +1 -1
  14. package/dist/hooks/index.js +124 -11
  15. package/dist/hooks/index.js.map +1 -1
  16. package/dist/hooks/index.mjs +124 -11
  17. package/dist/hooks/index.mjs.map +1 -1
  18. package/dist/{index-C3UzD0G3.d.mts → index-CDPQBsU5.d.mts} +19 -3
  19. package/dist/{index-C3UzD0G3.d.ts → index-CDPQBsU5.d.ts} +19 -3
  20. package/dist/{index-CBqbB_0J.d.ts → index-DUHmS74p.d.ts} +1 -1
  21. package/dist/{index-D-AMnAMa.d.mts → index-mJhG3vZU.d.mts} +1 -1
  22. package/dist/index.d.mts +5 -5
  23. package/dist/index.d.ts +5 -5
  24. package/dist/index.js +2240 -789
  25. package/dist/index.js.map +1 -1
  26. package/dist/index.mjs +2150 -739
  27. package/dist/index.mjs.map +1 -1
  28. package/dist/{media-CbcAfQvd.d.mts → media-BIApiPzS.d.mts} +21 -2
  29. package/dist/{media-CbcAfQvd.d.ts → media-BIApiPzS.d.ts} +21 -2
  30. package/dist/traces/index.d.mts +1 -1
  31. package/dist/traces/index.d.ts +1 -1
  32. package/dist/traces/index.js +253 -52
  33. package/dist/traces/index.js.map +1 -1
  34. package/dist/traces/index.mjs +243 -44
  35. package/dist/traces/index.mjs.map +1 -1
  36. package/dist/tracing/index.d.mts +2 -2
  37. package/dist/tracing/index.d.ts +2 -2
  38. package/dist/tracing/index.js +75 -13
  39. package/dist/tracing/index.js.map +1 -1
  40. package/dist/tracing/index.mjs +75 -13
  41. package/dist/tracing/index.mjs.map +1 -1
  42. package/dist/worlds/index.d.mts +893 -482
  43. package/dist/worlds/index.d.ts +893 -482
  44. package/dist/worlds/index.js +1968 -669
  45. package/dist/worlds/index.js.map +1 -1
  46. package/dist/worlds/index.mjs +1960 -662
  47. package/dist/worlds/index.mjs.map +1 -1
  48. package/package.json +1 -1
  49. package/runtime/gatewaysdk/environment/_bundle.py +2 -27
  50. package/runtime/gatewaysdk/environment/_materialize.py +48 -88
  51. package/runtime/gatewaysdk/environment/_world.py +155 -237
  52. package/runtime/gatewaysdk/environment/backing.py +133 -0
  53. package/runtime/gatewaysdk/environment/core.py +2 -17
  54. package/runtime/gatewaysdk/environment/legacy_sqlite.py +288 -0
  55. package/runtime/gatewaysdk/environment/reward_keys.py +25 -0
  56. package/runtime/gatewaysdk/environment/runtime.py +8 -13
  57. package/runtime/gatewaysdk/environment/schema/__init__.py +4 -4
  58. package/runtime/gatewaysdk/environment/schema/admin_routes.py +86 -0
  59. package/runtime/gatewaysdk/environment/schema/admission.py +174 -0
  60. package/runtime/gatewaysdk/environment/schema/api.py +347 -892
  61. package/runtime/gatewaysdk/environment/schema/assertions.py +458 -0
  62. package/runtime/gatewaysdk/environment/schema/batch.py +44 -39
  63. package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +17 -5
  64. package/runtime/gatewaysdk/environment/schema/cache_layout.py +5 -0
  65. package/runtime/gatewaysdk/environment/schema/call_capture.py +309 -0
  66. package/runtime/gatewaysdk/environment/schema/call_log.py +503 -0
  67. package/runtime/gatewaysdk/environment/schema/call_redaction.py +526 -0
  68. package/runtime/gatewaysdk/environment/schema/cast.py +15 -35
  69. package/runtime/gatewaysdk/environment/schema/compiler.py +334 -158
  70. package/runtime/gatewaysdk/environment/schema/conform.py +14 -39
  71. package/runtime/gatewaysdk/environment/schema/connector.py +113 -211
  72. package/runtime/gatewaysdk/environment/schema/connectors/confluence/connector.toml +1 -12
  73. package/runtime/gatewaysdk/environment/schema/connectors/github/connector.toml +1 -0
  74. package/runtime/gatewaysdk/environment/schema/connectors/servicenow/connector.toml +2 -5
  75. package/runtime/gatewaysdk/environment/schema/cors.py +54 -0
  76. package/runtime/gatewaysdk/environment/schema/credentials.py +313 -8
  77. package/runtime/gatewaysdk/environment/schema/data.py +60 -216
  78. package/runtime/gatewaysdk/environment/schema/database/__init__.py +24 -0
  79. package/runtime/gatewaysdk/environment/schema/database/audit.py +121 -0
  80. package/runtime/gatewaysdk/environment/schema/database/base.py +936 -0
  81. package/runtime/gatewaysdk/environment/schema/database/budget.py +33 -0
  82. package/runtime/gatewaysdk/environment/schema/database/connections.py +101 -0
  83. package/runtime/gatewaysdk/environment/schema/database/engines.py +8 -0
  84. package/runtime/gatewaysdk/environment/schema/database/guard.py +215 -0
  85. package/runtime/gatewaysdk/environment/schema/database/ingest.py +154 -0
  86. package/runtime/gatewaysdk/environment/schema/database/matching.py +58 -0
  87. package/runtime/gatewaysdk/environment/schema/database/provenance.py +30 -0
  88. package/runtime/gatewaysdk/environment/schema/database/reads.py +169 -0
  89. package/runtime/gatewaysdk/environment/schema/database/rows.py +53 -0
  90. package/runtime/gatewaysdk/environment/schema/database/runtime_rows.py +39 -0
  91. package/runtime/gatewaysdk/environment/schema/database/sqlite.py +393 -0
  92. package/runtime/gatewaysdk/environment/schema/declared_routes.py +210 -0
  93. package/runtime/gatewaysdk/environment/schema/domain_migration.py +236 -0
  94. package/runtime/gatewaysdk/environment/schema/door.py +899 -0
  95. package/runtime/gatewaysdk/environment/schema/envelope.py +227 -0
  96. package/runtime/gatewaysdk/environment/schema/extract.py +6 -13
  97. package/runtime/gatewaysdk/environment/schema/grading.py +90 -103
  98. package/runtime/gatewaysdk/environment/schema/handler_errors.py +163 -12
  99. package/runtime/gatewaysdk/environment/schema/host.py +237 -1795
  100. package/runtime/gatewaysdk/environment/schema/host_control.py +144 -0
  101. package/runtime/gatewaysdk/environment/schema/host_handoff.py +370 -0
  102. package/runtime/gatewaysdk/environment/schema/host_loops.py +97 -0
  103. package/runtime/gatewaysdk/environment/schema/host_owners.py +121 -0
  104. package/runtime/gatewaysdk/environment/schema/host_proxy.py +111 -0
  105. package/runtime/gatewaysdk/environment/schema/host_requests.py +6 -0
  106. package/runtime/gatewaysdk/environment/schema/host_session.py +126 -0
  107. package/runtime/gatewaysdk/environment/schema/host_surfaces.py +79 -21
  108. package/runtime/gatewaysdk/environment/schema/host_transfers.py +127 -0
  109. package/runtime/gatewaysdk/environment/schema/host_versions.py +242 -0
  110. package/runtime/gatewaysdk/environment/schema/host_workers.py +577 -0
  111. package/runtime/gatewaysdk/environment/schema/journal.py +437 -0
  112. package/runtime/gatewaysdk/environment/schema/lanes.py +53 -0
  113. package/runtime/gatewaysdk/environment/schema/ledger_spill.py +828 -0
  114. package/runtime/gatewaysdk/environment/schema/local.py +58 -170
  115. package/runtime/gatewaysdk/environment/schema/mapping.py +5 -25
  116. package/runtime/gatewaysdk/environment/schema/openapi_import.py +112 -73
  117. package/runtime/gatewaysdk/environment/schema/openapi_paging.py +147 -0
  118. package/runtime/gatewaysdk/environment/schema/openapi_payloads.py +288 -0
  119. package/runtime/gatewaysdk/environment/schema/openapi_routes.py +97 -102
  120. package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +113 -30
  121. package/runtime/gatewaysdk/environment/schema/platform.py +137 -187
  122. package/runtime/gatewaysdk/environment/schema/platform_import.py +2 -3
  123. package/runtime/gatewaysdk/environment/schema/platform_query.py +61 -5
  124. package/runtime/gatewaysdk/environment/schema/primary_key.py +61 -0
  125. package/runtime/gatewaysdk/environment/schema/proof.py +19 -12
  126. package/runtime/gatewaysdk/environment/schema/request_body.py +238 -0
  127. package/runtime/gatewaysdk/environment/schema/request_ledger.py +958 -0
  128. package/runtime/gatewaysdk/environment/schema/route_bindings.py +25 -3
  129. package/runtime/gatewaysdk/environment/schema/route_miss.py +54 -0
  130. package/runtime/gatewaysdk/environment/schema/runtime.py +178 -308
  131. package/runtime/gatewaysdk/environment/schema/served_names.py +58 -0
  132. package/runtime/gatewaysdk/environment/schema/session_files.py +275 -0
  133. package/runtime/gatewaysdk/environment/schema/session_move.py +275 -0
  134. package/runtime/gatewaysdk/environment/schema/skills/agents/connector-template-author.md +5 -1
  135. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +10 -11
  136. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +49 -16
  137. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +39 -9
  138. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +27 -27
  139. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +33 -33
  140. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +13 -7
  141. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +49 -1
  142. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +182 -0
  143. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/openapi-import.md +50 -21
  144. package/runtime/gatewaysdk/environment/schema/slack.py +4 -8
  145. package/runtime/gatewaysdk/environment/schema/snapshot.py +516 -140
  146. package/runtime/gatewaysdk/environment/schema/spill_files.py +228 -0
  147. package/runtime/gatewaysdk/environment/schema/store_contract.py +8 -14
  148. package/runtime/gatewaysdk/environment/schema/tasks.py +267 -276
  149. package/runtime/gatewaysdk/environment/schema/tools_world.py +146 -242
  150. package/runtime/gatewaysdk/environment/schema/ui.py +24 -5
  151. package/runtime/gatewaysdk/environment/schema/ui_static/app.js +100 -130
  152. package/runtime/gatewaysdk/environment/schema/ui_static/index.html +1 -8
  153. package/runtime/gatewaysdk/environment/schema/validation.py +235 -41
  154. package/runtime/gatewaysdk/environment/schema/verbs.py +32 -36
  155. package/runtime/gatewaysdk/environment/schema/worker.py +6 -4
  156. package/runtime/gatewaysdk/environment/schema/workers.py +345 -96
  157. package/runtime/gatewaysdk/environment/schema/world_host.py +953 -0
  158. package/runtime/gatewaysdk/environment/schema/world_sql.py +81 -0
  159. package/runtime/gatewaysdk/environment/schema/world_tests.py +80 -50
  160. package/runtime/gatewaysdk/environment/score.py +57 -0
  161. package/runtime/gatewaysdk/environment/secret_values.py +36 -0
  162. package/runtime/gatewaysdk/environment/world.py +43 -4
  163. package/runtime/gatewaysdk/environment/world_session_contract.py +46 -5
  164. package/skills/agents/connector-template-author.md +5 -1
  165. package/skills/benchmarks-getting-started/SKILL.md +10 -11
  166. package/skills/connector-schema-authoring/SKILL.md +49 -16
  167. package/skills/connector-schema-authoring/connector-worlds.md +142 -11
  168. package/skills/connector-schema-authoring/world-schema.md +103 -51
  169. package/skills/world-data-ingestion/ROWS.md +39 -9
  170. package/skills/world-data-ingestion/SKILL.md +27 -27
  171. package/skills/worlds-getting-started/SKILL.md +33 -33
  172. package/skills/worlds-getting-started/references/cli-mcp-map.md +13 -7
  173. package/skills/worlds-getting-started/references/gotchas.md +49 -1
  174. package/skills/worlds-getting-started/references/journal-checks.md +182 -0
  175. package/skills/worlds-getting-started/references/openapi-import.md +50 -21
  176. package/runtime/gatewaysdk/environment/schema/store.py +0 -1013
@@ -1,26 +1,4 @@
1
- """A schema world opened on this machine the way the World Host opens it.
2
-
3
- One :class:`LocalSession` is one session: the world's template copied into a
4
- scratch directory, its handlers loaded, every ``[dependencies]`` alias opened
5
- beside it from its ``path`` (dependency tools served as ``<alias>.<tool>``),
6
- and, when asked, an HTTP server on a loopback port. The server speaks the
7
- session verbs under ``/__session/`` for every schema world (``POST call``,
8
- ``GET state``, ``POST grade``, ``POST reset``, ``POST seed``, ``GET tools``,
9
- ``GET task``, ``POST close``, the host's own shapes) and, when the tree carries
10
- ``connector.toml``, the vendor routes beside them with the api pin as the key.
11
- Tool calls and HTTP requests hit the SAME store, as they do on the host.
12
-
13
- The session is what an outside agent works against: ``GET task`` hands it the
14
- prompt it is to carry out and the verifiers that will grade it (a
15
- dependency's as ``<alias>/<name>``), the tools answer at ``POST call``, ``POST
16
- grade`` scores every world's state where it lives, and ``POST close`` ends the
17
- session — the server stops answering and whoever opened it (``gateway worlds
18
- serve``) returns.
19
-
20
- This is what ``gateway worlds call``, ``gateway worlds test`` and
21
- ``gateway worlds serve`` open; what passes here passes hosted, and a world
22
- that will not open here will not open there either.
23
- """
1
+ """A schema world opened on this machine the way the World Host opens it: what passes here passes hosted."""
24
2
 
25
3
  from __future__ import annotations
26
4
 
@@ -37,13 +15,16 @@ from pathlib import Path
37
15
  from typing import Any, Callable
38
16
 
39
17
  from . import snapshot as snapshots
40
- from .api import Router, Via, WorldApp, load_api_settings, send_response, vendor_credential, with_query
18
+ from .admin_routes import AdminToken
19
+ from .api import Router, Via, WorldApp, load_api_settings, send_response, with_query
20
+ from .call_capture import WorldRequestHandler, write_body
21
+ from .call_log import CallLog
41
22
  from .compiler import bundle_mode, fail
42
23
  from .conform import PIN
43
24
  from .connector import SPEC, load_spec
44
25
  from .dependencies import local_dependency_trees
45
26
  from .host_surfaces import UiSurface, api_target, cross_site, load_ui_surface, static_file
46
- from .runtime import call_operation, client_grant, task_card
27
+ from .runtime import task_card
47
28
  from .tools_world import (
48
29
  DependencyWorld,
49
30
  ToolsTask,
@@ -59,29 +40,24 @@ LOCAL_TASK = ToolsTask(id="local", prompt="A local session; every verifier grade
59
40
 
60
41
 
61
42
  def has_http(root: str | Path) -> bool:
62
- """Whether the world serves HTTP at all: only a tree with ``connector.toml``
63
- has routes. A schema world without one is tools-only, and that is a whole
64
- world, not a broken one."""
43
+ """A schema world without ``connector.toml`` is tools-only: a whole world, not a broken one."""
65
44
  return (Path(root) / SPEC).is_file()
66
45
 
67
46
 
68
- def load_local_version(root: Path, scratch: Path, *, require_tasks: bool) -> ToolsVersion:
47
+ def load_local_version(root: Path, scratch: Path) -> ToolsVersion:
69
48
  if bundle_mode(root) is None:
70
49
  fail(
71
50
  "world",
72
51
  f"{root} is not a schema world (no gateway-env.toml with a [schema] table); "
73
52
  "`gateway worlds schema init` starts one",
74
53
  )
75
- return load_tools_version(root, scratch / "template.sqlite", None, run_handlers=True, require_tasks=require_tasks)
54
+ return load_tools_version(root, scratch / "template.db", None, run_handlers=True)
76
55
 
77
56
 
78
57
  def load_local_dependencies(root: Path, version: ToolsVersion, scratch: Path) -> dict[str, DependencyWorld]:
79
- """Every alias the manifest declares, opened from its ``path``. A pin with
80
- no path is refused by :func:`local_dependency_trees`: the platform resolves
81
- pins, this machine cannot."""
82
58
  out: dict[str, DependencyWorld] = {}
83
59
  for alias, tree in local_dependency_trees(root, version.dependencies).items():
84
- dep_version = load_local_version(tree, scratch / "deps" / alias, require_tasks=False)
60
+ dep_version = load_local_version(tree, scratch / "deps" / alias)
85
61
  out[alias] = DependencyWorld.of(version.dependencies[alias], dep_version)
86
62
  return out
87
63
 
@@ -92,47 +68,36 @@ class LocalSession:
92
68
  world: ToolsWorld
93
69
  server: ThreadingHTTPServer | None
94
70
  _scratch: str
95
- #: The routes connector.toml declares, over the session's store, when the
96
- #: world has any: :meth:`call` answers an operation by name through them.
71
+ calls: CallLog
97
72
  app: WorldApp | None = None
98
- #: The credential the app takes: the pin a local serve is opened with.
99
73
  api_key: str | None = PIN
100
- #: The static ui connector.toml's ``[ui]`` declares, when the server serves one.
74
+ #: The only key the runner's /__world/* routes answer, minted per session; the host serves none of them.
75
+ admin: AdminToken = field(default_factory=AdminToken)
101
76
  ui: UiSurface | None = None
102
- #: The ui's own origin: the page at ``/`` and its ``api_path`` beside it,
103
- #: the layout the World Host gives a session's ui, so a frontend built for
104
- #: the root (absolute ``/assets/…`` urls, a client-side router) runs here
105
- #: unchanged. ``/__ui/`` on :attr:`server` stays for the generated page.
77
+ #: The ui on its own origin, as the World Host lays it out, so a frontend built for the root runs unchanged.
106
78
  ui_server: ThreadingHTTPServer | None = None
107
- #: Set once ``POST /__session/close`` was answered: the opener's cue to :meth:`close`.
108
79
  closing: threading.Event = field(default_factory=threading.Event)
109
- #: Set by the opener's parent watch when the process that started the serve is
110
- #: gone; ``closing`` is set with it, so :meth:`wait` returns.
80
+ #: Set with ``closing`` when the opener's process is gone, so :meth:`wait` returns.
111
81
  orphaned: threading.Event = field(default_factory=threading.Event)
112
82
 
113
83
  @property
114
84
  def base_url(self) -> str | None:
115
- """Where the server answers, or ``None`` when opened without one."""
116
85
  if self.server is None:
117
86
  return None
118
87
  return f"http://127.0.0.1:{self.server.server_port}"
119
88
 
120
89
  @property
121
90
  def routes(self) -> bool:
122
- """Whether the vendor routes are served beside the session verbs."""
123
91
  return has_http(self.root)
124
92
 
125
93
  @property
126
94
  def ui_url(self) -> str | None:
127
- """Where the world's ui answers: its own origin plus its entry, or None
128
- when the world declares none or the session has no server."""
129
95
  if self.ui_server is None or self.ui is None:
130
96
  return None
131
97
  return f"http://127.0.0.1:{self.ui_server.server_port}{self.ui.entry}"
132
98
 
133
99
  @property
134
100
  def ui_prefix_url(self) -> str | None:
135
- """The same page under ``/__ui/`` on the session's port, or None."""
136
101
  if self.server is None or self.ui is None:
137
102
  return None
138
103
  return f"{self.base_url}{UI_PREFIX}{self.ui.entry.lstrip('/')}"
@@ -142,21 +107,16 @@ class LocalSession:
142
107
  return list(self.world.served)
143
108
 
144
109
  def task(self) -> dict:
145
- """The task this session runs, as the outside agent reads it: the prompt
146
- to carry out, the tools it may call, and the verifiers that grade it,
147
- the root's by name and each dependency's as ``<alias>/<name>``."""
148
110
  return task_card(self.world)
149
111
 
150
112
  def call(self, tool: str, args: dict[str, Any]) -> dict:
151
- """The tool's ``{status, body}``, a route's when ``tool`` names an
152
- operation of connector.toml; a refusal is a 400 answer, not an error."""
153
113
  try:
154
- return call_served(self.world, self.app, tool, args, api_key=self.api_key)
114
+ return self.world.call(tool, args)
155
115
  except ContractError as error:
156
116
  return refusal(error)
157
117
 
158
118
  def state(self) -> dict:
159
- return self.world.state()
119
+ return self.calls.into_state(self.world.state())
160
120
 
161
121
  def grade(self) -> dict:
162
122
  return self.world.grade()
@@ -167,12 +127,6 @@ class LocalSession:
167
127
  def seed(self, args: dict) -> dict:
168
128
  return self.world.seed(args)
169
129
 
170
- def export(self, destination: Path) -> Path:
171
- return self.world.export(destination)
172
-
173
- def restore(self, source: Path) -> None:
174
- self.world.restore(source)
175
-
176
130
  def close(self) -> None:
177
131
  self.closing.set()
178
132
  for server in (self.server, self.ui_server):
@@ -183,8 +137,6 @@ class LocalSession:
183
137
  shutil.rmtree(self._scratch, ignore_errors=True)
184
138
 
185
139
  def wait(self, timeout: float | None = None) -> bool:
186
- """Block until the session is asked to end (``POST /__session/close``
187
- or :meth:`close`); ``False`` when ``timeout`` ran out first."""
188
140
  return self.closing.wait(timeout)
189
141
 
190
142
  def __enter__(self) -> LocalSession:
@@ -205,33 +157,28 @@ def open_world(
205
157
  ui_port: int | None = None,
206
158
  api_key: str | None = PIN,
207
159
  ) -> LocalSession:
208
- """Open one session of the world at ``root``.
209
-
210
- ``task`` selects a task the world declares (its prompt is served, its
211
- verifiers grade — the root's and, per its ``worlds``, each dependency's —
212
- and its seed is laid); ``None`` opens a plain session where every
213
- verifier grades.
214
- ``scenario`` starts the root in one of its ``scenarios/<name>``, the
215
- overlay replacing whole entities on the default state. ``http`` starts the
216
- server: the session verbs under ``/__session/`` for every world, the
217
- vendor routes beside them when the world has ``connector.toml``. A world
218
- that declares ``[ui]`` gets a second listener for the page on its own
219
- origin (``ui_port``; the next port up when ``port`` is fixed, any free
220
- one when it is 0), the layout the host serves it in.
221
- """
160
+ """``task`` None opens a plain session every verifier grades; ``ui_port`` None is the next port up from a fixed
161
+ ``port``, any free one when ``port`` is 0."""
222
162
  root = Path(root)
223
163
  scratch = tempfile.mkdtemp(prefix="gateway-local-")
224
164
  closing = threading.Event()
165
+ admin = AdminToken.mint()
225
166
  try:
226
- version = load_local_version(root, Path(scratch) / "version", require_tasks=False)
167
+ version = load_local_version(root, Path(scratch) / "version")
227
168
  dependencies = load_local_dependencies(root, version, Path(scratch) / "version")
228
169
  if task is not None and task not in version.tasks:
229
170
  fail(
230
171
  "task",
231
172
  f"no task '{task}' in {root.name}; it has {', '.join(sorted(version.tasks)) or 'none'}",
232
173
  )
174
+ spec = load_spec(root) if has_http(root) else None
175
+ calls = CallLog.for_spec(spec, secret=api_key)
233
176
  world = ToolsWorld(
234
- version, Path(scratch) / "session", task if task is not None else LOCAL_TASK, dependencies=dependencies
177
+ version,
178
+ Path(scratch) / "session",
179
+ task if task is not None else LOCAL_TASK,
180
+ dependencies=dependencies,
181
+ calls=calls,
235
182
  )
236
183
  try:
237
184
  if scenario is not None:
@@ -240,20 +187,19 @@ def open_world(
240
187
  ui_server = None
241
188
  ui = None
242
189
  app = None
243
- if has_http(root):
244
- spec = load_spec(root)
190
+ if spec is not None:
245
191
  settings = load_api_settings(root, spec)
246
- app = WorldApp(ToolsWorldState(world, root), Router(spec, settings), api_key)
192
+ app = WorldApp(ToolsWorldState(world, root), Router(spec, settings), api_key, calls=calls, admin=admin)
247
193
  if http:
248
194
  if app is not None:
249
195
  ui = load_ui_surface(root)
250
- server = bind_server(host, port, make_session_handler(world, app, closing, ui=ui, api_key=api_key))
196
+ server = bind_server(host, port, make_session_handler(world, app, calls, closing, ui=ui))
251
197
  threading.Thread(target=server.serve_forever, daemon=True).start()
252
198
  if ui is not None:
253
199
  ui_server = bind_server(
254
200
  host,
255
201
  ui_port if ui_port is not None else (port + 1 if port else 0),
256
- make_session_handler(world, app, closing, ui=ui, api_key=api_key, ui_origin=True),
202
+ make_session_handler(world, app, calls, closing, ui=ui, ui_origin=True),
257
203
  )
258
204
  threading.Thread(target=ui_server.serve_forever, daemon=True).start()
259
205
  except BaseException:
@@ -267,8 +213,10 @@ def open_world(
267
213
  world=world,
268
214
  server=server,
269
215
  _scratch=scratch,
216
+ calls=calls,
270
217
  app=app,
271
218
  api_key=api_key,
219
+ admin=admin,
272
220
  closing=closing,
273
221
  ui=ui,
274
222
  ui_server=ui_server,
@@ -276,8 +224,7 @@ def open_world(
276
224
 
277
225
 
278
226
  def port_owner(port: int) -> str | None:
279
- """``pid <n> (<command>)`` of whatever listens on ``port``, from ``lsof`` when this
280
- machine has it; None when nothing can be said. Best effort, never an error."""
227
+ """Best effort from ``lsof``, never an error; None when nothing can be said."""
281
228
  try:
282
229
  found = subprocess.run(
283
230
  ["lsof", "-nP", f"-iTCP:{port}", "-sTCP:LISTEN", "-Fpc"],
@@ -300,10 +247,8 @@ def port_owner(port: int) -> str | None:
300
247
 
301
248
 
302
249
  def bind_server(host: str, port: int, handler: type[BaseHTTPRequestHandler]) -> ThreadingHTTPServer:
303
- """The session's server on ``host:port``, or a refusal that NAMES the port and,
304
- when it can, who holds it. A bare ``Address already in use`` from a backgrounded
305
- serve went unread, and every curl after it hit whatever else answered there
306
- (CRM dogfood, 2026-09-16); this serve never answers from another server."""
250
+ """A refusal names the port and its holder: a bare EADDRINUSE from a backgrounded serve goes unread while
251
+ every curl after it reaches whatever else answers there."""
307
252
  try:
308
253
  return ThreadingHTTPServer((host, port), handler)
309
254
  except OSError as error:
@@ -318,40 +263,21 @@ def bind_server(host: str, port: int, handler: type[BaseHTTPRequestHandler]) ->
318
263
 
319
264
 
320
265
  SESSION_PREFIX = "/__session/"
321
- #: Where the session's port mounts the world's static ui beside the routes,
322
- #: for the generated page (relative asset urls, `./app.js`). The host serves
323
- #: a ui on its own origin, and so does the session's second listener
324
- #: (:func:`open_world` ``ui_port``): the page at ``/``, its ``api_path``
325
- #: beside it, so a frontend built for the root works in both places.
326
266
  UI_PREFIX = "/__ui/"
327
267
 
328
268
 
329
269
  def make_session_handler(
330
270
  world: ToolsWorld,
331
271
  app: WorldApp | None,
272
+ calls: CallLog,
332
273
  closing: threading.Event | None = None,
333
274
  *,
334
275
  ui: UiSurface | None = None,
335
- api_key: str | None = PIN,
336
276
  ui_origin: bool = False,
337
277
  ) -> type[BaseHTTPRequestHandler]:
338
- """The local server's handler: ``/__session/<verb>`` is the session (the
339
- host's control verbs, one session, no secret — this is loopback on the
340
- author's machine); ``/__ui/…`` the world's static ui when connector.toml
341
- declares one, and its ``api_path`` prefix the vendor routes with the pin
342
- presented for the page (the host does the same with the session cookie);
343
- any other path is the vendor route when the world has routes, else a 404
344
- that says where the tools are. ``POST close`` answers ``{closed: true}``
345
- and sets ``closing``: the opener tears the session down (a handler cannot
346
- stop the server it runs in). With ``ui_origin`` the handler is the ui's own
347
- origin instead: the page at ``/`` (every path that is not a file of it
348
- falls back to ``index.html``, for a client-side router) and its
349
- ``api_path`` prefix answered with the pin — nothing else, as on the host."""
278
+ """``/__session/`` takes no secret: it is loopback on the author's machine. ``POST close`` only sets ``closing``,
279
+ as a handler cannot stop the server it runs in; the opener tears the session down."""
350
280
  closing = closing if closing is not None else threading.Event()
351
- # The page's calls and a `/__session/call` of an operation are presented
352
- # as a granted client, as the host presents them; the world's own token
353
- # dance stays available beside.
354
- grant = client_grant(app, api_key)
355
281
 
356
282
  def close() -> dict:
357
283
  closing.set()
@@ -362,33 +288,30 @@ def make_session_handler(
362
288
  fail("host", "a schema world has no [redact] policy; seed it with redact=off")
363
289
  return world.seed({"rows": rows, "mode": mode})
364
290
 
365
- def grade(report: str | None = None, context: dict | None = None) -> dict:
366
- # The local session grades by the world's own verifiers; an agent's
367
- # report and the other worlds' evidence are read by a session task's
368
- # graders, which only the host runs.
291
+ def grade(
292
+ report: str | None = None, context: dict | None = None, journal: dict | None = None, grader: dict | None = None
293
+ ) -> dict:
294
+ # Only the host runs the session-task graders these feed; a local session records no journal.
295
+ if grader is not None:
296
+ fail("host", "a candidate grader is graded on a World Host session (worlds task try)")
369
297
  return world.grade()
370
298
 
371
- # The session protocol (:data:`verbs.SESSION_VERBS`) bound to this
372
- # session's operations, by route; the host binds the same rows to its own.
373
299
  operations: dict[str, Callable[..., dict]] = {
374
300
  "GET tools": lambda: {"tools": list(world.served)},
375
301
  "GET task": lambda: task_card(world),
376
- "GET state": world.state,
377
- "GET evidence": world.grader_state,
302
+ "GET state": lambda: calls.into_state(world.state()),
303
+ "GET evidence": lambda: calls.into_state(world.grader_state()),
378
304
  "POST grade": grade,
379
305
  "POST reset": world.reset,
380
306
  "POST seed": seed,
381
- "POST call": lambda tool, args: call_served(world, app, tool, args, api_key=api_key, grant=grant),
307
+ "POST call": world.call,
382
308
  "POST close": close,
383
309
  }
384
310
 
385
- class Handler(BaseHTTPRequestHandler):
311
+ class Handler(WorldRequestHandler):
386
312
  server_version = "gateway-world-local"
387
313
 
388
- def log_message(self, *_):
389
- pass
390
-
391
- def _serve(self, method: str) -> None:
314
+ def _dispatch(self, method: str) -> None:
392
315
  length = int(self.headers.get("Content-Length") or 0)
393
316
  raw = self.rfile.read(length) if length else b""
394
317
  path = self.path.split("?", 1)[0]
@@ -397,6 +320,9 @@ def make_session_handler(
397
320
  if app is not None and api_target(ui, path) is not None:
398
321
  return self._ui_api(method, path, raw, Via.UI)
399
322
  return self._ui(method, path)
323
+ origin = self.headers.get("Origin")
324
+ if origin and not _local_origin(origin):
325
+ return self._reply(403, {"error": "this session answers this machine's pages, not another site's"})
400
326
  if path.startswith(SESSION_PREFIX):
401
327
  return self._session(method, path[len(SESSION_PREFIX) :].strip("/"), raw)
402
328
  if ui is not None and (path == UI_PREFIX.rstrip("/") or path.startswith(UI_PREFIX)):
@@ -427,13 +353,10 @@ def make_session_handler(
427
353
  self.send_header(name, value)
428
354
  self.send_header("Content-Length", str(len(payload)))
429
355
  self.end_headers()
430
- self.wfile.write(payload)
356
+ write_body(self, payload)
431
357
 
432
358
  def _ui_api(self, method: str, path: str, raw: bytes, via: Via) -> None:
433
- """The page's same-origin api call: strip the ``api_path`` prefix
434
- and answer the route with the world's own credential for the pin,
435
- the way the host answers it for the session cookie. Only the ui
436
- port's prefix is ``via: ui``; the session port is the api origin."""
359
+ """Answers with the world's own credential for the pin, as the host does for the session cookie."""
437
360
  assert app is not None and ui is not None
438
361
  route = api_target(ui, path)
439
362
  assert route is not None
@@ -444,7 +367,7 @@ def make_session_handler(
444
367
  )
445
368
  query = self.path.split("?", 1)[1] if "?" in self.path else ""
446
369
  headers = {k.lower(): v for k, v in self.headers.items() if k.lower() not in ("cookie", "authorization")}
447
- credential_headers, credential_query = vendor_credential(app.router.spec, api_key or "", grant=grant)
370
+ credential_headers, credential_query = app.door.present()
448
371
  target = with_query(route + (f"?{query}" if query else ""), credential_query)
449
372
  status, body, extra = app.handle(
450
373
  method,
@@ -477,51 +400,16 @@ def make_session_handler(
477
400
  self.send_header("Content-Type", "application/json")
478
401
  self.send_header("Content-Length", str(len(data)))
479
402
  self.end_headers()
480
- self.wfile.write(data)
481
-
482
- def do_GET(self):
483
- self._serve("GET")
484
-
485
- def do_POST(self):
486
- self._serve("POST")
487
-
488
- def do_PUT(self):
489
- self._serve("PUT")
490
-
491
- def do_PATCH(self):
492
- self._serve("PATCH")
493
-
494
- def do_DELETE(self):
495
- self._serve("DELETE")
403
+ write_body(self, data)
496
404
 
497
405
  return Handler
498
406
 
499
407
 
500
408
  def _local_origin(origin: str) -> bool:
501
- """Whether a browser ``Origin`` names this machine's loopback."""
502
409
  host = urllib.parse.urlsplit(origin).hostname
503
410
  return host in ("127.0.0.1", "localhost", "::1")
504
411
 
505
412
 
506
- def call_served(
507
- world: ToolsWorld,
508
- app: WorldApp | None,
509
- tool: str,
510
- args: dict,
511
- *,
512
- api_key: str | None = PIN,
513
- grant: str | None = None,
514
- ) -> dict:
515
- """One name of what the session serves, answered as the World Host answers
516
- it: a tool by name (a dependency's as ``alias.tool``); on a tree with
517
- connector.toml, an operation by name too, answered by its route over the
518
- same store, ``{status, body}`` the route's own. A name that is both is the
519
- tool's."""
520
- if app is not None and tool not in world.version.tool_names and tool in app.router.spec.operations:
521
- return call_operation(app, tool, args, api_key or "", allowed=world.allowed, grant=grant)
522
- return world.call(tool, args)
523
-
524
-
525
413
  def _apply_scenario(world: ToolsWorld, root: Path, name: str) -> None:
526
414
  scenarios = snapshots.scenario_dirs(root)
527
415
  if name not in scenarios:
@@ -57,6 +57,7 @@ from pathlib import Path
57
57
  from typing import Any, Iterable
58
58
 
59
59
  from .._toml import tomllib
60
+ from .primary_key import PrimaryKey
60
61
  from .transforms import apply_transforms, parse_transform
61
62
  from .validation import ContractError, fail
62
63
 
@@ -82,9 +83,6 @@ _SOURCE_REF = re.compile(r"^trace:([^/]+)/(.+)$")
82
83
  MISSING: Any = object()
83
84
 
84
85
 
85
- # ---------------------------------------------------------------- paths
86
-
87
-
88
86
  def parse_path(text: str, location: str) -> tuple[Any, ...]:
89
87
  """A path as segments: a key, an integer index, or ``"*"`` for a fan-out.
90
88
 
@@ -165,9 +163,6 @@ def resolve(segments: tuple[Any, ...], scope: Scope) -> tuple[Any, bool]:
165
163
  return _walk(scope.item, segments)
166
164
 
167
165
 
168
- # ---------------------------------------------------------------- the grammar
169
-
170
-
171
166
  @dataclass(frozen=True)
172
167
  class Field:
173
168
  name: str
@@ -400,9 +395,6 @@ def parse_mapping(raw: str | dict, where: str = FILE) -> Mapping:
400
395
  return Mapping(sources=sources, on_conflict=on_conflict, unmatched=unmatched)
401
396
 
402
397
 
403
- # ---------------------------------------------------------------- the contract
404
-
405
-
406
398
  Entities = dict[str, dict]
407
399
 
408
400
 
@@ -465,9 +457,6 @@ def load_mapping(root: str | Path, path: str | Path | None = None) -> Mapping |
465
457
  return parse_mapping(file.read_text(encoding="utf-8"), file.name)
466
458
 
467
459
 
468
- # ---------------------------------------------------------------- values
469
-
470
-
471
460
  def _instant(value: Any) -> datetime | None:
472
461
  if not isinstance(value, str) or not value.strip():
473
462
  return None
@@ -560,9 +549,6 @@ def _holds(source: Source, scope: Scope) -> bool:
560
549
  return True
561
550
 
562
551
 
563
- # ---------------------------------------------------------------- the report
564
-
565
-
566
552
  class _SourceReport:
567
553
  def __init__(self, source: Source, entities: Entities) -> None:
568
554
  self.source = source
@@ -619,9 +605,6 @@ def sample(value: Any) -> str:
619
605
  return text if len(text) <= SAMPLE_WIDTH else text[: SAMPLE_WIDTH - 1] + "…"
620
606
 
621
607
 
622
- # ---------------------------------------------------------------- the rows
623
-
624
-
625
608
  def record_meta(record: dict, index: int) -> dict[str, Any]:
626
609
  source = record.get("source")
627
610
  ref = _SOURCE_REF.match(source) if isinstance(source, str) else None
@@ -649,12 +632,12 @@ class _Held:
649
632
  def put(self, entity: str, row: dict, at: datetime | None) -> None:
650
633
  self.sequence += 1
651
634
  order = (at or datetime.min.replace(tzinfo=timezone.utc), self.sequence)
652
- keys = self.entities[entity].get("primary_key", [])
635
+ identity = PrimaryKey.of(self.entities[entity]).identity(row)
653
636
  listed = self.rows.setdefault(entity, [])
654
- if not keys or any(k not in row for k in keys):
655
- listed.append((order, row)) # the import refuses it, naming the missing key field
637
+ if identity is None:
638
+ listed.append((order, row))
656
639
  return
657
- key = (entity, tuple(json.dumps(row[k], sort_keys=True) for k in keys))
640
+ key = (entity, identity)
658
641
  held = self.index.get(key)
659
642
  if held is None:
660
643
  self.index[key] = len(listed)
@@ -815,9 +798,6 @@ def apply_mapping(mapping: Mapping, records: Iterable[Any], entities: Entities)
815
798
  return rows, report
816
799
 
817
800
 
818
- # ---------------------------------------------------------------- map init
819
-
820
-
821
801
  def _shape(value: Any) -> str:
822
802
  if isinstance(value, dict):
823
803
  return "an object"