@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
@@ -47,9 +47,9 @@ from dataclasses import dataclass, field
47
47
  from pathlib import Path
48
48
  from typing import Any
49
49
 
50
- from .._toml import tomllib
51
50
  from .. import _bundle
52
51
  from .._materialize import materialize_template
52
+ from .._toml import tomllib
53
53
  from .._world import World
54
54
  from ..errors import WorldStartError
55
55
  from ..world import World as WorldDetector
@@ -60,7 +60,8 @@ from .compiler import ContractError, bundle_mode, check_bundle, fail
60
60
  from .connector import SPEC, Spec, load_spec
61
61
  from .data import seed_batch
62
62
  from .dependencies import Dependency, parse_dependencies
63
- from .grading import world_state
63
+ from .grading import Grade, world_state
64
+ from .handler_errors import HANDLER_BUG_ERRORS, engine_failure_body, handler_bug_body
64
65
  from .tasks import TaskSpec
65
66
 
66
67
  Handler = Callable[..., Any]
@@ -93,10 +94,16 @@ class ToolsTask:
93
94
  #: The scenario's ``checks/verify.py``, when it grades by one instead of
94
95
  #: the world's SQL verifiers (the runtime's :class:`TaskGrader` runs it).
95
96
  verify: Path | None = None
97
+ #: Whether the world's verifiers grade this task at all. A bundled task's
98
+ #: do (all of them when it names none); a session task's never do — it
99
+ #: grades by its own grader or is ungraded (the platform's ``no grader``).
100
+ graded_by_world: bool = True
96
101
 
97
102
  def selected(self, all_verifiers: list[str]) -> list[str]:
98
103
  """The verifiers this task grades with: its own list, else the
99
104
  primary one, else every verifier the bundle ships."""
105
+ if not self.graded_by_world:
106
+ return []
100
107
  if self.verifiers:
101
108
  return list(self.verifiers)
102
109
  if self.verifier is not None:
@@ -105,6 +112,8 @@ class ToolsTask:
105
112
 
106
113
  def selected_of(self, alias: str, all_verifiers: list[str]) -> list[str]:
107
114
  """The verifiers of dependency ``alias`` this task grades with."""
115
+ if not self.graded_by_world:
116
+ return []
108
117
  if self.worlds is None:
109
118
  return list(all_verifiers) if not self.verifiers and self.verifier is None else []
110
119
  return list(self.worlds.get(alias, ()))
@@ -116,12 +125,14 @@ INLINE_TASK_ID = "session"
116
125
 
117
126
  def inline_task(spec: TaskSpec) -> ToolsTask:
118
127
  """A session task (:mod:`tasks`) as a schema-world task: the spec's
119
- instruction as the prompt. Without a grader of its own the task is graded
120
- by every verifier the bundle ships (:meth:`ToolsWorld.grade`); with one
121
- (assertions, python, rubric) the host grades it the way it grades an api
122
- world's session task, over :meth:`ToolsWorld.grader_state`. The seed is
123
- applied by :class:`ToolsWorld` once the template copy exists."""
124
- return ToolsTask(id=spec.name or INLINE_TASK_ID, prompt=spec.instruction, metadata=dict(spec.metadata))
128
+ instruction as the prompt. It grades by its own grader (assertions,
129
+ python, rubric) the way an api world's session task does, over
130
+ :meth:`ToolsWorld.grader_state`; without one it is ungraded — the
131
+ bundle's verifiers were written for the bundle's tasks, not this one.
132
+ The seed is applied by :class:`ToolsWorld` once the template copy exists."""
133
+ return ToolsTask(
134
+ id=spec.name or INLINE_TASK_ID, prompt=spec.instruction, metadata=dict(spec.metadata), graded_by_world=False
135
+ )
125
136
 
126
137
 
127
138
  @dataclass
@@ -548,6 +559,11 @@ class ToolsWorld:
548
559
  raise AssertionError # fail() never returns
549
560
 
550
561
  def call(self, tool: str, args: dict) -> dict:
562
+ """Run ``tool`` and answer as the handler's HTTP twin would: 200 with
563
+ the result, 400 when the handler itself is wrong (a name, attribute or
564
+ type error is the author's bug, never the engine's), 500 when anything
565
+ else fails inside the handler. Both failure bodies are structured
566
+ ``{error, detail, handler}`` — never a bare exception string."""
551
567
  world, local = self._route(tool)
552
568
  if self.allowed is not None and tool not in self.allowed:
553
569
  fail(
@@ -558,20 +574,26 @@ class ToolsWorld:
558
574
  result = world.execute(local, args)
559
575
  except ContractError:
560
576
  raise
577
+ except HANDLER_BUG_ERRORS as error:
578
+ return {"status": 400, "body": handler_bug_body(local, error)}
561
579
  except Exception as error: # noqa: BLE001 - the handler's failure is the call's answer
562
- return {"status": 500, "body": {"error": str(error)[:2000]}}
580
+ return {"status": 500, "body": engine_failure_body(local, error)}
563
581
  return {"status": 200, "body": result}
564
582
 
565
583
  def grade(self) -> dict:
566
584
  """The task's verifiers, the root's by name and each dependency's as
