@withgateway/sdk 0.2.6 → 0.2.9

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 (110) hide show
  1. package/README.md +24 -8
  2. package/dist/cli.js +15468 -11263
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +15233 -11028
  5. package/dist/cli.mjs.map +1 -1
  6. package/dist/files/index.d.mts +1 -1
  7. package/dist/files/index.d.ts +1 -1
  8. package/dist/files/index.js +291 -40
  9. package/dist/files/index.js.map +1 -1
  10. package/dist/files/index.mjs +284 -37
  11. package/dist/files/index.mjs.map +1 -1
  12. package/dist/hooks/index.d.mts +1 -1
  13. package/dist/hooks/index.d.ts +1 -1
  14. package/dist/hooks/index.js +203 -47
  15. package/dist/hooks/index.js.map +1 -1
  16. package/dist/hooks/index.mjs +198 -42
  17. package/dist/hooks/index.mjs.map +1 -1
  18. package/dist/{index-BaKu5ZSU.d.mts → index-C3UzD0G3.d.mts} +75 -1
  19. package/dist/{index-BaKu5ZSU.d.ts → index-C3UzD0G3.d.ts} +75 -1
  20. package/dist/{index-CLkMr6VG.d.ts → index-D-_4Ibcn.d.ts} +36 -4
  21. package/dist/{index-CdbmO4aX.d.mts → index-FfK4Nump.d.mts} +36 -4
  22. package/dist/index.d.mts +3 -3
  23. package/dist/index.d.ts +3 -3
  24. package/dist/index.js +2149 -615
  25. package/dist/index.js.map +1 -1
  26. package/dist/index.mjs +2053 -566
  27. package/dist/index.mjs.map +1 -1
  28. package/dist/traces/index.js +268 -31
  29. package/dist/traces/index.js.map +1 -1
  30. package/dist/traces/index.mjs +262 -28
  31. package/dist/traces/index.mjs.map +1 -1
  32. package/dist/tracing/index.js +19 -11
  33. package/dist/tracing/index.js.map +1 -1
  34. package/dist/tracing/index.mjs +19 -11
  35. package/dist/tracing/index.mjs.map +1 -1
  36. package/dist/worlds/index.d.mts +886 -117
  37. package/dist/worlds/index.d.ts +886 -117
  38. package/dist/worlds/index.js +1770 -452
  39. package/dist/worlds/index.js.map +1 -1
  40. package/dist/worlds/index.mjs +1752 -434
  41. package/dist/worlds/index.mjs.map +1 -1
  42. package/package.json +14 -10
  43. package/runtime/gatewaysdk/environment/_toml.py +3 -10
  44. package/runtime/gatewaysdk/environment/_world.py +95 -28
  45. package/runtime/gatewaysdk/environment/runtime.py +10 -6
  46. package/runtime/gatewaysdk/environment/schema/__main__.py +35 -0
  47. package/runtime/gatewaysdk/environment/schema/api.py +19 -23
  48. package/runtime/gatewaysdk/environment/schema/batch.py +68 -14
  49. package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +4 -2
  50. package/runtime/gatewaysdk/environment/schema/cast.py +264 -0
  51. package/runtime/gatewaysdk/environment/schema/compiler.py +35 -1
  52. package/runtime/gatewaysdk/environment/schema/conform.py +28 -10
  53. package/runtime/gatewaysdk/environment/schema/connector.py +59 -14
  54. package/runtime/gatewaysdk/environment/schema/connectors/custom/handlers.py +38 -1
  55. package/runtime/gatewaysdk/environment/schema/connectors/google-drive/readers/merge.toml +3 -1
  56. package/runtime/gatewaysdk/environment/schema/credentials.py +20 -0
  57. package/runtime/gatewaysdk/environment/schema/csv_rows.py +117 -0
  58. package/runtime/gatewaysdk/environment/schema/cycles.py +121 -0
  59. package/runtime/gatewaysdk/environment/schema/data.py +21 -5
  60. package/runtime/gatewaysdk/environment/schema/grading.py +95 -13
  61. package/runtime/gatewaysdk/environment/schema/handler_errors.py +44 -0
  62. package/runtime/gatewaysdk/environment/schema/handler_scan.py +175 -0
  63. package/runtime/gatewaysdk/environment/schema/host.py +68 -115
  64. package/runtime/gatewaysdk/environment/schema/host_requests.py +78 -0
  65. package/runtime/gatewaysdk/environment/schema/host_surfaces.py +12 -0
  66. package/runtime/gatewaysdk/environment/schema/ingest.py +5 -18
  67. package/runtime/gatewaysdk/environment/schema/local.py +7 -10
  68. package/runtime/gatewaysdk/environment/schema/openapi_document.py +322 -0
  69. package/runtime/gatewaysdk/environment/schema/openapi_import.py +382 -0
  70. package/runtime/gatewaysdk/environment/schema/openapi_routes.py +441 -0
  71. package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +629 -0
  72. package/runtime/gatewaysdk/environment/schema/openapi_source.py +210 -0
  73. package/runtime/gatewaysdk/environment/schema/platform.py +110 -299
  74. package/runtime/gatewaysdk/environment/schema/platform_import.py +182 -0
  75. package/runtime/gatewaysdk/environment/schema/platform_query.py +95 -0
  76. package/runtime/gatewaysdk/environment/schema/route_bindings.py +176 -0
  77. package/runtime/gatewaysdk/environment/schema/runtime.py +56 -7
  78. package/runtime/gatewaysdk/environment/schema/scaffold.py +64 -5
  79. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +70 -22
  80. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +54 -4
  81. package/runtime/gatewaysdk/environment/schema/skills/hooks-getting-started/SKILL.md +27 -2
  82. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +62 -0
  83. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +91 -54
  84. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +146 -146
  85. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +11 -7
  86. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +30 -0
  87. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/new-world-sandbox.md +43 -0
  88. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/openapi-import.md +90 -0
  89. package/runtime/gatewaysdk/environment/schema/store.py +15 -6
  90. package/runtime/gatewaysdk/environment/schema/store_contract.py +119 -0
  91. package/runtime/gatewaysdk/environment/schema/tasks.py +121 -32
  92. package/runtime/gatewaysdk/environment/schema/tools_world.py +32 -10
  93. package/runtime/gatewaysdk/environment/schema/tree_import.py +228 -0
  94. package/runtime/gatewaysdk/environment/schema/ui.py +18 -2
  95. package/runtime/gatewaysdk/environment/schema/validation.py +35 -0
  96. package/runtime/gatewaysdk/environment/schema/verbs.py +8 -2
  97. package/runtime/gatewaysdk/environment/world.py +42 -3
  98. package/runtime/gatewaysdk/environment/world_session_contract.py +57 -0
  99. package/skills/benchmarks-getting-started/SKILL.md +70 -22
  100. package/skills/connector-schema-authoring/SKILL.md +54 -4
  101. package/skills/connector-schema-authoring/connector-worlds.md +21 -7
  102. package/skills/connector-schema-authoring/world-schema.md +144 -83
  103. package/skills/hooks-getting-started/SKILL.md +27 -2
  104. package/skills/world-data-ingestion/ROWS.md +62 -0
  105. package/skills/world-data-ingestion/SKILL.md +91 -54
  106. package/skills/worlds-getting-started/SKILL.md +146 -146
  107. package/skills/worlds-getting-started/references/cli-mcp-map.md +11 -7
  108. package/skills/worlds-getting-started/references/gotchas.md +30 -0
  109. package/skills/worlds-getting-started/references/new-world-sandbox.md +43 -0
  110. package/skills/worlds-getting-started/references/openapi-import.md +90 -0
