@withgateway/sdk 0.2.1 → 0.2.3

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 (44) hide show
  1. package/dist/cli.js +438 -81
  2. package/dist/cli.js.map +1 -1
  3. package/dist/cli.mjs +439 -82
  4. package/dist/cli.mjs.map +1 -1
  5. package/dist/files/index.js +9 -5
  6. package/dist/files/index.js.map +1 -1
  7. package/dist/files/index.mjs +9 -5
  8. package/dist/files/index.mjs.map +1 -1
  9. package/dist/index.d.mts +1 -1
  10. package/dist/index.d.ts +1 -1
  11. package/dist/index.js +21 -10
  12. package/dist/index.js.map +1 -1
  13. package/dist/index.mjs +20 -10
  14. package/dist/index.mjs.map +1 -1
  15. package/dist/traces/index.js +9 -5
  16. package/dist/traces/index.js.map +1 -1
  17. package/dist/traces/index.mjs +9 -5
  18. package/dist/traces/index.mjs.map +1 -1
  19. package/dist/tracing/index.js +1 -1
  20. package/dist/tracing/index.js.map +1 -1
  21. package/dist/tracing/index.mjs +1 -1
  22. package/dist/tracing/index.mjs.map +1 -1
  23. package/dist/worlds/index.d.mts +7 -1
  24. package/dist/worlds/index.d.ts +7 -1
  25. package/dist/worlds/index.js +19 -9
  26. package/dist/worlds/index.js.map +1 -1
  27. package/dist/worlds/index.mjs +19 -9
  28. package/dist/worlds/index.mjs.map +1 -1
  29. package/package.json +1 -1
  30. package/runtime/gatewaysdk/environment/schema/api.py +61 -3
  31. package/runtime/gatewaysdk/environment/schema/batch.py +5 -1
  32. package/runtime/gatewaysdk/environment/schema/connector.py +11 -0
  33. package/runtime/gatewaysdk/environment/schema/data.py +76 -2
  34. package/runtime/gatewaysdk/environment/schema/dependencies.py +11 -1
  35. package/runtime/gatewaysdk/environment/schema/host.py +8 -17
  36. package/runtime/gatewaysdk/environment/schema/local.py +105 -19
  37. package/runtime/gatewaysdk/environment/schema/mapping.py +13 -1
  38. package/runtime/gatewaysdk/environment/schema/platform.py +32 -5
  39. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +4 -1
  40. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +5 -5
  41. package/runtime/gatewaysdk/environment/schema/tools_world.py +5 -1
  42. package/runtime/gatewaysdk/environment/schema/validation.py +4 -3
  43. package/skills/benchmarks-getting-started/SKILL.md +4 -1
  44. package/skills/worlds-getting-started/SKILL.md +5 -5
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@withgateway/sdk",
3
- "version": "0.2.1",
3
+ "version": "0.2.3",
4
4
  "description": "Gateway SDK for TypeScript - A/B experiments, tracing, and observability",
5
5
  "main": "./dist/index.js",
6
6
  "module": "./dist/index.mjs",
@@ -302,8 +302,19 @@ def _operation_settings(entry: dict, operation: Operation, location: str) -> Ope
302
302
  fail("spec", f"api.action must be one of {', '.join(ACTIONS)}", f"{location}/action")
303
303
  if action in ("create", "update", "delete") and not operation.entity:
304
304
  fail("spec", f"api.action {action} needs an entity to write", f"{location}/action")
305
- if action in ("update", "delete") and not mapping:
306
- fail("spec", f"api.action {action} needs a filter to find the row", f"{location}/filter")
305
+ if action in ("create", "update", "delete") and set(operation.methods) == {"GET"}:
306
+ fail(
307
+ "spec",
308
+ f"api.action {action} writes, but the route only answers GET; declare method = "
309
+ f"\"{'DELETE' if action == 'delete' else 'POST' if action == 'create' else 'PATCH'}\"",
310
+ f"{location}/action",
311
+ )
312
+ if action in ("update", "delete") and not mapping and not operation.placeholders:
313
+ fail(
314
+ "spec",
315
+ f"api.action {action} needs a filter to find the row, or a {{segment}} in its path naming the entity's key",
316
+ f"{location}/filter",
317
+ )
307
318
  handler = table.get("handler")
308
319
  if action == "handler":
309
320
  if not isinstance(handler, str) or not re.match(r"^[a-z_][a-z0-9_]*$", handler):