567
585
  ``<alias>/<name>``; ``reward`` is the primary verifier's score when the
568
- task names one, else the mean of the numeric scores."""
586
+ task names one, else the mean of the numeric scores — null when no
587
+ verifier answered a number (never 0). A task no verifier grades is
588
+ ungraded, with the reason."""
569
589
  rewards: dict[str, float | None] = {}
570
590
  for name in self.task.selected(self.version.verifiers):
571
591
  rewards[name] = self.world.verify(name).score
572
592
  for alias, dep in self.dependencies.items():
573
593
  for name in self.task.selected_of(alias, dep.version.verifiers):
574
594
  rewards[f"{alias}/{name}"] = self.worlds[alias].verify(name).score
595
+ if not rewards:
596
+ return Grade.ungraded().as_dict()
575
597
  if self.task.verifier is not None and self.task.verifier in rewards:
576
598
  reward = rewards[self.task.verifier]
577
599
  else:
@@ -0,0 +1,228 @@
1
+ """The tree door: rows files into a world *directory*'s data files.
2
+
3
+ :class:`TreeImport` is what ``gateway worlds data import|check <dir> <files>``
4
+ runs, in both CLIs (the Python one directly, the TypeScript one through the
5
+ bundled runtime's ``import-files`` command, which hands over the *paths* — the
6
+ rows never travel through the bridge request). The files are streamed
7
+ (:func:`batch.iter_rows`), a ``.csv``/``.tsv`` is split by ``delimiter`` (or by
8
+ name) and its cells cast by the tree's contract (:mod:`.cast`), and the rows go
9
+ in through :func:`data.import_rows` — the one gate, scratch copy first.
10
+
11
+ The same typed stream cut into the gzipped JSONL chunks a platform data batch
12
+ takes is :meth:`TreeImport.chunks` — ``gateway worlds data chunks`` in both CLIs
13
+ (the TypeScript one through the bundled runtime's ``chunk-files``), and the
14
+ sandbox-side half of ``gateway worlds sandbox import``: the platform runs it
15
+ inside the sandbox (whose staged ``gateway`` is the TypeScript CLI on this
16
+ runtime), then reads the chunk files out itself.
17
+
18
+ What this door cannot be: a home for bulk data. A directory import lands in the
19
+ source tree (``data/initial.json`` / ``data/batches/``), a JSON journal the
20
+ compiler reads whole, the runtime bridge carries whole (``platform.MAX_BYTES``)
21
+ and publication reads whole — and refuses over :data:`PUBLICATION_FILE_BYTES`
22
+ (the Node gate's ``WORLD_PUBLICATION_FILE_MAX_BYTES``). So the door has the same
23
+ cap, named in MiB and rows (:data:`TREE_BYTES`, :data:`TREE_ROWS`), checked on
24
+ the input before a row is held and on the journal before it is written, and the
25
+ refusal names the door bulk data takes: the platform world's snapshot —
26
+ ``gateway worlds sandbox import`` from a sandbox (the platform reads the file
27
+ out of it), ``gateway worlds data import <slug>`` where the keys are.
28
+ """
29
+
30
+ from __future__ import annotations
31
+
32
+ import json
33
+ from pathlib import Path
34
+ from typing import Any
35
+
36
+ from .csv_rows import is_delimited_name
37
+ from .validation import fail
38
+
39
+ #: The most publication reads out of one contract file (``data/initial.json`` among
40
+ #: them): the TypeScript ``WORLD_PUBLICATION_FILE_MAX_BYTES``, declared once per runtime.
41
+ PUBLICATION_FILE_BYTES = 4 * 1024 * 1024
42
+ #: What a world's source tree carries as data, at most: the journal is a source file
43
+ #: publication reads whole, so the door admits no more than publication does.
44
+ TREE_BYTES = PUBLICATION_FILE_BYTES
45
+ TREE_ROWS = 100_000
46
+
47
+
48
+ def world_slug(root: Path) -> str:
49
+ """The platform slug a local world would import into: its pulled metadata, else its name."""
50
+ meta = root / ".gateway" / ".env-metadata.json"
51
+ if meta.is_file():
52
+ try:
53
+ slug = json.loads(meta.read_text(encoding="utf-8")).get("slug")
54
+ if isinstance(slug, str) and slug:
55
+ return slug
56
+ except (OSError, ValueError):
57
+ pass
58
+ return root.resolve().name
59
+
60
+
61
+ def bulk_door(slug: str) -> str:
62
+ """Where rows over the tree cap go, as the refusal names it."""
63
+ return (
64
+ f"import into the platform world `{slug}` instead — its data snapshot has no such cap. From a sandbox: "
65
+ f"`gateway worlds sandbox import <sandbox-id> <path> --entity <entity>` (run where the project keys are; "
66
+ f"the platform reads the file out of the sandbox). With keys on this machine: "
67
+ f"`gateway worlds data import {slug} <file>`."
68
+ )
69
+
70
+
71
+ def tree_cap_message(files: list[Path], size: int, slug: str) -> str:
72
+ named = f"{files[0]}" if len(files) == 1 else f"{len(files)} files"
73
+ return (
74
+ f"{named} ({size / (1024 * 1024):.1f} MiB) is over what a world's source tree carries as data "
75
+ f"(data/initial.json is a source file publication reads whole: {TREE_BYTES // (1024 * 1024)} MiB / "
76
+ f"{TREE_ROWS} rows at most); {bulk_door(slug)}"
77
+ )
78
+
79
+
80
+ def journal_cap_message(path: Path, size: int, slug: str) -> str:
81
+ """The refusal when the rows fit but the journal they land in would not publish."""
82
+ return (
83
+ f"{path} would be {size / (1024 * 1024):.1f} MiB with these rows, over the {PUBLICATION_FILE_BYTES // (1024 * 1024)} MiB "
84
+ f"publication reads a source file whole (a push would refuse it); {bulk_door(slug)}"
85
+ )
86
+
87
+
88
+ def refuse_unpublishable_journal(root: Path, path: Path, payload: bytes) -> None:
89
+ """A journal publication would refuse is refused here, before it is written."""
90
+ if len(payload) <= PUBLICATION_FILE_BYTES:
91
+ return
92
+ fail("tree_cap", journal_cap_message(path, len(payload), world_slug(root)), "/rows")
93
+
94
+
95
+ class TreeImport:
96
+ """Rows files against one world directory. ``entity`` names what bare-row files
97
+ and ``.csv``/``.tsv`` columns hold; ``delimiter`` splits the cells (``None``: by
98
+ name); the tree's contract types them."""
99
+
100
+ def __init__(
101
+ self,
102
+ root: Path,
103
+ files: list[Path],
104
+ *,
105
+ entity: str | None = None,
106
+ delimiter: str | None = None,
107
+ ) -> None:
108
+ self.root = Path(root)
109
+ self.files = [Path(f) for f in files]
110
+ self.entity = entity
111
+ self.delimiter = delimiter
112
+ self._casters: Any = None
113
+
114
+ @property
115
+ def casters(self) -> Any:
116
+ """The tree's cell casters, compiled once and only for delimited inputs."""
117
+ if self._casters is None and any(is_delimited_name(str(f)) for f in self.files):
118
+ from .cast import tree_casters
119
+
120
+ self._casters = tree_casters(self.root)
121
+ return self._casters
122
+
123
+ def size(self) -> int:
124
+ return sum(path.stat().st_size for path in self.files if path.is_file())
125
+
126
+ def refuse_unreadable(self) -> None:
127
+ for path in self.files:
128
+ if not path.is_file():
129
+ fail("rows", f"Cannot read {path}", "/rows")
130
+
131
+ def refuse_over_tree_cap(self) -> None:
132
+ """Over :data:`TREE_BYTES` or :data:`TREE_ROWS` the import is refused before any
133
+ row is held, and told the door big data takes."""
134
+ from .batch import count_rows
135
+
136
+ size = self.size()
137
+ sources = [str(f) for f in self.files]
138
+ over_rows = count_rows(sources, entity=self.entity, cap=TREE_ROWS, delimiter=self.delimiter) > TREE_ROWS
139
+ if size > TREE_BYTES or over_rows:
140
+ fail(
141
+ "tree_cap",
142
+ tree_cap_message(self.files, size, world_slug(self.root)),
143
+ "/rows",
144
+ )
145
+
146
+ def rows(self, seen: dict[str, int] | None = None) -> Any:
147
+ """The typed rows, streamed: ``(entity, row)`` pairs."""
148
+ from .batch import iter_rows
149
+
150
+ return iter_rows(
151
+ [str(f) for f in self.files],
152
+ entity=self.entity,
153
+ seen=seen,
154
+ delimiter=self.delimiter,
155
+ casters=self.casters,
156
+ )
157
+
158
+ def parsed(self) -> dict[str, list[dict]]:
159
+ from .data import parse_rows
160
+
161
+ return parse_rows(
162
+ self.files,
163
+ entity=self.entity,
164
+ delimiter=self.delimiter,
165
+ casters=self.casters,
166
+ )
167
+
168
+ def chunks(
169
+ self,
170
+ workdir: Path,
171
+ *,
172
+ chunk_bytes: int | None = None,
173
+ chunk_rows: int | None = None,
174
+ ) -> list[Any]:
175
+ """The typed rows as the gzipped JSONL chunk files a data batch takes, written
176
+ under ``workdir`` (:func:`batch.chunk_rows`): one chunk of memory at a time, no tree
177
+ cap — the chunks are bound for a platform snapshot, not the source tree."""
178
+ from .batch import CHUNK_BYTES
179
+ from .batch import chunk_rows as split
180
+
181
+ self.refuse_unreadable()
182
+ return list(
183
+ split(
184
+ self.rows(),
185
+ workdir,
186
+ chunk_bytes=chunk_bytes or CHUNK_BYTES,
187
+ chunk_rows=chunk_rows,
188
+ entity=self.entity,
189
+ )
190
+ )
191
+
192
+ @staticmethod
193
+ def chunk_report(chunks: list[Any]) -> dict[str, Any]:
194
+ """What ``worlds data chunks`` prints and ``chunk-files`` answers: ``rows`` and,
195
+ per chunk, ``ordinal``, ``path``, ``rows``, ``bytes``, ``digest``, ``entity``."""
196
+ return {
197
+ "rows": sum(chunk.rows for chunk in chunks),
198
+ "chunks": [
199
+ {
200
+ "ordinal": chunk.ordinal,
201
+ "path": str(chunk.path),
202
+ "rows": chunk.rows,
203
+ "bytes": chunk.bytes,
204
+ "digest": chunk.digest,
205
+ "entity": chunk.entity,
206
+ }
207
+ for chunk in chunks
208
+ ],
209
+ }
210
+
211
+ def run(
212
+ self,
213
+ *,
214
+ mode: str = "append",
215
+ merge: str = "upsert",
216
+ redact: str = "off",
217
+ dry_run: bool = False,
218
+ ) -> dict:
219
+ """The import (or, ``dry_run``, its proof): :func:`data.import_rows`'s report plus
220
+ ``rows``, how many the files held. The cap is checked first, streaming, for a proof
221
+ as for an import: what is held in memory is bounded by the cap, never by the file."""
222
+ from .data import import_rows
223
+
224
+ self.refuse_unreadable()
225
+ self.refuse_over_tree_cap()
226
+ parsed = self.parsed()
227
+ report = import_rows(self.root, parsed, mode=mode, merge=merge, redact=redact, dry_run=dry_run)
228
+ return {**report, "rows": sum(len(listed) for listed in parsed.values())}
@@ -65,6 +65,20 @@ class UiDeclaration:
65
65
  #: so a world that built its own ui before this key existed keeps it.
