@withgateway/sdk 0.2.9 → 0.3.1

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 (58) hide show
  1. package/README.md +5 -1
  2. package/dist/cli.js +3812 -1158
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +3796 -1142
  5. package/dist/cli.mjs.map +1 -1
  6. package/dist/files/index.d.mts +1 -0
  7. package/dist/files/index.d.ts +1 -0
  8. package/dist/files/index.js +1358 -21
  9. package/dist/files/index.js.map +1 -1
  10. package/dist/files/index.mjs +1356 -13
  11. package/dist/files/index.mjs.map +1 -1
  12. package/dist/{index-BO2SNSgy.d.ts → index-CBqbB_0J.d.ts} +95 -46
  13. package/dist/{index-Cz8Q6Keo.d.mts → index-D-AMnAMa.d.mts} +95 -46
  14. package/dist/index.d.mts +4 -3
  15. package/dist/index.d.ts +4 -3
  16. package/dist/index.js +1942 -177
  17. package/dist/index.js.map +1 -1
  18. package/dist/index.mjs +1890 -146
  19. package/dist/index.mjs.map +1 -1
  20. package/dist/media-CbcAfQvd.d.mts +83 -0
  21. package/dist/media-CbcAfQvd.d.ts +83 -0
  22. package/dist/traces/index.d.mts +1 -0
  23. package/dist/traces/index.d.ts +1 -0
  24. package/dist/traces/index.js +1355 -18
  25. package/dist/traces/index.js.map +1 -1
  26. package/dist/traces/index.mjs +1353 -10
  27. package/dist/traces/index.mjs.map +1 -1
  28. package/dist/tracing/index.d.mts +2 -1
  29. package/dist/tracing/index.d.ts +2 -1
  30. package/dist/tracing/index.js +550 -30
  31. package/dist/tracing/index.js.map +1 -1
  32. package/dist/tracing/index.mjs +539 -29
  33. package/dist/tracing/index.mjs.map +1 -1
  34. package/dist/worlds/index.d.mts +648 -80
  35. package/dist/worlds/index.d.ts +648 -80
  36. package/dist/worlds/index.js +1875 -145
  37. package/dist/worlds/index.js.map +1 -1
  38. package/dist/worlds/index.mjs +1861 -131
  39. package/dist/worlds/index.mjs.map +1 -1
  40. package/package.json +1 -1
  41. package/runtime/gatewaysdk/environment/schema/api.py +43 -62
  42. package/runtime/gatewaysdk/environment/schema/cast.py +31 -4
  43. package/runtime/gatewaysdk/environment/schema/grading.py +1 -5
  44. package/runtime/gatewaysdk/environment/schema/host.py +53 -90
  45. package/runtime/gatewaysdk/environment/schema/local.py +15 -7
  46. package/runtime/gatewaysdk/environment/schema/platform.py +1 -7
  47. package/runtime/gatewaysdk/environment/schema/runtime.py +9 -9
  48. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +3 -3
  49. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +2 -2
  50. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +13 -13
  51. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +2 -1
  52. package/runtime/gatewaysdk/environment/schema/tasks.py +25 -1
  53. package/skills/connector-schema-authoring/SKILL.md +3 -3
  54. package/skills/connector-schema-authoring/connector-worlds.md +12 -5
  55. package/skills/connector-schema-authoring/world-schema.md +8 -0
  56. package/skills/world-data-ingestion/SKILL.md +2 -2
  57. package/skills/worlds-getting-started/SKILL.md +13 -13
  58. package/skills/worlds-getting-started/references/cli-mcp-map.md +2 -1
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@withgateway/sdk",
3
- "version": "0.2.9",
3
+ "version": "0.3.1",
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",
@@ -99,6 +99,7 @@ import urllib.parse
99
99
  import uuid
100
100
  from dataclasses import dataclass, field
101
101
  from datetime import datetime, timezone
102
+ from enum import StrEnum
102
103
  from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
103
104
  from pathlib import Path
104
105
  from typing import Any, Callable
