@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.
- package/README.md +8 -6
- package/dist/cli.js +4372 -2265
- package/dist/cli.js.map +1 -1
- package/dist/cli.mjs +4362 -2256
- 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 +259 -58
- package/dist/files/index.js.map +1 -1
- package/dist/files/index.mjs +249 -50
- package/dist/files/index.mjs.map +1 -1
- package/dist/hooks/index.d.mts +1 -1
- package/dist/hooks/index.d.ts +1 -1
- package/dist/hooks/index.js +124 -11
- package/dist/hooks/index.js.map +1 -1
- package/dist/hooks/index.mjs +124 -11
- package/dist/hooks/index.mjs.map +1 -1
- package/dist/{index-C3UzD0G3.d.mts → index-CDPQBsU5.d.mts} +19 -3
- package/dist/{index-C3UzD0G3.d.ts → index-CDPQBsU5.d.ts} +19 -3
- 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 +5 -5
- package/dist/index.d.ts +5 -5
- package/dist/index.js +2240 -789
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +2150 -739
- 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 +253 -52
- package/dist/traces/index.js.map +1 -1
- package/dist/traces/index.mjs +243 -44
- 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 +75 -13
- package/dist/tracing/index.js.map +1 -1
- package/dist/tracing/index.mjs +75 -13
- package/dist/tracing/index.mjs.map +1 -1
- package/dist/worlds/index.d.mts +893 -482
- package/dist/worlds/index.d.ts +893 -482
- package/dist/worlds/index.js +1968 -669
- package/dist/worlds/index.js.map +1 -1
- package/dist/worlds/index.mjs +1960 -662
- 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 +48 -88
- package/runtime/gatewaysdk/environment/_world.py +155 -237
- package/runtime/gatewaysdk/environment/backing.py +133 -0
- package/runtime/gatewaysdk/environment/core.py +2 -17
- package/runtime/gatewaysdk/environment/legacy_sqlite.py +288 -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/admission.py +174 -0
- package/runtime/gatewaysdk/environment/schema/api.py +347 -892
- package/runtime/gatewaysdk/environment/schema/assertions.py +458 -0
- package/runtime/gatewaysdk/environment/schema/batch.py +44 -39
- package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +17 -5
- package/runtime/gatewaysdk/environment/schema/cache_layout.py +5 -0
- package/runtime/gatewaysdk/environment/schema/call_capture.py +309 -0
- package/runtime/gatewaysdk/environment/schema/call_log.py +503 -0
- package/runtime/gatewaysdk/environment/schema/call_redaction.py +526 -0
- package/runtime/gatewaysdk/environment/schema/cast.py +15 -35
- package/runtime/gatewaysdk/environment/schema/compiler.py +334 -158
- package/runtime/gatewaysdk/environment/schema/conform.py +14 -39
- package/runtime/gatewaysdk/environment/schema/connector.py +113 -211
- package/runtime/gatewaysdk/environment/schema/connectors/confluence/connector.toml +1 -12
- package/runtime/gatewaysdk/environment/schema/connectors/github/connector.toml +1 -0
- package/runtime/gatewaysdk/environment/schema/connectors/servicenow/connector.toml +2 -5
- package/runtime/gatewaysdk/environment/schema/cors.py +54 -0
- package/runtime/gatewaysdk/environment/schema/credentials.py +313 -8
- package/runtime/gatewaysdk/environment/schema/data.py +60 -216
- 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 +936 -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 +215 -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/reads.py +169 -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 +393 -0
- package/runtime/gatewaysdk/environment/schema/declared_routes.py +210 -0
- package/runtime/gatewaysdk/environment/schema/domain_migration.py +236 -0
- package/runtime/gatewaysdk/environment/schema/door.py +899 -0
- package/runtime/gatewaysdk/environment/schema/envelope.py +227 -0
- package/runtime/gatewaysdk/environment/schema/extract.py +6 -13
- package/runtime/gatewaysdk/environment/schema/grading.py +90 -103
- package/runtime/gatewaysdk/environment/schema/handler_errors.py +163 -12
- package/runtime/gatewaysdk/environment/schema/host.py +237 -1795
- package/runtime/gatewaysdk/environment/schema/host_control.py +144 -0
- package/runtime/gatewaysdk/environment/schema/host_handoff.py +370 -0
- package/runtime/gatewaysdk/environment/schema/host_loops.py +97 -0
- package/runtime/gatewaysdk/environment/schema/host_owners.py +121 -0
- package/runtime/gatewaysdk/environment/schema/host_proxy.py +111 -0
- package/runtime/gatewaysdk/environment/schema/host_requests.py +6 -0
- package/runtime/gatewaysdk/environment/schema/host_session.py +126 -0
- package/runtime/gatewaysdk/environment/schema/host_surfaces.py +79 -21
- package/runtime/gatewaysdk/environment/schema/host_transfers.py +127 -0
- package/runtime/gatewaysdk/environment/schema/host_versions.py +242 -0
- package/runtime/gatewaysdk/environment/schema/host_workers.py +577 -0
- package/runtime/gatewaysdk/environment/schema/journal.py +437 -0
- package/runtime/gatewaysdk/environment/schema/lanes.py +53 -0
- package/runtime/gatewaysdk/environment/schema/ledger_spill.py +828 -0
- package/runtime/gatewaysdk/environment/schema/local.py +58 -170
- 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 +137 -187
- 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/request_body.py +238 -0
- package/runtime/gatewaysdk/environment/schema/request_ledger.py +958 -0
- package/runtime/gatewaysdk/environment/schema/route_bindings.py +25 -3
- package/runtime/gatewaysdk/environment/schema/route_miss.py +54 -0
- package/runtime/gatewaysdk/environment/schema/runtime.py +178 -308
- package/runtime/gatewaysdk/environment/schema/served_names.py +58 -0
- package/runtime/gatewaysdk/environment/schema/session_files.py +275 -0
- package/runtime/gatewaysdk/environment/schema/session_move.py +275 -0
- package/runtime/gatewaysdk/environment/schema/skills/agents/connector-template-author.md +5 -1
- package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +10 -11
- package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +49 -16
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +39 -9
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +27 -27
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +33 -33
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +13 -7
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +49 -1
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +182 -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 +516 -140
- package/runtime/gatewaysdk/environment/schema/spill_files.py +228 -0
- package/runtime/gatewaysdk/environment/schema/store_contract.py +8 -14
- package/runtime/gatewaysdk/environment/schema/tasks.py +267 -276
- package/runtime/gatewaysdk/environment/schema/tools_world.py +146 -242
- 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 +235 -41
- package/runtime/gatewaysdk/environment/schema/verbs.py +32 -36
- package/runtime/gatewaysdk/environment/schema/worker.py +6 -4
- package/runtime/gatewaysdk/environment/schema/workers.py +345 -96
- package/runtime/gatewaysdk/environment/schema/world_host.py +953 -0
- package/runtime/gatewaysdk/environment/schema/world_sql.py +81 -0
- package/runtime/gatewaysdk/environment/schema/world_tests.py +80 -50
- package/runtime/gatewaysdk/environment/score.py +57 -0
- package/runtime/gatewaysdk/environment/secret_values.py +36 -0
- package/runtime/gatewaysdk/environment/world.py +43 -4
- package/runtime/gatewaysdk/environment/world_session_contract.py +46 -5
- package/skills/agents/connector-template-author.md +5 -1
- package/skills/benchmarks-getting-started/SKILL.md +10 -11
- package/skills/connector-schema-authoring/SKILL.md +49 -16
- package/skills/connector-schema-authoring/connector-worlds.md +142 -11
- package/skills/connector-schema-authoring/world-schema.md +103 -51
- package/skills/world-data-ingestion/ROWS.md +39 -9
- package/skills/world-data-ingestion/SKILL.md +27 -27
- package/skills/worlds-getting-started/SKILL.md +33 -33
- package/skills/worlds-getting-started/references/cli-mcp-map.md +13 -7
- package/skills/worlds-getting-started/references/gotchas.md +49 -1
- package/skills/worlds-getting-started/references/journal-checks.md +182 -0
- package/skills/worlds-getting-started/references/openapi-import.md +50 -21
- 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 .
|
|
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
|
|
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
|
-
"""
|
|
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
|
|
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.
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
"""
|
|
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"
|
|
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,
|
|
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
|
|
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
|
|
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,
|
|
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
|
-
"""
|
|
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
|
-
"""
|
|
304
|
-
|
|
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
|
-
"""
|
|
339
|
-
|
|
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(
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
#
|
|
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":
|
|
307
|
+
"POST call": world.call,
|
|
382
308
|
"POST close": close,
|
|
383
309
|
}
|
|
384
310
|
|
|
385
|
-
class Handler(
|
|
311
|
+
class Handler(WorldRequestHandler):
|
|
386
312
|
server_version = "gateway-world-local"
|
|
387
313
|
|
|
388
|
-
def
|
|
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
|
|
356
|
+
write_body(self, payload)
|
|
431
357
|
|
|
432
358
|
def _ui_api(self, method: str, path: str, raw: bytes, via: Via) -> None:
|
|
433
|
-
"""
|
|
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 =
|
|
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
|
|
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
|
-
|
|
635
|
+
identity = PrimaryKey.of(self.entities[entity]).identity(row)
|
|
653
636
|
listed = self.rows.setdefault(entity, [])
|
|
654
|
-
if
|
|
655
|
-
listed.append((order, row))
|
|
637
|
+
if identity is None:
|
|
638
|
+
listed.append((order, row))
|
|
656
639
|
return
|
|
657
|
-
key = (entity,
|
|
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"
|