@@ -0,0 +1,175 @@
1
+ """The static pass of ``schema check`` over ``tools/*.py`` — syntax, names, store use.
2
+
3
+ Handlers are parsed, never imported: this pass reads the tree of each file
4
+ under ``tools/`` and answers three questions without running authored code.
5
+
6
+ 1. Does every file parse, and is it a regular file?
7
+ 2. Which tool does each handler serve — by ``@tool(name=…)``, by ``@tool`` on
8
+ a def named like a declared tool, by a bare ``def <tool>`` or by the
9
+ ``run`` convention — and do the served names match ``schema/world.json``
10
+ exactly?
11
+ 3. Does the handler call anything on ``store`` that the store does not
12
+ offer? ``store.upsert(...)`` fails here, at the file and line, with the
13
+ list of what the store does offer — instead of surfacing as a 400 on the
14
+ first hosted call.
15
+ """
16
+
17
+ from __future__ import annotations
18
+
19
+ import ast
20
+ from pathlib import Path
21
+
22
+ from .store_contract import STORE_METHOD_NAMES, unknown_store_method_detail
23
+ from .validation import fail
24
+
25
+ _RUNTIME_MODULE = "gateway_env"
26
+
27
+
28
+ class HandlerScan:
29
+ """One static scan of a bundle's handler files against its declared tools."""
30
+
31
+ def __init__(self, bundle: Path, declared: set[str]):
32
+ self.bundle = bundle
33
+ self.declared = declared
34
+ self.found: dict[str, str] = {}
35
+
36
+ def run(self) -> dict[str, str]:
37
+ """``{tool: file}`` for every handler; raises a ``handler`` contract error
38
+ on a syntax error, an unknown store method, a duplicate or a mismatch."""
39
+ for path in sorted((self.bundle / "tools").glob("*.py")):
40
+ self._scan_file(path)
41
+ self._require_exact_match()
42
+ return self.found
43
+
44
+ def _scan_file(self, path: Path) -> None:
45
+ if path.is_symlink():
46
+ fail("path", "Tool handlers must be regular files")
47
+ try:
48
+ tree = ast.parse(path.read_text(encoding="utf-8"), filename=path.name)
49
+ except (SyntaxError, UnicodeError):
50
+ fail("handler", f"Invalid Python handler syntax: {path.name}")
51
+ StoreUsage(path.name, tree).check()
52
+ for node in tree.body:
53
+ if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
54
+ self._record(path, node)
55
+
56
+ def _record(self, path: Path, node: ast.FunctionDef | ast.AsyncFunctionDef) -> None:
57
+ names = [
58
+ _tool_name(node, decorator)
59
+ for decorator in node.decorator_list
60
+ if _is_tool_decorator(decorator)
61
+ ]
62
+ if not names and node.name in self.declared:
63
+ names.append(node.name)
64
+ if not names and node.name == "run" and path.stem in self.declared:
65
+ names.append(path.stem)
66
+ for name in names:
67
+ if name in self.found:
68
+ fail("handler", f"Duplicate handler for {name}")
69
+ self.found[name] = path.name
70
+
71
+ def _require_exact_match(self) -> None:
72
+ if set(self.found) == self.declared:
73
+ return
74
+ undeclared = sorted(set(self.found) - self.declared)
75
+ unhandled = sorted(self.declared - set(self.found))
76
+ parts = []
77
+ if unhandled:
78
+ parts.append(
79
+ "declared in schema/world.json (tools) without a handler under tools/: "
80
+ + ", ".join(unhandled)
81
+ + " — add `@tool` def <name>(...) to a tools/*.py, or drop the declaration"
82
+ )
83
+ if undeclared:
84
+ parts.append(
85
+ "handled under tools/ without a declaration: "
86
+ + ", ".join(f"{name} ({self.found[name]})" for name in undeclared)
87
+ + " — declare each in schema/world.json, or remove the handler"
88
+ )
89
+ fail(
90
+ "handler",
91
+ "Declared tools and Python handlers must match exactly; "
92
+ + "; ".join(parts),
93
+ "/tools",
94
+ )
95
+
96
+
97
+ def _is_tool_decorator(decorator: ast.expr) -> bool:
98
+ target = decorator.func if isinstance(decorator, ast.Call) else decorator
99
+ if isinstance(target, ast.Name):
100
+ return target.id == "tool"
101
+ return isinstance(target, ast.Attribute) and target.attr == "tool"
102
+
103
+
104
+ def _tool_name(
105
+ node: ast.FunctionDef | ast.AsyncFunctionDef, decorator: ast.expr
106
+ ) -> str:
107
+ """The served name of a ``@tool`` handler: ``name=`` when given, else the def's."""
108
+ if not isinstance(decorator, ast.Call):
109
+ return node.name
110
+ for keyword in decorator.keywords:
111
+ if keyword.arg != "name":
112
+ continue
113
+ if not isinstance(keyword.value, ast.Constant) or not isinstance(
114
+ keyword.value.value, str
115
+ ):
116
+ fail("handler", "Publication requires literal tool names")
117
+ return keyword.value.value
118
+ return node.name
119
+
120
+
121
+ class StoreUsage(ast.NodeVisitor):
122
+ """Every ``store.<attr>`` in one handler file, checked against the contract.
123
+
124
+ ``store`` is recognised through ``from gateway_env import store`` (under
125
+ any alias), and through ``gateway_env.store`` / ``<alias>.store`` after an
126
+ ``import gateway_env``. Any attribute outside the contract is a handler bug
127
+ reported at ``file:line``."""
128
+
129
+ def __init__(self, filename: str, tree: ast.AST):
130
+ self.filename = filename
131
+ self.tree = tree
132
+ self.store_names: set[str] = set()
133
+ self.module_names: set[str] = set()
134
+
135
+ def check(self) -> None:
136
+ self._collect_bindings()
137
+ if not self.store_names and not self.module_names:
138
+ return
139
+ self.visit(self.tree)
140
+
141
+ def _collect_bindings(self) -> None:
142
+ for node in ast.walk(self.tree):
143
+ if isinstance(node, ast.ImportFrom) and node.module == _RUNTIME_MODULE:
144
+ self.store_names.update(
145
+ alias.asname or alias.name
146
+ for alias in node.names
147
+ if alias.name == "store"
148
+ )
149
+ if isinstance(node, ast.Import):
150
+ self.module_names.update(
151
+ alias.asname or alias.name
152
+ for alias in node.names
153
+ if alias.name == _RUNTIME_MODULE
154
+ )
155
+
156
+ def _is_store(self, value: ast.expr) -> bool:
157
+ if isinstance(value, ast.Name):
158
+ return value.id in self.store_names
159
+ return (
160
+ isinstance(value, ast.Attribute)
161
+ and value.attr == "store"
162
+ and isinstance(value.value, ast.Name)
163
+ and value.value.id in self.module_names
164
+ )
165
+
166
+ def visit_Attribute(self, node: ast.Attribute) -> None:
167
+ if self._is_store(node.value) and node.attr not in STORE_METHOD_NAMES:
168
+ fail(
169
+ "handler",
170
+ f"{self.filename}:{node.lineno}: {unknown_store_method_detail(node.attr)}",
171
+ f"/tools/{self.filename}",
172
+ line=node.lineno,
173
+ available=list(STORE_METHOD_NAMES),
174
+ )
175
+ self.generic_visit(node)
@@ -84,12 +84,15 @@ from .api import (
84
84
  )
