@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,117 @@
1
+ """Delimited rows files (``.csv``, ``.tsv``, gzipped or not), streamed one record at a time.
2
+
3
+ The header row names the fields; each later record is numbered from 2 as ``where``
4
+ pointers count (``file:2`` is the first data row), a blank line skipped, a record
5
+ wider than the header refused. A quoted cell may span physical lines; the file is
6
+ never read whole. Cells are text (an empty cell ``None``) until a :class:`.cast.RowCaster`
7
+ types them by the entity's schema. The TypeScript twin is ``worldData/csv.ts``.
8
+
9
+ Standard library only, so the bridge and the api bundle can load it.
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ import csv
15
+ import io
16
+ from collections.abc import Iterator
17
+ from typing import IO
18
+
19
+ from .validation import fail
20
+
21
+ DELIMITER_HELP = "Cell separator for .csv/.tsv inputs: one character, \\t for a tab. Default , (tab for a .tsv)."
22
+ BAD_DELIMITER = "--delimiter is one character (\\t for a tab), not a quote or a newline"
23
+ #: A quoted cell longer than this is refused rather than held (the stdlib default is 128 KiB).
24
+ FIELD_CAP = 16 * 1024 * 1024
25
+
26
+ Record = dict[str, "str | None"]
27
+
28
+
29
+ def is_csv_name(name: str) -> bool:
30
+ """A CSV by name (``.csv``, ``.csv.gz``): the one rows shape decided by name, not by its first byte."""
31
+ lowered = name.lower()
32
+ return lowered.endswith((".csv", ".csv.gz"))
33
+
34
+
35
+ def is_tsv_name(name: str) -> bool:
36
+ lowered = name.lower()
37
+ return lowered.endswith((".tsv", ".tsv.gz"))
38
+
39
+
40
+ def is_delimited_name(name: str) -> bool:
41
+ return is_csv_name(name) or is_tsv_name(name)
42
+
43
+
44
+ def parse_delimiter(text: str) -> str:
45
+ """``--delimiter`` as given: one character, ``\\t`` spelled out for a tab."""
46
+ value = "\t" if text == "\\t" else text
47
+ if len(value) != 1 or value in ('"', "\n", "\r"):
48
+ fail("rows", BAD_DELIMITER, "/delimiter")
49
+ return value
50
+
51
+
52
+ def csv_delimiter(name: str, explicit: str | None = None) -> str:
53
+ """The separator a delimited file uses: ``--delimiter`` when given, else tab for a ``.tsv``, else a comma."""
54
+ if explicit is None:
55
+ return "\t" if is_tsv_name(name) else ","
56
+ return parse_delimiter(explicit)
57
+
58
+
59
+ class _Dialect(csv.Dialect):
60
+ quotechar = '"'
61
+ doublequote = True
62
+ skipinitialspace = False
63
+ lineterminator = "\n"
64
+ quoting = csv.QUOTE_MINIMAL
65
+ #: A quote never closed or text after a closing quote is a refusal, as in the TypeScript twin.
66
+ strict = True
67
+
68
+
69
+ def iter_csv_records(stream: IO[str], where: str, delimiter: str) -> Iterator[tuple[int, Record]]:
70
+ """``(number, record)`` per data row of a delimited text stream, header first, never whole.
71
+ ``stream`` is opened with ``newline=""`` so the reader sees every line ending itself."""
72
+ dialect = type("Dialect", (_Dialect,), {"delimiter": delimiter})
73
+ if csv.field_size_limit() < FIELD_CAP:
74
+ csv.field_size_limit(FIELD_CAP)
75
+ reader = csv.reader(stream, dialect=dialect)
76
+ try:
77
+ header = next(reader, None)
78
+ if header is None:
79
+ return
80
+ if not header or any(not name.strip() for name in header):
81
+ fail("rows", f"{where}: the first row must name every column", where)
82
+ for number, cells in enumerate(reader, 2):
83
+ if not cells or cells == [""]:
84
+ continue
85
+ if len(cells) > len(header):
86
+ fail(
87
+ "rows",
88
+ f"{where}:{number} has more cells than the header names",
89
+ where,
90
+ )
91
+ cells.extend([""] * (len(header) - len(cells)))
92
+ yield (
93
+ number,
94
+ {name: (cell if cell != "" else None) for name, cell in zip(header, cells)},
95
+ )
96
+ except csv.Error as error:
97
+ fail("rows", f"{where}: not a readable delimited file ({error})", where)
98
+
99
+
100
+ def read_csv(text: str, where: str, delimiter: str = ",") -> list[Record]:
101
+ """A whole text as records — for the readers that hold a file whole anyway (a sample, a mapping preview)."""
102
+ stripped = text.removeprefix("\ufeff")
103
+ return [record for _, record in iter_csv_records(io.StringIO(stripped, newline=""), where, delimiter)]
104
+
105
+
106
+ __all__ = [
107
+ "BAD_DELIMITER",
108
+ "DELIMITER_HELP",
109
+ "Record",
110
+ "csv_delimiter",
111
+ "is_csv_name",
112
+ "is_delimited_name",
113
+ "is_tsv_name",
114
+ "iter_csv_records",
115
+ "parse_delimiter",
116
+ "read_csv",
117
+ ]
@@ -0,0 +1,121 @@
1
+ """Reference cycles in a world's schema (zero-context round 2, W4).
2
+
3
+ ``NodeA -> NodeB -> NodeA`` used to compile silently. The resolver projects a
4
+ reference met again to its bare type, so a value below the first level is
5
+ stored as JSON and checked as "an object", not against the shape the author
6
+ wrote. Three cases, decided here:
7
+
8
+ * a cycle with an untyped hop (``{"$ref": ...}`` and nothing else on the way
9
+ round, so no type can be projected): refused by the resolver itself, before
10
+ this module runs, as ``recursive_reference``.
11
+ * a typed cycle an entity reaches — its own root nesting itself (Brex's
12
+ ``Expense.parent``), or a definition below it (Jira's ``LinkGroup``): a
13
+ warning naming the entity and the cycle. The row compiles; the nested copy is
14
+ stored as JSON and checked as its bare type, the resolver's documented
15
+ typed-recursion contract. A model that means entity recursion is better told
16
+ as a relationship (``parent_id`` targeting the same entity, as the custom
17
+ template's records do), and the warning says so.
18
+ * a cycle among ``$defs`` no entity reaches: a warning; no row is affected.
19
+
20
+ :class:`ReferenceCycles` finds every cycle in linear time: only ``$ref``
21
+ targets go on the stack, a target proven acyclic is never walked twice, and a
22
+ cycle is reported once however many entities reach it.
23
+ """
24
+
25
+ from __future__ import annotations
26
+
27
+ from typing import Any
28
+
29
+ from .validation import Resolver
30
+
31
+ CODE = "recursive_reference"
32
+ _BRANCHES = ("allOf", "anyOf", "oneOf")
33
+
34
+
35
+ class ReferenceCycles:
36
+ def __init__(self, resolver: Resolver):
37
+ self.resolver = resolver
38
+ self.acyclic: set[str] = set()
39
+ self.reported: set[str] = set()
40
+
41
+ def through(self, schema: Any, name: str) -> list[list[str]]:
42
+ """The cycles one depth-first walk from ``schema`` closes: each is the
43
+ reference targets on the stack from the repeated one, which ends it. Every
44
+ target reachable from ``schema`` is walked once, so a cycle back to the
45
+ root target is always among them."""
46
+ found: list[list[str]] = []
47
+ self._walk(schema, name, (), set(), found)
48
+ return found
49
+
50
+ def reached(self, entity: str, schema: Any, location: str) -> list[dict]:
51
+ """One warning per cycle the entity's root reaches, the first entity to reach it."""
52
+ return [
53
+ self._warning(
54
+ cycle,
55
+ f"Entity {entity} reaches a $ref cycle ({_spell(cycle)}); below the first level rows store that "
56
+ "value as JSON checked only as its bare type. If it models entity recursion, make it a relationship "
57
+ "(a parent_id field targeting the entity), not a nested object",
58
+ location,
59
+ entity=entity,
60
+ )
61
+ for cycle in self.through(schema, "world.json")
62
+ if self._fresh(cycle)
63
+ ]
64
+
65
+ def unreached(self, defs: dict, name: str) -> list[dict]:
66
+ """One warning per ``$defs`` cycle no entity reached (entities were walked first)."""
67
+ return [
68
+ self._warning(
69
+ cycle,
70
+ f"$defs/{key} reaches itself through $ref ({_spell(cycle)}); no entity uses it, so no row is "
71
+ "affected — a definition meant for an entity must not nest itself",
72
+ f"{name}#/$defs/{key}",
73
+ )
74
+ for key in defs
75
+ for cycle in self.through({"$ref": f"#/$defs/{key}"}, name)
76
+ if self._fresh(cycle)
77
+ ]
78
+
79
+ def _fresh(self, cycle: list[str]) -> bool:
80
+ if self.reported & set(cycle):
81
+ return False
82
+ self.reported.update(cycle)
83
+ return True
84
+
85
+ def _warning(self, cycle: list[str], message: str, location: str, **context: Any) -> dict:
86
+ return {"code": CODE, "message": message, "schema_path": location, "cycle": cycle, **context}
87
+
88
+ def _walk(self, schema: Any, name: str, stack: tuple[str, ...], done: set[str], found: list[list[str]]) -> None:
89
+ if type(schema) is not dict:
90
+ return
91
+ if "$ref" in schema:
92
+ self._follow(schema["$ref"], name, stack, done, found)
93
+ for child in _children(schema):
94
+ self._walk(child, name, stack, done, found)
95
+
96
+ def _follow(self, ref: str, name: str, stack: tuple[str, ...], done: set[str], found: list[list[str]]) -> None:
97
+ target, target_name, target_location = self.resolver.reference(ref, name, "")
98
+ if target_location in stack:
99
+ found.append([*stack[stack.index(target_location) :], target_location])
100
+ return
101
+ if target_location in self.acyclic or target_location in done:
102
+ return
103
+ before = len(found)
104
+ self._walk(target, target_name, (*stack, target_location), done, found)
105
+ done.add(target_location)
106
+ if len(found) == before:
107
+ self.acyclic.add(target_location)
108
+
109
+
110
+ def _spell(cycle: list[str]) -> str:
111
+ return " -> ".join(location.rsplit("/", 1)[-1] for location in cycle)
112
+
113
+
114
+ def _children(schema: dict) -> list[Any]:
115
+ properties = schema.get("properties")
116
+ children: list[Any] = list(properties.values()) if isinstance(properties, dict) else []
117
+ children.extend(schema[key] for key in ("items", "additionalProperties") if isinstance(schema.get(key), dict))
118
+ for key in _BRANCHES:
119
+ branches = schema.get(key)
120
+ children.extend(branches if isinstance(branches, list) else [])
121
+ return children
@@ -36,9 +36,11 @@ from pathlib import Path
36
36
  from typing import Any, Iterable, Iterator
37
37
 
38
38
  from ..world import KIND_API, KIND_HARBOR, KIND_MOCK_TOOLS, SCHEMA_MANIFEST_KIND, World
39
+ from .cast import EntityCasters
39
40
  from .compiler import bundle_mode, check_bundle, compile_bundle
40
41
  from .proof import SCRATCH_IGNORE, RowProof
41
42
  from .store import SQLiteStore
43
+ from .tree_import import refuse_unpublishable_journal
42
44
  from .validation import ContractError, digest, encoded, fail, journal_paths, read_json, validate
43
45
 
44
46
  MODES = ("append", "replace")
@@ -59,20 +61,33 @@ Rows = dict[str, list[dict]]
59
61
  # ---------------------------------------------------------------- rows files
60
62
 
61
63
 
62
- def parse_rows(paths: Iterable[str | Path], *, entity: str | None = None) -> Rows:
64
+ def parse_rows(
65
+ paths: Iterable[str | Path],
66
+ *,
67
+ entity: str | None = None,
68
+ delimiter: str | None = None,
69
+ casters: EntityCasters | None = None,
70
+ ) -> Rows:
63
71
  """Read rows from files into ``{entity: [row, …]}``.
64
72
 
65
73
  Each file is one of: a JSON object ``{"<entity>": [row, …]}``; JSONL where
66
74
  every line is ``{"entity": "<name>", "row": {…}}``; or — only with
67
- ``entity`` — a JSON array or JSONL of bare rows. Several files merge in
68
- order. A file that fits none of these is refused, naming the file. The
69
- files are streamed (:func:`batch.iter_rows`); this holds the result.
75
+ ``entity`` — a JSON array or JSONL of bare rows, or a ``.csv``/``.tsv`` whose
76
+ cells ``casters`` type by the entity's fields (:mod:`.cast`; text without them).
77
+ Several files merge in order. A file that fits none of these is refused, naming
78
+ the file. The files are streamed (:func:`batch.iter_rows`); this holds the result.
70
79
  """
71
80
  from .batch import iter_rows
72
81
 
73
82
  rows: Rows = {}
74
83
  seen: dict[str, int] = {}
75
- for name, row in iter_rows([str(path) for path in paths], entity=entity, seen=seen):
84
+ for name, row in iter_rows(
85
+ [str(path) for path in paths],
86
+ entity=entity,
87
+ seen=seen,
88
+ delimiter=delimiter,
89
+ casters=casters,
90
+ ):
76
91
  rows.setdefault(name, []).append(row)
77
92
  for name in seen:
78
93
  rows.setdefault(name, []) # an entity named with no rows: a replace empties it
@@ -299,6 +314,7 @@ def _import_schema(root: Path, rows: Rows, mode: str, batch_id: str | None) -> d
299
314
  }
300
315
  written = Path("data/initial.json")
301
316
  payload = (json.dumps(batch, sort_keys=True, indent=1) + "\n").encode("utf-8")
317
+ refuse_unpublishable_journal(root, written, payload)
302
318
  from .snapshot import build_default, default_snapshot, sidecar_path
303
319
 
304
320
  with tempfile.TemporaryDirectory(prefix="gateway-import-") as scratch:
@@ -27,6 +27,7 @@ from dataclasses import dataclass, field
27
27
  from pathlib import Path
28
28
  from typing import Any, Protocol
29
29
 
30
+ from ..world_session_contract import NO_GRADER_REASON
30
31
  from .tasks import evaluate_assertions
31
32
 
32
33
  GRADER_KINDS = ("assertions", "python", "rubric")
@@ -41,12 +42,14 @@ class GraderError(Exception):
41
42
  class Grade:
42
43
  """A task's grade: the scalar ``reward`` (None when ungraded) and every
43
44
  named dimension under ``rewards`` (nulls kept). ``pending`` is a grade the
44
- platform still owes (a rubric)."""
45
+ platform still owes (a rubric); ``reason`` says why a grade is null when
46
+ no grader ran at all (an exploratory session, a task without one)."""
45
47
 
46
48
  reward: float | None
47
49
  rewards: dict[str, float | None] = field(default_factory=dict)
48
50
  pending: bool = False
49
51
  grader: str | None = None
52
+ reason: str | None = None
50
53
 
51
54
  def as_dict(self) -> dict[str, Any]:
52
55
  """The wire shape ``grade`` answers with (and ``verify.py`` prints)."""
@@ -54,19 +57,30 @@ class Grade:
54
57
  if self.pending:
55
58
  out["pending"] = True
56
59
  out["grader"] = self.grader
60
+ if self.reason is not None:
61
+ out["reason"] = self.reason
57
62
  return out
58
63
 
59
64
  @staticmethod
60
- def of_rewards(printed: Mapping[str, Any]) -> "Grade":
65
+ def ungraded() -> Grade:
66
+ """The grade of a session with no grader: null, and it says so."""
67
+ return Grade(None, reason=NO_GRADER_REASON)
68
+
69
+ @staticmethod
70
+ def of_rewards(printed: Mapping[str, Any]) -> Grade:
61
71
  """The grade a verifier printed: the scalar under ``reward``, every
62
72
  other key a dimension (non-numeric ones null)."""
63
73
  return Grade(
64
74
  reward=_number(printed.get("reward")),
65
- rewards={key: _number(value) for key, value in printed.items() if key != "reward"},
75
+ rewards={
76
+ key: _number(value) for key, value in printed.items() if key != "reward"
77
+ },
66
78
  )
67
79
 
68
80
 
69
81
  def _number(value: Any) -> float | None:
82
+ """A score is a number; a boolean is the 1.0 / 0.0 it claims (the tracing
83
+ reward emitter's convention), anything else null."""
70
84
  if isinstance(value, (int, float)):
71
85
  return float(value)
72
86
  return None
@@ -91,7 +105,15 @@ class TaskGrader:
91
105
  ``grader`` is the spec's normalised ``grader`` table. A python grader's
92
106
  source must already be on disk at ``verify`` (the session's or the run's
93
107
  ``<task>/checks/verify.py``); a bundled scenario's ``verify.py`` is graded
94
- as a python grader with no table of its own."""
108
+ as a python grader with no table of its own.
109
+
110
+ A grader with a ``scope`` is a CROSS-WORLD VERIFIER: the same table, read
111
+ over several of a multi-world task's worlds at once. ``scope`` names the
112
+ aliases (the first is the session it runs on); :meth:`evidence` builds
113
+ the dump it grades, every scoped world's rows as ``<alias>.<entity>`` and
114
+ its calls as ``<alias>.calls`` — the naming a world's dependencies use, so
115
+ a check or a ``verify.py`` reads it unchanged. An unscoped grader's
116
+ evidence is the session's own state, untouched."""
95
117
 
96
118
  def __init__(
97
119
  self,
@@ -101,18 +123,63 @@ class TaskGrader:
101
123
  sandbox: VerifierSandbox | None = None,
102
124
  home: Path | None = None,
103
125
  default_timeout_s: float = VERIFY_TIMEOUT_S,
126
+ scope: Iterable[str] = (),
127
+ name: str | None = None,
104
128
  ) -> None:
105
129
  kind = grader.get("kind")
106
130
  if kind not in GRADER_KINDS:
107
- raise GraderError(f"unknown grader kind {kind!r}; a task grades by {', '.join(GRADER_KINDS)}")
131
+ raise GraderError(
132
+ f"unknown grader kind {kind!r}; a task grades by {', '.join(GRADER_KINDS)}"
133
+ )
108
134
  self.grader = dict(grader)
109
135
  self.kind: str = kind
110
136
  self.verify = verify
111
137
  self.sandbox = sandbox or VerifierSandbox()
112
138
  self.home = home
139
+ self.scope: tuple[str, ...] = tuple(scope)
140
+ self.name = name
113
141
  timeout = grader.get("timeoutSeconds")
114
142
  own = None if isinstance(timeout, bool) else _number(timeout)
115
- self.timeout_s = own if own is not None and own > 0 else float(default_timeout_s)
143
+ self.timeout_s = (
144
+ own if own is not None and own > 0 else float(default_timeout_s)
145
+ )
146
+
147
+ @property
148
+ def anchor(self) -> str | None:
149
+ """The alias whose session runs a scoped grader; None when unscoped."""
150
+ return self.scope[0] if self.scope else None
151
+
152
+ def evidence(self, own: Mapping[str, Any], context: Mapping[str, Mapping[str, Any]]) -> dict:
153
+ """The dump this grader reads. Unscoped: ``own`` as it is. Scoped:
154
+ every scoped world's state under ``<alias>.<key>`` — the anchor's from
155
+ ``own``, the others from ``context`` (``{alias: state}``, what the
156
+ platform gathered from those sessions) — with the agent's ``report``
157
+ kept at the top. A scoped alias ``context`` lacks, or a check over an
158
+ entity no scoped world holds, is a :class:`GraderError`: ungraded with
159
+ the reason, never zero."""
160
+ if not self.scope:
161
+ return dict(own)
162
+ missing = [alias for alias in self.scope[1:] if alias not in context]
163
+ if missing:
164
+ raise GraderError(
165
+ f"no evidence for {', '.join(missing)}: not named on the grade (worlds: {{alias: sessionId}}), "
166
+ "or no longer a live session of this task"
167
+ )
168
+ states = {self.anchor: own, **{alias: context[alias] for alias in self.scope[1:]}}
169
+ dump: dict[str, Any] = {}
170
+ for alias in self.scope:
171
+ dump.update({f"{alias}.{key}": value for key, value in states[alias].items() if key != "report"})
172
+ if "report" in own:
173
+ dump["report"] = own["report"]
174
+ # No world's contract vets a cross-world check's entity (a session knows
175
+ # only its own), and a check over a key the dump lacks selects nothing —
176
+ # which `absent` and `count: eq 0` would pass on a typo.
177
+ unknown = [check["entity"] for check in self.grader.get("checks", ()) if check["entity"] not in dump]
178
+ if unknown:
179
+ raise GraderError(
180
+ f"no scoped world's evidence holds {', '.join(unknown)}; the evidence holds {', '.join(sorted(dump))}"
181
+ )
182
+ return dump
116
183
 
117
184
  @staticmethod
118
185
  def for_verifier(
@@ -121,9 +188,15 @@ class TaskGrader:
121
188
  sandbox: VerifierSandbox | None = None,
122
189
  home: Path | None = None,
123
190
  timeout_s: float = VERIFY_TIMEOUT_S,
124
- ) -> "TaskGrader":
191
+ ) -> TaskGrader:
125
192
  """A bundled scenario's ``verify.py``: a python grader with the host's timeout."""
126
- return TaskGrader({"kind": "python"}, verify=verify, sandbox=sandbox, home=home, default_timeout_s=timeout_s)
193
+ return TaskGrader(
194
+ {"kind": "python"},
195
+ verify=verify,
196
+ sandbox=sandbox,
197
+ home=home,
198
+ default_timeout_s=timeout_s,
199
+ )
127
200
 
128
201
  @property
129
202
  def pending(self) -> bool:
@@ -163,20 +236,27 @@ class TaskGrader:
163
236
  env=self.sandbox.environment(home),
164
237
  )