@@ -145,9 +146,6 @@ CLOCK_ENV = "GATEWAY_WORLD_CLOCK"
145
146
  INHERITED: Any = object()
146
147
 
147
148
 
148
- # ---------------------------------------------------------------- settings
149
-
150
-
151
149
  @dataclass(frozen=True)
152
150
  class Paging:
153
151
  style: str = "none"
@@ -509,9 +507,6 @@ def load_api_settings(world: Path, spec: Spec) -> ApiSettings:
509
507
  )
510
508
 
511
509
 
512
- # ---------------------------------------------------------------- state
513
-
514
-
515
510
  class WorldState:
516
511
  """The store behind the served API.
517
512
 
@@ -557,8 +552,6 @@ class WorldState:
557
552
  self._clear_events()
558
553
  self._open(self._snapshot_path if initial and self.snapshot else None, initial=initial)
559
554
 
560
- # -- the live feed: what changed, for a page that polls
561
-
562
555
  def _clear_events(self) -> None:
563
556
  self._events: list[dict] = []
564
557
  self.event_seq = 0
@@ -743,9 +736,6 @@ class WorldState:
743
736
  self._dir.cleanup()
744
737
 
745
738
 
746
- # ---------------------------------------------------------------- routing
747
-
748
-
749
739
  def _dig(row: Any, path: str) -> Any:
750
740
  for part in path.split("."):
751
741
  if not isinstance(row, dict) or part not in row:
@@ -937,8 +927,10 @@ class Router:
937
927
  return presented in self.tokens
938
928
  return key is None or presented == key
939
929
 
940
-
941
- # ---------------------------------------------------------------- handlers
930
+ def without_credential(self, query_all: dict) -> dict:
931
+ """The query as the call log keeps it: a query-auth world's key is never recorded."""
932
+ credential = self.spec.auth_name if self.spec.scheme == "query" else None
933
+ return {k: v for k, v in query_all.items() if k != credential}
942
934
 
943
935
 
944
936
  class ApiContext:
@@ -960,7 +952,6 @@ class ApiContext:
960
952
  #: The ``query`` a handler is passed keeps only the first, as most routes want.
961
953
  self.query_all: dict[str, list[str]] = {}
962
954
 
963
- # -- the store
964
955
  def rows(self, entity: str) -> list[dict]:
965
956
  return self.state.rows(entity)
966
957
 
@@ -986,7 +977,6 @@ class ApiContext:
986
977
  def fields_of(self, entity: str) -> set[str]:
987
978
  return self.state.fields_of(entity)
988
979
 
989
- # -- the live feed
990
980
  def emit(self, event: dict) -> dict:
991
981
  """Record what this write changed for a page that polls (:meth:`WorldState.emit`)."""
992
982
  return self.state.emit(event)
@@ -1001,7 +991,6 @@ class ApiContext:
1001
991
  return (plaintext,)
1002
992
  return stored_forms(self.spec, field, plaintext)
1003
993
 
1004
- # -- time and identity
1005
994
  @staticmethod
1006
995
  def clock() -> float:
1007
996
  frozen = os.environ.get(CLOCK_ENV)
@@ -1037,7 +1026,6 @@ class ApiContext:
1037
1026
  def uuid() -> str:
1038
1027
  return str(uuid.uuid4())
1039
1028
 
1040
- # -- the vendor's shapes
1041
1029
  def envelope(self, rows: list[dict], query: dict[str, str] | None = None, *, envelope: str | None = None) -> Any:
1042
1030
  page = paginate(rows, query or {}, self.settings.paging)
1043
1031
  return wrap(page, self.settings, envelope, link=self.link, omit_done_cursor=self._omits_done_cursor())
@@ -1105,9 +1093,6 @@ def load_handlers(settings: ApiSettings) -> dict[str, Handler]:
1105
1093
  return handlers
1106
1094
 
1107
1095
 
1108
- # ---------------------------------------------------------------- pages and envelopes
1109
-
1110
-
1111
1096
  @dataclass(frozen=True)
1112
1097
  class Page:
1113
1098
  rows: list[dict]