85
85
  from .compiler import check_bundle
86
86
  from .connector import Spec, load_spec
87
+ from .credentials import basic_user
87
88
  from .dependencies import Dependency
89
+ from .host_requests import BrowserRelay, DependencyRef, parse_dependency_refs
88
90
  from .host_surfaces import (
89
91
  HOP_HEADER,
90
92
  UiSurface,
91
93
  api_target,
92
94
  cookie_token,
95
+ cross_site,
93
96
  load_ui_surface,
94
97
  matches,
95
98
  mint_live_grant,
@@ -561,11 +564,10 @@ class Session:
561
564
  worker: Worker | None = None
562
565
  #: The version's static ui, served by the supervisor for this session.
563
566
  ui: UiSurface | None = None
564
- #: The pool browser leased for this session: its relay's ``ws://ip:port``
565
- #: and the token that relay answers to. None when the session has no
566
- #: browser surface.
567
- browser_url: str | None = None
568
- browser_token: str | None = None
567
+ #: The pool browser leased for this session (:class:`BrowserRelay`), or
568
+ #: None when the session has no browser surface. Swapped in place when
569
+ #: the platform replaces a browser that died (:meth:`WorldHost.set_browser`).
570
+ browser: BrowserRelay | None = None
569
571
  #: Requests inside the world right now. A session is only torn down once
570
572
  #: this reaches zero, so a close or an expiry never pulls the database out
571
573
  #: from under a handler mid-request.
@@ -609,56 +611,6 @@ class Session:
609
611
  return max(0.0, time.time() - self.opened_at)
610
612
 
611
613
 
612
- @dataclass(frozen=True)
613
- class DependencyRef:
614
- """One entry of an open's ``dependencies``: the version a manifest alias
615
- resolved to, and where its bundle (and pinned snapshot) are."""
616
-
617
- alias: str
618
- version_id: str
619
- bundle_url: str
620
- snapshot: dict[str, str] | None
621
- raw: dict[str, Any]
622
-
623
-
624
- def parse_dependency_refs(dependencies: Any) -> list[DependencyRef]:
625
- if dependencies is None:
626
- return []
627
- if not isinstance(dependencies, list):
628
- fail("host", "dependencies must be a list of {alias, versionId, bundleUrl, snapshot?}")
629
- refs: list[DependencyRef] = []
630
- seen: set[str] = set()
631
- for entry in dependencies:
632
- if not isinstance(entry, dict):
633
- fail("host", "dependencies must be a list of {alias, versionId, bundleUrl, snapshot?}")
634
- alias, version_id, bundle_url = entry.get("alias"), entry.get("versionId"), entry.get("bundleUrl")
635
- if not (isinstance(alias, str) and isinstance(version_id, str) and isinstance(bundle_url, str)) or not (
636
- alias and version_id and bundle_url
637
- ):
638
- fail("host", "each dependency needs alias, versionId and bundleUrl")
639
- raise AssertionError # fail() never returns
640
- if alias in seen:
641
- fail("host", f"dependency alias '{alias}' is listed twice")
642
- seen.add(alias)
643
- snapshot = entry.get("snapshot")
644
- if snapshot is not None and not isinstance(snapshot, dict):
645
- fail("host", f"dependency '{alias}': snapshot must be {{url, sha256, digest}}")
646
- refs.append(DependencyRef(alias, version_id, bundle_url, snapshot, dict(entry)))
647
- return refs
648
-
649
-
650
- def browser_lease(browser: dict[str, str] | None) -> tuple[str | None, str | None]:
651
- """The ``browser`` field of an open request: the leased relay's ``url`` and
652
- ``token``, both required when either is given, or ``(None, None)``."""
653
- if not browser:
654
- return None, None
655
- url, token = browser.get("url"), browser.get("token")
656
- if not isinstance(url, str) or not url.startswith("ws://") or not isinstance(token, str) or not token:
657
- fail("host", "browser must be {url: 'ws://host:port', token: <relay token>}")
658
- raise AssertionError # fail() never returns
659
- return url.rstrip("/"), token
660
-
661
-
662
614
  # --------------------------------------------------------------------------- #
663
615
  # The host: the session registry and the control operations.
664
616
  # --------------------------------------------------------------------------- #
@@ -828,7 +780,7 @@ class WorldHost:
828
780
  fail("host", unsupported)
829
781
  if spec is not None:
830
782
  self._check_task_tools(spec, cached.served_tools(dependencies))
831
- browser_url, browser_token = browser_lease(browser)
783
+ relay = BrowserRelay.parse(browser)
832
784
  if cached.needs_worker and not self.run_handlers:
833
785
  if self.workers is None:
834
786
  fail(
@@ -837,7 +789,7 @@ class WorldHost:
837
789
  "this host runs none in its process and has no version workers",
838
790
  )
839
791
  return self._open_on_worker(
840
- cached, session_id, bundle_url, task, spec, token, browser_url, browser_token, restore, deps
792
+ cached, session_id, bundle_url, task, spec, token, relay, restore, deps
841
793
  )
842
794
  session_dir = self.sessions_root / session_id
843
795
  runtime = WorldRuntime.open(
@@ -860,8 +812,7 @@ class WorldHost:
860
812
  lease_until=time.time() + self.lease_s,
861
813
  runtime=runtime,
862
814
  ui=cached.ui,
863
- browser_url=browser_url,
864
- browser_token=browser_token,
815
+ browser=relay,
865
816
  restored=runtime.restored,
866
817
  task_spec=spec,
867
818
  )
@@ -876,8 +827,7 @@ class WorldHost:
876
827
  task: str | None,
877
828
  spec: TaskSpec | None,
878
829
  token: str | None,
879
- browser_url: str | None,
880
- browser_token: str | None,
830
+ relay: BrowserRelay | None,
881
831
  restore: dict[str, str] | None,
882
832
  deps: list[DependencyRef],
883
833
  ) -> dict:
@@ -937,8 +887,7 @@ class WorldHost:
937
887
  lease_until=time.time() + self.lease_s,
938
888
  worker=worker,
939
889
  ui=cached.ui,
940
- browser_url=browser_url,
941
- browser_token=browser_token,
890
+ browser=relay,
942
891
  restored=source is not None,
943
892
  task_spec=spec,
944
893
  )
@@ -1018,7 +967,7 @@ class WorldHost:
1018
967
  "leaseUntil": session.lease_until,
1019
968
  "workerPid": session.worker.pid if session.worker is not None else None,
1020
969
  "ui": {"entry": session.ui.entry, "apiPath": session.ui.api_path} if session.ui is not None else None,
1021
- "browser": session.browser_url is not None,
970
+ "browser": session.browser is not None,
1022
971
  "restored": session.restored,
1023
972
  "openedAt": session.opened_at,
1024
973
  "sessionSeconds": session.seconds,
@@ -1037,6 +986,23 @@ class WorldHost:
1037
986
  return {"closed": True, "openedAt": None, "sessionSeconds": 0.0}
1038
987
  return {"closed": True, "openedAt": session.opened_at, "sessionSeconds": session.seconds}
1039
988
 
989
+ def set_browser(self, session_id: str, browser: Any) -> dict:
990
+ """Point the session's browser surface at another pool relay: the one
991
+ it had died and the platform leased a replacement. Connections open
992
+ on the old relay end with it; every connection after this reaches the
993
+ new one. A session opened without a browser never gains one here."""
994
+ relay = BrowserRelay.parse(browser)
995
+ if relay is None:
996
+ fail("host", "browser must be {url: 'ws://host:port', token: <relay token>}")
997
+ with self._lock:
998
+ session = self._sessions.get(session_id)
999
+ if session is None:
1000
+ fail(UNKNOWN_SESSION, f"no session {session_id} on this host")
1001
+ if session.browser is None:
1002
+ fail("host", f"session {session_id} was opened without a browser surface")
1003
+ session.browser = relay
1004
+ return {"sessionId": session_id, "browser": True}
1005
+
1040
1006
  # -- durability: a session's state as a file the platform keeps ---------- #