66
66
  generated: bool | None
67
67
 
68
+ @property
69
+ def kind(self) -> str:
70
+ """``product`` when the ui is hand-built (``generated = false``: a
71
+ replica of the vendor's own product), else ``generated`` (made from the
72
+ contract at compile time). What the connector pages badge and label."""
73
+ return "product" if self.generated is False else "generated"
74
+
75
+
76
+ def ui_kind(world: Path) -> str:
77
+ """The world's ui as the connector pages show it: ``product``,
78
+ ``generated``, or ``none`` when it declares no ``[ui]``."""
79
+ declaration = read_ui_declaration(world)
80
+ return declaration.kind if declaration is not None else "none"
81
+
68
82
 
69
83
  def read_ui_declaration(world: Path) -> UiDeclaration | None:
70
84
  """``[ui]`` of the world's connector.toml, or None when the world declares
@@ -89,8 +103,10 @@ def read_ui_declaration(world: Path) -> UiDeclaration | None:
89
103
  if not isinstance(static, str) or not static or static.startswith("/") or ".." in static.split("/"):
90
104
  fail("spec", "ui.static is a directory inside the world holding the ui", "/ui/static")
91
105
  entry = ui.get("entry", DEFAULT_ENTRY)
92
- if not isinstance(entry, str) or not entry.startswith("/"):
93
- fail("spec", "ui.entry is the path the agent lands on, starting with /", "/ui/entry")
106
+ # `//host` and `/\host` are paths only in form: a browser resolves them to
107
+ # another origin, which would carry the session token off the ui's own.
108
+ if not isinstance(entry, str) or not entry.startswith("/") or entry.startswith("//") or "\\" in entry:
109
+ fail("spec", "ui.entry is the path the agent lands on, starting with / on the ui's own origin", "/ui/entry")
94
110
  api_path = ui.get("api_path", "/__world-api")
95
111
  if not isinstance(api_path, str) or not api_path.startswith("/") or api_path == "/":
96
112
  fail("spec", "ui.api_path is the same-origin prefix the ui calls the api at", "/ui/api_path")
@@ -15,6 +15,8 @@ import struct
15
15
  from pathlib import Path
16
16
  from typing import Any, NoReturn
17
17
 
18
+ from .._toml import tomllib
19
+
18
20
  DIALECT = "https://json-schema.org/draft/2020-12/schema"
19
21
  LANGUAGE = "gateway-world/1"
20
22
  SAFE_INTEGER = 2**53 - 1
@@ -217,6 +219,39 @@ def nonempty(value: Any, location: str) -> None:
217
219
  fail("schema", "Expected a nonempty string of at most 256 characters", location)
218
220
 
219
221
 
222
+ #: A connector operation name: snake_case, at most this long. The bound is shared with
223
+ #: the TypeScript ``route add`` (``MAX_OPERATION_NAME`` in scaffoldRoutes.ts) and the
224
+ #: OpenAPI importer, which truncates an ``operationId`` to fit; a 300-character name
225
+ #: used to compile (zero-context round 2, W3).
226
+ MAX_OPERATION_NAME = 64
227
+ #: An entity name: at most this long, so ``data-import:<entity>:<identity>`` source
228
+ #: records and SQLite table names stay inside the 256-character record limit. Shared
229
+ #: with the TypeScript ``schema entity add`` (``MAX_ENTITY_NAME`` in scaffold.ts) and
230
+ #: the OpenAPI importer, which truncates a schema name to fit.
231
+ MAX_ENTITY_NAME = 64
232
+ OPERATION_NAME = re.compile(r"^[a-z][a-z0-9_]*$")
233
+
234
+
235
+ def parse_toml(text: str) -> dict:
236
+ """A connector.toml's tables, or the structured refusal every reader of it raises."""
237
+ try:
238
+ return tomllib.loads(text)
239
+ except tomllib.TOMLDecodeError as error:
240
+ fail("spec", f"connector.toml is not valid TOML: {error}", "/connector.toml")
241
+
242
+
243
+ def operation_name(name: Any, location: str) -> None:
244
+ if type(name) is not str or not OPERATION_NAME.match(name):
245
+ fail("spec", "operation name must be snake_case ([a-z][a-z0-9_]*)", location)
246
+ if len(name) > MAX_OPERATION_NAME:
247
+ fail(
248
+ "spec",
249
+ f"operation name must be at most {MAX_OPERATION_NAME} characters, got {len(name)}",
250
+ location,
251
+ limit=MAX_OPERATION_NAME,
252
+ )
253
+
254
+
220
255
  def equal(left: Any, right: Any) -> bool:
221
256
  """JSON equality: bool is distinct from number; 1 and 1.0 are equal."""
222
257
  if type(left) in (int, float) and type(right) in (int, float):
@@ -69,11 +69,16 @@ def read_seed(body: dict) -> dict[str, Any]:
69
69
  def read_grade(body: dict) -> dict[str, Any]:
70
70
  """``report`` is the agent's own account of the run, read by a rubric
71
71
  judge or put beside the state for a deterministic grader; absent is fine,
72
- anything but a string is not."""
72
+ anything but a string is not. ``context`` is the evidence of the task's
73
+ other worlds (``{alias: state}``, each what that session's ``evidence``
74
+ answers), read by the cross-world verifiers anchored on this session."""
73
75
  report = body.get("report")
74
76
  if report is not None and not isinstance(report, str):
75
77
  fail("input", "report must be a string", "/report")
76
- return {"report": report}
78
+ context = body.get("context")
79
+ if context is not None and (not isinstance(context, dict) or any(not isinstance(v, dict) for v in context.values())):
80
+ fail("input", "context must be {alias: state} of the task's other worlds", "/context")
81
+ return {"report": report, "context": context}
77
82
 
78
83
 
79
84
  def read_call(body: dict) -> dict[str, Any]:
@@ -95,6 +100,7 @@ SESSION_VERBS: tuple[SessionVerb, ...] = (
95
100
  SessionVerb("GET", "tools", read_nothing),
96
101
  SessionVerb("GET", "task", read_nothing),
97
102
  SessionVerb("GET", "state", read_nothing),
103
+ SessionVerb("GET", "evidence", read_nothing),
98
104
  SessionVerb("POST", "grade", read_grade),
99
105
  SessionVerb("POST", "reset", read_nothing),
100
106
  SessionVerb("POST", "seed", read_seed),
@@ -37,6 +37,7 @@ API_BUNDLE_MANIFEST = "gateway-api-world.toml"
37
37
  BUNDLED_WORLD_PREFIX = "server/world/"
38
38
  CONNECTOR_SPEC = "connector.toml"
39
39
  PYPROJECT = "pyproject.toml"
40
+ BENCHMARK_CONFIG = "benchmark.json"
40
41
  WORLD_SCHEMA_MARKERS = ("schema/world.json", "schema/runtime.json", "schema/lock.json")
41
42
  WORLD_ROOT_MARKERS = (CONNECTOR_SPEC, *WORLD_SCHEMA_MARKERS)
42
43
  SCHEMA_MANIFEST_KIND = "schema"
@@ -48,10 +49,11 @@ KIND_HARBOR = "harbor"
48
49
  KIND_VERIFIERS = "verifiers"
49
50
  KIND_VERIFIERS_V1 = "verifiers-v1"
50
51
 
51
- _SKIPPED_DIRS = frozenset({"dist", "build", "outputs", "__pycache__"})
52
+ _SKIPPED_DIRS = frozenset({"dist", "build", "outputs", "__pycache__", "node_modules"})
52
53
  # A root Gateway marker widens the hashed root from Prime's source globs to
53
- # every ordinary root file: those kinds keep executable contract at the root.
54
- _BROAD_ROOT_MARKERS = frozenset({WORLD_MANIFEST, API_BUNDLE_MANIFEST})
54
+ # every ordinary root file: those kinds keep executable contract (tasks.json,
55
+ # connector.toml, a benchmark's config and fixtures) at the root.
56
+ _BROAD_ROOT_MARKERS = frozenset({WORLD_MANIFEST, API_BUNDLE_MANIFEST, BENCHMARK_CONFIG})
55
57
  _HASH_CHUNK = 1 << 20
56
58
  _HARBOR_TASK = re.compile(r"^(?:tasks/)?([^/]+)/task\.toml$")
57
59
 
@@ -178,6 +180,15 @@ class WorldManifest:
178
180
  WorldManifest.ABSENT = WorldManifest(None, None, None)
179
181
 
180
182
 
183
+ @dataclass(frozen=True)
184
+ class Exclusion:
185
+ """One entry the archive rules dropped: a whole directory (``name/``,
186
+ ``files`` counted) or a single root file."""
187
+
188
+ path: str
189
+ files: int
190
+
191
+
181
192
  @dataclass(frozen=True)
182
193
  class WorldTree:
183
194
  """A tree on disk and where the authored world lives inside it. Immutable;