@@ -1245,9 +1230,6 @@ def _normalize(result: Any, default_status: int | None) -> Any:
1245
1230
  return default_status, result, None
1246
1231
 
1247
1232
 
1248
- # ---------------------------------------------------------------- writes
1249
-
1250
-
1251
1233
  def _set(row: dict, target: str, value: Any, current: dict | None) -> None:
1252
1234
  """Assign a dotted target (``attributes.note``), keeping the rest of a nested
1253
1235
  object an update leaves alone."""
@@ -1293,9 +1275,6 @@ def _bind(op: OperationSettings, ctx: ApiContext, body: Any, current: dict | Non
1293
1275
  return row
1294
1276
 
1295
1277
 
1296
- # ---------------------------------------------------------------- presenting a credential
1297
-
1298
-
1299
1278
  def vendor_credential(spec: Spec, presented: str, *, grant: str | None = None) -> tuple[dict[str, str], dict[str, str]]:
1300
1279
  """(headers, query) carrying the world's own credential: ``presented`` in
1301
1280
  the shape the vendor's scheme declares — a ``query`` world reads its key
@@ -1365,9 +1344,6 @@ def operation_request(spec: Spec, operation: Operation, args: dict) -> tuple[str
1365
1344
  return operation.method, f"{base}{path}", raw
1366
1345
 
1367
1346
 
1368
- # ---------------------------------------------------------------- the server
1369
-
1370
-
1371
1347
  Response = tuple[int, Any, dict[str, str] | None]
1372
1348
 
1373
1349
 
@@ -1387,14 +1363,28 @@ def _strings_in(node: Any, out: list[str] | None = None) -> list[str]:
1387
1363
  return out
1388
1364
 
1389
1365
 
1366
+ class Via(StrEnum):
1367
+ """The door a vendor-route request came in by, set by the server from where
1368
+ it arrived and never from a request header. It names the door, not the
1369
+ actor: a token holder calling the ui origin's prefix without a browser is
1370
+ ``ui``."""
1371
+
1372
+ API = "api"
1373
+ UI = "ui"
1374
+ TOOL = "tool"
1375
+
1376
+
1390
1377
  class CallLog:
1391
1378
  """The vendor-route requests one session answered, in order: what the agent
1392
- asked (operation, method, path, path args, query, body) and what came back
1393
- (status, ``rows`` = the length of the operation's ``results`` list when the
1394
- answer carries one, elapsed). Bounded; ``total`` counts past the bound.
1395
- ``/__world/calls`` serves it and a task's ``verify.py`` is handed it as
1396
- ``calls`` beside the rows, because a read-only investigation leaves no row
1397
- behind and its calls are the only evidence of what it did."""
1379
+ asked (operation, method, path, path args, query, body), the door it came
1380
+ in by (``via``) and what came back (status, ``rows`` = the length of the
1381
+ operation's ``results`` list when the answer carries one, elapsed).
1382
+ ``selectors`` is every string the request carried wherever it sat, and
1383
+ ``found`` is "answered with rows", so a grader's scalar ``where`` can ask
1384
+ either without the vendor's request shape. Bounded; ``total`` counts past
1385
+ the bound. ``/__world/calls`` serves it and a task's ``verify.py`` is
1386
+ handed it as ``calls`` beside the rows, because a read-only investigation
1387
+ leaves no row behind and its calls are the only evidence of what it did."""
1398
1388
 
1399
1389
  def __init__(self, maximum: int | None = None):
1400
1390
  if maximum is None:
@@ -1416,6 +1406,7 @@ class CallLog:
1416
1406
  status: int,
1417
1407
  answer: Any,
1418
1408
  elapsed_s: float,
1409
+ via: Via | None,
1419
1410
  ) -> None:
1420
1411
  if self.maximum == 0:
1421
1412
  return
@@ -1434,15 +1425,10 @@ class CallLog:
1434
1425
  "args": dict(args),
1435
1426
  "query": query,
1436
1427
  "body": body if isinstance(body, (dict, list)) and body else None,