165
238
  except subprocess.TimeoutExpired:
166
- raise GraderError(f"verify.py timed out after {self.timeout_s:g}s") from None
239
+ raise GraderError(
240
+ f"verify.py timed out after {self.timeout_s:g}s"
241
+ ) from None
167
242
  if proc.returncode != 0:
168
- raise GraderError(f"verify.py exited {proc.returncode}: {proc.stderr.strip()[-800:]}")
243
+ raise GraderError(
244
+ f"verify.py exited {proc.returncode}: {proc.stderr.strip()[-800:]}"
245
+ )
169
246
  try:
170
247
  printed = json.loads(proc.stdout.strip().splitlines()[-1])
171
248
  except (json.JSONDecodeError, IndexError):
172
- raise GraderError(f"verify.py printed no rewards JSON: {proc.stdout.strip()[-400:]}") from None
249
+ raise GraderError(
250
+ f"verify.py printed no rewards JSON: {proc.stdout.strip()[-400:]}"
251
+ ) from None
173
252
  if not isinstance(printed, dict):
174
253
  raise GraderError("verify.py rewards output is not an object")
175
254
  return Grade.of_rewards(printed)
176
255
 
177
256
 
178
257
  def keyed_entities(
179
- entities: Mapping[str, Mapping[str, Any]], rows_of: Callable[[str], Iterable[Mapping[str, Any]]]
258
+ entities: Mapping[str, Mapping[str, Any]],
259
+ rows_of: Callable[[str], Iterable[Mapping[str, Any]]],
180
260
  ) -> dict:
181
261
  """A world's rows the way a grader reads them: every contract entity by
182
262
  name, its rows keyed by their primary key (``a:b`` for a composite key) —
@@ -202,7 +282,9 @@ class StoredWorld(Protocol):
202
282
  def store(self) -> Any: ...
203
283
 
204
284
 
205
- def world_state(root: StoredWorld | None, dependencies: Mapping[str, StoredWorld]) -> dict:
285
+ def world_state(
286
+ root: StoredWorld | None, dependencies: Mapping[str, StoredWorld]
287
+ ) -> dict:
206
288
  """The rows as a task's grader reads them, on the host and in the batch
207
289
  runner alike: the root's entities by name and each dependency's as
208
290
  ``<alias>.<entity>``, every entity's rows keyed by primary key — the api
@@ -0,0 +1,44 @@
1
+ """What a failing handler answers — structured, classified, never a bare string.
2
+
3
+ A tool call that raises inside ``tools/handlers.py`` is answered like the
4
+ HTTP twin of the tool would answer:
5
+
6
+ * ``AttributeError`` / ``TypeError`` / ``NameError`` are the author's bug
7
+ (``store.upsert`` on a store with no ``upsert``, a misspelled name, a
8
+ wrong argument shape) — status **400**, ``error: "handler"``.
9
+ * Anything else is a failure inside the handler's own logic — status **500**,
10
+ ``error: "engine"``.
11
+
12
+ Both carry ``detail`` (one line, bounded) and ``handler`` (the tool's local
13
+ name) so the caller knows which handler to fix without reading a trace.
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ #: The exception classes that mark a handler bug rather than a runtime failure.
19
+ HANDLER_BUG_ERRORS: tuple[type[BaseException], ...] = (
20
+ AttributeError,
21
+ TypeError,
22
+ NameError,
23
+ )
24
+
25
+ _DETAIL_LIMIT = 2000
26
+
27
+
28
+ def _detail(error: BaseException) -> str:
29
+ text = str(error).strip() or type(error).__name__
30
+ return text[:_DETAIL_LIMIT]
31
+
32
+
33
+ def handler_bug_body(handler: str, error: BaseException) -> dict:
34
+ """The 400 body for a handler-authored bug."""
35
+ return {"error": "handler", "detail": _detail(error), "handler": handler}
36
+
37
+
38
+ def engine_failure_body(handler: str, error: BaseException) -> dict:
39
+ """The 500 body for a failure inside the handler that is not a coding bug."""
40
+ return {
41
+ "error": "engine",
42
+ "detail": f"{type(error).__name__}: {_detail(error)}"[:_DETAIL_LIMIT],
43
+ "handler": handler,
44
+ }