@withgateway/sdk 0.3.3 → 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 +4 -3
- package/dist/cli.js +2221 -962
- package/dist/cli.js.map +1 -1
- package/dist/cli.mjs +2212 -953
- package/dist/cli.mjs.map +1 -1
- package/dist/files/index.js +81 -19
- package/dist/files/index.js.map +1 -1
- package/dist/files/index.mjs +79 -17
- 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.d.mts +2 -2
- package/dist/index.d.ts +2 -2
- package/dist/index.js +903 -221
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +868 -212
- package/dist/index.mjs.map +1 -1
- package/dist/traces/index.js +78 -16
- package/dist/traces/index.js.map +1 -1
- package/dist/traces/index.mjs +76 -14
- package/dist/traces/index.mjs.map +1 -1
- package/dist/tracing/index.js +7 -1
- package/dist/tracing/index.js.map +1 -1
- package/dist/tracing/index.mjs +7 -1
- package/dist/tracing/index.mjs.map +1 -1
- package/dist/worlds/index.d.mts +692 -410
- package/dist/worlds/index.d.ts +692 -410
- package/dist/worlds/index.js +740 -197
- package/dist/worlds/index.js.map +1 -1
- package/dist/worlds/index.mjs +736 -193
- package/dist/worlds/index.mjs.map +1 -1
- package/package.json +1 -1
- package/runtime/gatewaysdk/environment/_materialize.py +5 -25
- package/runtime/gatewaysdk/environment/_world.py +58 -65
- package/runtime/gatewaysdk/environment/backing.py +20 -24
- package/runtime/gatewaysdk/environment/core.py +1 -16
- package/runtime/gatewaysdk/environment/legacy_sqlite.py +14 -27
- package/runtime/gatewaysdk/environment/schema/admission.py +174 -0
- package/runtime/gatewaysdk/environment/schema/api.py +174 -471
- package/runtime/gatewaysdk/environment/schema/assertions.py +458 -0
- package/runtime/gatewaysdk/environment/schema/batch.py +3 -3
- 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 +230 -18
- package/runtime/gatewaysdk/environment/schema/call_redaction.py +201 -19
- package/runtime/gatewaysdk/environment/schema/cast.py +15 -35
- package/runtime/gatewaysdk/environment/schema/conform.py +6 -27
- package/runtime/gatewaysdk/environment/schema/connector.py +89 -152
- 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 +14 -13
- package/runtime/gatewaysdk/environment/schema/database/base.py +106 -165
- package/runtime/gatewaysdk/environment/schema/database/guard.py +43 -36
- package/runtime/gatewaysdk/environment/schema/database/reads.py +169 -0
- package/runtime/gatewaysdk/environment/schema/database/sqlite.py +57 -31
- package/runtime/gatewaysdk/environment/schema/declared_routes.py +210 -0
- package/runtime/gatewaysdk/environment/schema/door.py +899 -0
- package/runtime/gatewaysdk/environment/schema/envelope.py +86 -28
- package/runtime/gatewaysdk/environment/schema/grading.py +58 -86
- package/runtime/gatewaysdk/environment/schema/handler_errors.py +25 -4
- package/runtime/gatewaysdk/environment/schema/host.py +229 -1695
- 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/ledger_spill.py +828 -0
- package/runtime/gatewaysdk/environment/schema/local.py +31 -116
- package/runtime/gatewaysdk/environment/schema/platform.py +15 -17
- 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 +129 -176
- package/runtime/gatewaysdk/environment/schema/session_files.py +133 -24
- 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 +8 -9
- package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +31 -6
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +12 -8
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +13 -13
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +23 -23
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +11 -6
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +35 -2
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +182 -0
- package/runtime/gatewaysdk/environment/schema/snapshot.py +149 -29
- package/runtime/gatewaysdk/environment/schema/spill_files.py +228 -0
- package/runtime/gatewaysdk/environment/schema/tasks.py +229 -323
- package/runtime/gatewaysdk/environment/schema/tools_world.py +84 -203
- package/runtime/gatewaysdk/environment/schema/validation.py +69 -1
- 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 +203 -39
- package/runtime/gatewaysdk/environment/schema/world_host.py +953 -0
- package/runtime/gatewaysdk/environment/schema/world_tests.py +9 -11
- package/runtime/gatewaysdk/environment/world.py +1 -1
- package/runtime/gatewaysdk/environment/world_session_contract.py +14 -0
- package/skills/agents/connector-template-author.md +5 -1
- package/skills/benchmarks-getting-started/SKILL.md +8 -9
- package/skills/connector-schema-authoring/SKILL.md +31 -6
- package/skills/connector-schema-authoring/connector-worlds.md +129 -7
- package/skills/world-data-ingestion/ROWS.md +12 -8
- package/skills/world-data-ingestion/SKILL.md +13 -13
- package/skills/worlds-getting-started/SKILL.md +23 -23
- package/skills/worlds-getting-started/references/cli-mcp-map.md +11 -6
- package/skills/worlds-getting-started/references/gotchas.md +35 -2
- package/skills/worlds-getting-started/references/journal-checks.md +182 -0
|
@@ -5,26 +5,54 @@ starts from. Its rows are proven once, when the host caches the version; an
|
|
|
5
5
|
open or a reset clones it and the store runs only its contract and DDL check.
|
|
6
6
|
A :class:`SessionExport` is a checkpoint a session continues from: its bytes
|
|
7
7
|
must hash to the sha256 the platform recorded when the host exported it, and
|
|
8
|
-
it carries the session's call log beside the rows.
|
|
8
|
+
it carries the session's call log beside the rows. A :class:`RecoveredSession`
|
|
9
|
+
is the directory a version worker that died left a session in, set aside by its
|
|
10
|
+
supervisor: its store's committed state and its call journal are the checkpoint
|
|
11
|
+
the next worker continues the session from.
|
|
9
12
|
"""
|
|
10
13
|
|
|
11
14
|
from __future__ import annotations
|
|
12
15
|
|
|
13
16
|
import json
|
|
14
17
|
import os
|
|
18
|
+
import shutil
|
|
15
19
|
import uuid
|
|
16
20
|
from pathlib import Path
|
|
17
|
-
from typing import NamedTuple
|
|
21
|
+
from typing import TYPE_CHECKING, Iterable, NamedTuple
|
|
18
22
|
|
|
19
23
|
from .._materialize import materialize_template
|
|
24
|
+
from .call_log import CallJournal
|
|
20
25
|
from .compiler import Contract
|
|
21
26
|
from .database import WorldDatabase
|
|
27
|
+
from .database.reads import FORMAT as READ_INDEXES
|
|
22
28
|
from .snapshot import contract_hash, file_sha256, runtime_version
|
|
23
29
|
from .validation import fail
|
|
24
30
|
|
|
31
|
+
if TYPE_CHECKING:
|
|
32
|
+
from .runtime import WorldRuntime
|
|
33
|
+
|
|
34
|
+
#: A session's call journal, beside its store in the session's directory.
|
|
35
|
+
CALLS_JOURNAL = "calls.jsonl"
|
|
36
|
+
#: A session's unsent request ledger entries, beside its store (:class:`~.request_ledger.RequestOutbox`).
|
|
37
|
+
LEDGER_JOURNAL = "requests.jsonl"
|
|
38
|
+
#: Where a supervisor sets a dead worker's session directories aside, under that worker's home.
|
|
39
|
+
RECOVERED_DIR = "recovered"
|
|
40
|
+
|
|
25
41
|
_PROVEN = object()
|
|
26
42
|
|
|
27
43
|
|
|
44
|
+
def real_dir(path: Path) -> bool:
|
|
45
|
+
"""A directory at ``path`` itself, not a link to one somewhere else."""
|
|
46
|
+
return path.is_dir() and not path.is_symlink()
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
def clear(path: Path) -> None:
|
|
50
|
+
"""Remove whatever sits at ``path``, a symlink as a link, never what it points at."""
|
|
51
|
+
if path.is_symlink() or (path.exists() and not path.is_dir()):
|
|
52
|
+
path.unlink()
|
|
53
|
+
shutil.rmtree(path, ignore_errors=True)
|
|
54
|
+
|
|
55
|
+
|
|
28
56
|
def refuse_digest_mismatch(path: Path, sha256: str) -> None:
|
|
29
57
|
"""Refuse a session export whose bytes do not hash to the sha256 recorded for them."""
|
|
30
58
|
actual = file_sha256(path)
|
|
@@ -68,12 +96,21 @@ class ProvenTemplate:
|
|
|
68
96
|
return template
|
|
69
97
|
|
|
70
98
|
@classmethod
|
|
71
|
-
def prove(
|
|
72
|
-
|
|
99
|
+
def prove(
|
|
100
|
+
cls,
|
|
101
|
+
bundle: Path,
|
|
102
|
+
path: Path,
|
|
103
|
+
contract: Contract,
|
|
104
|
+
*,
|
|
105
|
+
fetched: bool,
|
|
106
|
+
read_fields: Iterable[tuple[str, tuple[str, ...]]] = (),
|
|
107
|
+
) -> ProvenTemplate:
|
|
108
|
+
"""The version's template at ``path``, with its read indexes (its keys' and the
|
|
109
|
+
``read_fields`` its routes filter on). ``fetched`` says the tree's snapshot is
|
|
73
110
|
the platform's, downloaded and verified against its recorded sha256 just now."""
|
|
74
111
|
template = cls(path, contract, _PROVEN)
|
|
75
112
|
if not template._recorded():
|
|
76
|
-
template._build(bundle, fetched=fetched)
|
|
113
|
+
template._build(bundle, fetched=fetched, read_fields=read_fields)
|
|
77
114
|
return template
|
|
78
115
|
|
|
79
116
|
@property
|
|
@@ -85,6 +122,7 @@ class ProvenTemplate:
|
|
|
85
122
|
"sha256": file_sha256(self.path),
|
|
86
123
|
"contractHash": contract_hash(self.contract),
|
|
87
124
|
"runtime": runtime_version(),
|
|
125
|
+
"readIndexes": READ_INDEXES,
|
|
88
126
|
}
|
|
89
127
|
|
|
90
128
|
def _recorded(self) -> bool:
|
|
@@ -94,12 +132,12 @@ class ProvenTemplate:
|
|
|
94
132
|
return False
|
|
95
133
|
return self.path.is_file() and recorded == self._proof()
|
|
96
134
|
|
|
97
|
-
def _build(self, bundle: Path, *, fetched: bool) -> None:
|
|
135
|
+
def _build(self, bundle: Path, *, fetched: bool, read_fields: Iterable[tuple[str, tuple[str, ...]]]) -> None:
|
|
98
136
|
staging = self.path.with_name(f".{self.path.name}.{uuid.uuid4().hex}")
|
|
99
137
|
try:
|
|
100
138
|
copied = materialize_template(bundle, staging, require_sql=True) is not None
|
|
101
|
-
|
|
102
|
-
|
|
139
|
+
with WorldDatabase.open(staging, self.contract, audit=copied and not fetched) as store:
|
|
140
|
+
store.index_reads(read_fields)
|
|
103
141
|
os.replace(staging, self.path)
|
|
104
142
|
finally:
|
|
105
143
|
staging.unlink(missing_ok=True)
|
|
@@ -117,28 +155,68 @@ class ExportFile(NamedTuple):
|
|
|
117
155
|
def for_worker(self) -> dict[str, str]:
|
|
118
156
|
return {"path": str(self.path), "sha256": self.sha256}
|
|
119
157
|
|
|
158
|
+
def checkpoint(self, engine: type[WorldDatabase], runtime: type[WorldRuntime]) -> SessionExport:
|
|
159
|
+
return SessionExport.verified(self, engine)
|
|
120
160
|
|
|
121
|
-
|
|
161
|
+
def discard(self) -> None:
|
|
162
|
+
self.path.unlink(missing_ok=True)
|
|
122
163
|
|
|
123
164
|
|
|
124
|
-
class
|
|
125
|
-
"""A
|
|
165
|
+
class RecoveredSession(NamedTuple):
|
|
166
|
+
"""A session's directory a dead version worker left on this host, which its
|
|
167
|
+
supervisor set aside before starting the next worker (that worker clears the
|
|
168
|
+
sessions directory it starts in). The file was the session's own store and the
|
|
169
|
+
worker that wrote it ran this version's code, as the next one does: it is the
|
|
170
|
+
session's committed state, every row audited as it committed, and its call
|
|
171
|
+
journal beside it."""
|
|
172
|
+
|
|
173
|
+
directory: Path
|
|
174
|
+
|
|
175
|
+
def checkpoint(self, engine: type[WorldDatabase], runtime: type[WorldRuntime]) -> SessionExport:
|
|
176
|
+
directory = self.directory
|
|
177
|
+
return SessionExport.recovered_from(
|
|
178
|
+
directory, engine, runtime.live_state(directory), runtime.dependency_states(directory)
|
|
179
|
+
)
|
|
180
|
+
|
|
181
|
+
def discard(self) -> None:
|
|
182
|
+
shutil.rmtree(self.directory, ignore_errors=True)
|
|
126
183
|
|
|
127
|
-
The bytes hash to the sha256 the platform recorded when the host exported them,
|
|
128
|
-
so they are the store's own copy, every row audited as it committed, and the
|
|
129
|
-
session opens on them without a second row audit. :meth:`verified` is the only
|
|
130
|
-
way to get one. The call log rides in the file as ``_gateway_calls``, a table the
|
|
131
|
-
store never opens: :meth:`carry_calls` writes it into a fresh export, and
|
|
132
|
-
:meth:`verified` reads it back and drops it before the store sees the file. What
|
|
133
|
-
it names is fixed once :meth:`verified` returns."""
|
|
134
184
|
|
|
135
|
-
|
|
185
|
+
_VERIFIED = object()
|
|
186
|
+
_RECOVERED = object()
|
|
187
|
+
|
|
136
188
|
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
189
|
+
class SessionExport:
|
|
190
|
+
"""A checkpoint the host continues a session from, opened without a second row audit.
|
|
191
|
+
|
|
192
|
+
Either an export whose bytes hash to the sha256 the platform recorded when the host
|
|
193
|
+
exported them (:meth:`verified`), so they are the store's own copy, every row
|
|
194
|
+
audited as it committed; or the committed state of a session's own store a dead
|
|
195
|
+
worker of the same version left on this host (:meth:`recovered_from`), which no
|
|
196
|
+
platform recorded: it was the live session's file, and the contract and DDL are
|
|
197
|
+
checked as for any open. The call log rides in an export as
|
|
198
|
+
``_gateway_calls``, a table the store never opens: :meth:`carry_calls` writes it
|
|
199
|
+
into a fresh export, and :meth:`verified` reads it back and drops it before the
|
|
200
|
+
store sees the file; a recovered checkpoint reads it from the call journal and
|
|
201
|
+
carries each dependency world's own checkpoint under ``worlds``. What it names is
|
|
202
|
+
fixed once it is made."""
|
|
203
|
+
|
|
204
|
+
__slots__ = ("_path", "_calls", "_worlds", "_unsent")
|
|
205
|
+
|
|
206
|
+
def __init__(
|
|
207
|
+
self,
|
|
208
|
+
path: Path,
|
|
209
|
+
calls: list[dict],
|
|
210
|
+
proof: object,
|
|
211
|
+
worlds: dict[str, SessionExport] | None = None,
|
|
212
|
+
unsent: list[dict] | None = None,
|
|
213
|
+
) -> None:
|
|
214
|
+
if proof is not _VERIFIED and proof is not _RECOVERED:
|
|
215
|
+
raise TypeError("a SessionExport comes from SessionExport.verified or SessionExport.recovered_from")
|
|
140
216
|
self._path = Path(path)
|
|
141
217
|
self._calls = tuple(calls)
|
|
218
|
+
self._worlds = dict(worlds or {})
|
|
219
|
+
self._unsent = tuple(unsent or ())
|
|
142
220
|
|
|
143
221
|
@property
|
|
144
222
|
def path(self) -> Path:
|
|
@@ -148,11 +226,23 @@ class SessionExport:
|
|
|
148
226
|
def calls(self) -> list[dict]:
|
|
149
227
|
return list(self._calls)
|
|
150
228
|
|
|
229
|
+
@property
|
|
230
|
+
def unsent(self) -> list[dict]:
|
|
231
|
+
"""The request ledger entries a dead worker had not sent; an export carries none."""
|
|
232
|
+
return list(self._unsent)
|
|
233
|
+
|
|
234
|
+
@property
|
|
235
|
+
def worlds(self) -> dict[str, SessionExport]:
|
|
236
|
+
"""Each dependency world's checkpoint, by alias; an export carries none."""
|
|
237
|
+
return dict(self._worlds)
|
|
238
|
+
|
|
151
239
|
@staticmethod
|
|
152
240
|
def required(export: object) -> SessionExport:
|
|
153
|
-
"""``export`` itself, refused unless :meth:`verified` made it."""
|
|
241
|
+
"""``export`` itself, refused unless :meth:`verified` or :meth:`recovered_from` made it."""
|
|
154
242
|
if not isinstance(export, SessionExport):
|
|
155
|
-
raise TypeError(
|
|
243
|
+
raise TypeError(
|
|
244
|
+
"a session resumes only from a SessionExport (SessionExport.verified, SessionExport.recovered_from)"
|
|
245
|
+
)
|
|
156
246
|
return export
|
|
157
247
|
|
|
158
248
|
@classmethod
|
|
@@ -161,6 +251,25 @@ class SessionExport:
|
|
|
161
251
|
calls = [json.loads(entry) for entry in engine.take_entries(export.path)]
|
|
162
252
|
return cls(export.path, calls, _VERIFIED)
|
|
163
253
|
|
|
254
|
+
@classmethod
|
|
255
|
+
def recovered_from(
|
|
256
|
+
cls, directory: Path, engine: type[WorldDatabase], live: Path, dependencies: dict[str, Path]
|
|
257
|
+
) -> SessionExport:
|
|
258
|
+
"""The committed state of the store at ``live`` and of each dependency world's
|
|
259
|
+
(a transaction their dead writer left half written undone by the engine), each
|
|
260
|
+
copied beside it, with the calls the session's journal kept."""
|
|
261
|
+
if not live.is_file() or live.is_symlink():
|
|
262
|
+
fail("host", f"the recovered session holds no store at {live.name}")
|
|
263
|
+
worlds = {alias: cls(cls._committed(store, engine), [], _RECOVERED) for alias, store in dependencies.items()}
|
|
264
|
+
calls, unsent = CallJournal.read(directory / CALLS_JOURNAL), CallJournal.read(directory / LEDGER_JOURNAL)
|
|
265
|
+
return cls(cls._committed(live, engine), calls, _RECOVERED, worlds, unsent)
|
|
266
|
+
|
|
267
|
+
@staticmethod
|
|
268
|
+
def _committed(live: Path, engine: type[WorldDatabase]) -> Path:
|
|
269
|
+
copy = live.with_name(f"recovered{Path(engine.snapshot_name).suffix}")
|
|
270
|
+
engine.recover_copy(live, copy)
|
|
271
|
+
return copy
|
|
272
|
+
|
|
164
273
|
@staticmethod
|
|
165
274
|
def carry_calls(path: Path, calls: list[dict], engine: type[WorldDatabase]) -> None:
|
|
166
275
|
engine.carry_entries(path, [json.dumps(call, sort_keys=True) for call in calls])
|
|
@@ -0,0 +1,275 @@
|
|
|
1
|
+
"""A session's way in while it changes hosts.
|
|
2
|
+
|
|
3
|
+
:class:`SessionMove` gates every request of one session that takes a turn. On the host a session
|
|
4
|
+
leaves (:mod:`host_handoff`) it goes ``serving`` → ``fenced`` (new requests wait, those inside
|
|
5
|
+
finish) → ``asking`` (quiet and settled: the platform may take its final export now) → ``moved``
|
|
6
|
+
(its requests go one hop to the new owner); back to ``serving`` when the platform keeps it here,
|
|
7
|
+
``closed`` when the platform says it is gone, ``shut`` when the host stops before it could move.
|
|
8
|
+
On the host it goes to, the platform opens it ``pending``: that copy serves nothing until the
|
|
9
|
+
platform's row names this host, which a platform verb says, or the owner lookup does for a request.
|
|
10
|
+
A fence the host lifts on its own (an ask turned away, a step that failed) puts the session back as
|
|
11
|
+
it was, a pending copy back to pending; only the platform's word makes a copy serve.
|
|
12
|
+
|
|
13
|
+
A data-plane request a move holds waits at most ``hold_s``, counted against its version's and its
|
|
14
|
+
session's waiting caps (:meth:`Admission.waiting`), then is told to come back (``503 moving`` with
|
|
15
|
+
``Retry-After``). A platform verb is never held: it is refused ``moving`` at once, and the platform
|
|
16
|
+
asks again where its row says the session is."""
|
|
17
|
+
|
|
18
|
+
from __future__ import annotations
|
|
19
|
+
|
|
20
|
+
import http.client
|
|
21
|
+
import threading
|
|
22
|
+
import time
|
|
23
|
+
from collections.abc import Callable, Iterator
|
|
24
|
+
from contextlib import AbstractContextManager, contextmanager
|
|
25
|
+
from typing import TYPE_CHECKING
|
|
26
|
+
|
|
27
|
+
from .host_workers import MOVING, NOT_MOVING, UNKNOWN_SESSION
|
|
28
|
+
from .validation import ContractError, fail
|
|
29
|
+
|
|
30
|
+
if TYPE_CHECKING:
|
|
31
|
+
from .world_host import WorldHost
|
|
32
|
+
|
|
33
|
+
SERVING = "serving"
|
|
34
|
+
PENDING = "pending"
|
|
35
|
+
FENCED = "fenced"
|
|
36
|
+
ASKING = "asking"
|
|
37
|
+
MOVED = "moved"
|
|
38
|
+
CLOSED = "closed"
|
|
39
|
+
SHUT = "shut"
|
|
40
|
+
HELD = frozenset({FENCED, ASKING})
|
|
41
|
+
|
|
42
|
+
HOLD_S = 25.0
|
|
43
|
+
MOVING_RETRY_AFTER_S = 2
|
|
44
|
+
PENDING_CHECK_S = 1.0
|
|
45
|
+
PENDING_LEASE_S = 300.0
|
|
46
|
+
|
|
47
|
+
Waiting = Callable[[], AbstractContextManager[None]]
|
|
48
|
+
OwnerNow = Callable[[], "str | None"]
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
def same_host(one: str | None, other: str | None) -> bool:
|
|
52
|
+
return one is not None and other is not None and one.rstrip("/") == other.rstrip("/")
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
def moving_refusal(session_id: str) -> ContractError:
|
|
56
|
+
return ContractError(
|
|
57
|
+
MOVING,
|
|
58
|
+
f"session {session_id} is moving to another host; retry after {MOVING_RETRY_AFTER_S} s",
|
|
59
|
+
retryAfter=MOVING_RETRY_AFTER_S,
|
|
60
|
+
)
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
class SessionMoved(Exception):
|
|
64
|
+
"""A request for a session that moved to ``owner``: it is sent on there, one hop."""
|
|
65
|
+
|
|
66
|
+
def __init__(self, session_id: str, owner: str) -> None:
|
|
67
|
+
super().__init__(f"session {session_id} moved to {owner}")
|
|
68
|
+
self.session_id = session_id
|
|
69
|
+
self.owner = owner
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
class SessionMove:
|
|
73
|
+
"""One session's state while it changes hosts, and the way in that state gives its requests."""
|
|
74
|
+
|
|
75
|
+
def __init__(self, session_id: str, *, pending: bool = False, hold_s: float = HOLD_S) -> None:
|
|
76
|
+
self.session_id = session_id
|
|
77
|
+
self.hold_s = hold_s
|
|
78
|
+
self._state = PENDING if pending else SERVING
|
|
79
|
+
self._owner: str | None = None
|
|
80
|
+
self._inside = 0
|
|
81
|
+
self._asked: tuple[float, str | None] = (float("-inf"), None)
|
|
82
|
+
self._exported = False
|
|
83
|
+
self._fenced_from = SERVING
|
|
84
|
+
self._changed = threading.Condition()
|
|
85
|
+
|
|
86
|
+
@property
|
|
87
|
+
def state(self) -> str:
|
|
88
|
+
with self._changed:
|
|
89
|
+
return self._state
|
|
90
|
+
|
|
91
|
+
@contextmanager
|
|
92
|
+
def request(self, waiting: Waiting, owner_now: OwnerNow, me: str | None, hopped: bool) -> Iterator[None]:
|
|
93
|
+
"""A data-plane request's way in: a pending copy serves it once the platform names this host, a
|
|
94
|
+
moving session keeps it up to ``hold_s``, a moved one sends it on (:class:`SessionMoved`)."""
|
|
95
|
+
self._confirm(owner_now, me, hopped)
|
|
96
|
+
with self._changed:
|
|
97
|
+
self._wait_out(waiting)
|
|
98
|
+
if self._state == MOVED:
|
|
99
|
+
raise SessionMoved(self.session_id, str(self._owner))
|
|
100
|
+
self._let_in()
|
|
101
|
+
try:
|
|
102
|
+
yield
|
|
103
|
+
finally:
|
|
104
|
+
self._leave()
|
|
105
|
+
|
|
106
|
+
@contextmanager
|
|
107
|
+
def verb(self) -> Iterator[None]:
|
|
108
|
+
"""A platform verb's way in, never held: refused ``moving`` while the session moves or once it moved."""
|
|
109
|
+
with self._changed:
|
|
110
|
+
self._let_in()
|
|
111
|
+
try:
|
|
112
|
+
yield
|
|
113
|
+
finally:
|
|
114
|
+
self._leave()
|
|
115
|
+
|
|
116
|
+
def _wait_out(self, waiting: Waiting) -> None:
|
|
117
|
+
if self._state not in HELD:
|
|
118
|
+
return
|
|
119
|
+
with waiting():
|
|
120
|
+
self._changed.wait_for(lambda: self._state not in HELD, self.hold_s)
|
|
121
|
+
|
|
122
|
+
def _let_in(self) -> None:
|
|
123
|
+
if self._state == CLOSED:
|
|
124
|
+
fail(UNKNOWN_SESSION, f"no session {self.session_id} on this host")
|
|
125
|
+
if self._state != SERVING:
|
|
126
|
+
raise moving_refusal(self.session_id)
|
|
127
|
+
self._inside += 1
|
|
128
|
+
|
|
129
|
+
def _leave(self) -> None:
|
|
130
|
+
with self._changed:
|
|
131
|
+
self._inside -= 1
|
|
132
|
+
self._changed.notify_all()
|
|
133
|
+
|
|
134
|
+
def _confirm(self, owner_now: OwnerNow, me: str | None, hopped: bool) -> None:
|
|
135
|
+
if self.state != PENDING:
|
|
136
|
+
return
|
|
137
|
+
owner = self._pending_owner(owner_now, hopped)
|
|
138
|
+
if same_host(owner, me):
|
|
139
|
+
self.commit()
|
|
140
|
+
return
|
|
141
|
+
if owner is None:
|
|
142
|
+
fail(UNKNOWN_SESSION, f"no session {self.session_id} on this host")
|
|
143
|
+
raise SessionMoved(self.session_id, owner)
|
|
144
|
+
|
|
145
|
+
def _pending_owner(self, owner_now: OwnerNow, hopped: bool) -> str | None:
|
|
146
|
+
"""Who the platform says owns the session, asked at most once every ``PENDING_CHECK_S`` unless
|
|
147
|
+
another host sent the request here, which it does only once the session moved here."""
|
|
148
|
+
with self._changed:
|
|
149
|
+
asked_at, owner = self._asked
|
|
150
|
+
if not hopped and time.monotonic() - asked_at < PENDING_CHECK_S:
|
|
151
|
+
return owner
|
|
152
|
+
try:
|
|
153
|
+
owner = owner_now()
|
|
154
|
+
except (OSError, ValueError, http.client.HTTPException) as error:
|
|
155
|
+
raise moving_refusal(self.session_id) from error
|
|
156
|
+
with self._changed:
|
|
157
|
+
self._asked = (time.monotonic(), owner)
|
|
158
|
+
return owner
|
|
159
|
+
|
|
160
|
+
def commit(self) -> None:
|
|
161
|
+
"""A pending copy the platform's row names: it serves from now on, or once a fence is lifted."""
|
|
162
|
+
with self._changed:
|
|
163
|
+
self._fenced_from = SERVING
|
|
164
|
+
self._become(SERVING, {PENDING})
|
|
165
|
+
|
|
166
|
+
def fence(self, within_s: float) -> bool:
|
|
167
|
+
"""Hold every new request, remembering what the session was; True once those already inside have
|
|
168
|
+
left, within ``within_s``."""
|
|
169
|
+
with self._changed:
|
|
170
|
+
if self._state in (SERVING, PENDING):
|
|
171
|
+
self._fenced_from, self._state = self._state, FENCED
|
|
172
|
+
return self._state == FENCED and self._changed.wait_for(lambda: self._inside == 0, max(0.0, within_s))
|
|
173
|
+
|
|
174
|
+
def ask(self) -> None:
|
|
175
|
+
self._become(ASKING, {FENCED})
|
|
176
|
+
|
|
177
|
+
def stay(self) -> None:
|
|
178
|
+
"""The platform keeps the session on this host, whose copy its row names: it serves from now on,
|
|
179
|
+
and the export a move took is moot."""
|
|
180
|
+
with self._changed:
|
|
181
|
+
self._exported = False
|
|
182
|
+
self._fenced_from = SERVING
|
|
183
|
+
self._become(SERVING, HELD)
|
|
184
|
+
|
|
185
|
+
def unfence(self) -> bool:
|
|
186
|
+
"""Lift a fence on this host's own word (an ask turned away, a step that failed): the session is
|
|
187
|
+
again what it was, serving or a copy pending a move here. Refused while the platform holds its
|
|
188
|
+
final export, which a move may still publish elsewhere."""
|
|
189
|
+
with self._changed:
|
|
190
|
+
if self._exported:
|
|
191
|
+
return False
|
|
192
|
+
self._become(self._fenced_from, HELD)
|
|
193
|
+
return True
|
|
194
|
+
|
|
195
|
+
def closing(self) -> None:
|
|
196
|
+
"""The platform closes the session here: refused ``moving`` while a move holds its final export,
|
|
197
|
+
which another host may yet serve; from then on no move exports it."""
|
|
198
|
+
with self._changed:
|
|
199
|
+
if self._exported:
|
|
200
|
+
raise moving_refusal(self.session_id)
|
|
201
|
+
self._become(CLOSED, {SERVING, PENDING, FENCED, ASKING, SHUT})
|
|
202
|
+
|
|
203
|
+
def moved(self, owner: str) -> None:
|
|
204
|
+
with self._changed:
|
|
205
|
+
self._owner = owner
|
|
206
|
+
self._become(MOVED, {SERVING, PENDING, FENCED, ASKING, SHUT})
|
|
207
|
+
|
|
208
|
+
def closed(self) -> None:
|
|
209
|
+
self._become(CLOSED, {SERVING, PENDING, FENCED, ASKING, SHUT})
|
|
210
|
+
|
|
211
|
+
def shut(self) -> None:
|
|
212
|
+
"""The host stops before this session could move: its requests are told to come back from now on."""
|
|
213
|
+
self._become(SHUT, {SERVING, PENDING, FENCED, ASKING})
|
|
214
|
+
|
|
215
|
+
def _become(self, state: str, after: set[str] | frozenset[str]) -> None:
|
|
216
|
+
with self._changed:
|
|
217
|
+
self._state = state if self._state in after else self._state
|
|
218
|
+
self._changed.notify_all()
|
|
219
|
+
|
|
220
|
+
@property
|
|
221
|
+
def pending(self) -> bool:
|
|
222
|
+
return self.state == PENDING
|
|
223
|
+
|
|
224
|
+
@property
|
|
225
|
+
def leaving(self) -> bool:
|
|
226
|
+
return self.state in (FENCED, ASKING, MOVED, SHUT)
|
|
227
|
+
|
|
228
|
+
def check_export(self, handoff: bool) -> None:
|
|
229
|
+
"""A handoff export is answered only once the session is asking to move, and marks it taken; no
|
|
230
|
+
other export while it moves."""
|
|
231
|
+
with self._changed:
|
|
232
|
+
if handoff and self._state != ASKING:
|
|
233
|
+
fail(NOT_MOVING, f"this host is not handing session {self.session_id} off")
|
|
234
|
+
if not handoff and self._state in HELD:
|
|
235
|
+
raise moving_refusal(self.session_id)
|
|
236
|
+
self._exported = self._exported or handoff
|
|
237
|
+
|
|
238
|
+
|
|
239
|
+
def platform_close(host: WorldHost, session_id: str) -> dict:
|
|
240
|
+
"""The platform's close of a session (``DELETE``, ``POST close``), which goes where its row points:
|
|
241
|
+
while a move holds the final export here, the host says ``moving`` and the platform asks again."""
|
|
242
|
+
session = host.held(session_id)
|
|
243
|
+
if session is not None:
|
|
244
|
+
session.move.closing()
|
|
245
|
+
return host.close(session_id)
|
|
246
|
+
|
|
247
|
+
|
|
248
|
+
class Forwarding:
|
|
249
|
+
"""Where each session this host handed off went, so a request for it that still lands here
|
|
250
|
+
(a stale route, an owner another replica remembers) is sent on there, or, from the platform,
|
|
251
|
+
told the session is moving rather than lost."""
|
|
252
|
+
|
|
253
|
+
def __init__(self, self_url: str | None = None) -> None:
|
|
254
|
+
self.self_url = self_url
|
|
255
|
+
self._owners: dict[str, str] = {}
|
|
256
|
+
self._lock = threading.Lock()
|
|
257
|
+
|
|
258
|
+
def record(self, session_id: str, owner: str) -> None:
|
|
259
|
+
if same_host(owner, self.self_url):
|
|
260
|
+
raise ValueError(f"session {session_id} cannot move to the host it leaves")
|
|
261
|
+
with self._lock:
|
|
262
|
+
self._owners[session_id] = owner
|
|
263
|
+
|
|
264
|
+
def owner(self, session_id: str) -> str | None:
|
|
265
|
+
with self._lock:
|
|
266
|
+
return self._owners.get(session_id)
|
|
267
|
+
|
|
268
|
+
def refuse(self, session_id: str) -> None:
|
|
269
|
+
if self.owner(session_id) is not None:
|
|
270
|
+
raise moving_refusal(session_id)
|
|
271
|
+
|
|
272
|
+
def instead_of(self, error: ContractError, session_id: str | None) -> ContractError:
|
|
273
|
+
"""A session this host handed off answers ``moving``, never the ``unknown_session`` the platform reads as a loss."""
|
|
274
|
+
handed_off = session_id is not None and self.owner(session_id) is not None
|
|
275
|
+
return moving_refusal(str(session_id)) if handed_off and error.detail.get("code") == UNKNOWN_SESSION else error
|
|
@@ -93,7 +93,11 @@ ship `connector.toml` in the template directory. `init` copies it to the world r
|
|
|
93
93
|
The format is documented in `SKILL.md` under "Custom connections" and "Serving the vendor's API":
|
|
94
94
|
|
|
95
95
|
- `[connector]` slug and `base_url`; `[auth]` scheme (`header|bearer|basic|query|oauth2|none`),
|
|
96
|
-
`name`, and `secret_env` naming the environment variable, never a value
|
|
96
|
+
`name`, and `secret_env` naming the environment variable, never a value; `prefixes` when the
|
|
97
|
+
vendor takes other `Authorization` words than `Bearer`, `credential = "password"` when its Basic
|
|
98
|
+
key is the password; `[auth.login]` when the vendor trades its key for a token,
|
|
99
|
+
`[auth.downloads]` when it hands out links to files; `[api] unauthorized_status` and
|
|
100
|
+
`unauthorized` as the vendor refuses a bad key.
|
|
97
101
|
- `[capture]` pacing (`requests_per_minute` low; providers ask us to be sparing), cursor
|
|
98
102
|
pagination when the vendor has it (`cursor_field` in the body or `cursor_header`);
|
|
99
103
|
`[redact]` `hash`/`drop` for every PII field the vendor documents returning, `round` for
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: benchmarks-getting-started
|
|
3
|
-
description: Build, validate, dry-run, push, run and read a benchmark on the platform, for an agent (Claude Code, Cursor, Codex). A benchmark is either a world with tasks (tools + data, a schema when the vendor has one; a prompt and the SQL verifiers that grade the world's end state) or a container benchmark (a harbor task tree graded by its own tests/test.sh in a container, or a verifiers package graded by Python reward functions), run k times per task per model. Use when building a benchmark, an eval suite, a coding benchmark, a task set or a leaderboard for an agent; when you have a harbor task tree, task.toml files, a verifiers package, a Taskset, or tests that grade an agent; when choosing between a world benchmark and a container (benchmark runner) benchmark; when you need a dry run before pushing (locally in Docker, or hosted on the benchmark runner with `--hosted` when the machine has no Docker); when running k rollouts per task per model or reading per-task results. Every CLI step names its MCP twin (create_world, env_write_file, env_commit, create_environment_version, run_evaluation, get_task_performance, list_rollouts, get_rollout_samples) and where the result shows in the UI.
|
|
3
|
+
description: Build, validate, dry-run, push, run and read a benchmark on the platform, for an agent (Claude Code, Cursor, Codex). A benchmark is either a world with tasks (tools + data, a schema when the vendor has one; a prompt and the SQL verifiers that grade the world's end state and the requests it received) or a container benchmark (a harbor task tree graded by its own tests/test.sh in a container, or a verifiers package graded by Python reward functions), run k times per task per model. Use when building a benchmark, an eval suite, a coding benchmark, a task set or a leaderboard for an agent; when you have a harbor task tree, task.toml files, a verifiers package, a Taskset, or tests that grade an agent; when choosing between a world benchmark and a container (benchmark runner) benchmark; when you need a dry run before pushing (locally in Docker, or hosted on the benchmark runner with `--hosted` when the machine has no Docker); when running k rollouts per task per model or reading per-task results. Every CLI step names its MCP twin (create_world, env_write_file, env_commit, create_environment_version, run_evaluation, get_task_performance, list_rollouts, get_rollout_samples) and where the result shows in the UI.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Benchmarks: getting started
|
|
@@ -355,13 +355,12 @@ gateway worlds schema task add ./crm-bench close_ticket --prompt "Close ticket T
|
|
|
355
355
|
gateway worlds schema task add ./crm-bench escalate --prompt "..." --verifier state_present --world slack=state_present
|
|
356
356
|
```
|
|
357
357
|
|
|
358
|
-
- `--prompt` is what the agent is told. `--verifier <name>` names `verifiers/<name>.sql`; it must
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
`
|
|
362
|
-
- A verifier
|
|
363
|
-
|
|
364
|
-
"crm_tickets" WHERE id = 'T-7' AND status = 'closed';`
|
|
358
|
+
- `--prompt` is what the agent is told. `--verifier <name>` names `verifiers/<name>.sql`; it must exist — `schema verifier add <dir> <name> --entity <entity> [--where "<sql condition>"]` scaffolds
|
|
359
|
+
it (without `--where`, the `state_present` placeholder). Each verifier becomes a key in `rewards`; `reward` is their mean.
|
|
360
|
+
- A verifier is one SQL statement returning one number in 0..1 over the world's tables (entity names from `schema/world.json`):
|
|
361
|
+
`SELECT CASE WHEN COUNT(*) > 0 THEN 1.0 ELSE 0.0 END FROM "crm_tickets" WHERE id = 'T-7' AND status = 'closed';`
|
|
362
|
+
- A verifier can also read every request the session's world received, in `gateway_requests` (and its summary `gateway_journal`):
|
|
363
|
+
`SELECT CASE WHEN COUNT(*) = 0 THEN 1.0 ELSE 0.0 END FROM gateway_requests WHERE method = 'DELETE';`. Only a World Host session records them (`dry-run` and `validate` read them as not recorded, and such a verifier scores 0 there whatever it accepts); on a journal that may be missing requests it scores 0 with the reason unless `gateway-env.toml` has `[verifiers.<name>] accepts_incomplete_journal = true`, which suits a check a missing request can only fail (`COUNT(*) > 0`), never `= 0`. A linked world's verifier gets no journal, so one that reads it scores 0. Columns, fail-closed rules, declarative and `verify.py` checks over the same requests: `worlds-getting-started` `references/journal-checks.md`.
|
|
365
364
|
- `--world <alias>=<verifier>` grades a linked world's state too (`schema link` first).
|
|
366
365
|
- Stored task specs (`instruction`, `seed`, `grader` of kind `assertions` | `python` | `rubric`):
|
|
367
366
|
`gateway worlds task create task.json --world <slug>`; `worlds-getting-started` §6.
|
|
@@ -496,5 +495,5 @@ Every run records the version it ran against; `results` shows the per-version tr
|
|
|
496
495
|
|
|
497
496
|
- `worlds-getting-started`: the world itself — contract, data, sessions, stored tasks, links.
|
|
498
497
|
- `world-data-ingestion`: rows in, calls out. `connector-schema-authoring`: contract, fidelity shapes.
|
|
499
|
-
- Consumer pages: `
|
|
498
|
+
- Consumer pages (docs.surfacearea.ai): `cli/benchmarks`, `worlds/benchmarks`, `evaluation/benchmarks-harbor`.
|
|
500
499
|
- `documentation/features/benchmark-containers.md`: the container substrate, kinds, the runner.
|
|
@@ -273,8 +273,12 @@ These source checks do not imply live-provider validation or executed fidelity s
|
|
|
273
273
|
|
|
274
274
|
A world can describe the vendor it mirrors in `connector.toml` at its root: base URL,
|
|
275
275
|
auth scheme (`header`, `bearer`, `basic`, `query`, `oauth2`, `none`) with the secret named by an
|
|
276
|
-
environment variable (
|
|
277
|
-
|
|
276
|
+
environment variable (a `bearer`'s `prefixes` lists the `Authorization` words the vendor takes,
|
|
277
|
+
`["Bearer", "token"]` for GitHub, the first carried; a `basic` key is the Basic user with an empty
|
|
278
|
+
password, or with `credential = "password"` the password under any user, as Atlassian and
|
|
279
|
+
ServiceNow take it), the vendor's own login route (`[auth.login]`; an oauth2 `token_url` path may
|
|
280
|
+
name a segment, `/ccx/oauth2/{tenant}/token`) and presigned download routes (`[auth.downloads]`),
|
|
281
|
+
capture pacing, a redaction policy (`hash` or `drop` fields at any
|
|
278
282
|
depth), and the operations the agent actually calls (method, path with `{args}`, query
|
|
279
283
|
params, and the entity plus results path their rows land in). The same file is meant to
|
|
280
284
|
drive the platform's custom source later, so describe once.
|
|
@@ -316,6 +320,10 @@ Three refinements the first three vendors forced:
|
|
|
316
320
|
as well as a path argument; a parameter the caller leaves out does not narrow, and one
|
|
317
321
|
sent more than once (`status[]=a&status[]=b`) matches rows carrying any of its values.
|
|
318
322
|
Handlers read every value from `ctx.query_all`; the `query` argument keeps the first.
|
|
323
|
+
- **Uploads.** A multipart form reaches a handler as its fields (a file part reads
|
|
324
|
+
`{"filename", "content_type", "size"}`) with the bytes in `ctx.files[name].content`; a raw
|
|
325
|
+
body (`application/octet-stream`, `text/csv`) reads `body` as `{}` with the bytes in
|
|
326
|
+
`ctx.raw`. A declared route refuses an upload as the vendor's 400.
|
|
319
327
|
|
|
320
328
|
Four more the Brex retrospective forced (each cost a day of one-field-per-run fixing):
|
|
321
329
|
|
|
@@ -399,23 +407,40 @@ them:
|
|
|
399
407
|
- `unauthorized` / `not_found` / `invalid` are JSON strings replayed on 401 / 404 / 400, so
|
|
400
408
|
the vendor's own error bodies come back; `""` (or `'null'`) means no body at all. A route
|
|
401
409
|
whose missing row the vendor answers its own way sets `not_found` and `not_found_status`
|
|
402
|
-
under `[operations.api]`, falling back to `[api]`.
|
|
410
|
+
under `[operations.api]`, falling back to `[api]`. A path the world does not serve answers
|
|
411
|
+
`not_found`; a path it serves, called with another method, answers `wrong_method` (405 with
|
|
412
|
+
`Allow`, no body unless declared; `wrong_method_status` for a vendor that says 404). A write
|
|
413
|
+
the contract refuses answers `invalid` exactly as declared; the refusal's rule goes to the
|
|
414
|
+
host's log, never the answer.
|
|
415
|
+
- `link_header = true` sends RFC 8288 `Link: <next>; rel="next"` (and `rel="prev"`) on list
|
|
416
|
+
answers, each URL the request's own (GitHub's paging); `cors = true` answers a browser's
|
|
417
|
+
preflight before any credential and names any origin (exposing `Link`) on every answer, for a vendor whose
|
|
418
|
+
API serves pages (`worlds serve` answers only this machine's pages). HEAD answers as GET
|
|
419
|
+
without a body on every world.
|
|
403
420
|
- `[operations.api] action` makes a route a `create`, `update`, `delete` or `handler`; handlers live in the world's `api/handlers.py` and carry computed results and workflow state (`ctx.ladder` on the clock). A world is read _and_ write: an agent that creates a search and gets 501 is not testing anything. Full reference: `documentation/features/connector-worlds.md`.
|
|
404
421
|
- `[operations.api] filter = { email = "attributes.email" }` maps a path argument to the
|
|
405
422
|
row field it selects on, matched case-insensitively at any depth. An operation without
|
|
406
423
|
an `entity` answers 501 `not_modelled` rather than inventing a response.
|
|
424
|
+
- `[auth.login]` mirrors a vendor that trades its key for a token (`path`, `credential = { json |
|
|
425
|
+
form | header = "<field>" }`, `required`, `reply = '{"data": {"token": "{token}"}}'`);
|
|
426
|
+
later calls carry the token the way `scheme` says, and only tokens minted for that session count.
|
|
427
|
+
`[auth.downloads] routes = ["download_x"]` lets those GET routes answer a link a handler signs with
|
|
428
|
+
`ctx.signed_url(path)` without the key. Tokens and links live as long as the session; set
|
|
429
|
+
`ttl_seconds` (login, downloads, oauth2) only when the eval needs expiry. `mode = "open"` under
|
|
430
|
+
`[auth]` opens sessions with no credential at all (a capability URL; `--auth` on the session's
|
|
431
|
+
open overrides; `scheme = "open"` is refused). Full grammar: connector-worlds.md, "The door".
|
|
407
432
|
- `[ui] static = "ui/static"` (+ `entry`, `api_path`, `generated`) is the page over the
|
|
408
433
|
routes: generated by `compile` from the contract unless `generated = false`, served by the
|
|
409
434
|
host on the session's ui origin (`?token=` once, then a cookie; `api_path` rewritten onto
|
|
410
435
|
the routes) and locally on its own port (and at `/__ui/`). A page holds no key; the host presents the world's
|
|
411
|
-
credential for it, the way it does for a
|
|
436
|
+
credential for it, the way it does for a caller holding the session token in `X-World-Session`.
|
|
412
437
|
|
|
413
438
|
`gateway worlds serve PATH --port 8080 [--api-key K]` runs it locally; the runner's admin
|
|
414
439
|
endpoints (`/__world/seed`, `/__world/reset`, `/__world/state`) sit beside the vendor routes
|
|
415
440
|
and answer only the run's `X-World-Admin-Token` (`gateway worlds test` hands a world's pytest
|
|
416
441
|
files theirs as `WORLD_ADMIN_TOKEN`; by hand, use `/__session/*`); `/healthz` answers everyone,
|
|
417
|
-
and a World Host session's doors answer none of the
|
|
442
|
+
and a World Host session's api and tool doors answer none of them (there `/healthz` is the world's own path; its ui origin answers `/healthz` under `api_path` to the twin's own page). `gateway bench push PATH` publishes the world: for a world carrying
|
|
418
443
|
`connector.toml` it packages the api-kind bundle the platform hosts on the way (root
|
|
419
444
|
legacy-shaped on purpose, since the api runner refuses a schema bundle there; `server/`
|
|
420
445
|
needs nothing installed). Open a session with `--surface api` and hand the client that
|
|
421
|
-
URL; the vendor's auth
|
|
446
|
+
URL; the vendor's auth applies as `[auth]` declares it, with the session's own api token as the credential.
|