1437
- # Every string the request carried, wherever it sat (a path segment, a
1438
- # query value, a body list of lists), so a grader can ask "was X searched"
1439
- # with one `contains` and no knowledge of the vendor's request shape.
1440
1428
  "selectors": _strings_in([args, query, body]),
1429
+ **({} if via is None else {"via": str(via)}),
1441
1430
  "status": status,
1442
1431
  "rows": rows,
1443
- # `found`: the request was answered and returned rows. A grader's `where`
1444
- # takes scalars, and "asked and got something back" is the question an
1445
- # investigation's grader asks most.
1446
1432
  "found": status < 400 and rows is not None and rows > 0,
1447
1433
  "elapsed_ms": round(elapsed_s * 1000, 1),
1448
1434
  }
@@ -1491,8 +1477,6 @@ class WorldApp:
1491
1477
  self.allowed = allowed
1492
1478
  self.calls = CallLog(call_log_max)
1493
1479
 
1494
- # ------------------------------------------------------------ helpers
1495
-
1496
1480
  @staticmethod
1497
1481
  def _json(raw: bytes) -> Any:
1498
1482
  if not raw:
@@ -1540,11 +1524,12 @@ class WorldApp:
1540
1524
  return path[len(self.prefix) :] or "/"
1541
1525
  return path
1542
1526
 