@@ -276,6 +287,34 @@ class WorldTree:
276
287
  def hashed_paths(self) -> list[str]:
277
288
  return [path.relative_to(self.root).as_posix() for path in self.archive_files()]
278
289
 
290
+ def exclusions(self) -> list[Exclusion]:
291
+ """What the archive rules leave out, collapsed to the entry that
292
+ decided it: a pruned directory counts its files once, a dropped root
293
+ file is named. Dot entries (``.git/``, ``.gateway/``, ``.gitignore``)
294
+ are the one universal convention and stay unreported. ``push`` prints
295
+ the rest so nothing disappears silently."""
296
+ kept = {path.relative_to(self.root).as_posix() for path in self.archive_files()}
297
+ out: list[Exclusion] = []
298
+ for entry in sorted(self.root.iterdir(), key=lambda p: p.name):
299
+ relative = entry.name
300
+ if relative.startswith("."):
301
+ continue
302
+ if entry.is_dir() and not entry.is_symlink():
303
+ dropped = [
304
+ Path(dirpath, name).relative_to(self.root).as_posix()
305
+ for dirpath, _dirnames, filenames in os.walk(entry)
306
+ for name in filenames
307
+ ]
308
+ missing = [path for path in dropped if path not in kept]
309
+ if not missing:
310
+ continue
311
+ whole = len(missing) == len(dropped)
312
+ out.extend([Exclusion(f"{relative}/", len(missing))] if whole else [Exclusion(p, 1) for p in missing])
313
+ continue
314
+ if relative not in kept:
315
+ out.append(Exclusion(relative, 1))
316
+ return out
317
+
279
318
  @property