@@ -756,6 +767,16 @@ def _matches(
756
767
  return True
757
768
 
758
769
 
770
+ def _key_filter(operation: Operation, ctx: ApiContext, entity: str) -> dict[str, str]:
771
+ """The filter a route with no ``filter`` of its own implies: each ``{segment}``
772
+ of its path that names a primary-key field of its entity narrows to the row
773
+ keyed so, as ``GET /wallets/{id}`` reads everywhere. A segment naming no key
774
+ field (``/users/{user_id}/messages``) implies nothing, the route's rows are
775
+ its entity's; a declared ``filter`` says it all itself."""
776
+ keys = set(ctx.key_of(entity, {}))
777
+ return {name: name for name in operation.placeholders if name in keys}
778
+
779
+
759
780
  def _compare(have: str, wanted: str, mode: str) -> bool:
760
781
  if mode == "contains":
761
782
  return wanted in have
@@ -1286,6 +1307,35 @@ def with_query(target: str, extra: dict[str, str]) -> str:
1286
1307
  return urllib.parse.urlunsplit(url._replace(query=urllib.parse.urlencode(query)))
1287
1308
 
1288
1309
 
1310
+ def operation_request(spec: Spec, operation: Operation, args: dict) -> tuple[str, str, bytes]:
1311
+ """``(method, target, raw body)`` of an operation called by name with a
1312
+ tool call's ``args``, the way a session's ``call`` verb takes one:
1313
+ ``args.path`` fills the route's ``{segments}`` (a top-level argument of
1314
+ the segment's name does too, so ``get_wallet {"id": "W1"}`` reads as
1315
+ ``/wallets/W1``), ``args.query`` is its query string, ``args.body`` (or
1316
+ every other key, for a call written like a tool's) its JSON body; a GET
1317
+ carries none. The target is under the spec's ``base_url`` path."""
1318
+ path = operation.path
1319
+ path_params = dict(args.get("path")) if isinstance(args.get("path"), dict) else {}
1320
+ consumed: set[str] = set()
1321
+ for name in operation.placeholders:
1322
+ if name not in path_params and name in args and not isinstance(args[name], (dict, list)):
1323
+ path_params[name] = args[name]
1324
+ consumed.add(name)
1325
+ for key, value in path_params.items():
1326
+ path = path.replace("{" + str(key) + "}", urllib.parse.quote(str(value), safe=""))
1327
+ query = args.get("query") if isinstance(args.get("query"), dict) else {}
1328
+ if query:
1329
+ path = f"{path}?" + urllib.parse.urlencode(query)
1330
+ body = args.get("body") if isinstance(args.get("body"), dict) else None
1331
+ if body is None:
1332
+ leftovers = {k: v for k, v in args.items() if k not in ("path", "query", "body") and k not in consumed}
1333
+ body = leftovers or None
1334
+ raw = json.dumps(body).encode("utf-8") if body is not None and operation.method != "GET" else b""
1335
+ base = urllib.parse.urlsplit(spec.base_url).path.rstrip("/")
1336
+ return operation.method, f"{base}{path}", raw
1337
+
1338
+
1289
1339
  # ---------------------------------------------------------------- the server
1290
1340
 
1291
1341
 
@@ -1473,7 +1523,15 @@ class WorldApp:
1473
1523
  if op.action == "create":
1474
1524
  row = ctx.insert(entity, _bind(op, ctx, body))
1475
1525
  return op.status, row if op.single else wrap([row], ctx.settings, op.envelope)
1476
- rows = [row for row in ctx.rows(entity) if _matches(row, op.filter, values, op.match)]
1526
+ filters = op.filter or _key_filter(operation, ctx, entity)
1527
+ if op.action in ("update", "delete") and not filters:
1528
+ fail(
1529
+ "spec",
1530
+ f"route {operation.name} finds its row by nothing: its path names no primary-key field of {entity} "
1531
+ f"and it declares no api.filter",
1532
+ f"/operations/{operation.name}/api/filter",
1533
+ )
1534
+ rows = [row for row in ctx.rows(entity) if _matches(row, filters, values, op.match)]
1477
1535
  if op.action in ("update", "delete"):
1478
1536
  if len(rows) != 1:
1479
1537
  return ctx.not_found()
@@ -409,7 +409,11 @@ def iter_chunk_rows(path: str | Path, entity: str | None = None) -> Iterator[tup
409
409
 
410
410
  def _field_of(error: ContractError) -> str | None:
411
411
  path = error.detail.get("path") or ""
412
- return path[1:] if path.startswith("/") and len(path) > 1 else None
412
+ inside = path[1:] if path.startswith("/") and len(path) > 1 else None
413
+ named = error.detail.get("property")
414
+ if not isinstance(named, str):
415
+ return inside
416
+ return f"{inside}/{named}" if inside else named
413
417
 
414
418
 
415
419
  def refusal(
@@ -348,6 +348,7 @@ def parse_spec(text: str) -> Spec:
348
348
  hash_fields, drop_fields, round_fields, preserve_fields = parse_redact(raw.get("redact", {}), "/redact")
349
349
 
350
350
  operations: dict[str, Operation] = {}
351
+ routes: dict[tuple[str, str, tuple[str, ...]], str] = {}
351
352
  listed = raw.get("operations", [])
352
353
  if not isinstance(listed, list) or not listed:
353
354
  fail("spec", "Declare at least one [[operations]] entry", "/operations")
@@ -389,6 +390,16 @@ def parse_spec(text: str) -> Spec:
389
390
  operations[name] = Operation(
390
391
  name, method, path, params, entity, results.strip("."), drop, explode, carry_args, methods
391
392
  )
393
+ for verb in operations[name].methods:
394
+ route = (verb, re.sub(r"\{[^}]*\}", "{}", path), tuple(sorted(params)))
395
+ if route in routes:
396
+ fail(
397
+ "spec",
398
+ f"operation {name} answers {verb} {path} with the same params as {routes[route]}, "
399
+ "which would never be reached; give it another path, verb or params",
400
+ f"{location}/path",
401
+ )
402
+ routes[route] = name
392
403
 
393
404
  return Spec(
394
405
  slug=slug,
@@ -37,7 +37,7 @@ from typing import Any, Iterable, Iterator
37
37
 
38
38
  from .compiler import bundle_mode, check_bundle, compile_bundle
39
39
  from .store import SQLiteStore
40
- from .validation import ContractError, digest, encoded, fail, journal_paths, read_json
40
+ from .validation import ContractError, digest, encoded, fail, journal_paths, read_json, validate
41
41
 
42
42
  MODES = ("append", "replace")
43
43
  MERGES = ("upsert", "fill")
@@ -132,6 +132,7 @@ def import_rows(
132
132
  rows: Rows,
133
133
  *,
134
134
  mode: str = "append",
135
+ merge: str = "upsert",
135
136
  batch_id: str | None = None,
136
137
  redact: str = "off",
137
138
  ) -> dict:
@@ -141,6 +142,11 @@ def import_rows(
141
142
  named entities wholesale. Nothing is written until the result has been
142
143
  proven to load in a scratch copy.
143
144
 
145
+ ``merge`` settles two rows of one key inside ``rows``: ``upsert`` (the
146
+ default) keeps the last, ``fill`` keeps the first and lets the later ones
147
+ add the fields it lacks — the platform batch's rule, so a directory and a
148
+ slug import the same file the same way.
149
+
144
150
  ``redact`` — ``off`` (default) stores the rows as given; ``apply`` runs them
145
151
  through the world's ``[redact]`` policy first; ``refuse`` rejects a row that
146
152
  carries plaintext in a redacted field (:mod:`.redaction`).
@@ -150,13 +156,17 @@ def import_rows(
150
156
  root = Path(root)
151
157
  if mode not in MODES:
152
158
  fail("mode", f"mode must be one of {', '.join(MODES)}", "/mode")
159
+ if merge not in MERGES:
160
+ fail("merge", f"merge must be one of {', '.join(MERGES)}", "/merge")
153
161
  if not isinstance(rows, dict) or not all(isinstance(v, list) for v in rows.values()):
154
162
  fail("rows", "rows must map entity names to arrays of rows", "/rows")
155
163
  redact = parse_mode(redact)
156
164
  rows = redact_rows(require_policy(root, redact), rows, redact)
157
165
  kind = world_kind(root)
158
166
  if kind == KIND_SCHEMA:
159
- report = _import_schema(root, rows, mode, batch_id)
167
+ settled = _merged(root, rows, merge)
168
+ _refuse_shapes(root, settled)
169
+ report = _import_schema(root, settled, mode, batch_id)
160
170
  elif kind == KIND_MOCK_TOOLS:
161
171
  report = _import_mock_tools(root, rows, mode)
162
172
  else:
@@ -166,6 +176,70 @@ def import_rows(
166
176
  return report
167
177
 
168
178
 
179
+ def _refuse_shapes(root: Path, rows: Rows) -> None:
180
+ """Every row's shape against the contract (type, bounds, required, unknown
181
+ property, primary key present), all of them, before any is applied: one
182
+ ``ContractError`` with the first refusal's own code (``required``,
183
+ ``additionalProperties``, ``primary_key``, ``entity``, ...), the entity and
184
+ the row's index in the file, carrying the full ``refusals`` list — each
185
+ naming its entity, index, primary key and field — the shape the batch lane
186
+ reports."""
187
+ from .batch import shape_refusal
188
+
189
+ contract = compile_bundle(root)
190
+ refusals = [
191
+ refused
192
+ for entity, listed in rows.items()
193
+ for index, row in enumerate(listed)
194
+ if (refused := shape_refusal(contract, 0, index, entity, row)) is not None
195
+ ]
196
+ if not refusals:
197
+ return
198
+ first = refusals[0]
199
+ entity, index = first["entity"], first["index"]
200
+ row = rows[entity][index]
201
+ total = sum(len(listed) for listed in rows.values())
202
+ summary = f"{len(refusals)} of {total} row(s) refused; {first['pointer']}: " if len(refusals) > 1 else ""
203
+ context = {"entity": entity, "index": index, "refused": len(refusals), "rows": total, "refusals": refusals}
204
+ if entity not in contract.entities:
205
+ fail("entity", summary + first["detail"], f"/{entity}", **context)
206
+ if not isinstance(row, dict):
207
+ fail("rows", summary + first["detail"], first["pointer"], **context)
208
+ spec = contract.entities[entity]
209
+ if any(name not in row for name in spec["primary_key"]):
210
+ fail("primary_key", summary + first["detail"], first["pointer"], **context)
211
+ try:
212
+ validate(spec["schema"], row, location=f"{spec['location']}/schema")
213
+ except ContractError as error:
214
+ raise error.contextualize(message=summary + error.detail["message"], **context)
215
+ fail("rows", summary + first["detail"], first["pointer"], **context)
216
+
217
+
218
+ def _merged(root: Path, rows: Rows, merge: str) -> Rows:
219
+ """``rows`` with each entity's duplicate keys settled by ``merge``; a row the
220
+ plan will refuse (not an object, key missing) is left in place for it."""
221
+ if merge != "fill":
222
+ return rows
223
+ contract = compile_bundle(root)
224
+ settled: Rows = {}
225
+ for entity, listed in rows.items():
226
+ first: dict[tuple, dict] = {}
227
+ kept: list = []
228
+ for row in listed:
229
+ key = _key(contract, entity, row) if isinstance(row, dict) else None
230
+ if key is None:
231
+ kept.append(row)
232
+ continue
233
+ if key in first:
234
+ for name, value in row.items():
235
+ first[key].setdefault(name, value)
236
+ continue
237
+ first[key] = dict(row)
238
+ kept.append(first[key])
239
+ settled[entity] = kept
240
+ return settled
241
+
242
+
169
243
  def _import_schema(root: Path, rows: Rows, mode: str, batch_id: str | None) -> dict:
170
244
  """Rows into a schema world, landing after everything the world already replays.
171
245
 
@@ -230,6 +230,16 @@ def local_dependency_trees(bundle: Path, dependencies: dict[str, Dependency]) ->
230
230
  )
231
231
  tree = (bundle / dep.path).resolve()
232
232
  if not (tree / "gateway-env.toml").is_file():
233
- fail(f"'{alias}'.path {dep.path!r} ({tree}) is not a schema world (no gateway-env.toml)")
233
+ what = (
234
+ "does not exist"
235
+ if not tree.exists()
236
+ else "is not a directory"
237
+ if not tree.is_dir()
238
+ else "is not a schema world (no gateway-env.toml)"
239
+ )
240
+ fail(
241
+ f"'{alias}'.path {dep.path!r} ({tree}) {what}; point [dependencies.{alias}].path in "
242
+ "gateway-env.toml at the world's directory, or re-run `gateway worlds schema link` with --replace"
243
+ )
234
244
  trees[alias] = tree
235
245
  return trees
@@ -82,6 +82,7 @@ from .api import (
82
82
  WorldState,
83
83
  load_api_settings,
84
84
  load_handlers,
85
+ operation_request,
85
86
  send_response,
86
87
  vendor_credential,
87
88
  with_query,
@@ -1612,7 +1613,11 @@ class WorldHost:
1612
1613
  def seed(self, session_id: str, args: dict) -> dict:
1613
1614
  rows = args.get("rows")
1614
1615
  if not isinstance(rows, dict):
1615
- fail("host", "seed needs args.rows as {entity: [row, ...]}")
1616
+ fail(
1617
+ "host",
1618
+ 'seed needs rows as {"rows": {entity: [row, ...]}, "mode": "append"|"replace"}; '
1619
+ "a dependency's entity is named alias.entity",
1620
+ )
1616
1621
  mode = args.get("mode", "append")
1617
1622
  from .redaction import parse_mode
1618
1623
 
@@ -1764,23 +1769,9 @@ class WorldHost:
1764
1769
  if session.task_spec is not None and not session.task_spec.allows_tool(tool):
1765
1770
  allowed = ", ".join(session.task_spec.tools or ())
1766
1771
  fail("tool_not_allowed", f"tool '{tool}' is not allowed by this session's task; it allows: {allowed}")
1767
- path = operation.path # type: ignore[union-attr]
1768
- path_params = args.get("path") if isinstance(args.get("path"), dict) else {}
1769
- for key, value in (path_params or {}).items():
1770
- path = path.replace("{" + str(key) + "}", urllib.parse.quote(str(value), safe=""))
1771
- query = args.get("query") if isinstance(args.get("query"), dict) else {}
1772
- if query:
1773
- path = f"{path}?" + urllib.parse.urlencode(query)
1774
- body = args.get("body") if isinstance(args.get("body"), dict) else None
1775
- if body is None:
1776
- leftovers = {k: v for k, v in args.items() if k not in ("path", "query", "body")}
1777
- body = leftovers or None
1778
- method = operation.method # type: ignore[union-attr]
1779
- raw = json.dumps(body).encode("utf-8") if body is not None and method != "GET" else b""
1780
- base = urllib.parse.urlsplit(session.spec.base_url).path.rstrip("/")
1772
+ method, target, raw = operation_request(session.spec, operation, args)
1781
1773
  headers, credential_query = world_credential(session)
1782
- target = with_query(f"{base}{path}", credential_query)
1783
- status, answer, _ = session.app.handle(method, target, headers, raw, "127.0.0.1")
1774
+ status, answer, _ = session.app.handle(method, with_query(target, credential_query), headers, raw, "127.0.0.1")
1784
1775
  return {"status": status, "body": answer}
1785
1776
 
1786
1777
 
@@ -37,7 +37,7 @@ from pathlib import Path
37
37
  from typing import Any, Callable
38
38
 
39
39
  from . import snapshot as snapshots
40
- from .api import Router, WorldApp, load_api_settings, send_response, vendor_credential, with_query
40
+ from .api import Router, WorldApp, load_api_settings, operation_request, send_response, vendor_credential, with_query
41
41
  from .host_surfaces import UiSurface, api_target, load_ui_surface, static_file
42
42
  from .compiler import bundle_mode, fail
43
43
  from .conform import PIN
@@ -63,6 +63,19 @@ def refusal(error: ContractError) -> dict:
63
63
  return {"status": 400, "body": {"error": error.detail.get("code", "host"), "detail": str(error)}}
64
64
 
65
65
 
66
+ def seed_args(body: dict) -> dict:
67
+ """The seed a ``POST /__session/seed`` body asks for: ``{rows, mode}``, the
68
+ same under ``args``, or bare ``{entity: [row, ...]}`` — the shape a rows
69
+ file has — taken as the rows of an append."""
70
+ if isinstance(body.get("args"), dict):
71
+ body = body["args"]
72
+ if "rows" in body or "mode" in body:
73
+ return body
74
+ if body and all(isinstance(value, list) for value in body.values()):
75
+ return {"rows": body}
76
+ return body
77
+
78
+
66
79
  def has_http(root: str | Path) -> bool:
67
80
  """Whether the world serves HTTP at all: only a tree with ``connector.toml``
68
81
  has routes. A schema world without one is tools-only, and that is a whole
@@ -97,6 +110,11 @@ class LocalSession:
97
110
  world: ToolsWorld
98
111
  server: ThreadingHTTPServer | None
99
112
  _scratch: str
113
+ #: The routes connector.toml declares, over the session's store, when the
114
+ #: world has any: :meth:`call` answers an operation by name through them.
115
+ app: WorldApp | None = None
116
+ #: The credential the app takes: the pin a local serve is opened with.
117
+ api_key: str | None = PIN
100
118
  #: The static ui connector.toml's ``[ui]`` declares, when the server serves one.
101
119
  ui: UiSurface | None = None
102
120
  #: The ui's own origin: the page at ``/`` and its ``api_path`` beside it,
@@ -148,9 +166,10 @@ class LocalSession:
148
166
  return task_card(self.world)
149
167
 
150
168
  def call(self, tool: str, args: dict[str, Any]) -> dict:
151
- """The tool's ``{status, body}``; a refusal is a 400 answer, not an error."""
169
+ """The tool's ``{status, body}``, a route's when ``tool`` names an
170
+ operation of connector.toml; a refusal is a 400 answer, not an error."""
152
171
  try:
153
- return self.world.call(tool, args)
172
+ return call_served(self.world, self.app, tool, args, api_key=self.api_key)
154
173
  except ContractError as error:
155
174
  return refusal(error)
156
175
 
@@ -238,12 +257,13 @@ def open_world(
238
257
  server = None
239
258
  ui_server = None
240
259
  ui = None
260
+ app = None
261
+ if has_http(root):
262
+ spec = load_spec(root)
263
+ settings = load_api_settings(root, spec)
264
+ app = WorldApp(ToolsWorldState(world, root), Router(spec, settings), api_key)
241
265
  if http:
242
- app = None
243
- if has_http(root):
244
- spec = load_spec(root)
245
- settings = load_api_settings(root, spec)
246
- app = WorldApp(ToolsWorldState(world, root), Router(spec, settings), api_key)
266
+ if app is not None:
247
267
  ui = load_ui_surface(root)
248
268
  server = bind_server(host, port, make_session_handler(world, app, closing, ui=ui, api_key=api_key))
249
269
  threading.Thread(target=server.serve_forever, daemon=True).start()
@@ -261,7 +281,15 @@ def open_world(
261
281
  shutil.rmtree(scratch, ignore_errors=True)
262
282
  raise
263
283
  return LocalSession(
264
- root=root, world=world, server=server, _scratch=scratch, closing=closing, ui=ui, ui_server=ui_server
284
+ root=root,
285
+ world=world,
286
+ server=server,
287
+ _scratch=scratch,
288
+ app=app,
289
+ api_key=api_key,
290
+ closing=closing,
291
+ ui=ui,
292
+ ui_server=ui_server,
265
293
  )
266
294
 
267
295
 
@@ -372,12 +400,10 @@ def make_session_handler(
372
400
  falls back to ``index.html``, for a client-side router) and its
373
401
  ``api_path`` prefix answered with the pin — nothing else, as on the host."""
374
402
  closing = closing if closing is not None else threading.Event()
375
- grant: str | None = None
376
- if app is not None and ui is not None and app.router.spec.scheme == "oauth2":
377
- # The page's calls are presented as a granted client, as the host
378
- # presents them; the world's own token dance stays available beside.
379
- issued = app.router.issue_token({"grant_type": "client_credentials", "client_secret": api_key or ""}, api_key)
380
- grant = issued["access_token"] if issued else None
403
+ # The page's calls and a `/__session/call` of an operation are presented
404
+ # as a granted client, as the host presents them; the world's own token
405
+ # dance stays available beside.
406
+ grant = local_grant(app, api_key)
381
407
 
382
408
  def close(_body: dict) -> dict:
383
409
  closing.set()
@@ -389,8 +415,8 @@ def make_session_handler(
389
415
  ("GET", "state"): lambda _body: world.state(),
390
416
  ("POST", "grade"): lambda _body: world.grade(),
391
417
  ("POST", "reset"): lambda _body: world.reset(),
392
- ("POST", "seed"): lambda body: world.seed(body.get("args") or body),
393
- ("POST", "call"): lambda body: _call(world, body),
418
+ ("POST", "seed"): lambda body: world.seed(seed_args(body)),
419
+ ("POST", "call"): lambda body: _call(world, app, body, api_key=api_key, grant=grant),
394
420
  ("POST", "close"): close,
395
421
  }
396
422
 
@@ -515,14 +541,74 @@ def _local_origin(origin: str) -> bool:
515
541
  return host in ("127.0.0.1", "localhost", "::1")
516
542
 
517
543
 
518
- def _call(world: ToolsWorld, body: dict) -> dict:
544
+ def local_grant(app: WorldApp | None, api_key: str | None) -> str | None:
545
+ """The bearer an ``oauth2`` world's routes take when the session itself
546
+ calls them (the page's api prefix, an operation by name); None for any
547
+ other scheme, or when the world refuses the client-credentials grant."""
548
+ if app is None or app.router.spec.scheme != "oauth2":
549
+ return None
550
+ issued = app.router.issue_token({"grant_type": "client_credentials", "client_secret": api_key or ""}, api_key)
551
+ return issued["access_token"] if issued else None
552
+
553
+
554
+ def call_served(
555
+ world: ToolsWorld,
556
+ app: WorldApp | None,
557
+ tool: str,
558
+ args: dict,
559
+ *,
560
+ api_key: str | None = PIN,
561
+ grant: str | None = None,
562
+ ) -> dict:
563
+ """One name of what the session serves, answered as the World Host answers
564
+ it: a tool by name (a dependency's as ``alias.tool``); on a tree with
565
+ connector.toml, an operation by name too, answered by its route over the
566
+ same store, ``{status, body}`` the route's own. A name that is both is the
567
+ tool's."""
568
+ if app is not None and tool not in world.version.tool_names and tool in app.router.spec.operations:
569
+ return call_operation(world, app, tool, args, api_key=api_key, grant=grant)
570
+ return world.call(tool, args)
571
+
572
+
573
+ def call_operation(
574
+ world: ToolsWorld,
575
+ app: WorldApp,
576
+ name: str,
577
+ args: dict,
578
+ *,
579
+ api_key: str | None = PIN,
580
+ grant: str | None = None,
581
+ ) -> dict:
582
+ """An operation of connector.toml called by name (:func:`operation_request`
583
+ reads the args); the world's own credential is presented, as the host
584
+ presents a session's. The answer is the route's ``{status, body}``."""
585
+ operation = app.router.spec.operations.get(name)
586
+ if operation is None:
587
+ known = ", ".join(sorted(app.router.spec.operations)) or "(none)"
588
+ fail("host", f"unknown tool '{name}'; this world serves: {known}")
589
+ if world.allowed is not None and name not in world.allowed:
590
+ fail(
591
+ "tool_not_allowed",
592
+ f"tool '{name}' is not allowed by this session's task; it allows: {', '.join(sorted(world.allowed))}",
593
+ )
594
+ method, target, raw = operation_request(app.router.spec, operation, args)
595
+ headers, credential_query = vendor_credential(app.router.spec, api_key or "", grant=grant)
596
+ status, answer, _ = app.handle(
597
+ method, with_query(target, credential_query), {"content-type": "application/json", **headers}, raw, "127.0.0.1"
598
+ )
599
+ return {"status": status, "body": answer}
600
+
601
+
602
+ def _call(
603
+ world: ToolsWorld, app: WorldApp | None, body: dict, *, api_key: str | None = PIN, grant: str | None = None
604
+ ) -> dict:
519
605
  tool = body.get("tool")
520
606
  if not isinstance(tool, str) or not tool:
521
607
  fail("host", "tool must be a tool name (root) or alias.tool (a dependency's)")
522
608
  args = body.get("args") or {}
523
609
  if not isinstance(args, dict):
524
610
  fail("host", "args must be an object of the tool's arguments")
525
- return world.call(tool, args)
611
+ return call_served(world, app, tool, args, api_key=api_key, grant=grant)
526
612
 
527
613
 
528
614
  def _apply_scenario(world: ToolsWorld, root: Path, name: str) -> None:
@@ -757,9 +757,16 @@ def apply_mapping(mapping: Mapping, records: Iterable[Any], entities: Entities)
757
757
  claimed = False
758
758
  for position, item in enumerate(items):
759
759
  if not isinstance(item, dict):
760
+ if not fanned and isinstance(item, list):
761
+ fail(
762
+ "mapping",
763
+ f"records[{index}]: {source.select_text} is an array of {len(item)} items, not one object; "
764
+ f'select each item with select = "{source.select_text}[*]"',
765
+ f"/records/{index}",
766
+ )
760
767
  fail(
761
768
  "mapping",
762
- f"records[{index}]: {source.select_text}[{position}] is not an object",
769
+ f"records[{index}]: {source.select_text}[{position}] is {_shape(item)}, not an object",
763
770
  f"/records/{index}",
764
771
  )
765
772
  scope = Scope(item=item, record=record, meta=meta)
@@ -890,6 +897,11 @@ def skeleton(
890
897
  select = "result" if kind == "tool-call" else "$record"
891
898
  if kind == "tool-call" and group["shapes"] and all(shape == "an array of objects" for shape in group["shapes"]):
892
899
  select = "result[*]"
900
+ elif kind == "tool-call" and group["shapes"] and all(shape == "an object" for shape in group["shapes"]):
901
+ listed = [name for name, info in group["fields"].items() if info["list"] and info["nested"]]
902
+ if len(listed) == 1:
903
+ select = f"result.{listed[0]}[*]"
904
+ lines.append(f"# result.{listed[0]} holds the rows: [*] selects each item of an array")
893
905
  lines.append("[[sources]]")
894
906
  lines.append(f'name = "{name}"')
895
907
  lines.append(f'kind = "{kind}"')
@@ -234,7 +234,7 @@ def validate_bundle(bundle: str | Path, *, execute: bool = False) -> dict:
234
234
  this runtime may run authored code (:func:`may_execute`)."""
235
235
  bundle = Path(bundle)
236
236
  if bundle_mode(bundle) is None:
237
- fail("mode", "Expected a schema-backed mock-tools world")
237
+ fail("mode", "Expected a schema world: gateway-env.toml with [schema] beside schema/world.json")
238
238
  contract = check_bundle(bundle)
239
239
  declared = set(contract.tools)
240
240
  found: dict[str, str] = {}
@@ -273,7 +273,31 @@ def validate_bundle(bundle: str | Path, *, execute: bool = False) -> dict:
273
273
  fail("handler", f"Duplicate handler for {name}")
274
274
  found[name] = path.name
275
275
  if set(found) != declared:
276
- fail("handler", "Declared tools and Python handlers must match exactly")
276
+ undeclared = sorted(set(found) - declared)
277
+ unhandled = sorted(declared - set(found))
278
+ parts = []
279
+ if unhandled:
280
+ parts.append(
281
+ "declared in schema/world.json (tools) without a handler under tools/: "
282
+ + ", ".join(unhandled)
283
+ + " — add `@tool` def <name>(...) to a tools/*.py, or drop the declaration"
284
+ )
285
+ if undeclared:
286
+ parts.append(
287
+ "handled under tools/ without a declaration: "
288
+ + ", ".join(f"{name} ({found[name]})" for name in undeclared)
289
+ + " — declare each in schema/world.json, or remove the handler"
290
+ )
291
+ fail(
292
+ "handler",
293
+ "Declared tools and Python handlers must match exactly; " + "; ".join(parts),
294
+ "/tools",
295
+ )
296
+ if (bundle / "connector.toml").is_file():
297
+ from .api import load_api_settings
298
+ from .connector import parse_spec
299
+
300
+ load_api_settings(bundle, parse_spec((bundle / "connector.toml").read_text(encoding="utf-8")))
277
301
  _check_mappings(bundle, contract)
278
302
  check_world_redaction(bundle)
279
303
  pinned = _pinned_state(bundle, contract)
@@ -509,7 +533,7 @@ def _handler_execution(bundle: Path, execute: bool) -> dict[str, Any]:
509
533
  if not execute:
510
534
  return {
511
535
  "status": "not_run",
512
- "reason": "handlers run where the world runs; `gateway worlds check` "
536
+ "reason": "handlers run where the world runs; `gateway worlds schema check` "
513
537
  "with the bundled runtime imports them, `gateway worlds call` runs one",
514
538
  }
515
539
  if not may_execute():
@@ -931,22 +955,25 @@ def _import_data(request: dict) -> dict:
931
955
  (the same gate the CLI uses, scratch copy first), and every file of the updated
932
956
  tree comes back the way ``init-template`` returns one, so the platform commits a
933
957
  version from it without knowing which file changed."""
934
- from .data import KIND_SCHEMA, MODES, import_rows
958
+ from .data import KIND_SCHEMA, MERGES, MODES, import_rows
935
959
  from .redaction import parse_mode
936
960
 
937
961
  rows = request.get("rows")
938
962
  mode = request.get("mode", "append")
963
+ merge = request.get("merge", "upsert")
939
964
  if not isinstance(rows, dict) or not all(isinstance(v, list) for v in rows.values()):
940
965
  fail("input", "Expected rows as {entity: [row, …]}")
941
966
  if mode not in MODES:
942
967
  fail("input", f"mode must be one of {', '.join(MODES)}")
968
+ if merge not in MERGES:
969
+ fail("input", f"merge must be one of {', '.join(MERGES)}")
943
970
  redact = parse_mode(request.get("redact"))
944
971
  with tempfile.TemporaryDirectory(prefix="gateway-import-") as directory:
945
972
  root = Path(directory) / "bundle"
946
973
  root.mkdir()
947
974
  _write_files(root, request.get("files"))
948
975
  world = world_root(root)
949
- result = import_rows(world, rows, mode=mode, redact=redact)
976
+ result = import_rows(world, rows, mode=mode, merge=merge, redact=redact)
950
977
  if result["kind"] == KIND_SCHEMA and snapshots.default_snapshot(world).is_file():
951
978
  # The journals grew; a snapshot built before this import would be
952
979
  # served over them. Rebuild so the tree that travels back is one thing.
@@ -244,12 +244,15 @@ crm-bench/
244
244
  Entities, tools and routes: `worlds-getting-started` §2 and `connector-schema-authoring`. Tasks:
245
245
 
246
246
  ```bash
247
+ gateway worlds schema verifier add ./crm-bench ticket_closed --entity crm_tickets --where "id = 'T-7' AND status = 'closed'"
247
248
  gateway worlds schema task add ./crm-bench close_ticket --prompt "Close ticket T-7 and note the reason." --verifier ticket_closed
248
249
  gateway worlds schema task add ./crm-bench escalate --prompt "..." --verifier state_present --world slack=state_present
249
250
  ```
250
251
 
251
252
  - `--prompt` is what the agent is told. `--verifier <name>` names `verifiers/<name>.sql`; it must
252
- exist. Each verifier becomes a key in `rewards`; `reward` is their mean.
253
+ exist — `schema verifier add <dir> <name> --entity <entity> [--where "<sql condition>"]` scaffolds
254
+ it (without `--where`, the `state_present` placeholder). Each verifier becomes a key in `rewards`;
255
+ `reward` is their mean.
253
256
  - A verifier is one SQL statement returning one number in 0..1 over the world's tables (entity
254
257
  names from `schema/world.json`): `SELECT CASE WHEN COUNT(*) > 0 THEN 1.0 ELSE 0.0 END FROM
255
258
  "crm_tickets" WHERE id = 'T-7' AND status = 'closed';`