@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
@@ -0,0 +1,58 @@
1
+ """The names a world's tool door answers to: the tools it declares.
2
+
3
+ Its connector.toml operations are routes. A route answers over the world's
4
+ HTTP api, never through ``call``, so a call or a task naming one is refused
5
+ with :func:`~gatewaysdk.environment.world_session_contract.route_not_a_tool`.
6
+ A tool and an operation may share a name: the door runs the tool, the api the
7
+ route."""
8
+
9
+ from __future__ import annotations
10
+
11
+ from collections.abc import Iterable
12
+ from dataclasses import dataclass
13
+ from typing import NoReturn
14
+
15
+ from ..world_session_contract import NOT_A_TOOL, route_not_a_tool
16
+ from .connector import Spec
17
+ from .validation import fail
18
+
19
+
20
+ @dataclass(frozen=True)
21
+ class ServedNames:
22
+ tools: frozenset[str]
23
+ routes: frozenset[str]
24
+
25
+ @classmethod
26
+ def of(cls, tools: Iterable[str], spec: Spec | None) -> ServedNames:
27
+ return cls(frozenset(tools), frozenset(spec.operations) if spec is not None else frozenset())
28
+
29
+ @property
30
+ def served(self) -> list[str]:
31
+ return sorted(self.tools)
32
+
33
+ def is_route(self, name: str) -> bool:
34
+ return name in self.routes and name not in self.tools
35
+
36
+ def refuse(self, name: str) -> NoReturn:
37
+ """``name`` is no tool here: a route's name is told the api URL, any
38
+ other name the tools this world serves."""
39
+ if self.is_route(name):
40
+ fail(NOT_A_TOOL, route_not_a_tool(name))
41
+ fail("host", f"unknown tool '{name}'; this world serves: {', '.join(self.served) or '(none)'}")
42
+
43
+ def check_allowed(self, allowed: Iterable[str] | None) -> None:
44
+ """A task's allow-list names tools this world serves, every one of them:
45
+ a route is never a tool, and a misspelt name would narrow the list
46
+ without anyone noticing."""
47
+ listed = list(allowed or ())
48
+ routes = "; ".join(route_not_a_tool(name) for name in listed if self.is_route(name))
49
+ if routes:
50
+ fail("task", routes, "/task/tools")
51
+ unknown = [name for name in listed if name not in self.tools]
52
+ if unknown:
53
+ served = ", ".join(self.served) or "none"
54
+ fail(
55
+ "task",
56
+ f"the task allows {', '.join(unknown)}, which this world does not serve; its tools are {served}",
57
+ "/task/tools",
58
+ )
@@ -0,0 +1,275 @@
1
+ """The files a session's store opens without auditing every row again.
2
+
3
+ A version's :class:`ProvenTemplate` is the file every session of the version
4
+ starts from. Its rows are proven once, when the host caches the version; an
5
+ open or a reset clones it and the store runs only its contract and DDL check.
6
+ A :class:`SessionExport` is a checkpoint a session continues from: its bytes
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. 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.
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ import json
17
+ import os
18
+ import shutil
19
+ import uuid
20
+ from pathlib import Path
21
+ from typing import TYPE_CHECKING, Iterable, NamedTuple
22
+
23
+ from .._materialize import materialize_template
24
+ from .call_log import CallJournal
25
+ from .compiler import Contract
26
+ from .database import WorldDatabase
27
+ from .database.reads import FORMAT as READ_INDEXES
28
+ from .snapshot import contract_hash, file_sha256, runtime_version
29
+ from .validation import fail
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
+
41
+ _PROVEN = object()
42
+
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
+
56
+ def refuse_digest_mismatch(path: Path, sha256: str) -> None:
57
+ """Refuse a session export whose bytes do not hash to the sha256 recorded for them."""
58
+ actual = file_sha256(path)
59
+ if actual != sha256.lower():
60
+ fail("host", f"session export checksum mismatch: expected {sha256}, got {actual}")
61
+
62
+
63
+ class ProvenTemplate:
64
+ """The file every session of a version starts from, its rows proven once.
65
+
66
+ When the host caches a version the template is built through the store (every
67
+ row audited as it was written), copied from the snapshot the host fetched and
68
+ verified against the sha256 the platform recorded, or copied from the tree's own
69
+ ``db/state.sqlite`` and audited in full there and then: a sidecar the tree wrote
70
+ is its author's claim, not a proof. The proof beside the file names its sha256,
71
+ the contract and the runtime, so a later build (a restart, the version's worker)
72
+ trusts the same bytes without a second audit, and builds any other bytes afresh.
73
+ What it names is fixed once :meth:`prove` returns."""
74
+
75
+ __slots__ = ("_path", "_contract")
76
+
77
+ def __init__(self, path: Path, contract: Contract, proof: object) -> None:
78
+ if proof is not _PROVEN:
79
+ raise TypeError("a ProvenTemplate comes from ProvenTemplate.prove")
80
+ self._path = Path(path)
81
+ self._contract = contract
82
+
83
+ @property
84
+ def path(self) -> Path:
85
+ return self._path
86
+
87
+ @property
88
+ def contract(self) -> Contract:
89
+ return self._contract
90
+
91
+ @staticmethod
92
+ def required(template: object) -> ProvenTemplate:
93
+ """``template`` itself, refused unless :meth:`prove` made it."""
94
+ if not isinstance(template, ProvenTemplate):
95
+ raise TypeError("a world opens unaudited only on a ProvenTemplate (ProvenTemplate.prove)")
96
+ return template
97
+
98
+ @classmethod
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
110
+ the platform's, downloaded and verified against its recorded sha256 just now."""
111
+ template = cls(path, contract, _PROVEN)
112
+ if not template._recorded():
113
+ template._build(bundle, fetched=fetched, read_fields=read_fields)
114
+ return template
115
+
116
+ @property
117
+ def proof_path(self) -> Path:
118
+ return self.path.with_name(f"{self.path.name}.proof.json")
119
+
120
+ def _proof(self) -> dict[str, str]:
121
+ return {
122
+ "sha256": file_sha256(self.path),
123
+ "contractHash": contract_hash(self.contract),
124
+ "runtime": runtime_version(),
125
+ "readIndexes": READ_INDEXES,
126
+ }
127
+
128
+ def _recorded(self) -> bool:
129
+ try:
130
+ recorded = json.loads(self.proof_path.read_text(encoding="utf-8"))
131
+ except (OSError, ValueError):
132
+ return False
133
+ return self.path.is_file() and recorded == self._proof()
134
+
135
+ def _build(self, bundle: Path, *, fetched: bool, read_fields: Iterable[tuple[str, tuple[str, ...]]]) -> None:
136
+ staging = self.path.with_name(f".{self.path.name}.{uuid.uuid4().hex}")
137
+ try:
138
+ copied = materialize_template(bundle, staging, require_sql=True) is not None
139
+ with WorldDatabase.open(staging, self.contract, audit=copied and not fetched) as store:
140
+ store.index_reads(read_fields)
141
+ os.replace(staging, self.path)
142
+ finally:
143
+ staging.unlink(missing_ok=True)
144
+ record = self.proof_path.with_name(f".{self.proof_path.name}.{uuid.uuid4().hex}")
145
+ record.write_text(json.dumps(self._proof(), sort_keys=True) + "\n", encoding="utf-8")
146
+ os.replace(record, self.proof_path)
147
+
148
+
149
+ class ExportFile(NamedTuple):
150
+ """A session export on this host's disk and the sha256 the platform recorded for it."""
151
+
152
+ path: Path
153
+ sha256: str
154
+
155
+ def for_worker(self) -> dict[str, str]:
156
+ return {"path": str(self.path), "sha256": self.sha256}
157
+
158
+ def checkpoint(self, engine: type[WorldDatabase], runtime: type[WorldRuntime]) -> SessionExport:
159
+ return SessionExport.verified(self, engine)
160
+
161
+ def discard(self) -> None:
162
+ self.path.unlink(missing_ok=True)
163
+
164
+
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)
183
+
184
+
185
+ _VERIFIED = object()
186
+ _RECOVERED = object()
187
+
188
+
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")
216
+ self._path = Path(path)
217
+ self._calls = tuple(calls)
218
+ self._worlds = dict(worlds or {})
219
+ self._unsent = tuple(unsent or ())
220
+
221
+ @property
222
+ def path(self) -> Path:
223
+ return self._path
224
+
225
+ @property
226
+ def calls(self) -> list[dict]:
227
+ return list(self._calls)
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
+
239
+ @staticmethod
240
+ def required(export: object) -> SessionExport:
241
+ """``export`` itself, refused unless :meth:`verified` or :meth:`recovered_from` made it."""
242
+ if not isinstance(export, SessionExport):
243
+ raise TypeError(
244
+ "a session resumes only from a SessionExport (SessionExport.verified, SessionExport.recovered_from)"
245
+ )
246
+ return export
247
+
248
+ @classmethod
249
+ def verified(cls, export: ExportFile, engine: type[WorldDatabase]) -> SessionExport:
250
+ refuse_digest_mismatch(export.path, export.sha256)
251
+ calls = [json.loads(entry) for entry in engine.take_entries(export.path)]
252
+ return cls(export.path, calls, _VERIFIED)
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
+
273
+ @staticmethod
274
+ def carry_calls(path: Path, calls: list[dict], engine: type[WorldDatabase]) -> None:
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
- exist — `schema verifier add <dir> <name> --entity <entity> [--where "<sql condition>"]` scaffolds
360
- it (without `--where`, the `state_present` placeholder). Each verifier becomes a key in `rewards`;
361
- `reward` is their mean.
362
- - A verifier is one SQL statement returning one number in 0..1 over the world's tables (entity
363
- names from `schema/world.json`): `SELECT CASE WHEN COUNT(*) > 0 THEN 1.0 ELSE 0.0 END FROM
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.
@@ -407,8 +406,8 @@ reward: 0 {"ticket_closed":0}
407
406
  reward is for the untouched world; an agent's rollout is what `benchmarks run` grades. Drive one by hand: …
408
407
  ```
409
408
 
410
- A verifier that cannot run — bad SQL, a missing entity — prints `FAIL verifier 'x': …` with SQLite's
411
- words and exits 1; that is what the dry run is for. A reward of 1.0 here means the verifier passes
409
+ A verifier that cannot run — bad SQL, a missing entity — prints `FAIL verifier 'x': …` with the database
410
+ engine's words and exits 1; that is what the dry run is for. A reward of 1.0 here means the verifier passes
412
411
  before any agent acts: rewrite it. Without the bundled runtime (no python3 >= 3.12) the four steps
413
412
  print and the run is marked not executed, exit 0.
414
413
 
@@ -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: `gateway_documentation/pages/cli/benchmarks.mdx`, `pages/worlds/benchmarks.mdx`, `pages/evaluation/benchmarks-harbor.mdx`.
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.