1543
- # ------------------------------------------------------------ the request
1544
-
1545
- def handle(self, method: str, target: str, headers: dict[str, str], raw: bytes, default_host: str) -> Response:
1527
+ def handle(
1528
+ self, method: str, target: str, headers: dict[str, str], raw: bytes, default_host: str, *, via: Via | None
1529
+ ) -> Response:
1546
1530
  """Answer one request. ``headers`` are lower-cased; ``default_host`` is what
1547
- a link uses when the request carries no Host header."""
1531
+ a link uses when the request carries no Host header; ``via`` is the door
1532
+ the caller took it in by, recorded on the call when there is one."""
1548
1533
  url = urllib.parse.urlsplit(target)
1549
1534
  settings, router, state = self.settings, self.router, self.state
1550
1535
  if method == "GET":
@@ -1578,13 +1563,13 @@ class WorldApp:
1578
1563
  return 200, issued, None
1579
1564
  if method not in ("GET", "POST", "PUT", "PATCH", "DELETE"):
1580
1565
  return 405, {"error": "method_not_allowed"}, None
1581
- return self._route(method, url, headers, raw, default_host)
1566
+ return self._route(method, url, headers, raw, default_host, via)
1582
1567
 
1583
- def _route(self, method: str, url, headers: dict[str, str], raw: bytes, default_host: str) -> Response:
1584
- settings, router, state, handlers = self.settings, self.router, self.state, self.handlers
1568
+ def _route(
1569
+ self, method: str, url, headers: dict[str, str], raw: bytes, default_host: str, via: Via | None
1570
+ ) -> Response:
1571
+ settings, router = self.settings, self.router
1585
1572
  path = self._strip(url.path)
1586
- # Every value of a repeated key is kept; ``query`` hands routes the first, the way
1587
- # they always read it, and ``ctx.query_all`` hands handlers and filters the rest.
1588
1573
  query_all = {k: list(v) for k, v in urllib.parse.parse_qs(url.query).items()}
1589
1574
  query = {k: v[0] for k, v in query_all.items()}
1590
1575
  if not router.authorized(headers, query, self.key):
@@ -1601,7 +1586,9 @@ class WorldApp:
1601
1586
  return settings.invalid_status, settings.invalid, None
1602
1587
  started = time.monotonic()
1603
1588
  status, answer, extra = self._answer_route(op, operation, args, query, query_all, body, headers, url, default_host)
1604
- self.calls.record(operation, method, path, args, query_all, body, status, answer, time.monotonic() - started)
1589
+ elapsed = time.monotonic() - started
1590
+ logged_query = router.without_credential(query_all)
1591
+ self.calls.record(operation, method, path, args, logged_query, body, status, answer, elapsed, via)
1605
1592
  return status, answer, extra
1606
1593
 
1607
1594
  def _answer_route(self, op, operation, args, query, query_all, body, headers, url, default_host) -> Response:
@@ -1613,8 +1600,6 @@ class WorldApp:
1613
1600
  ctx.query_all = query_all
1614
1601
  try:
1615
1602
  if BEFORE in handlers:
1616
- # The world's gate: quotas, allow-lists, key states — whatever the vendor
1617
- # checks before any route, declarative ones included.
1618
1603
  verdict = _normalize(handlers[BEFORE](ctx, args, query, body), None)
1619
1604
  if verdict is not None:
1620
1605
  return verdict
@@ -1708,7 +1693,6 @@ def send_response(
1708
1693
  return
1709
1694
  headers = dict(extra or {})
1710
1695
  if isinstance(body, bytes):
1711
- # As the handler shaped them, under the Content-Type it named (checked in _normalize).
1712
1696
  payload = body
1713
1697
  else:
1714
1698
  payload = json.dumps(body, ensure_ascii=False).encode("utf-8")
@@ -1734,7 +1718,9 @@ def make_handler(state: WorldState, router: Router, key: str | None):
1734
1718
  length = int(self.headers.get("Content-Length") or 0)
1735
1719
  raw = self.rfile.read(length) if length else b""
1736
1720
  headers = {k.lower(): v for k, v in self.headers.items()}
1737
- status, body, extra = app.handle(method, self.path, headers, raw, f"127.0.0.1:{self.server.server_port}")
1721
+ default_host = f"127.0.0.1:{self.server.server_port}"
1722
+ # A runner forwards tool calls here too, so this server cannot name the door.
1723
+ status, body, extra = app.handle(method, self.path, headers, raw, default_host, via=None)
1738
1724
  send_response(self, status, body, extra, app.settings.error_content_type)
1739
1725
 
1740
1726
  def do_GET(self):
@@ -1815,9 +1801,6 @@ def serve_forever(
1815
1801
  server.world_state.close() # type: ignore[attr-defined]
1816
1802
 
1817
1803
 
1818
- # ---------------------------------------------------------------- bundle
1819
-
1820
-
1821
1804
  def openapi_document(spec: Spec, contract_id: str, settings: ApiSettings | None = None) -> dict:
1822
1805
  parameters = {"header": "header", "query": "query"}
1823
1806
  security_scheme: dict[str, Any] = {}
@@ -1858,8 +1841,6 @@ def openapi_document(spec: Spec, contract_id: str, settings: ApiSettings | None
1858
1841
  ):
1859
1842
  entry["requestBody"] = {"content": {"application/json": {"schema": {"type": "object"}}}}
1860
1843
  if len(operation.methods) > 1:
1861
- # One OpenAPI operation, listed under the verb a capture sends; the
1862
- # others the served route also answers are named here.
1863
1844
  entry["x-gateway-methods"] = list(operation.methods)
1864
1845
  methods = paths.setdefault(operation.path, {})
1865
1846
  method = operation.method.lower()
@@ -36,11 +36,19 @@ _MISSING = object()
36
36
  @dataclass(frozen=True)
37
37
  class FieldType:
38
38
  """One field as ``gateway worlds describe`` reports it: ``type`` is the JSON Schema
39
- type word(s) joined by ``" | "``, a ``$ref`` name, or None when the schema says nothing."""
39
+ type word(s) joined by ``" | "``, a ``$ref`` name, or None when the schema says nothing;
40
+ ``enum`` the values the schema allows, when it lists them."""
40
41
 
41
42
  name: str
42
43
  type: str | None
43
44
  required: bool
45
+ enum: tuple | None = None
46
+
47
+ def describe(self) -> dict:
48
+ described: dict = {"name": self.name, "type": self.type, "required": self.required}
49
+ if self.enum is not None:
50
+ described["enum"] = list(self.enum)
51
+ return described
44
52
 
45
53
 
46
54
  def _article(kind: str) -> str:
@@ -160,7 +168,7 @@ class RowCaster:
160
168
  return row
161
169
 
162
170
 