280
319
  def content_hash(self) -> str:
281
320
  """Streams every file; a large tree never has to fit in memory.
@@ -0,0 +1,57 @@
1
+ """THE NUMBERS AND WORDS A WORLD SESSION PROMISES — the Python twin.
2
+
3
+ Stdlib only, and inside ``gatewaysdk.environment`` because that package is
4
+ what gets vendored on its own — the web/worker images ship
5
+ ``/opt/gateway-schema/gatewaysdk/environment``, ``installSandboxRuntime``
6
+ copies it into agent sandboxes and api bundles stage it beside
7
+ ``server/main.py`` — so the World Host's grader, the SDK client
8
+ (:mod:`gatewaysdk.world_sessions`) and the CLI all read this one module.
9
+
10
+ The TypeScript source of truth is
11
+ ``gateway/packages/shared/src/server/services/worldSessionContract.ts``;
12
+ both are pinned to ``conformance/world-sessions.json`` by a test on each
13
+ side, so the route, the World Host and the two CLIs cannot drift apart.
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ from datetime import datetime, timezone
19
+
20
+ #: The largest body ``POST world-sessions/{id}/calls`` accepts. The CLI
21
+ #: measures the serialized body against the byte count and refuses before
22
+ #: sending; the label is what help and the refusal name.
23
+ CALL_BODY_LIMIT_BYTES = 4 * 1024 * 1024
24
+ CALL_BODY_LIMIT_LABEL = "4mb"
25
+
26
+ #: ``session status`` warns once an unpinned session has less than this left.
27
+ IDLE_WARNING_MINUTES = 5
28
+
29
+ #: The task an exploratory session runs on when the caller names none, and
30
+ #: the ``task.source`` the platform reports for it.
31
+ EXPLORATORY_TASK: dict[str, str] = {"instruction": "exploratory session"}
32
+ EXPLORATORY_TASK_SOURCE = "none"
33
+
34
+ #: What a session that has no grader answers ``grade`` with, beside
35
+ #: ``reward: null``.
36
+ NO_GRADER_REASON = "no grader"
37
+
38
+
39
+ def idle_warning(idle_expires_at: str | None, *, now: str | None = None) -> str | None:
40
+ """The line ``session status`` prints when an unpinned session has under
41
+ :data:`IDLE_WARNING_MINUTES` left, else ``None``. ``now`` is for tests."""
42
+ if not idle_expires_at:
43
+ return None
44
+ expires = datetime.fromisoformat(idle_expires_at.replace("Z", "+00:00"))
45
+ current = (
46
+ datetime.fromisoformat(now.replace("Z", "+00:00"))
47
+ if now
48
+ else datetime.now(timezone.utc)
49
+ )
50
+ left_s = (expires - current).total_seconds()
51
+ if left_s >= IDLE_WARNING_MINUTES * 60:
52
+ return None
53
+ minutes = max(0, int(left_s // 60))
54
+ return (
55
+ f"warning: session expires in {minutes}m (idle TTL); "
56
+ "call a tool to extend it or `gateway worlds session pin` to keep it"
57
+ )