@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
@@ -36,7 +36,8 @@ environment, running the same :class:`WorldHost` with ``run_handlers`` on. The
36
36
  supervisor keeps the registry, the leases and the token gate; the worker keeps
37
37
  the world. The **ui** surface is the version's prebuilt static app, served from
38
38
  the cache by the supervisor with its ``api_path`` rewritten onto the session's
39
- api; the **browser** surface is a websocket tunnel to the pool Chromium the
39
+ api and logged ``via: ui`` (the api origin's calls ``via: api``, an operation
40
+ called by name ``via: tool``); the **browser** surface is a websocket tunnel to the pool Chromium the
40
41
  platform leased for the session (:mod:`host_surfaces`). Custom-server worlds
41
42
  stay on pods; this module refuses a version it cannot open rather than
42
43
  guessing.
@@ -76,6 +77,7 @@ from .api import (
76
77
  ApiSettings,
77
78
  Handler,
78
79
  Router,
80
+ Via,
79
81
  WorldApp,
80
82
  load_api_settings,
81
83
  load_handlers,
@@ -297,11 +299,6 @@ def upload_file(url: str, path: Path, sha256: str, size: int, content_type: str
297
299
  fail("host", f"could not upload the export: {error.reason}")
298
300
 
299
301
 
300
- # --------------------------------------------------------------------------- #
301
- # Locating and reading a world tree.
302
- # --------------------------------------------------------------------------- #
303
-
304
-
305
302
  def world_tree(bundle: Path) -> Path:
306
303
  """The compiled schema world inside an extracted bundle (``WorldTree.world``:
307
304
  ``bench push`` packages a schema world as its api bundle with the tree
@@ -318,11 +315,6 @@ def world_tree(bundle: Path) -> Path:
318
315
  raise AssertionError # fail() never returns
319
316
 
320
317
 
321
- # --------------------------------------------------------------------------- #
322
- # Per-version cache: bundle + snapshot + parsed spec, fetched once per host.
323
- # --------------------------------------------------------------------------- #
324
-
325
-
326
318
  @dataclass
327
319
  class CachedVersion:
328
320
  """One cached version, of either shape the host serves: an api bundle (a
@@ -517,11 +509,6 @@ class VersionCache:
517
509
  shutil.rmtree(staging, ignore_errors=True)
518
510
 
519
511
 
520
- # --------------------------------------------------------------------------- #
521
- # Session state: the cached snapshot, cloned into this session's own file.
522
- # --------------------------------------------------------------------------- #
523
-
524
-
525
512
  @dataclass
526
513
  class Export:
527
514
  """A session's state copied to a file on this host, hashed, waiting for the
@@ -611,11 +598,6 @@ class Session:
611
598
  return max(0.0, time.time() - self.opened_at)
612
599
 
613
600
 
614
- # --------------------------------------------------------------------------- #
615
- # The host: the session registry and the control operations.
616
- # --------------------------------------------------------------------------- #
617
-
618
-
619
601
  class WorldHost:
620
602
  """The session registry and the control operations, in one of two roles:
621
603
 
@@ -682,8 +664,6 @@ class WorldHost:
682
664
  self._counters: Counter[str] = Counter()
683
665
  self._session_seconds = 0.0
684
666
 
685
- # -- lifecycle ---------------------------------------------------------- #
686
-
687
667
  def open(
688
668
  self,
689
669
  session_id: str,
@@ -833,9 +813,10 @@ class WorldHost:
833
813
  ) -> dict:
834
814
  """Place the session on the version's worker. The worker opens it from
835
815
  the bundle this process already cached (no snapshot to fetch: the file
836
- is on disk), and the supervisor records only where it went. The ui and
837
- browser surfaces are the supervisor's own (static files, a tunnel), so
838
- the worker hears nothing of them. An export to restore from is fetched
816
+ is on disk), and the supervisor records only where it went. The ui's
817
+ static files and the browser tunnel stay the supervisor's; the ui's
818
+ api-prefix calls are relayed as they came, so the worker logs them
819
+ ``via: ui``. An export to restore from is fetched
839
820
  and verified here too, then handed to the worker as a local file.
840
821
  A worker every one of whose peers holds sessions cannot be started
841
822
  past the pool's memory budget: that is ``at_capacity``, and the
@@ -1003,8 +984,6 @@ class WorldHost:
1003
984
  session.browser = relay
1004
985
  return {"sessionId": session_id, "browser": True}
1005
986
 
1006
- # -- durability: a session's state as a file the platform keeps ---------- #
1007
-
1008
987
  def export(self, session_id: str, known_sha256: str | None = None) -> dict:
1009
988
  """Copy the session's state to a file on this host and hash it. The copy
1010
989
  is consistent (sqlite's online backup under the store's lock) and waits
@@ -1159,8 +1138,6 @@ class WorldHost:
1159
1138
  def worker_count(self) -> int:
1160
1139
  return len(self.workers._workers) if self.workers is not None else 0
1161
1140
 
1162
- # -- fleet: warming, draining, what the platform and prometheus see ------- #
1163
-
1164
1141
  def warm(self, version_id: str, bundle_url: str, snapshot: dict[str, str] | None) -> dict:
1165
1142
  """Cache a version before any session asks for it, so the first open
1166
1143
  pays nothing. Idempotent: a version already here is reported, not
@@ -1316,8 +1293,6 @@ class WorldHost:
1316
1293
  with self._lock:
1317
1294
  return session_id in self._sessions
1318
1295
 
1319
- # -- control operations (the platform's rendezvous, run in-process) ----- #
1320
-
1321
1296
  def _control(self, session: Session, method: str, verb: str, body: dict | None) -> dict:
1322
1297
  return self._worker_control(session.worker, method, f"/__host/sessions/{session.session_id}/{verb}", body)
1323
1298
 
@@ -1392,11 +1367,6 @@ HOSTED_OPERATIONS: dict[str, Callable[..., dict]] = {
1392
1367
  assert set(HOSTED_OPERATIONS) == {verb.route for verb in SESSION_VERBS}, "the host serves every session verb"
1393
1368
 
1394
1369
 
1395
- # --------------------------------------------------------------------------- #
1396
- # The HTTP server: control plane by secret, data plane by Host header.
1397
- # --------------------------------------------------------------------------- #
1398
-
1399
-
1400
1370
  def public_host(host_header: str | None, worlds_domain: str) -> bool:
1401
1371
  """True when ``Host`` names something under the worlds domain: a session,
1402
1372
  or any other label the wildcard ALB forwarded. That is the public side.
@@ -1490,7 +1460,7 @@ def admits(session: Session, path: str, headers: dict[str, str]) -> str | None:
1490
1460
  return "session"
1491
1461
  if session.spec is not None and session.spec.scheme == "oauth2":
1492
1462
  if session.app is None:
1493
- return "world" # the world's tokens live in its worker, which runs this same gate # the world's tokens live in its worker, which runs this same gate
1463
+ return "world" # the world's tokens live in its worker, which runs this same gate
1494
1464
  token_path = session.app.settings.token_path
1495
1465
  if token_path and session.app._strip(path) == token_path:
1496
1466
  return "world"
@@ -1589,8 +1559,6 @@ def make_host_handler(
1589
1559
  def log_message(self, format: str, *args: object) -> None:
1590
1560
  pass
1591
1561
 
1592
- # -- plumbing ------------------------------------------------------- #
1593
-
1594
1562
  def _read(self) -> bytes:
1595
1563
  declared = self.headers.get("Content-Length")
1596
1564
  if declared is None:
@@ -1611,8 +1579,6 @@ def make_host_handler(
1611
1579
  def _headers(self) -> dict[str, str]:
1612
1580
  return {k.lower(): v for k, v in self.headers.items()}
1613
1581
 
1614
- # -- dispatch ------------------------------------------------------- #
1615
-
1616
1582
  def do_GET(self):
1617
1583
  self._dispatch("GET")
1618
1584
 
@@ -1651,8 +1617,6 @@ def make_host_handler(
1651
1617
  self.close_connection = True
1652
1618
  return self._reply(refused.status, {"error": refused.error}, {"Connection": "close"})
1653
1619
 
1654
- # -- control plane -------------------------------------------------- #
1655
-
1656
1620
  def _control(self, method: str, url) -> None:
1657
1621
  if not hmac.compare_digest(self.headers.get("X-Host-Secret") or "", secret):
1658
1622
  return self._reply(403, {"error": "forbidden"})
@@ -1730,8 +1694,6 @@ def make_host_handler(
1730
1694
  except WorkerGone as error:
1731
1695
  return self._reply(502, {"error": "worker exited", "detail": str(error)})
1732
1696
 
1733
- # -- data plane ----------------------------------------------------- #
1734
-
1735
1697
  def _data(self, method: str, url) -> None:
1736
1698
  headers = self._headers()
1737
1699
  named = session_from_host(headers.get("host"))
@@ -1769,25 +1731,30 @@ def make_host_handler(
1769
1731
  admitted = admits(session, url.path, headers)
1770
1732
  if admitted is None:
1771
1733
  return self._reply(401, {"error": "invalid session token"})
1772
- self._serve_api(session, method, self.path, headers, admitted)
1734
+ if session.worker is not None:
1735
+ return self._on_worker(session, method, headers)
1736
+ self._serve_api(session, method, self.path, headers, admitted, Via.API)
1737
+
1738
+ def _on_worker(self, session: Session, method: str, headers: dict[str, str]) -> None:
1739
+ """Relay the request as it came, Host and path unchanged, to the
1740
+ session's version worker: it runs the same gate and picks the same
1741
+ door (api or ui) on its own copy of the session."""
1742
+ assert session.worker is not None
1743
+ try:
1744
+ status, answer_headers, payload = session.worker.request(method, self.path, headers, self._read())
1745
+ except WorkerGone as error:
1746
+ host.lose_worker(session.worker)
1747
+ return self._reply(502, {"error": "worker exited", "detail": str(error)})
1748
+ return self._relay(status, answer_headers, payload, drop=FRAMING_HEADERS)
1773
1749
 
1774
1750
  def _serve_api(
1775
- self, session: Session, method: str, target: str, headers: dict[str, str], admitted: str
1751
+ self, session: Session, method: str, target: str, headers: dict[str, str], admitted: str, via: Via
1776
1752
  ) -> None:
1777
- """Answer ``target`` (a path plus query) from the session's world,
1778
- in this process or its worker, once the gate has admitted it."""
1779
- sid = session.session_id
1780
- raw = self._read()
1781
- if session.worker is not None:
1782
- # The gate passed here; the worker runs it again and presents the
1783
- # world its credential, so the request goes over as it came.
1784
- try:
1785
- status, answer_headers, payload = session.worker.request(method, target, headers, raw)
1786
- except WorkerGone as error:
1787
- host.lose_worker(session.worker)
1788
- return self._reply(502, {"error": "worker exited", "detail": str(error)})
1789
- return self._relay(status, answer_headers, payload, drop=FRAMING_HEADERS)
1753
+ """Answer ``target`` (a path plus query) from the session's world in
1754
+ this process, once the gate has admitted it; the call is logged as
1755
+ having come in by ``via``, the door this host took it in by."""
1790
1756
  assert session.app is not None
1757
+ raw = self._read()
1791
1758
  world_headers = headers
1792
1759
  if admitted == "session":
1793
1760
  # The host's token gate is the access control; present the world
@@ -1795,48 +1762,44 @@ def make_host_handler(
1795
1762
  credential_headers, credential_query = world_credential(session)
1796
1763
  world_headers = {**headers, **credential_headers}
1797
1764
  target = with_query(target, credential_query)
1798
- status, body, extra = session.app.handle(method, target, world_headers, raw, f"w-{sid}-api.{worlds_domain}")
1765
+ default_host = f"w-{session.session_id}-api.{worlds_domain}"
1766
+ status, body, extra = session.app.handle(method, target, world_headers, raw, default_host, via=via)
1799
1767
  self._reply(status, body, extra)
1800
1768
 
1801
- # -- the ui surface -------------------------------------------------- #
1802
-
1803
1769
  def _serve_ui(self, session: Session, method: str, url, headers: dict[str, str]) -> None:
1804
1770
  ui = session.ui
1805
1771
  if ui is None:
1806
1772
  return self._reply(404, {"error": "this world has no static ui"})
1807
1773
  token = session.token
1808
- if token is not None:
1809
- if matches(query_token(url.query), token):
1810
- # The way in: trade the one-time ``?token=`` for the cookie
1811
- # and land on the same page without it.
1812
- landing = without_query_token(url)
1813
- return self._reply(
1814
- 303,
1815
- {"location": landing},
1816
- {
1817
- "Location": landing,
1818
- "Set-Cookie": session_cookie(token, secure=secure_cookies, max_age_s=host.lease_s),
1819
- },
1820
- )
1821
- if not matches(cookie_token(headers), token) and not matches(bearer_of(headers), token):
1822
- return self._reply(401, {"error": "invalid session token"})
1774
+ if token is not None and matches(query_token(url.query), token):
1775
+ return self._trade_token_for_cookie(url, token)
1776
+ if token is not None and not (matches(cookie_token(headers), token) or matches(bearer_of(headers), token)):
1777
+ return self._reply(401, {"error": "invalid session token"})
1823
1778
  route = api_target(ui, url.path)
1824
- if route is not None: # as the api origin answers the token; a version worker routes by Host
1825
- if cross_site(headers, lambda origin: urllib.parse.urlsplit(origin).netloc == headers.get("host")):
1826
- return self._reply(403, {"error": "the ui's api prefix answers its own page, not another site"})
1827
- target = urllib.parse.urlunsplit(("", "", route, url.query, ""))
1828
- api_headers = {k: v for k, v in headers.items() if k not in ("cookie", "authorization")}
1829
- api_headers["host"] = f"w-{session.session_id}-api.{worlds_domain}"
1830
- if token is not None:
1831
- api_headers["authorization"] = f"Bearer {token}"
1832
- return self._serve_api(session, method, target, api_headers, "session")
1779
+ if route is None:
1780
+ return self._serve_static(ui, method, url)
1781
+ if cross_site(headers, lambda origin: urllib.parse.urlsplit(origin).netloc == headers.get("host")):
1782
+ return self._reply(403, {"error": "the ui's api prefix answers its own page, not another site"})
1783
+ if session.worker is not None:
1784
+ return self._on_worker(session, method, headers)
1785
+ target = urllib.parse.urlunsplit(("", "", route, url.query, ""))
1786
+ api_headers = {k: v for k, v in headers.items() if k not in ("cookie", "authorization")}
1787
+ api_headers["host"] = f"w-{session.session_id}-api.{worlds_domain}"
1788
+ if token is not None:
1789
+ api_headers["authorization"] = f"Bearer {token}"
1790
+ return self._serve_api(session, method, target, api_headers, "session", Via.UI)
1791
+
1792
+ def _trade_token_for_cookie(self, url, token: str) -> None:
1793
+ landing = without_query_token(url)
1794
+ cookie = session_cookie(token, secure=secure_cookies, max_age_s=host.lease_s)
1795
+ self._reply(303, {"location": landing}, {"Location": landing, "Set-Cookie": cookie})
1796
+
1797
+ def _serve_static(self, ui: UiSurface, method: str, url) -> None:
1833
1798
  if method != "GET":
1834
1799
  return self._reply(405, {"error": "the static ui answers GET only"})
1835
1800
  status, static_headers, payload = static_file(ui, url.path)
1836
1801
  self._relay(status, static_headers.items(), payload, drop=FRAMING_HEADERS)
1837
1802
 
1838
- # -- the browser surface --------------------------------------------- #
1839
-
1840
1803
  def _serve_browser(self, session: Session, url, headers: dict[str, str]) -> None:
1841
1804
  """``/cdp/<session token>`` and ``/live/<grant>`` on the session's
1842
1805
  cdp host: check the credential against the SESSION, then tunnel
@@ -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, Via, WorldApp, load_api_settings, send_response, vendor_credential, with_query
41
41
  from .compiler import bundle_mode, fail
42
42
  from .conform import PIN
43
43
  from .connector import SPEC, load_spec
@@ -395,14 +395,14 @@ def make_session_handler(
395
395
  if ui_origin:
396
396
  assert ui is not None
397
397
  if app is not None and api_target(ui, path) is not None:
398
- return self._ui_api(method, path, raw)
398
+ return self._ui_api(method, path, raw, Via.UI)
399
399
  return self._ui(method, path)
400
400
  if path.startswith(SESSION_PREFIX):
401
401
  return self._session(method, path[len(SESSION_PREFIX) :].strip("/"), raw)
402
402
  if ui is not None and (path == UI_PREFIX.rstrip("/") or path.startswith(UI_PREFIX)):
403
403
  return self._ui(method, path[len(UI_PREFIX) - 1 :] if path.startswith(UI_PREFIX) else "/")
404
404
  if app is not None and ui is not None and api_target(ui, path) is not None:
405
- return self._ui_api(method, path, raw)
405
+ return self._ui_api(method, path, raw, Via.API)
406
406
  if app is None:
407
407
  return self._reply(
408
408
  404,
@@ -412,7 +412,9 @@ def make_session_handler(
412
412
  },
413
413
  )
414
414
  headers = {k.lower(): v for k, v in self.headers.items()}
415
- status, body, extra = app.handle(method, self.path, headers, raw, f"127.0.0.1:{self.server.server_port}")
415
+ status, body, extra = app.handle(
416
+ method, self.path, headers, raw, f"127.0.0.1:{self.server.server_port}", via=Via.API
417
+ )
416
418
  send_response(self, status, body, extra, app.settings.error_content_type)
417
419
 
418
420
  def _ui(self, method: str, path: str) -> None:
@@ -427,10 +429,11 @@ def make_session_handler(
427
429
  self.end_headers()
428
430
  self.wfile.write(payload)
429
431
 
430
- def _ui_api(self, method: str, path: str, raw: bytes) -> None:
432
+ def _ui_api(self, method: str, path: str, raw: bytes, via: Via) -> None:
431
433
  """The page's same-origin api call: strip the ``api_path`` prefix
432
434
  and answer the route with the world's own credential for the pin,
433
- the way the host answers it for the session cookie."""
435
+ the way the host answers it for the session cookie. Only the ui
436
+ port's prefix is ``via: ui``; the session port is the api origin."""
434
437
  assert app is not None and ui is not None
435
438
  route = api_target(ui, path)
436
439
  assert route is not None
@@ -444,7 +447,12 @@ def make_session_handler(
444
447
  credential_headers, credential_query = vendor_credential(app.router.spec, api_key or "", grant=grant)
445
448
  target = with_query(route + (f"?{query}" if query else ""), credential_query)
446
449
  status, body, extra = app.handle(
447
- method, target, {**headers, **credential_headers}, raw, f"127.0.0.1:{self.server.server_port}"
450
+ method,
451
+ target,
452
+ {**headers, **credential_headers},
453
+ raw,
454
+ f"127.0.0.1:{self.server.server_port}",
455
+ via=via,
448
456
  )
449
457
  send_response(self, status, body, extra, app.settings.error_content_type)
450
458
 
@@ -21,7 +21,6 @@ import shutil
21
21
  import sys
22
22
  import tarfile
23
23
  import tempfile
24
- from dataclasses import asdict
25
24
  from pathlib import Path, PurePosixPath
26
25
  from typing import TYPE_CHECKING, Any
27
26
 
@@ -719,7 +718,7 @@ def _template_summary(files: dict[str, bytes]) -> dict:
719
718
  "primaryKey": list(entity.get("primary_key") or []) if isinstance(entity, dict) else [],
720
719
  "unique": list(entity.get("unique") or []) if isinstance(entity, dict) else [],
721
720
  "relationships": list(entity.get("relationships") or []) if isinstance(entity, dict) else [],
722
- "fields": [asdict(field) for field in fields_by_entity.get(name, [])],
721
+ "fields": [field.describe() for field in fields_by_entity.get(name, [])],
723
722
  }
724
723
  )
725
724
  _annotate_redaction(entities, policy)
@@ -929,9 +928,6 @@ def _ingest_calls(request: dict) -> dict:
929
928
  return answer
930
929
 
931
930
 
932
- # ---------------------------------------------------------------- batches
933
-
934
-
935
931
  def _workdir(request: dict) -> Path:
936
932
  """The absolute directory the caller prepared; every path in the request is under it."""
937
933
  workdir = request.get("workdir")
@@ -1502,8 +1498,6 @@ def execute(request: dict) -> dict:
1502
1498
  )
1503
1499
  extra["batch"] = append_batch(world, batch, source=source)
1504
1500
  if request["command"] == "init-template":
1505
- # The platform's "create world" for every connector template: the same
1506
- # init + compile the CLI runs, on a fresh empty tree, with nothing seeded.
1507
1501
  from .scaffold import init_bundle
1508
1502
 
1509
1503
  connector = request.get("connector")
@@ -34,7 +34,7 @@ from pathlib import Path
34
34
  from typing import TYPE_CHECKING, Any, Optional
35
35
 
36
36
  from . import snapshot as snapshots
37
- from .api import WorldApp, WorldState, operation_request, vendor_credential, with_query
37
+ from .api import Via, WorldApp, WorldState, operation_request, vendor_credential, with_query
38
38
  from .dependencies import Dependency
39
39
  from .grading import Grade, GraderError, TaskGrader
40
40
  from .snapshot import SCENARIOS
@@ -654,12 +654,6 @@ class SnapshotRuntime(WorldRuntime):
654
654
  }
655
655
 
656
656
 
657
- # --------------------------------------------------------------------------- #
658
- # Shared by the runtimes and the local session: an operation by name, the
659
- # client grant, the task card.
660
- # --------------------------------------------------------------------------- #
661
-
662
-
663
657
  def client_grant(app: WorldApp | None, credential: str | None) -> str | None:
664
658
  """The bearer an ``oauth2`` world's routes take when the session itself
665
659
  calls them (the page's api prefix, an operation by name); None for any
@@ -682,7 +676,8 @@ def call_operation(
682
676
  """An operation of connector.toml called by name (:func:`operation_request`
683
677
  reads the args: ``path``/``query``/``body``, or leftover top-level keys as
684
678
  the body); the world's own credential is presented, as the host presents a
685
- session's. The answer is the route's ``{status, body}``."""
679
+ session's. The call is logged ``via: tool``. The answer is the route's
680
+ ``{status, body}``."""
686
681
  spec = app.router.spec
687
682
  operation = spec.operations.get(name)
688
683
  if operation is None:
@@ -696,7 +691,12 @@ def call_operation(
696
691
  method, target, raw = operation_request(spec, operation, args)
697
692
  headers, credential_query = vendor_credential(spec, credential, grant=grant)
698
693
  status, answer, _ = app.handle(
699
- method, with_query(target, credential_query), {"content-type": "application/json", **headers}, raw, "127.0.0.1"
694
+ method,
695
+ with_query(target, credential_query),
696
+ {"content-type": "application/json", **headers},
697
+ raw,
698
+ "127.0.0.1",
699
+ via=Via.TOOL,
700
700
  )
701
701
  return {"status": status, "body": answer}
702
702
 
@@ -64,7 +64,8 @@ registration, a platform builder, live ingestion, tools, or a registry framework
64
64
  | `gateway worlds schema compile \| check \| describe PATH` | exists (#216); `compile` also writes `ui/static` (index.html, app.js, contract.json) when connector.toml declares `[ui]` (every shipped template does): the page over the routes an agent drives with `--surface ui,browser`; `[ui] generated = false` keeps a hand-written page |
65
65
  | `gateway worlds schema ui init PATH` | exists (TS CLI + `python -m … ui-init`); declares `[ui]` in connector.toml when missing (before the first `[[operations]]`) and compiles, which generates the page; refuses a world with no connector.toml (a page shows routes). `worlds serve` serves it on its own port at `/` (and at `/__ui/`) and answers its `api_path` for the pin; `generated = false` + any frontend built to static files into `ui/static` is served the same way |
66
66
  | `gateway worlds schema entity add PATH NAME --ref D \| --fields "a:string,b:integer?" \| --schema JSON --key F [--unique F,F] [--relationship F->entity]` | exists (TS CLI, local); declares one entity in `schema/world.json` without hand-editing the document: keeps `$defs`, package metadata and other entities byte-for-byte in meaning, refuses duplicate names, non-required or non-string/integer keys, unknown `$defs` and undeclared relationship targets, and writes nothing on refusal |
67
- | `gateway worlds connector route add PATH NAME --path /v1/x/{id} [-X POST] [--param q] [--entity E] [--results r] [--action create] [--filter id=id] [--body f=p] [--handler fn]` | exists (TS CLI, local); appends one `[[operations]]` (+ `[operations.api]`) to `connector.toml` leaving existing bytes untouched; validates name, method, path, entity against `schema/world.json`, filter keys against `{args}`/params, and the handler/action pairing |
67
+ | `gateway worlds schema entity remove PATH NAME` | exists (TS CLI, local); takes one entity out of `schema/world.json` with the `$defs` only it used; refused (exit 2, nothing written) while a `connector.toml` operation, a `verifiers/*.sql`, rows in `data/initial.json`, a `[dependencies.<alias>.entities]` map or another entity's relationship uses it, each named; keeps at least one entity and re-points the untouched `state_present.sql` placeholder |
68
+ | `gateway worlds connector route add PATH NAME --path /v1/x/{id} [-X POST] [--param q] [--entity E] [--results r] [--action create] [--filter id=id] [--body f=p] [--handler fn]` | exists (TS CLI, local); appends one `[[operations]]` (+ `[operations.api]`) to `connector.toml` leaving existing bytes untouched; validates name, method, path, entity against `schema/world.json`, filter keys against `{args}`/params, and the handler/action pairing; a new `connector.toml` starts with `[auth] scheme = "bearer"` (the hosted session token) and `--action handler --handler fn` writes a 501 stub into `api/handlers.py` unless `fn` is defined |
68
69
  | `gateway worlds connector publish DIR [--slug S] [-m MSG] [--tag T] [--workspace-visible] [--project-scope]` | exists; saves a template directory, or the world it was authored in, as a workspace connector (Context Hub `connector` repo, org-owned, versioned); the platform compiles the template before accepting it and answers 400 with the reason; a re-publish is a new commit and paths no longer present are removed; `data/`, `captures/`, `db/` and generated files stay behind |
69
70
  | `gateway worlds connector list [--hub] [--query Q]` / `pull SLUG [--out DIR] [--version V]` / `clone SLUG-OR-ID [--name N] [--slug S]` | exists; `list` shows this org's connectors (vendor, auth, entities, operations), `--hub` adds every connector another org published; `pull` writes the template files; `clone` copies a published connector into this org with provenance — a live reference is never made, so the publisher's later edits need a re-clone |
70
71
  | `gateway worlds schema init PATH --connector workspace:<slug>` | exists; initializes from the platform's copy through `init_bundle_from_files` (needs `GATEWAY_*` keys); the offline `python -m gatewaysdk.environment.schema init` refuses `workspace:` and names this command |
@@ -409,5 +410,4 @@ vendor routes. `gateway bench push PATH` publishes the world: for a world carryi
409
410
  `connector.toml` it packages the api-kind bundle the platform hosts on the way (root
410
411
  legacy-shaped on purpose, since the api runner refuses a schema bundle there; `server/`
411
412
  needs nothing installed). Open a session with `--surface api` and hand the client that
412
- URL; the vendor's auth scheme applies (`WORLD_API_KEY` on the host pins the credential,
413
- otherwise any non-empty one).
413
+ URL; the vendor's auth scheme applies, with the session's own api token as the credential.
@@ -269,7 +269,7 @@ level}]}`; text before the JSON is skipped; `input`/`output` decoded as JSON or
269
269
  ```
270
270
 
271
271
  A `gateway worlds session export` line (`{seq, kind, tool, args, result, error, completedAt}`)
272
- is accepted as it is: `kind != "call"` and a failed call are skipped and counted, never
272
+ is accepted as it is: `kind != "call"` (a grade, or a `--requests` line of kind `request`) and a failed call are skipped and counted, never
273
273
  silently dropped. `captureToolCalls` (TS) / `capture_tool_calls` (Python) write the same
274
274
  record at the source.
275
275
 
@@ -388,7 +388,7 @@ gateway worlds session open <slug> -t <scenario> --surface api # prints s
388
388
  gateway worlds session seed <SESSION_ID> rows.json # kind:"seed" call, waits for the result
389
389
  gateway worlds session seed <SESSION_ID> rows.json --redact refuse # same, refusing plaintext in a redacted field (apply hashes it first)
390
390
  gateway worlds session seed <SESSION_ID> rows.json --mode replace # swap the named entities
391
- curl -H 'x-api-key: any' "$API_URL/<route>" # read it back through the vendor's route
391
+ curl -H "Authorization: Bearer $API_TOKEN" "$API_URL/<route>" # read it back (api.token from session open)
392
392
  ```
393
393
 
394
394
  Prints `{sessionId, mode, result}`. MCP: `seed_world_session({ sessionId, rows, mode? })` waits
@@ -134,7 +134,7 @@ gateway worlds connector route add ./x create_account -X POST --path /v1/account
134
134
 
135
135
  Each refuses (and writes nothing) on a duplicate name, an undeclared entity or `$defs` reference, a key that is not a
136
136
  required string/integer field, or a filter on an unknown argument. A create route mints its single-field primary key (`uuid` for strings, `int` for integers) unless `--body` maps it;
137
- `--generate field=uuid|int|now` and `--default field=value` fill the rest. A custom world's first `route add` creates `connector.toml`; `schema init` prints `kind: "schema"`, `api` and the `next` commands in order (custom: entity add → route add → task add → compile → check → import → serve → `worlds create`).
137
+ `--generate field=uuid|int|now` and `--default field=value` fill the rest. A custom world's first `route add` creates `connector.toml` with `[auth] scheme = "bearer"` (a hosted session's api token; `worlds serve` answers 401 without one); `--action handler --handler fn` writes a 501 stub `fn(ctx, args, query, body)` into `api/handlers.py` unless it is defined. The custom scaffold's example entity is `records`: `gateway worlds schema entity remove ./x records` once yours are declared (refused, naming each reference, while a route, verifier, row, dependency map or relationship uses it). `schema init` prints `kind: "schema"`, `api` and the `next` commands in order (custom: entity add → entity remove records → route add → task add → compile → check → import → serve → `worlds create`).
138
138
  Manifest `kind` is `schema` (older trees: `mock-tools`). Handlers: `def name(ctx, args, query, body)`; `ctx` reads and writes the store and keeps the clock.
139
139
 
140
140
  ### From an OpenAPI spec (Swagger 2.0, OpenAPI 3.x)
@@ -188,7 +188,7 @@ MCP: `validate_connector_template({ files, slug? })` compiles without writing; a
188
188
  ## 4. Data
189
189
 
190
190
  ```bash
191
- gateway worlds describe ./x # entities, keys, relationships, row counts, [redact] per field
191
+ gateway worlds describe ./x # entities, keys, relationships, row counts, enum values, [redact] per field
192
192
  gateway worlds data show ./x # kind + entity counts
193
193
  gateway worlds data query ./x users --where email=jo@acme.test --resolve # the rows you mean; plaintext into a hashed field
194
194
  gateway worlds data import ./x rows.json # rows file: {entity: [rows]} | JSONL | .csv/.tsv --entity (cells cast by the schema; --delimiter)
@@ -321,7 +321,7 @@ gateway worlds session seed <SESSION_ID> rows.json # rows into this ses
321
321
  gateway worlds session state <SESSION_ID> # every entity's rows, the dump a grader reads
322
322
  gateway worlds session reset <SESSION_ID> # back to the snapshot (+ the task's seed)
323
323
  gateway worlds session grade <SESSION_ID> [--timeout S] # {reward, rewards, raw}; exploratory → {reward: null, reason: "no grader"}
324
- gateway worlds session export <SESSION_ID> --out calls.jsonl
324
+ gateway worlds session export <SESSION_ID> --out calls.jsonl [--requests] # the platform's ledger; --requests (live session, one state call) adds the world's own request log, kind "request" with via
325
325
  gateway worlds data ingest x calls.jsonl --transform shape.py # the calls back in as rows, shaped by your code or --map ingest.toml (world-data-ingestion §2c)
326
326
  gateway worlds session close <SESSION_ID> # a closed session reopens by id, same URLs + token, from its last checkpoint: gateway worlds session reopen <SESSION_ID>
327
327
  ```
@@ -341,10 +341,10 @@ verifiers) is refused `world_kind_retired`; one on an api bundle opens and lists
341
341
  "metadata": { "externalUserId": "u_42" } }
342
342
  ```
343
343
 
344
- `instruction` is what the agent is told; `seed` (`{mode?, rows}`, the live-seed contract) is
345
- laid on the clone and re-applied by `reset`; `grader` is `assertions` (`entity`, `where`,
346
- `exists|absent|count|all|any`, `field op value`; each check's `id` becomes a `rewards` key),
347
- `{kind: "python", source}` (a `verify.py` body) or `{kind: "rubric", rubric, criteria?, model?}`
344
+ `instruction` is what the agent is told; `seed` (`{mode?, rows}`, the live-seed contract) is laid on the clone and re-applied by `reset`;
345
+ `grader` is `assertions` (`entity`, `where`, `exists|absent|count|all|any`, `field op value`; each check's `id` becomes a `rewards` key;
346
+ `entity: "calls"` reads the call log — `operation`, `args`, `selectors`, `status`, `rows`, `found`, and `via`: `ui` from the page's `api_path`,
347
+ `api` from the api origin, `tool` by name), `{kind: "python", source}` (a `verify.py` body) or `{kind: "rubric", rubric, criteria?, model?}`
348
348
  (an LLM judge over end state + call log, graded on the platform: `grade` answers pending until
349
349
  the worker finalizes it); `tools: [names]` narrows the operations the session may call to
350
350
  exactly those (a name the world does not serve is a 400); `metadata` rides the session. At most one of
@@ -395,11 +395,11 @@ answers 503. That is a cold start, not a fault, until about twenty minutes have
395
395
  `status` print `idleExpiresAt` (null once pinned) + `pinned`; `status` warns under 5 minutes. A call
396
396
  body over 4mb is refused client-side: `{status: "error", code: "payload_too_large"}`, exit 2.
397
397
 
398
- The world's API honours the vendor's auth scheme; `WORLD_API_KEY` on the host pins the
399
- credential, otherwise any non-empty one is accepted.
398
+ The world's API honours the vendor's auth scheme and accepts the session's own api token (bearer or
399
+ the vendor's header); `worlds serve` accepts the `--api-key` pin (default `conform`).
400
400
 
401
401
  MCP: `seed_world_session`, `export_world_session`, `save_world_session_task`; open/call/close are CLI or REST only.
402
- Find what you opened: `gateway worlds session list` / `sandbox list`; `session pin <id>` stops the reaper.
402
+ Find what you opened: `gateway worlds session list` (every state; the live ones are `--state RUNNING` and `--state IDLE`) / `sandbox list`; `session pin <id>` stops the reaper.
403
403
 
404
404
  ## Test the world (not the agent)
405
405
 
@@ -456,8 +456,7 @@ gateway environment rollouts <container-id>
456
456
  ```
457
457
 
458
458
  MCP: `run_evaluation({ models | runConfigId, versionId?, numExamples?, rolloutsPerExample? })`,
459
- `create_task_set`, `create_task`, `link_task_set`, `list_rollouts`, `get_rollout_samples`,
460
- `get_task_performance`; `promote_failure_to_scenario({...})` turns a failed rollout into a scenario.
459
+ `create_task_set`, `create_task`, `link_task_set`, `list_rollouts`, `get_rollout_samples`, `get_task_performance`; `promote_failure_to_scenario({...})` turns a failed rollout into a scenario.
461
460
 
462
461
  ## 8. Iterate
463
462
 
@@ -467,6 +466,7 @@ gateway bench fork x --into x-experiment # a new container sh
467
466
  gateway worlds edit status x # your open EDIT SESSION: every push / sandbox commit / data import after the first version lands there; only this credential reads it as main
468
467
  gateway worlds edit close x -m "why" # seal it: main moves to the session's tip for everyone; each version stays in `log`, `edit rollback` undoes the whole session (60 idle minutes seal it too). `edit list x` = history, `edit discard x` drops it unseen
469
468
  gateway worlds edit rollback x <sessionId> # undo a sealed session (source + data together) as a new sealed session; --force when later sessions would go too
469
+ gateway worlds task edit close <task> -m "why" # a change across a TASK's worlds: seal them all in ONE step or none (`task edit status <task>` first: your unsealed worlds, only you see them; `task edit rollback <task> --group <groupId>` undoes the group)
470
470
  gateway worlds sandbox open x@main # no local checkout: write|exec|check|commit|close <id> edit the tree server-side; `bench sandbox` is the same set
471
471
  gateway worlds sandbox exec <id> 'gateway worlds schema entity add . tickets --fields id:string,title:string -k id && gateway worlds schema compile . && gateway worlds data import . rows.json && gateway worlds schema check . && gateway worlds test .'
472
472
  gateway worlds sandbox open --new y --from custom # a world that does not exist yet (no base); its first `commit` creates it — references/new-world-sandbox.md
@@ -482,7 +482,7 @@ into its tree — `check`/`commit` hold back scratch, credential-shaped files (`
482
482
  any read. `sandbox commit <id> -m why --rebase` replays your edits onto a branch that moved since `open`; a path changed on both sides is a 409, one `conflict: <path> (<reason>)` line each on stderr, exit 1. `worlds run --path` on a clean `bench pull` checkout files runs pinned to the base version.
483
483
  Work is saved while a sandbox sits idle and resumes by id, but after 7 idle days (`status` shows `idleExpiresAt`) the platform closes it even with uncommitted files, and a closed sandbox cannot be reopened: commit before you walk away. `sandbox close <id>` refuses uncommitted files (exit 1, their paths on stderr) unless `--force`. Sandbox twins and every limit: `references/cli-mcp-map.md`.
484
484
 
485
- MCP: `list_world_edits({ slug })`, `close_world_edit`, `discard_world_edit`, `rollback_world_edit({ slug, sessionId })`; `env_diff({ containerId })`, `env_run_tests`, `env_get_run`; proposals (`env_propose`, `env_list_proposals`, `env_apply_proposal`, `env_dismiss_proposal`) are the legacy PR-style door.
485
+ MCP: `list_world_edits({ slug })`, `close_world_edit`, `discard_world_edit`, `rollback_world_edit({ slug, sessionId })`; across a task's worlds `get_task_edit({ task })`, `close_task_edit({ task, requireAll?, force? })`, `rollback_task_edit({ task, groupId })`; `env_diff({ containerId })`, `env_run_tests`, `env_get_run`; proposals (`env_propose`, `env_list_proposals`, `env_apply_proposal`, `env_dismiss_proposal`) are the legacy PR-style door.
486
486
 
487
487
  ## 9. Where it shows in the UI, the CLI to MCP map, gotchas
488
488
 
@@ -36,7 +36,8 @@ Reference for `worlds-getting-started`: every CLI step and its MCP twin, then ho
36
36
  | `environment link-task-set` / `create-task` | `create_task_set`, `create_task`, `link_task_set` |
37
37
  | `bench diff` / `propose` | `env_diff`, `env_propose` (proposals are the legacy PR-style door; edit sessions below are the version-control loop) |
38
38
  | `worlds\|bench edit status\|list\|close\|discard\|rollback <slug>` | `list_world_edits({ slug, status?, limit? })`, `close_world_edit({ slug, sessionId?, force?, message? })`, `discard_world_edit`, `rollback_world_edit({ slug, sessionId, force?, message? })` (`GET /api/public/worlds/{slug}/edits`, `POST …/edits/close\|discard\|rollback`). After a world's first version every push, sandbox commit, data import, agent `env_commit` and UI save lands on the credential's open edit session — a private `edit/<id>` branch only that credential reads as `main` (`describe`, `pull`, `log`, `session open`, `sandbox open`); the write's JSON carries `editSessionId` + a hint. `close`, or 60 minutes without an edit, seals the session: the shared `main` moves to its tip (every version stays in `log`; the session is the rollback unit); a `main` that moved meanwhile is rebased when the paths differ, else the session parks as `conflict` (`close --force` takes its content). `rollback` restores source + data snapshot from before a sealed session as a new sealed session (`--force` when later sessions would be undone too). UI: world › History › Edit sessions |
39
- | `worlds\|bench sandbox open\|status\|read\|write\|exec\|check\|commit\|close` | `open_world_sandbox`, `get_world_sandbox`, `read_world_sandbox_file`, `write_world_sandbox_file` (base64), `exec_in_world_sandbox`, `check_world_sandbox`, `commit_world_sandbox`, `close_world_sandbox({ sandboxId, force? })` (`/api/public/benchmark-containers/sandboxes[/{id}[/file\|exec\|check\|commit]]`; `close` with uncommitted work is a 409 `sandbox_uncommitted` naming the paths, nothing closed, unless `force: true` / `--force`; the source tree only — no data snapshot, nothing on the caller's disk; `commit` lands on the recorded base; `commit --rebase` sends `rebase: true` and replays onto a branch head that moved, a 409 naming each conflicting path). `open` reports `cli: {version, digest}` — the platform's own `gateway` CLI and a `sqlite3` are on PATH inside `exec`, so `gateway worlds schema entity add\|verifier add\|task add\|compile\|check .`, `gateway worlds data import\|show\|query .`, `gateway worlds test .`, `gateway worlds serve . --port 8080 & sleep 2; gateway worlds call http://localhost:8080 <tool> …` (one `exec`; a served world lives only as long as that command) and `sqlite3 db/state.sqlite "…"` run on the working copy; remote verbs (push, run, session open) stop in the sandbox by design — `check`/`commit` from your machine. `cli: null` + `warnings[]` means the image cannot host the runtime (python3 < 3.12 or node < 18); plain shell still runs |
39
+ | `worlds task edit status\|close\|rollback <task>` (task id, spec file with `worlds`, or `task up` manifest) | `get_task_edit({ task })`, `close_task_edit({ task, requireAll?, force?, message? })`, `rollback_task_edit({ task, groupId, force?, message? })` (`POST /api/public/world-task-edits/status\|close\|rollback`). The same edit sessions across every world a task names: `status` shows each world's unsealed edits (open and `parked` in conflict) and what closing would do (`fast-forward`, `rebase`, `conflict`) — your own `task up` opens them at your tip (`private: true`), everyone else still gets shared `main`; `close` seals every world in ONE transaction (a conflict, a missing world, a ref other than `main` or a parked session anywhere seals nothing, and the 409 names every world's problem; worlds with no edit are skipped unless `--require-all`), and the sessions share a `groupId`; `rollback --group` restores every world together to the `main` the group replaced, refused when anything reached a world's `main` after the group (a later session or a write outside sessions) unless `--force` |
40
+ | `worlds\|bench sandbox open\|status\|read\|write\|exec\|check\|commit\|close` | `open_world_sandbox`, `get_world_sandbox`, `read_world_sandbox_file`, `write_world_sandbox_file` (base64), `exec_in_world_sandbox`, `check_world_sandbox`, `commit_world_sandbox`, `close_world_sandbox({ sandboxId, force? })` (`/api/public/benchmark-containers/sandboxes[/{id}[/file\|exec\|check\|commit]]`; `close` with uncommitted work is a 409 `sandbox_uncommitted` naming the paths, nothing closed, unless `force: true` / `--force`; a sandbox whose machine was replaced gets its tree back (latest snapshot, or the base) and the next verb answers 409 `sandbox_recreated` once — look at the tree, redo lost edits, retry; 503 `sandbox_restore_failed` means retry; 409 `sandbox_tree_missing` means the world root was deleted, so close and reopen; the source tree only — no data snapshot, nothing on the caller's disk; `commit` lands on the recorded base; `commit --rebase` sends `rebase: true` and replays onto a branch head that moved, a 409 naming each conflicting path). `open` reports `cli: {version, digest}` — the platform's own `gateway` CLI and a `sqlite3` are on PATH inside `exec`, so `gateway worlds schema entity add\|verifier add\|task add\|compile\|check .`, `gateway worlds data import\|show\|query .`, `gateway worlds test .`, `gateway worlds serve . --port 8080 & sleep 2; gateway worlds call http://localhost:8080 <tool> …` (one `exec`; a served world lives only as long as that command) and `sqlite3 db/state.sqlite "…"` run on the working copy; remote verbs (push, run, session open) stop in the sandbox by design — `check`/`commit` from your machine. `cli: null` + `warnings[]` means the image cannot host the runtime (python3 < 3.12 or node < 18); plain shell still runs |
40
41
  | `worlds\|bench sandbox open --new <slug> --from custom\|<template>` | `open_world_sandbox({ new, from })` (same route, body `{new, from}`; a world that does not exist yet — `baseVersionId`/`containerId`/`baseContentHash` null, `branch: main`, `pendingSlug`; `custom` = the `schema init` scaffold, else a shipped template (`GET /api/public/worlds/templates`; unknown → 400 naming the list); taken slug → 409 `world_exists`, never renamed; `check_world_sandbox` runs the first commit's gate; the first `commit_world_sandbox` creates the world on `main` through the `worlds create --from <dir>` door, later commits land on the new base; the same staged CLI runs on the scaffold) |
41
42
  | `worlds skill <name>` / `worlds connector skill` | `get_connector_authoring_skill`, `guide` |
42
43
  | `worlds connector capture --remote` / poll + download | `start_connector_capture`, `get_connector_capture` (platform agent only) |