163
- #: Text cells as the untyped reader always made them: the text, or None for an empty cell.
171
+ #: The untyped reader: every cell as its text, or None for an empty cell.
164
172
  TEXT_CASTER = RowCaster([])
165
173
 
166
174
  EntityCasters = Callable[[str], "RowCaster | None"]
@@ -178,7 +186,6 @@ def _definition(world: dict, entity: Any) -> dict:
178
186
  if isinstance(ref, str) and ref.startswith("#/$defs/"):
179
187
  definition = (world.get("$defs") or {}).get(ref[len("#/$defs/") :])
180
188
  return definition if isinstance(definition, dict) else {}
181
- # An inline payload (`schema entity add --schema '{…}'`) declares its fields right here.
182
189
  if isinstance(schema, dict) and isinstance(schema.get("properties"), dict):
183
190
  return schema
184
191
  return {}
@@ -196,19 +203,39 @@ def _field_type(field_schema: Any) -> str | None:
196
203
  return kind if isinstance(kind, str) else None
197
204
 
198
205
 
206
+ def _field_enum(field_schema: Any, defs: dict) -> tuple | None:
207
+ if not isinstance(field_schema, dict):
208
+ return None
209
+ branches = field_schema.get("anyOf") or field_schema.get("oneOf")
210
+ if isinstance(branches, list):
211
+ return _branches_enum(branches, defs)
212
+ ref = field_schema.get("$ref")
213
+ target = defs.get(ref[len("#/$defs/") :]) if isinstance(ref, str) and ref.startswith("#/$defs/") else field_schema
214
+ values = target.get("enum") if isinstance(target, dict) else None
215
+ return tuple(values) if isinstance(values, list) else None
216
+
217
+
218
+ def _branches_enum(branches: list, defs: dict) -> tuple | None:
219
+ """A nullable enum (``anyOf: [{$ref: Enum}, {type: null}]``) allows the enum's values and null."""
220
+ values = [value for branch in branches for value in (_field_enum(branch, defs) or ())]
221
+ nullable = any(isinstance(branch, dict) and branch.get("type") == "null" for branch in branches)
222
+ return tuple(values) + ((None,) if nullable else ()) if values else None
223
+
224
+
199
225
  def world_fields(world: dict) -> dict[str, list[FieldType]]:
200
226
  """Every entity's fields as a world.json document declares them (the ``$defs`` entry its
201
227
  ``schema.$ref`` names, or an inline ``properties``), sorted by entity name — the field
202
228
  list ``gateway worlds describe`` reports and a CSV import casts by."""
203
229
  gateway = world.get("x-gateway") if isinstance(world, dict) else None
204
230
  entities = (gateway.get("entities") or {}) if isinstance(gateway, dict) else {}
231
+ defs = world.get("$defs") or {}
205
232
  fields: dict[str, list[FieldType]] = {}
206
233
  for name, entity in sorted(entities.items()):
207
234
  definition = _definition(world, entity)
208
235
  required = set(definition.get("required") or [])
209
236
  properties = definition.get("properties") or {}
210
237
  fields[name] = [
211
- FieldType(field_name, _field_type(field_schema), field_name in required)
238
+ FieldType(field_name, _field_type(field_schema), field_name in required, _field_enum(field_schema, defs))
212
239
  for field_name, field_schema in properties.items()
213
240
  ]
214
241
  return fields
@@ -28,16 +28,12 @@ from pathlib import Path
28
28
  from typing import Any, Protocol
29
29
 
30
30
  from ..world_session_contract import NO_GRADER_REASON
31
- from .tasks import evaluate_assertions
31
+ from .tasks import GraderError, evaluate_assertions
32
32
 
33
33
  GRADER_KINDS = ("assertions", "python", "rubric")
34
34
  VERIFY_TIMEOUT_S = 30.0
35
35
 
36
36
 
37
- class GraderError(Exception):
38
- """A grader that could not deliver a grade, with the reason a reader acts on."""
39
-
40
-
41
37
  @dataclass(frozen=True)
42
38
  class Grade:
43
39
  """A task's grade: the scalar ``reward`` (None when ungraded) and every