@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
@@ -10,7 +10,7 @@
10
10
 
11
11
  Local mode only in P1: the version bundle is pulled via the existing
12
12
  environments/benchmark-hub clients, extracted to a cache dir, and executed
13
- in-process (sqlite worlds for ``mock-tools``; per-task docker sandboxes for
13
+ in-process (database-backed worlds for ``mock-tools``; per-task docker sandboxes for
14
14
  ``harbor``). ``mode="remote"`` and ``hosts=`` transport patching are P2/P3.
15
15
  """
16
16
 
@@ -153,7 +153,6 @@ class Environment:
153
153
 
154
154
  _install_ambient_interceptor()
155
155
 
156
- # -- kind guards -----------------------------------------------------
157
156
 
158
157
  def _require_mock(self, operation: str) -> None:
159
158
  if self.kind != KIND_MOCK_TOOLS:
@@ -172,7 +171,6 @@ class Environment:
172
171
  "the registry/execute seams instead."
173
172
  )
174
173
 
175
- # -- mock-tools: template + worlds ------------------------------------
176
174
 
177
175
  def _build_template_db(self) -> None:
178
176
  from ._materialize import materialize_template
@@ -235,7 +233,6 @@ class Environment:
235
233
  self._implicit_world = World(self)
236
234
  return self._implicit_world
237
235
 
238
- # -- delegates to the implicit world ----------------------------------
239
236
 
240
237
  def execute(self, tool_name: str, tool_input: Any = _NO_INPUT) -> Any:
241
238
  return self._ensure_world().execute(tool_name, tool_input)
@@ -255,7 +252,6 @@ class Environment:
255
252
  def reset(self) -> None:
256
253
  self._ensure_world().reset()
257
254
 
258
- # -- harbor ----------------------------------------------------------
259
255
 
260
256
  @property
261
257
  def tasks(self) -> List[HarborTask]:
@@ -284,7 +280,6 @@ class Environment:
284
280
  self._docker_runtime = CliDockerRuntime()
285
281
  return self._docker_runtime
286
282
 
287
- # -- routing ----------------------------------------------------------
288
283
 
289
284
  def resolve_route(self, tool_name: str) -> str:
290
285
  """Route map > effects default (read→default_route, write→env,
@@ -339,11 +334,6 @@ def _effects_of(tool_name: str) -> Optional[str]:
339
334
  return None
340
335
 
341
336
 
342
- # ---------------------------------------------------------------------------
343
- # Ambient interception — the define_tool wrapper's hook (spec §4.4, rung 1.5)
344
- # ---------------------------------------------------------------------------
345
-
346
-
347
337
  def _ambient_intercept(name: str, fn: Any, args: tuple, kwargs: dict) -> Any:
348
338
  """Called by the ``define_tool`` wrapper on every invocation. No active
349
339
  world → miss sentinel (the wrapper calls the original fn — the identity
@@ -410,11 +400,6 @@ def _install_ambient_interceptor() -> None:
410
400
  _interceptor_installed = True
411
401
 
412
402
 
413
- # ---------------------------------------------------------------------------
414
- # init
415
- # ---------------------------------------------------------------------------
416
-
417
-
418
403
  def init_from_path(
419
404
  path: Union[str, Path],
420
405
  *,
@@ -494,7 +479,7 @@ def init(
494
479
 
495
480
  bench = GatewayBenchmarkClient(resolved_host, resolved_public, resolved_secret)
496
481
  try:
497
- details = bench.resolve_version(slug, version or "latest")
482
+ details = bench.resolve_version(slug, version)
498
483
  except BenchmarkPushError as error:
499
484
  raise EnvironmentNotReady(f"no runnable version for '{slug}': {error}") from None
500
485
  content_hash = details.get("contentHash")
@@ -0,0 +1,288 @@
1
+ """Handlers write SQL through ``conn`` and seeds are SQL text, so a mock-tools world is SQLite by definition."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import shutil
6
+ import sqlite3
7
+ import tempfile
8
+ from contextlib import AbstractContextManager, nullcontext
9
+ from pathlib import Path
10
+ from typing import TYPE_CHECKING, Any, Callable, Dict, List, Optional
11
+
12
+ from .backing import WorldBacking
13
+ from .errors import VerifierError, WorldStartError
14
+ from .schema.compiler import Contract, quote
15
+ from .schema.database import SQLiteWorldDatabase
16
+ from .schema.database.runtime_rows import CONVERSATION_EVENTS, RUN_PARAMETERS, TASK_CONTEXT, RuntimeRows, Statement
17
+ from .schema.validation import fail
18
+
19
+ if TYPE_CHECKING:
20
+ from .schema.journal import JournalDatabase, JournalUse
21
+
22
+ MODES = ("append", "replace")
23
+ #: Undoing a failed runtime write: the outermost savepoint is the transaction, and its RELEASE is the
24
+ #: commit, so a busy RELEASE must be answered with ROLLBACK or the connection stays inside it.
25
+ ABORT = {True: ("ROLLBACK",), False: ("ROLLBACK TO gateway_runtime", "RELEASE gateway_runtime")}
26
+ Rows = Dict[str, List[dict]]
27
+
28
+
29
+ def _sql_literal(value: Any) -> str:
30
+ if value is None:
31
+ return "NULL"
32
+ if isinstance(value, bool):
33
+ return "1" if value else "0"
34
+ if isinstance(value, (int, float)):
35
+ return repr(value)
36
+ return "'" + str(value).replace("'", "''") + "'"
37
+
38
+
39
+ def _check_rows(columns: Dict[str, List[str]], rows: Rows) -> None:
40
+ for table, listed in rows.items():
41
+ if table not in columns:
42
+ fail(
43
+ "table",
44
+ f"No table {table} in db/schema.sql; tables: {', '.join(sorted(columns)) or 'none'}",
45
+ f"/{table}",
46
+ )
47
+ for index, row in enumerate(listed):
48
+ if not isinstance(row, dict):
49
+ fail("rows", "A row must be an object", f"/{table}/{index}")
50
+ _check_row(columns[table], table, index, row)
51
+
52
+
53
+ def _check_row(columns: List[str], table: str, index: int, row: dict) -> None:
54
+ for column, value in row.items():
55
+ if column not in columns:
56
+ fail(
57
+ "column",
58
+ f"Column {column} is not in table {table}; columns: {', '.join(columns)}",
59
+ f"/{table}/{index}/{column}",
60
+ )
61
+ if not isinstance(value, (str, int, float, bool, type(None))):
62
+ fail(
63
+ "value",
64
+ f"Column {column} of {table} takes a scalar; encode nested values as text yourself",
65
+ f"/{table}/{index}/{column}",
66
+ )
67
+
68
+
69
+ def seed_statements(columns: Dict[str, List[str]], rows: Rows, mode: str = "append") -> List[str]:
70
+ """``append`` upserts by each table's own primary key; ``replace`` first empties only the tables ``rows`` names."""
71
+ if mode not in MODES:
72
+ fail("mode", f"mode must be one of {', '.join(MODES)}", "/mode")
73
+ _check_rows(columns, rows)
74
+ statements: List[str] = []
75
+ verb = "INSERT" if mode == "replace" else "INSERT OR REPLACE"
76
+ for table, listed in rows.items():
77
+ if mode == "replace":
78
+ statements.append(f"DELETE FROM {quote(table)};")
79
+ statements.extend(_insert(verb, table, row) for row in listed)
80
+ return statements
81
+
82
+
83
+ def _insert(verb: str, table: str, row: dict) -> str:
84
+ if not row:
85
+ return f"{verb} INTO {quote(table)} DEFAULT VALUES;"
86
+ names = ", ".join(quote(column) for column in row)
87
+ values = ", ".join(_sql_literal(value) for value in row.values())
88
+ return f"{verb} INTO {quote(table)} ({names}) VALUES ({values});"
89
+
90
+
91
+ def columns_of(conn: sqlite3.Connection) -> Dict[str, List[str]]:
92
+ tables = [
93
+ row[0]
94
+ for row in conn.execute("SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'")
95
+ ]
96
+ return {table: [row[1] for row in conn.execute(f"PRAGMA table_info({quote(table)})")] for table in tables}
97
+
98
+
99
+ def seed_sqlite(conn: sqlite3.Connection, rows: Rows, mode: str = "append") -> Dict[str, int]:
100
+ statements = seed_statements(columns_of(conn), rows, mode)
101
+ try:
102
+ conn.execute("BEGIN")
103
+ for statement in statements:
104
+ conn.execute(statement)
105
+ conn.commit()
106
+ except sqlite3.Error as error:
107
+ conn.rollback()
108
+ fail("sqlite", f"seed refused by the database: {error}", "/rows")
109
+ return {table: conn.execute(f"SELECT COUNT(*) FROM {quote(table)}").fetchone()[0] for table in rows}
110
+
111
+
112
+ def schema_columns(schema: Path) -> Dict[str, List[str]]:
113
+ with sqlite3.connect(":memory:") as probe:
114
+ try:
115
+ probe.executescript(schema.read_text(encoding="utf-8"))
116
+ except sqlite3.Error as error:
117
+ fail("schema", f"db/schema.sql does not load: {error}", "db/schema.sql")
118
+ return columns_of(probe)
119
+
120
+
121
+ def materialize(schema: Path, seed: Path, destination: Path) -> None:
122
+ conn = sqlite3.connect(destination)
123
+ try:
124
+ if schema.is_file():
125
+ conn.executescript(schema.read_text(encoding="utf-8"))
126
+ if seed.is_file():
127
+ conn.executescript(seed.read_text(encoding="utf-8"))
128
+ conn.commit()
129
+ except sqlite3.Error as error:
130
+ raise WorldStartError("Failed to build seed database; check db/schema.sql and db/seed.sql") from error
131
+ finally:
132
+ conn.close()
133
+
134
+
135
+ class LegacySQLiteBacking(WorldBacking):
136
+ """Autocommit, shared across threads: agents call tools from worker threads."""
137
+
138
+ def __init__(self, path: Path, contract: Optional[Contract] = None) -> None:
139
+ self.path = Path(path)
140
+ self._conn = sqlite3.connect(self.path, isolation_level=None, check_same_thread=False)
141
+ self._conn.row_factory = sqlite3.Row
142
+
143
+ def transaction(self) -> AbstractContextManager[Any]:
144
+ return nullcontext()
145
+
146
+ def handler_connection(self) -> Any:
147
+ return self._conn
148
+
149
+ def split_statements(self, script: str) -> List[str]:
150
+ return SQLiteWorldDatabase.split_statements(script)
151
+
152
+ def rows(self, sql: str, params: tuple) -> List[Dict[str, Any]]:
153
+ head = sql.lstrip().split(None, 1)[0].upper() if sql.strip() else ""
154
+ if head not in ("SELECT", "WITH"):
155
+ raise ValueError(
156
+ "world.state() is read-only — only SELECT/WITH queries are "
157
+ "allowed (use tool handlers or verifiers for writes)."
158
+ )
159
+ return [dict(row) for row in self._conn.execute(sql, params).fetchall()]
160
+
161
+ def journal(self, database: JournalDatabase) -> AbstractContextManager[Callable[[list[str]], JournalUse]]:
162
+ """A legacy tools world keeps no journal: its verifiers read none."""
163
+ from .schema.journal import JournalUse
164
+
165
+ return nullcontext(lambda statements: JournalUse.none())
166
+
167
+ def verifier_rows(self, verifier: str, statement: str) -> Optional[List[Any]]:
168
+ try:
169
+ cursor = self._conn.execute(statement)
170
+ except sqlite3.Error as error:
171
+ raise VerifierError(f"verifier '{verifier}' failed: {error}\n SQL: {statement}") from error
172
+ if cursor.description is None:
173
+ return None
174
+ row = cursor.fetchone()
175
+ return [] if row is None else [row]
176
+
177
+ def snapshot(self, destination: Path) -> Path:
178
+ dest = Path(destination)
179
+ dest.parent.mkdir(parents=True, exist_ok=True)
180
+ shutil.copyfile(self.path, dest)
181
+ return dest
182
+
183
+ def columns(self) -> Dict[str, List[str]]:
184
+ return columns_of(self._conn)
185
+
186
+ def counts(self) -> Dict[str, int]:
187
+ return {
188
+ table: self._conn.execute(f"SELECT COUNT(*) FROM {quote(table)}").fetchone()[0] for table in self.columns()
189
+ }
190
+
191
+ def seed(self, rows: Rows, mode: str = "append") -> Dict[str, int]:
192
+ return seed_sqlite(self._conn, rows, mode)
193
+
194
+ def entities(self) -> Rows:
195
+ return {
196
+ table: [dict(row) for row in self._conn.execute(f"SELECT * FROM {quote(table)}")]
197
+ for table in sorted(self.columns())
198
+ }
199
+
200
+ def table_rows(self, table: str) -> tuple[List[dict], List[str]]:
201
+ columns = self.columns()
202
+ if table not in columns:
203
+ fail("table", f"No table {table}; tables: {', '.join(sorted(columns)) or 'none'}", f"/{table}")
204
+ return [dict(row) for row in self._conn.execute(f"SELECT * FROM {quote(table)}")], columns[table]
205
+
206
+ def _declares(self, table: str) -> bool:
207
+ found = self._conn.execute("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?", (table,))
208
+ return found.fetchone() is not None
209
+
210
+ def _write_runtime(self, table: str, statements: list[Statement]) -> bool:
211
+ if not self._declares(table):
212
+ return False
213
+ outer = not self._conn.in_transaction
214
+ self._conn.execute("SAVEPOINT gateway_runtime")
215
+ try:
216
+ for sql, params in statements:
217
+ self._conn.execute(sql, params)
218
+ self._conn.execute("RELEASE gateway_runtime")
219
+ except BaseException:
220
+ for abort in ABORT[outer]:
221
+ self._conn.execute(abort)
222
+ raise
223
+ return True
224
+
225
+ def set_task_context(self, scenario_id: str) -> bool:
226
+ return self._write_runtime(TASK_CONTEXT, RuntimeRows.task_context(scenario_id))
227
+
228
+ def set_run_parameters(self, parameters: Dict[str, str]) -> bool:
229
+ return self._write_runtime(RUN_PARAMETERS, RuntimeRows.run_parameters(parameters))
230
+
231
+ def record_conversation_event(
232
+ self,
233
+ scenario_id: str,
234
+ user_turn_index: int,
235
+ event_type: str,
236
+ actor: str,
237
+ name: Optional[str],
238
+ payload_json: str,
239
+ ) -> bool:
240
+ return self._write_runtime(
241
+ CONVERSATION_EVENTS,
242
+ RuntimeRows.conversation_event(scenario_id, user_turn_index, event_type, actor, name, payload_json),
243
+ )
244
+
245
+ def close(self) -> None:
246
+ try:
247
+ self._conn.close()
248
+ except sqlite3.Error:
249
+ pass
250
+
251
+
252
+ class LegacyVerifiers:
253
+ """Each verifier scores its own copy of the seeded state, so no verifier sees another's writes."""
254
+
255
+ def __init__(self, root: Path) -> None:
256
+ self.root = Path(root)
257
+ self.paths = sorted((self.root / "verifiers").glob("*.sql"))
258
+
259
+ def scores(self) -> List[Dict[str, Any]]:
260
+ schema = self.root / "db" / "schema.sql"
261
+ if not schema.is_file():
262
+ return [self._refused(path, "db/schema.sql is missing") for path in self.paths]
263
+ with tempfile.TemporaryDirectory(prefix="gateway-verify-") as scratch:
264
+ template = Path(scratch) / "template.db"
265
+ try:
266
+ materialize(schema, self.root / "db" / "seed.sql", template)
267
+ except WorldStartError as error:
268
+ return [self._refused(path, f"{error}: {error.__cause__}") for path in self.paths]
269
+ return [self._score(path, template, Path(scratch) / f"{index}.db") for index, path in enumerate(self.paths)]
270
+
271
+ def _score(self, path: Path, template: Path, copy: Path) -> Dict[str, Any]:
272
+ from ._world import SqlVerifier
273
+
274
+ backing = WorldBacking.branch(template, copy, None)
275
+ try:
276
+ verifier = SqlVerifier.read(path, backing.split_statements)
277
+ score, _sql = verifier.score(lambda statement: backing.verifier_rows(verifier.name, statement))
278
+ except (VerifierError, ValueError, OSError) as error:
279
+ return self._refused(path, str(error))
280
+ finally:
281
+ backing.close()
282
+ return {"path": self._relative(path), "ok": True, "score": score}
283
+
284
+ def _refused(self, path: Path, reason: str) -> Dict[str, Any]:
285
+ return {"path": self._relative(path), "ok": False, "score": None, "error": reason}
286
+
287
+ def _relative(self, path: Path) -> str:
288
+ return path.relative_to(self.root).as_posix()
@@ -0,0 +1,25 @@
1
+ """How a task's grade names its rewards, so no two of them share a key.
2
+
3
+ Each world scores under its alias (``<alias>``, ``<alias>.<check>``) and each
4
+ cross-world verifier under ``x`` (``x.<name>``, ``x.<name>.<check>``). A world
5
+ aliased ``x``, or ``x.<anything>``, would score its checks under a verifier's
6
+ key, and the flattened grade would keep only one of the two. Stdlib only,
7
+ inside the vendored ``gatewaysdk.environment``; the platform's twin is
8
+ ``TaskRewardKeys`` in ``gateway/packages/shared/src/domain/worldTaskRewardKeys.ts``,
9
+ both pinned by ``gatewaysdk/fixtures/tasks/grade-vectors.json``.
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+
15
+ class RewardKeys:
16
+ VERIFIERS = "x"
17
+ PREFIX = f"{VERIFIERS}."
18
+
19
+ @staticmethod
20
+ def reserved(alias: str) -> bool:
21
+ return alias == RewardKeys.VERIFIERS or alias.startswith(RewardKeys.PREFIX)
22
+
23
+ @staticmethod
24
+ def refusal(alias: str) -> str:
25
+ return f"'{alias}' is reserved: cross-world verifiers' rewards are named x.<name>; give the world another alias"
@@ -14,7 +14,7 @@ FIXED contract::
14
14
  ``gateway_env`` is importable ONLY while a bundle's handler modules are being
15
15
  loaded — the loader injects this module into ``sys.modules`` under that name
16
16
  for the duration of the load and restores it after (never globally installed).
17
- ``db`` operations bind to the ACTIVE world's sqlite connection at call time via
17
+ ``db`` operations bind to the ACTIVE world's connection at call time via
18
18
  a contextvar, so the same handler object serves every world/branch.
19
19
 
20
20
  Handlers may also be plain ``def <tool_name>(...)`` functions — the loader
@@ -24,7 +24,6 @@ falls back to discovery by function name == served tool name.
24
24
  from __future__ import annotations
25
25
 
26
26
  import re
27
- import sqlite3
28
27
  from contextvars import ContextVar
29
28
  from typing import Any, Callable, Dict, Optional
30
29
 
@@ -32,12 +31,8 @@ from .schema.store_contract import STORE_METHOD_NAMES, unknown_store_method_deta
32
31
 
33
32
  __all__ = ["tool", "db", "store"]
34
33
 
35
- #: The active world's sqlite connection. Set by ``World.execute`` around each
36
- #: handler invocation; ``db`` reads it at call time.
37
- _active_connection: ContextVar[Optional[sqlite3.Connection]] = ContextVar("gateway_env_active_connection", default=None)
34
+ _active_connection: ContextVar[Optional[Any]] = ContextVar("gateway_env_active_connection", default=None)
38
35
 
39
- #: The registry the loader is currently filling. ``@tool`` registers into it
40
- #: at module-exec time; outside a bundle load the decorator is a no-op tagger.
41
36
  _load_registry: ContextVar[Optional[Dict[str, Callable[..., Any]]]] = ContextVar(
42
37
  "gateway_env_load_registry", default=None
43
38
  )
@@ -67,7 +62,7 @@ store = _Store()
67
62
  _IDENTIFIER_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
68
63
 
69
64
 
70
- def _connection() -> sqlite3.Connection:
65
+ def _connection() -> Any:
71
66
  conn = _active_connection.get()
72
67
  if conn is None:
73
68
  raise RuntimeError(
@@ -84,14 +79,14 @@ def _identifier(name: str, what: str) -> str:
84
79
 
85
80
 
86
81
  class _Db:
87
- """Tiny sqlite facade bound to the active world (rows are ``sqlite3.Row``,
88
- dict-like: ``row["col"]`` and ``dict(row)`` both work)."""
82
+ """Tiny SQL facade bound to the active world (rows are dict-like:
83
+ ``row["col"]`` and ``dict(row)`` both work)."""
89
84
 
90
- def one(self, sql: str, *params: Any) -> Optional[sqlite3.Row]:
85
+ def one(self, sql: str, *params: Any) -> Optional[Any]:
91
86
  """First row of the query, or ``None``."""
92
87
  return _connection().execute(sql, params).fetchone()
93
88
 
94
- def all(self, sql: str, *params: Any) -> list[sqlite3.Row]:
89
+ def all(self, sql: str, *params: Any) -> list[Any]:
95
90
  """Every row of the query."""
96
91
  return list(_connection().execute(sql, params).fetchall())
97
92
 
@@ -115,7 +110,7 @@ class _Db:
115
110
 
116
111
  def execute(self, sql: str, *params: Any) -> int:
117
112
  """Run any statement (UPDATE/DELETE/DDL…), returning the affected
118
- rowcount (-1 for non-DML per sqlite3 semantics)."""
113
+ rowcount (-1 for a statement that changes no rows' count, e.g. DDL)."""
119
114
  if _active_store.get() is not None:
120
115
  from .schema import ContractError
121
116
 
@@ -1,5 +1,7 @@
1
1
  """Offline executable world contracts: compile, validate, and store state."""
2
2
 
3
+ from .api import build_api_bundle
4
+ from .api import serve as serve_api
3
5
  from .compiler import (
4
6
  Contract,
5
7
  bundle_mode,
@@ -11,10 +13,8 @@ from .connector import capture as capture_connection
11
13
  from .connector import ingest as ingest_captures
12
14
  from .connector import load_spec as load_connection
13
15
  from .connector import parse_spec, redaction_of, stored_forms
16
+ from .database import IngestConnection, WorldDatabase
14
17
  from .scaffold import init_bundle, list_templates
15
- from .store import IngestConnection, SQLiteStore
16
- from .api import build_api_bundle
17
- from .api import serve as serve_api
18
18
  from .transforms import TRANSFORMS, apply_transforms, parse_transform
19
19
  from .validation import ContractError
20
20
 
@@ -22,8 +22,8 @@ __all__ = [
22
22
  "Contract",
23
23
  "ContractError",
24
24
  "IngestConnection",
25
- "SQLiteStore",
26
25
  "TRANSFORMS",
26
+ "WorldDatabase",
27
27
  "apply_transforms",
28
28
  "build_api_bundle",
29
29
  "bundle_mode",
@@ -0,0 +1,86 @@
1
+ """The runner's ``/__world/*`` routes, and the per-run token that admits a caller to them.
2
+
3
+ Whoever starts a world's server mints the token and hands it to the one process that drives
4
+ the world: the platform to a session pod's world and runner containers, the Batch runner to a
5
+ world it boots, a local session to ``worlds test``. A server started without one refuses the
6
+ routes, and the World Host serves none of them on a session's doors."""
7
+
8
+ from __future__ import annotations
9
+
10
+ import hmac
11
+ import os
12
+ import posixpath
13
+ import re
14
+ import secrets
15
+ import urllib.parse
16
+ from collections.abc import Iterable, Mapping
17
+ from dataclasses import dataclass
18
+
19
+ from ..world_session_contract import ADMIN_TOKEN_ENV
20
+
21
+ ADMIN = {
22
+ "seed": "/__world/seed",
23
+ "reset": "/__world/reset",
24
+ "state": "/__world/state",
25
+ "calls": "/__world/calls",
26
+ "health": "/healthz",
27
+ }
28
+ ADMIN_TOKEN_HEADER = "X-World-Admin-Token"
29
+ RESERVED_SEGMENT = ADMIN["seed"].split("/")[1]
30
+
31
+
32
+ def resolved_path(path: str) -> str:
33
+ """``path`` as any server could read it: decoded, slashes merged, dot segments resolved, lower case."""
34
+ decoded = urllib.parse.unquote(path.split("?", 1)[0])
35
+ return posixpath.normpath(re.sub(r"[/\\]+", "/", "/" + decoded)).lower()
36
+
37
+
38
+ @dataclass(frozen=True)
39
+ class ReservedPaths:
40
+ """What a world's server answers as the runner's own routes: every ``/__world/*`` path and any
41
+ ``[admin]`` path its manifest names, at the root or under the ui's ``api_path``."""
42
+
43
+ admin: frozenset[str] = frozenset()
44
+ prefixes: frozenset[str] = frozenset()
45
+
46
+ @classmethod
47
+ def of(cls, admin: Iterable[str], api_path: str | None) -> ReservedPaths:
48
+ return cls(frozenset(map(resolved_path, admin)), frozenset(map(resolved_path, filter(None, [api_path]))))
49
+
50
+ def __contains__(self, path: object) -> bool:
51
+ whole = resolved_path(str(path))
52
+ under = [whole[len(prefix) :] for prefix in self.prefixes if whole.startswith(prefix + "/")]
53
+ return any(self._names(candidate) for candidate in (whole, *under))
54
+
55
+ def _names(self, candidate: str) -> bool:
56
+ return candidate.split("/")[1] == RESERVED_SEGMENT or candidate in self.admin
57
+
58
+
59
+ RUNNER_PATHS = ReservedPaths()
60
+
61
+
62
+ @dataclass(frozen=True, repr=False)
63
+ class AdminToken:
64
+ """The secret that admits a caller to the runner's routes; without a value it admits nobody."""
65
+
66
+ value: str | None = None
67
+
68
+ @classmethod
69
+ def mint(cls) -> AdminToken:
70
+ return cls(secrets.token_urlsafe(32))
71
+
72
+ @classmethod
73
+ def from_env(cls) -> AdminToken:
74
+ return cls(os.environ.get(ADMIN_TOKEN_ENV) or None)
75
+
76
+ def admits(self, headers: Mapping[str, str]) -> bool:
77
+ """``headers`` keyed lower-case, as ``WorldApp.handle`` takes them; compared in constant time."""
78
+ expected = self.value or ""
79
+ presented = headers.get(ADMIN_TOKEN_HEADER.lower(), "")
80
+ return bool(expected) and hmac.compare_digest(presented.encode("utf-8", "replace"), expected.encode())
81
+
82
+ def header(self) -> dict[str, str]:
83
+ return {ADMIN_TOKEN_HEADER: self.value} if self.value else {}
84
+
85
+ def __repr__(self) -> str:
86
+ return f"AdminToken({'set' if self.value else 'unset'})"