1041
1007
 
1042
1008
  def export(self, session_id: str, known_sha256: str | None = None) -> dict:
@@ -1355,53 +1321,45 @@ class WorldHost:
1355
1321
  def _control(self, session: Session, method: str, verb: str, body: dict | None) -> dict:
1356
1322
  return self._worker_control(session.worker, method, f"/__host/sessions/{session.session_id}/{verb}", body)
1357
1323
 
1358
- def tools(self, session_id: str) -> dict:
1324
+ def _verb(self, session_id: str, method: str, verb: str, body: dict | None, local: Callable[[Any], dict]) -> dict:
1325
+ """One session verb: forwarded to the session's worker when it has
1326
+ one, else answered by its in-process runtime through ``local``."""
1359
1327
  with self.using(session_id) as session:
1360
1328
  if session.worker is not None:
1361
- return self._control(session, "GET", "tools", None)
1329
+ return self._control(session, method, verb, body)
1362
1330
  assert session.runtime is not None
1363
- return {"tools": session.runtime.served()}
1331
+ return local(session.runtime)
1332
+
1333
+ def tools(self, session_id: str) -> dict:
1334
+ return self._verb(session_id, "GET", "tools", None, lambda runtime: {"tools": runtime.served()})
1364
1335
 
1365
1336
  def task(self, session_id: str) -> dict:
1366
- with self.using(session_id) as session:
1367
- if session.worker is not None:
1368
- return self._control(session, "GET", "task", None)
1369
- assert session.runtime is not None
1370
- return session.runtime.task_card()
1337
+ return self._verb(session_id, "GET", "task", None, lambda runtime: runtime.task_card())
1371
1338
 
1372
1339
  def reset(self, session_id: str) -> dict:
1373
- with self.using(session_id) as session:
1374
- if session.worker is not None:
1375
- return self._control(session, "POST", "reset", {})
1376
- assert session.runtime is not None
1377
- return session.runtime.reset()
1340
+ return self._verb(session_id, "POST", "reset", {}, lambda runtime: runtime.reset())
1378
1341
 
1379
1342
  def seed(self, session_id: str, rows: dict, mode: str = "append", redact: str = "off") -> dict:
1380
- with self.using(session_id) as session:
1381
- if session.worker is not None:
1382
- args = {"rows": rows, "mode": mode, **({"redact": redact} if redact != "off" else {})}
1383
- return self._control(session, "POST", "seed", {"args": args})
1384
- assert session.runtime is not None
1385
- return session.runtime.seed(rows, mode, redact)
1343
+ args = {"rows": rows, "mode": mode, **({"redact": redact} if redact != "off" else {})}
1344
+ return self._verb(session_id, "POST", "seed", {"args": args}, lambda runtime: runtime.seed(rows, mode, redact))
1386
1345
 
1387
1346
  def state(self, session_id: str) -> dict:
1388
- with self.using(session_id) as session:
1389
- if session.worker is not None:
1390
- return self._control(session, "GET", "state", None)
1391
- assert session.runtime is not None
1392
- return session.runtime.state()
1347
+ return self._verb(session_id, "GET", "state", None, lambda runtime: runtime.state())
1393
1348
 
1394
- def grade(self, session_id: str, report: Optional[str] = None) -> dict:
1349
+ def evidence(self, session_id: str) -> dict:
1350
+ """The session's state as a grader reads it (rows keyed by primary key,
1351
+ the calls): what the platform gathers from each world of a multi-world
1352
+ task and hands another world's ``grade`` as ``context``."""
1353
+ return self._verb(session_id, "GET", "evidence", None, lambda runtime: runtime.grader_state())
1354
+
1355
+ def grade(self, session_id: str, report: Optional[str] = None, context: Optional[dict] = None) -> dict:
1395
1356
  """Grade the session. ``report`` is the agent's own account of the run — the
1396
1357
  text a rubric judge reads; here it is put beside the state as ``report`` so a
1397
1358
  deterministic grader (assertions, verify.py) can check what the agent CLAIMED
1398
- against what the calls show, without a judge."""
1399
- with self.using(session_id) as session:
1400
- if session.worker is not None:
1401
- body = {"report": report} if report is not None else {}
1402
- return self._control(session, "POST", "grade", body)
1403
- assert session.runtime is not None
1404
- return session.runtime.grade(report)
1359
+ against what the calls show, without a judge. ``context`` is the other
1360
+ worlds' evidence the task's cross-world verifiers read (``{alias: state}``)."""
1361
+ body = {key: value for key, value in (("report", report), ("context", context)) if value is not None}
1362
+ return self._verb(session_id, "POST", "grade", body, lambda runtime: runtime.grade(report, context))
1405
1363
 
1406
1364
  def call(self, session_id: str, tool: str, args: dict) -> dict:
1407
1365
  """Invoke one of the world's tools or vendor routes by name, in process.
@@ -1421,6 +1379,7 @@ HOSTED_OPERATIONS: dict[str, Callable[..., dict]] = {
1421
1379
  "GET tools": WorldHost.tools,
1422
1380
  "GET task": WorldHost.task,
1423
1381
  "GET state": WorldHost.state,
1382
+ "GET evidence": WorldHost.evidence,
1424
1383
  "POST grade": WorldHost.grade,
1425
1384
  "POST reset": WorldHost.reset,
1426
1385
  "POST seed": WorldHost.seed,
@@ -1503,17 +1462,8 @@ def vendor_shaped_token(spec: Spec, headers: dict[str, str], token: str) -> bool
1503
1462
  presented = headers.get((spec.auth_name or "x-api-key").lower())
1504
1463
  return presented is not None and hmac.compare_digest(presented, token)
1505
1464
  if spec.scheme == "basic":
1506
- auth = headers.get("authorization", "")
1507
- if not auth.lower().startswith("basic "):
1508
- return False
1509
- import base64 as _b64
1510
-
1511
- try:
1512
- decoded = _b64.b64decode(auth[6:].strip().encode("ascii"), validate=True).decode("utf-8")
1513
- except (ValueError, UnicodeDecodeError):
1514
- return False
1515
- user = decoded.split(":", 1)[0]
1516
- return hmac.compare_digest(user, token)
1465
+ user = basic_user(headers.get("authorization", ""))
1466
+ return user is not None and hmac.compare_digest(user, token)
1517
1467
  return False
1518
1468
 
1519
1469
 
@@ -1746,6 +1696,8 @@ def make_host_handler(
1746
1696
  if len(parts) >= 3 and parts[:2] == ["__host", "sessions"]:
1747
1697
  sid = parts[2]
1748
1698
  verb = parts[3] if len(parts) > 3 else None
1699
+ if method == "PUT" and verb == "browser" and len(parts) == 4:
1700
+ return self._reply(200, host.set_browser(sid, body.get("browser")))
1749
1701
  if method == "POST" and verb == "export" and len(parts) == 5:
1750
1702
  url = body.get("url")
1751
1703
  if not isinstance(url, str) or not url.startswith(("https://", "http://")):
@@ -1869,12 +1821,12 @@ def make_host_handler(
1869
1821
  if not matches(cookie_token(headers), token) and not matches(bearer_of(headers), token):
1870
1822
  return self._reply(401, {"error": "invalid session token"})
1871
1823
  route = api_target(ui, url.path)
1872
- if route is not None:
1873
- # The SPA's same-origin api call: strip the prefix and answer it
1874
- # as the api surface would for a caller holding the session
1875
- # token (the cookie stood in for the bearer here).
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"})
1876
1827
  target = urllib.parse.urlunsplit(("", "", route, url.query, ""))
1877
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}"
1878
1830
  if token is not None:
1879
1831
  api_headers["authorization"] = f"Bearer {token}"
1880
1832
  return self._serve_api(session, method, target, api_headers, "session")
@@ -1890,7 +1842,8 @@ def make_host_handler(
1890
1842
  cdp host: check the credential against the SESSION, then tunnel
1891
1843
  the websocket to the leased relay with the POOL credential the
1892
1844
  relay knows. The relay's token never leaves the host."""
1893
- if session.browser_url is None or session.browser_token is None:
1845
+ relay = session.browser
1846
+ if relay is None:
1894
1847
  return self._reply(404, {"error": "this session has no browser surface"})
1895
1848
  parts = url.path.strip("/").split("/")
1896
1849
  if len(parts) != 2 or parts[0] not in ("cdp", "live"):
@@ -1902,17 +1855,17 @@ def make_host_handler(
1902
1855
  return self._reply(401, {"error": "invalid session token"})
1903
1856
  # The relay decodes the path segment, so a token with '/' or
1904
1857
  # '=' (openssl rand -base64) must travel percent-encoded.
1905
- upstream_path = f"/cdp/{urllib.parse.quote(session.browser_token, safe='')}"
1858
+ upstream_path = f"/cdp/{urllib.parse.quote(relay.token, safe='')}"
1906
1859
  else:
1907
1860
  scope = verify_live_grant(credential, token)
1908
1861
  if scope is None:
1909
1862
  return self._reply(401, {"error": "invalid or expired live grant"})
1910
- upstream_path = f"/live/{mint_live_grant(session.browser_token, LIVE_RELAY_GRANT_MS, scope)}"
1863
+ upstream_path = f"/live/{mint_live_grant(relay.token, LIVE_RELAY_GRANT_MS, scope)}"
1911
1864
  if headers.get("upgrade", "").lower() != "websocket":
1912
1865
  return self._reply(400, {"error": "the browser surface is a websocket"})
1913
1866
  self.close_connection = True
1914
1867
  try:
1915
- tunnel(self.connection, session.browser_url, upstream_path, headers)
1868
+ tunnel(self.connection, relay.url, upstream_path, headers)
1916
1869
  except OSError as error:
1917
1870
  self._reply(502, {"error": "browser unreachable", "detail": str(error)})
1918
1871
 
@@ -0,0 +1,78 @@
1
+ """What a World Host control request carries, parsed once.
2
+
3
+ The platform opens a session with ``dependencies`` (the worlds its manifest's
4
+ ``[dependencies]`` resolved to) and, for a session with a browser surface, the
5
+ ``browser`` relay it leased from the pool. A browser can also be swapped
6
+ later (``PUT /__host/sessions/<sid>/browser``): the pool pod behind it died
7
+ (a spot reclaim, an eviction) and the platform leased another. Each field is
8
+ parsed here into a value object, and refused with a ``host`` contract error
9
+ naming the expected shape.
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ from dataclasses import dataclass
15
+ from typing import Any
16
+
17
+ from .validation import fail
18
+
19
+
20
+ @dataclass(frozen=True)
21
+ class DependencyRef:
22
+ """One entry of an open's ``dependencies``: the version a manifest alias
23
+ resolved to, and where its bundle (and pinned snapshot) are."""
24
+
25
+ alias: str
26
+ version_id: str
27
+ bundle_url: str
28
+ snapshot: dict[str, str] | None
29
+ raw: dict[str, Any]
30
+
31
+
32
+ def parse_dependency_refs(dependencies: Any) -> list[DependencyRef]:
33
+ if dependencies is None:
34
+ return []
35
+ if not isinstance(dependencies, list):
36
+ fail("host", "dependencies must be a list of {alias, versionId, bundleUrl, snapshot?}")
37
+ refs: list[DependencyRef] = []
38
+ seen: set[str] = set()
39
+ for entry in dependencies:
40
+ if not isinstance(entry, dict):
41
+ fail("host", "dependencies must be a list of {alias, versionId, bundleUrl, snapshot?}")
42
+ alias, version_id, bundle_url = entry.get("alias"), entry.get("versionId"), entry.get("bundleUrl")
43
+ if not (isinstance(alias, str) and isinstance(version_id, str) and isinstance(bundle_url, str)) or not (
44
+ alias and version_id and bundle_url
45
+ ):
46
+ fail("host", "each dependency needs alias, versionId and bundleUrl")
47
+ raise AssertionError # fail() never returns
48
+ if alias in seen:
49
+ fail("host", f"dependency alias '{alias}' is listed twice")
50
+ seen.add(alias)
51
+ snapshot = entry.get("snapshot")
52
+ if snapshot is not None and not isinstance(snapshot, dict):
53
+ fail("host", f"dependency '{alias}': snapshot must be {{url, sha256, digest}}")
54
+ refs.append(DependencyRef(alias, version_id, bundle_url, snapshot, dict(entry)))
55
+ return refs
56
+
57
+
58
+ @dataclass(frozen=True)
59
+ class BrowserRelay:
60
+ """The pool browser a session's ``w-<sid>-cdp`` surface tunnels to: the
61
+ relay's ``ws://ip:port`` and the token it answers to. The token never
62
+ leaves the host; clients present the session's own."""
63
+
64
+ url: str
65
+ token: str
66
+
67
+ @classmethod
68
+ def parse(cls, browser: Any) -> BrowserRelay | None:
69
+ """The ``browser`` field of a request, or None when absent. Both
70
+ ``url`` and ``token`` are required when either is given."""
71
+ if not browser:
72
+ return None
73
+ url = browser.get("url") if isinstance(browser, dict) else None
74
+ token = browser.get("token") if isinstance(browser, dict) else None
75
+ if not isinstance(url, str) or not url.startswith("ws://") or not isinstance(token, str) or not token:
76
+ fail("host", "browser must be {url: 'ws://host:port', token: <relay token>}")
77
+ raise AssertionError # fail() never returns
78
+ return cls(url.rstrip("/"), token)
@@ -194,6 +194,18 @@ def static_file(ui: UiSurface, path: str) -> tuple[int, dict[str, str], bytes]:
194
194
  # --------------------------------------------------------------------------- #
195
195
 
196
196
 
197
+ def cross_site(headers: dict[str, str], own_origin) -> bool:
198
+ """Whether a browser marked this request as coming from another site: a
199
+ ``Sec-Fetch-Site`` other than same-origin/none, or an ``Origin`` that
200
+ ``own_origin`` does not accept. A ui's api prefix answers with the page's
201
+ credential (the session cookie, the local pin), so it answers the page
202
+ only; curl and a world's own tests send neither header. ``headers`` are
203
+ lower-cased."""
204
+ site = headers.get("sec-fetch-site")
205
+ origin = headers.get("origin")
206
+ return bool(site and site not in ("same-origin", "none")) or bool(origin and not own_origin(origin))
207
+
208
+
197
209
  def cookie_token(headers: dict[str, str]) -> str | None:
198
210
  """The session token a request's cookie carries, if any."""
199
211
  raw = headers.get("cookie")
@@ -30,14 +30,13 @@ Redaction is optional and OFF by default: rows land as the source had them.
30
30
 
31
31
  from __future__ import annotations
32
32
 
33
- import csv
34
33
  import hashlib
35
- import io
36
34
  import json
37
35
  from pathlib import Path
38
36
  from typing import Any, Callable, Iterable
39
37
 
40
38
  from .connector import SPEC, Spec, load_spec, response_rows
39
+ from .csv_rows import csv_delimiter, read_csv
41
40
  from .validation import ContractError, fail
42
41
 
43
42
  FROM = ("tool-calls", "traces", "rows", "csv")
@@ -191,14 +190,15 @@ def project_records(spec: Spec, records: Iterable[Any]) -> tuple[Rows, dict[str,
191
190
  # ---------------------------------------------------------------- inputs
192
191
 
193
192
 
194
- def read_input(paths: Iterable[str | Path], kind: str) -> list[dict]:
193
+ def read_input(paths: Iterable[str | Path], kind: str, *, delimiter: str | None = None) -> list[dict]:
195
194
  """Records from files, as ``kind`` says they are shaped.
196
195
 
197
196
  ``tool-calls`` and ``traces``: JSONL or a JSON array of tool-call records
198
197
  (:func:`read_records`). ``rows``: JSON objects — a JSONL of objects, a JSON
199
198
  array of objects, or one JSON object (a saved query result stays one record:
200
199
  select ``rows[*]`` in the mapping). ``csv``: a header row names the fields;
201
- every cell is text until a mapping's ``type`` says otherwise."""
200
+ every cell is text until a mapping's ``type`` says otherwise; the separator is
201
+ ``delimiter`` when given, else by file name (tab for a ``.tsv``, a comma otherwise)."""
202
202
  if kind not in FROM:
203
203
  fail("records", f"from must be one of {', '.join(FROM)}", "/from")
204
204
  if kind in ("tool-calls", "traces"):
@@ -207,7 +207,7 @@ def read_input(paths: Iterable[str | Path], kind: str) -> list[dict]:
207
207
  for path in paths:
208
208
  text = Path(path).read_text(encoding="utf-8")
209
209
  if kind == "csv":
210
- records.extend(read_csv(text, str(path)))
210
+ records.extend(read_csv(text, str(path), csv_delimiter(str(path), delimiter)))
211
211
  continue
212
212
  stripped = text.strip()
213
213
  if not stripped:
@@ -223,19 +223,6 @@ def read_input(paths: Iterable[str | Path], kind: str) -> list[dict]:
223
223
  return records
224
224
 
225
225
 
226
- def read_csv(text: str, where: str) -> list[dict]:
227
- """Rows of a CSV with a header row, every value a string; an empty cell is ``None``."""
228
- reader = csv.DictReader(io.StringIO(text))
229
- if not reader.fieldnames or any(not name or not name.strip() for name in reader.fieldnames):
230
- fail("records", f"{where}: the first row must name every column", "/records")
231
- records = []
232
- for number, row in enumerate(reader, 2):
233
- if None in row:
234
- fail("records", f"{where}:{number} has more cells than the header names", f"/records/{number - 2}")
235
- records.append({name: (value if value != "" else None) for name, value in row.items()})
236
- return records
237
-
238
-
239
226
  def records_from_clickhouse(document: Any, where: str = "clickhouse") -> list[dict]:
240
227
  """Tool-call records from a saved ClickHouse result of TOOL observations
241
228
  (``{rows|results: [...]}`` or the bare list; a saved MCP answer may start with