@withgateway/sdk 0.6.0 → 0.9.3

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 (150) hide show
  1. package/dist/agents/index.d.mts +581 -0
  2. package/dist/agents/index.d.ts +581 -0
  3. package/dist/agents/index.js +1473 -0
  4. package/dist/agents/index.js.map +1 -0
  5. package/dist/agents/index.mjs +1424 -0
  6. package/dist/agents/index.mjs.map +1 -0
  7. package/dist/apiError-DHpfbmdx.d.mts +17 -0
  8. package/dist/apiError-DHpfbmdx.d.ts +17 -0
  9. package/dist/cli.js +11611 -6845
  10. package/dist/cli.js.map +1 -1
  11. package/dist/cli.mjs +10090 -5325
  12. package/dist/cli.mjs.map +1 -1
  13. package/dist/files/index.d.mts +3 -1
  14. package/dist/files/index.d.ts +3 -1
  15. package/dist/files/index.js +371 -102
  16. package/dist/files/index.js.map +1 -1
  17. package/dist/files/index.mjs +371 -102
  18. package/dist/files/index.mjs.map +1 -1
  19. package/dist/hooks/index.js +346 -136
  20. package/dist/hooks/index.js.map +1 -1
  21. package/dist/hooks/index.mjs +346 -136
  22. package/dist/hooks/index.mjs.map +1 -1
  23. package/dist/{index-LA-PMRJT.d.ts → index-DIN14Lhg.d.ts} +1 -1
  24. package/dist/{index-Di9nNqOY.d.mts → index-DuB-eQ0Z.d.mts} +1 -1
  25. package/dist/index.d.mts +7 -4
  26. package/dist/index.d.ts +7 -4
  27. package/dist/index.js +3177 -748
  28. package/dist/index.js.map +1 -1
  29. package/dist/index.mjs +2987 -590
  30. package/dist/index.mjs.map +1 -1
  31. package/dist/media-CQUC7TkS.d.mts +39 -0
  32. package/dist/media-DQnBloaX.d.ts +39 -0
  33. package/dist/traces/index.d.mts +3 -1
  34. package/dist/traces/index.d.ts +3 -1
  35. package/dist/traces/index.js +371 -102
  36. package/dist/traces/index.js.map +1 -1
  37. package/dist/traces/index.mjs +371 -102
  38. package/dist/traces/index.mjs.map +1 -1
  39. package/dist/tracing/index.d.mts +3 -2
  40. package/dist/tracing/index.d.ts +3 -2
  41. package/dist/tracing/index.js +257 -16
  42. package/dist/tracing/index.js.map +1 -1
  43. package/dist/tracing/index.mjs +257 -16
  44. package/dist/tracing/index.mjs.map +1 -1
  45. package/dist/transport-CpRe7zgd.d.mts +123 -0
  46. package/dist/transport-CpRe7zgd.d.ts +123 -0
  47. package/dist/worlds/index.d.mts +1986 -1746
  48. package/dist/worlds/index.d.ts +1986 -1746
  49. package/dist/worlds/index.js +1470 -290
  50. package/dist/worlds/index.js.map +1 -1
  51. package/dist/worlds/index.mjs +1465 -286
  52. package/dist/worlds/index.mjs.map +1 -1
  53. package/package.json +6 -1
  54. package/runtime/gatewaysdk/environment/bundle_manifest.py +531 -0
  55. package/runtime/gatewaysdk/environment/factory_documents.py +670 -0
  56. package/runtime/gatewaysdk/environment/factory_rules.py +973 -0
  57. package/runtime/gatewaysdk/environment/factory_shapes.py +253 -0
  58. package/runtime/gatewaysdk/environment/factory_spine.py +1155 -0
  59. package/runtime/gatewaysdk/environment/factory_spine_shapes.py +480 -0
  60. package/runtime/gatewaysdk/environment/schema/__main__.py +2 -2
  61. package/runtime/gatewaysdk/environment/schema/_slack_fidelity.py +8 -23
  62. package/runtime/gatewaysdk/environment/schema/admission.py +61 -59
  63. package/runtime/gatewaysdk/environment/schema/api.py +3 -4
  64. package/runtime/gatewaysdk/environment/schema/assertions.py +7 -1
  65. package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +1 -0
  66. package/runtime/gatewaysdk/environment/schema/call_log.py +20 -0
  67. package/runtime/gatewaysdk/environment/schema/cast.py +133 -67
  68. package/runtime/gatewaysdk/environment/schema/compiler.py +16 -17
  69. package/runtime/gatewaysdk/environment/schema/database/base.py +2 -2
  70. package/runtime/gatewaysdk/environment/schema/handler_errors.py +58 -4
  71. package/runtime/gatewaysdk/environment/schema/host.py +94 -12
  72. package/runtime/gatewaysdk/environment/schema/host_browser.py +48 -0
  73. package/runtime/gatewaysdk/environment/schema/host_control.py +35 -2
  74. package/runtime/gatewaysdk/environment/schema/host_handoff.py +4 -1
  75. package/runtime/gatewaysdk/environment/schema/host_loops.py +27 -4
  76. package/runtime/gatewaysdk/environment/schema/host_metrics.py +69 -0
  77. package/runtime/gatewaysdk/environment/schema/host_requests.py +35 -0
  78. package/runtime/gatewaysdk/environment/schema/host_session.py +20 -2
  79. package/runtime/gatewaysdk/environment/schema/host_surfaces.py +6 -0
  80. package/runtime/gatewaysdk/environment/schema/host_versions.py +100 -19
  81. package/runtime/gatewaysdk/environment/schema/host_workers.py +172 -50
  82. package/runtime/gatewaysdk/environment/schema/ingest.py +12 -3
  83. package/runtime/gatewaysdk/environment/schema/journal.py +7 -2
  84. package/runtime/gatewaysdk/environment/schema/local.py +32 -7
  85. package/runtime/gatewaysdk/environment/schema/mapping.py +1 -1
  86. package/runtime/gatewaysdk/environment/schema/measured_tests.py +187 -0
  87. package/runtime/gatewaysdk/environment/schema/page_checks.py +123 -0
  88. package/runtime/gatewaysdk/environment/schema/platform.py +80 -270
  89. package/runtime/gatewaysdk/environment/schema/platform_query.py +4 -3
  90. package/runtime/gatewaysdk/environment/schema/platform_templates.py +420 -0
  91. package/runtime/gatewaysdk/environment/schema/process_memory.py +76 -0
  92. package/runtime/gatewaysdk/environment/schema/redaction.py +13 -0
  93. package/runtime/gatewaysdk/environment/schema/request_ledger.py +4 -1
  94. package/runtime/gatewaysdk/environment/schema/run_parameters.py +25 -0
  95. package/runtime/gatewaysdk/environment/schema/runtime.py +57 -5
  96. package/runtime/gatewaysdk/environment/schema/scaffold.py +386 -219
  97. package/runtime/gatewaysdk/environment/schema/session_files.py +13 -2
  98. package/runtime/gatewaysdk/environment/schema/shape_catalog.py +493 -0
  99. package/runtime/gatewaysdk/environment/schema/shape_declarations.py +219 -0
  100. package/runtime/gatewaysdk/environment/schema/skill.py +1 -0
  101. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +1 -1
  102. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +2 -2
  103. package/runtime/gatewaysdk/environment/schema/skills/factory-orchestrator/SKILL.md +147 -0
  104. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +5 -1
  105. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +8 -6
  106. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +9 -9
  107. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +33 -2
  108. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +6 -6
  109. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +17 -2
  110. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/new-world-sandbox.md +1 -1
  111. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/shape-catalog.md +59 -0
  112. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/ui-map.md +3 -2
  113. package/runtime/gatewaysdk/environment/schema/slack.py +55 -10
  114. package/runtime/gatewaysdk/environment/schema/snapshot.py +28 -2
  115. package/runtime/gatewaysdk/environment/schema/tasks.py +25 -2
  116. package/runtime/gatewaysdk/environment/schema/template_record.py +131 -0
  117. package/runtime/gatewaysdk/environment/schema/tools_world.py +7 -5
  118. package/runtime/gatewaysdk/environment/schema/ui.py +54 -33
  119. package/runtime/gatewaysdk/environment/schema/ui_interactions.py +419 -0
  120. package/runtime/gatewaysdk/environment/schema/ui_recorder.js +895 -0
  121. package/runtime/gatewaysdk/environment/schema/ui_replay.py +366 -0
  122. package/runtime/gatewaysdk/environment/schema/ui_replay_record.LICENSE +25 -0
  123. package/runtime/gatewaysdk/environment/schema/ui_replay_record.js +109 -0
  124. package/runtime/gatewaysdk/environment/schema/validation.py +24 -1
  125. package/runtime/gatewaysdk/environment/schema/worker.py +12 -5
  126. package/runtime/gatewaysdk/environment/schema/worker_key.py +38 -0
  127. package/runtime/gatewaysdk/environment/schema/worker_peaks.py +38 -0
  128. package/runtime/gatewaysdk/environment/schema/worker_watch.py +50 -0
  129. package/runtime/gatewaysdk/environment/schema/workers.py +245 -69
  130. package/runtime/gatewaysdk/environment/schema/world_host.py +96 -73
  131. package/runtime/gatewaysdk/environment/schema/world_tests.py +3 -1
  132. package/runtime/gatewaysdk/environment/secret_values.py +1 -1
  133. package/runtime/gatewaysdk/environment/world.py +34 -43
  134. package/runtime/gatewaysdk/environment/world_session_contract.py +7 -34
  135. package/skills/benchmarks-getting-started/SKILL.md +1 -1
  136. package/skills/connector-schema-authoring/SKILL.md +2 -2
  137. package/skills/connector-schema-authoring/connector-worlds.md +3 -2
  138. package/skills/connector-schema-authoring/world-schema.md +36 -23
  139. package/skills/factory-orchestrator/SKILL.md +147 -0
  140. package/skills/world-data-ingestion/ROWS.md +5 -1
  141. package/skills/world-data-ingestion/SKILL.md +8 -6
  142. package/skills/worlds-getting-started/SKILL.md +9 -9
  143. package/skills/worlds-getting-started/references/cli-mcp-map.md +33 -2
  144. package/skills/worlds-getting-started/references/gotchas.md +6 -6
  145. package/skills/worlds-getting-started/references/journal-checks.md +17 -2
  146. package/skills/worlds-getting-started/references/new-world-sandbox.md +1 -1
  147. package/skills/worlds-getting-started/references/shape-catalog.md +59 -0
  148. package/skills/worlds-getting-started/references/ui-map.md +3 -2
  149. package/dist/media-BIApiPzS.d.mts +0 -102
  150. package/dist/media-BIApiPzS.d.ts +0 -102
@@ -1,14 +1,16 @@
1
- """``Admission``: how many requests run on one version at once, and how many wait.
2
-
3
- Every session of a version is served by one process (its version worker, or the
4
- host itself for a world with no code of its own), so a burst on a version is a
5
- burst on that process. The host admits a version's requests a few at a time and
6
- one per session (a session's store answers one request at a time anyway); the
7
- rest wait their turn in the order they came, up to a bound. A request past the
8
- bound, or one whose turn did not come in time, is refused ``busy`` with when to
9
- come back, so a burst queues or is told to retry and the process never holds
10
- more requests than it has room for. A request held outside the queue (its session moving to
11
- another host) is counted against the same bounds (:meth:`Admission.waiting`).
1
+ """``Admission``: how many requests run on one worker key at once, and how many wait.
2
+
3
+ Every session of a :class:`WorkerKey` (a version's main, or its world states) is
4
+ served by one process (its version worker, or the host itself for a world with
5
+ no code of its own), so a burst on a key is a burst on that process. The host
6
+ admits a key's requests a few at a time and one per session (a session's store
7
+ answers one request at a time anyway); the rest wait their turn in the order
8
+ they came, up to a bound. A request past the bound, or one whose turn did not
9
+ come in time, is refused ``busy`` with when to come back, so a burst queues or
10
+ is told to retry and the process never holds more requests than it has room
11
+ for, and a version's states never take main's turns. A request held outside the
12
+ queue (its session moving to another host) is counted against the same bounds
13
+ (:meth:`Admission.waiting`).
12
14
  """
13
15
 
14
16
  from __future__ import annotations
@@ -25,7 +27,7 @@ from .validation import fail
25
27
  VERSION_SLOTS = 8
26
28
  SESSION_SLOTS = 1
27
29
  QUEUE_DEPTH = 256
28
- #: A session's own share of the waiting, so one session's burst cannot fill its version's queue.
30
+ #: A session's own share of the waiting, so one session's burst cannot fill its key's queue.
29
31
  SESSION_QUEUE_DEPTH = 32
30
32
  #: With a call's own budget it stays under the platform's 60 s (``conformance/world-sessions.json``).
31
33
  QUEUE_WAIT_S = 10.0
@@ -41,14 +43,14 @@ def _less(counter: Counter, key: object) -> None:
41
43
 
42
44
  @dataclass(eq=False)
43
45
  class _Turn:
44
- version: str
46
+ key: str
45
47
  session: str
46
48
  started: float | None = None
47
49
 
48
50
 
49
51
  class Admission:
50
- """Turns on each version, first come first served within the version's and
51
- each session's slots; another version never waits."""
52
+ """Turns on each key, first come first served within the key's and
53
+ each session's slots; another key never waits."""
52
54
 
53
55
  def __init__(
54
56
  self,
@@ -75,34 +77,34 @@ class Admission:
75
77
  self._outside_by: Counter[tuple[str, str]] = Counter()
76
78
 
77
79
  @contextmanager
78
- def turn(self, version: str, session: str) -> Iterator[None]:
79
- """Hold one of ``version``'s slots for ``session`` while the block runs; refused
80
+ def turn(self, key: str, session: str) -> Iterator[None]:
81
+ """Hold one of ``key``'s slots for ``session`` while the block runs; refused
80
82
  ``busy`` (a :class:`ContractError` carrying ``retryAfter``) when none comes."""
81
- turn = self._enter(_Turn(version, session))
83
+ turn = self._enter(_Turn(key, session))
82
84
  try:
83
85
  yield
84
86
  finally:
85
87
  self._leave(turn)
86
88
 
87
89
  @contextmanager
88
- def waiting(self, version: str, session: str) -> Iterator[None]:
89
- """Count a request waiting outside the queue against ``version``'s and ``session``'s waiting
90
+ def waiting(self, key: str, session: str) -> Iterator[None]:
91
+ """Count a request waiting outside the queue against ``key``'s and ``session``'s waiting
90
92
  bounds while the block runs; refused ``busy`` past them, as a queued request would be."""
91
93
  with self._lock:
92
- self._outside[version] += 1
93
- self._outside_by[(version, session)] += 1
94
- if self._overfull(version, session):
95
- self._unwait(version, session)
96
- self._refuse(version, "too many requests are waiting")
94
+ self._outside[key] += 1
95
+ self._outside_by[(key, session)] += 1
96
+ if self._overfull(key, session):
97
+ self._unwait(key, session)
98
+ self._refuse(key, "too many requests are waiting")
97
99
  try:
98
100
  yield
99
101
  finally:
100
102
  with self._lock:
101
- self._unwait(version, session)
103
+ self._unwait(key, session)
102
104
 
103
- def _unwait(self, version: str, session: str) -> None:
104
- _less(self._outside, version)
105
- _less(self._outside_by, (version, session))
105
+ def _unwait(self, key: str, session: str) -> None:
106
+ _less(self._outside, key)
107
+ _less(self._outside_by, (key, session))
106
108
 
107
109
  def held_ages(self) -> dict[str, float]:
108
110
  """Each session holding a turn now, with how long its oldest has run, in seconds."""
@@ -116,57 +118,57 @@ class Admission:
116
118
 
117
119
  def _enter(self, turn: _Turn) -> _Turn:
118
120
  with self._lock:
119
- queue = self._waiting.setdefault(turn.version, deque())
121
+ queue = self._waiting.setdefault(turn.key, deque())
120
122
  queue.append(turn)
121
- self._admit(turn.version)
122
- if turn.started is None and self._overfull(turn.version, turn.session):
123
+ self._admit(turn.key)
124
+ if turn.started is None and self._overfull(turn.key, turn.session):
123
125
  queue.remove(turn)
124
- self._refuse(turn.version, f"{len(queue)} requests are waiting")
126
+ self._refuse(turn.key, f"{len(queue)} requests are waiting")
125
127
  deadline = time.monotonic() + self.wait_s
126
128
  while turn.started is None:
127
129
  left = deadline - time.monotonic()
128
130
  if left <= 0:
129
131
  queue.remove(turn)
130
- self._refuse(turn.version, f"no turn came within {self.wait_s:g} s")
132
+ self._refuse(turn.key, f"no turn came within {self.wait_s:g} s")
131
133
  self._changed.wait(left)
132
134
  return turn
133
135
 
134
- def _overfull(self, version: str, session: str) -> bool:
135
- queue = self._waiting.get(version, deque())
136
- mine = sum(waiting.session == session for waiting in queue) + self._outside_by[(version, session)]
137
- return len(queue) + self._outside[version] > self.queue or mine > self.session_queue
136
+ def _overfull(self, key: str, session: str) -> bool:
137
+ queue = self._waiting.get(key, deque())
138
+ mine = sum(waiting.session == session for waiting in queue) + self._outside_by[(key, session)]
139
+ return len(queue) + self._outside[key] > self.queue or mine > self.session_queue
138
140
 
139
141
  def _leave(self, turn: _Turn) -> None:
140
142
  with self._lock:
141
- key = (turn.version, turn.session)
142
- self._holding[key].remove(turn)
143
- if not self._holding[key]:
144
- del self._holding[key]
145
- self._running[turn.version] -= 1
146
- if self._running[turn.version] <= 0:
147
- del self._running[turn.version]
148
- self._admit(turn.version)
149
- self._forget(turn.version)
150
-
151
- def _admit(self, version: str) -> None:
143
+ held = (turn.key, turn.session)
144
+ self._holding[held].remove(turn)
145
+ if not self._holding[held]:
146
+ del self._holding[held]
147
+ self._running[turn.key] -= 1
148
+ if self._running[turn.key] <= 0:
149
+ del self._running[turn.key]
150
+ self._admit(turn.key)
151
+ self._forget(turn.key)
152
+
153
+ def _admit(self, key: str) -> None:
152
154
  """Under the lock: give free slots to the earliest waiters whose session has room."""
153
- queue = self._waiting.get(version, deque())
155
+ queue = self._waiting.get(key, deque())
154
156
  for waiting in list(queue):
155
- if self._running[version] >= self.slots:
157
+ if self._running[key] >= self.slots:
156
158
  break
157
- if len(self._holding.get((version, waiting.session), ())) < self.per_session:
159
+ if len(self._holding.get((key, waiting.session), ())) < self.per_session:
158
160
  queue.remove(waiting)
159
161
  waiting.started = time.monotonic()
160
- self._running[version] += 1
161
- self._holding.setdefault((version, waiting.session), []).append(waiting)
162
+ self._running[key] += 1
163
+ self._holding.setdefault((key, waiting.session), []).append(waiting)
162
164
  self._changed.notify_all()
163
165
 
164
- def _forget(self, version: str) -> None:
165
- if not self._waiting.get(version) and not self._running[version]:
166
- self._waiting.pop(version, None)
166
+ def _forget(self, key: str) -> None:
167
+ if not self._waiting.get(key) and not self._running[key]:
168
+ self._waiting.pop(key, None)
167
169
 
168
- def _refuse(self, version: str, why: str) -> None:
169
- self._forget(version)
170
+ def _refuse(self, key: str, why: str) -> None:
171
+ self._forget(key)
170
172
  fail(
171
173
  BUSY,
172
174
  f"this world's version is busy ({why}); retry after {self.retry_after_s} s",
@@ -131,6 +131,7 @@ from .handler_errors import handled_answer, handler_bug_body, log_contract_refus
131
131
  from .primary_key import PrimaryKey
132
132
  from .request_body import RequestBody, Upload, json_value
133
133
  from .route_miss import RouteMiss, served_methods
134
+ from .ui import checked_api_path
134
135
  from .validation import ContractError, fail, read_json
135
136
 
136
137
  EVENT_LOG_SIZE = 500
@@ -435,10 +436,8 @@ def _ui_settings(raw: dict, world: Path) -> UiSettings | None:
435
436
  entry = ui.get("entry", "/")
436
437
  if not isinstance(entry, str) or not entry.startswith("/"):
437
438
  fail("spec", "ui.entry is the path the agent lands on, starting with /", "/ui/entry")
438
- api_path = ui.get("api_path", "/__world-api")
439
- if not isinstance(api_path, str) or not api_path.startswith("/") or api_path == "/":
440
- fail("spec", "ui.api_path is the same-origin prefix the ui calls the api at", "/ui/api_path")
441
- return UiSettings(static=static.rstrip("/"), entry=entry, api_path=api_path.rstrip("/"))
439
+ api_path = checked_api_path(ui.get("api_path", "/__world-api"))
440
+ return UiSettings(static=static.rstrip("/"), entry=entry, api_path=api_path)
442
441
 
443
442
 
444
443
  def load_api_settings(world: Path, spec: Spec) -> ApiSettings:
@@ -10,6 +10,7 @@ from dataclasses import dataclass
10
10
  from typing import Any, Mapping
11
11
 
12
12
  from .journal import NOT_RECORDED
13
+ from .page_checks import PageCheck, PageReport, page_rows
13
14
  from .tasks import (
14
15
  CALL_LOG,
15
16
  DOOR_FIELD,
@@ -302,7 +303,12 @@ class Selection(ABC):
302
303
  entity = check["entity"]
303
304
  meta = _journal_meta(state, entity)
304
305
  kind = KINDS[(_log_of(entity), meta is not None)]
305
- return kind.read(check, state, meta)
306
+ selection = kind.read(check, state, meta)
307
+ refusal = PageReport.of(state, entity).refusal() if PageCheck(check).names_the_page else None
308
+ if refusal is not None:
309
+ raise GraderError(refusal)
310
+ selection.rows = page_rows(check, selection.rows)
311
+ return selection
306
312
 
307
313
  @classmethod
308
314
  @abstractmethod
@@ -10,6 +10,7 @@ ENVIRONMENT_PACKAGE = SCHEMA_PACKAGE.parent
10
10
  SIBLING_MODULES = (
11
11
  "_toml.py",
12
12
  "backing.py",
13
+ "bundle_manifest.py",
13
14
  "errors.py",
14
15
  "legacy_sqlite.py",
15
16
  "reward_keys.py",
@@ -34,6 +34,7 @@ LINE_BOUNDS = {"method": METHOD_CHARS, "operation": OPERATION_CHARS, "path": PAT
34
34
  DEFAULT_CALL_LOG_MAX = 5000
35
35
  DEFAULT_CALL_LOG_VALUES = 200_000
36
36
  DEFAULT_CALL_LOG_CHARS = 8 << 20
37
+ INTERACTION_STATUS = 204
37
38
  WITHHELD_ROUTE = {
38
39
  "args": REDACTED,
39
40
  "query": {},
@@ -133,6 +134,7 @@ class Via(StrEnum):
133
134
  UI = "ui"
134
135
  TOOL = "tool"
135
136
  WEBHOOK = "webhook"
137
+ PAGE = "page"
136
138
 
137
139
 
138
140
  @dataclass(frozen=True)
@@ -428,6 +430,24 @@ class CallLog:
428
430
  request, budget = dict(WITHHELD_TOOL), RequestBudget()
429
431
  self._append({**heading, **request, "via": str(Via.TOOL)}, answered, budget)
430
432
 
433
+ def record_interaction(self, operation: str, page: str, summary: dict, detail: dict, graded: bool = True) -> None:
434
+ """One interaction on a UI world's page (:mod:`.ui_interactions`): a ``via`` page call named
435
+ ``operation`` at ``page`` with no method, ``summary`` as its query and ``detail`` as what was
436
+ asked, kept by the request ledger and, ``graded``, by the grader's log."""
437
+ secret = self.redaction.secret
438
+ heading = {"operation": operation, "method": None, "path": self.redaction.raw_path(page, secret)}
439
+ query = self.redaction.value(summary)
440
+ answered = _answered(INTERACTION_STATUS, None, 0.0)
441
+ exchange = partial(Exchange.of_tool, detail, INTERACTION_STATUS, None, self.redaction)
442
+ self._send({**heading, "query": query, "via": str(Via.PAGE)}, answered, exchange)
443
+ if self.maximum == 0 or not graded:
444
+ return
445
+ try:
446
+ request, budget = self._tool_request(detail)
447
+ except (RecursionError, RequestTooLarge):
448
+ request, budget = dict(WITHHELD_TOOL), RequestBudget()
449
+ self._append({**heading, **request, "query": query, "via": str(Via.PAGE)}, answered, budget)
450
+
431
451
  def record_webhooks(self, deliveries: Iterable[Delivery]) -> None:
432
452
  """Each delivery the world sent, kept by the request ledger with ``via`` webhook and no
433
453
  answer yet (status 0); the grader's call log keeps only what the agent called."""
@@ -23,6 +23,8 @@ from dataclasses import dataclass
23
23
  from pathlib import Path
24
24
  from typing import Any
25
25
 
26
+ from .validation import local_key
27
+
26
28
  INTEGER_TEXT = re.compile(r"^[+-]?\d+$")
27
29
  NUMBER_TEXT = re.compile(r"^[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?$")
28
30
  BOOLEANS = {"true": True, "false": False, "1": True, "0": False}
@@ -33,19 +35,23 @@ _MISSING = object()
33
35
 
34
36
  @dataclass(frozen=True)
35
37
  class FieldType:
36
- """One field as ``gateway worlds describe`` reports it: ``type`` is the JSON Schema
37
- type word(s) joined by ``" | "``, a ``$ref`` name, or None when the schema says nothing;
38
- ``enum`` the values the schema allows, when it lists them."""
38
+ """One field as ``gateway worlds describe`` reports it: ``type`` is the JSON Schema type
39
+ words the field admits, through references and unions, joined by ``" | "``, or None when the
40
+ schema says nothing; ``enum`` the values it allows, when it lists every one; ``format`` the
41
+ schema's ``format`` (``date-time``, ``email``, ...), when it names one."""
39
42
 
40
43
  name: str
41
44
  type: str | None
42
45
  required: bool
43
46
  enum: tuple | None = None
47
+ format: str | None = None
44
48
 
45
49
  def describe(self) -> dict:
46
50
  described: dict = {"name": self.name, "type": self.type, "required": self.required}
47
51
  if self.enum is not None:
48
52
  described["enum"] = list(self.enum)
53
+ if self.format is not None:
54
+ described["format"] = self.format
49
55
  return described
50
56
 
51
57
 
@@ -160,87 +166,147 @@ def casters_of(entities: dict[str, list[FieldType]]) -> EntityCasters:
160
166
  return by_name.get
161
167
 
162
168
 
163
- def _definition(world: dict, entity: Any) -> dict:
164
- schema = entity.get("schema") if isinstance(entity, dict) else None
165
- ref = schema.get("$ref") if isinstance(schema, dict) else None
166
- if isinstance(ref, str) and ref.startswith("#/$defs/"):
167
- definition = (world.get("$defs") or {}).get(ref[len("#/$defs/") :])
168
- return definition if isinstance(definition, dict) else {}
169
- if isinstance(schema, dict) and isinstance(schema.get("properties"), dict):
170
- return schema
171
- return {}
169
+ Resolve = Callable[[Any, frozenset], tuple[dict, frozenset]]
170
+ UNFOLLOWED = "$ref"
171
+
172
+
173
+ def unresolved(schema: Any, seen: frozenset) -> tuple[dict, frozenset]:
174
+ return (schema if isinstance(schema, dict) else {}), seen
175
+
176
+
177
+ class LocalDefinitions:
178
+ """Follows ``#/$defs/<key>`` references into ``defs``; ``seen`` carries the keys on the path,
179
+ so a cycle through compositions ends."""
180
+
181
+ def __init__(self, defs: Any):
182
+ self.defs = defs if isinstance(defs, dict) else {}
183
+
184
+ def __call__(self, schema: Any, seen: frozenset = frozenset()) -> tuple[dict, frozenset]:
185
+ while isinstance(schema, dict):
186
+ key = local_key(schema.get("$ref"))
187
+ if key is None or key in seen or not isinstance(self.defs.get(key), dict):
188
+ break
189
+ seen = seen | {key}
190
+ schema = self.defs[key]
191
+ return unresolved(schema, seen)
192
+
193
+
194
+ def schema_types(schema: Any, resolve: Resolve = unresolved, seen: frozenset = frozenset()) -> tuple[str, ...]:
195
+ """The JSON type words a schema admits, in the order it declares them, through references
196
+ and ``anyOf`` / ``oneOf`` / ``allOf``; :data:`UNFOLLOWED` for a reference ``resolve`` cannot follow
197
+ that carries no ``type`` of its own (a shared compile keeps the target's ``type`` beside its ``$ref``)."""
198
+ node, seen = resolve(schema, seen)
199
+ if isinstance(node.get("$ref"), str) and local_key(node["$ref"]) not in seen and "type" not in node:
200
+ return (UNFOLLOWED,)
201
+ kind = node.get("type")
202
+ found = [kind] if isinstance(kind, str) else [part for part in kind or [] if isinstance(part, str)]
203
+ for key in ("anyOf", "oneOf", "allOf"):
204
+ for branch in node.get(key) or []:
205
+ found += schema_types(branch, resolve, seen)
206
+ return tuple(dict.fromkeys(found))
207
+
208
+
209
+ def allowed_values(
210
+ schema: Any, resolve: Resolve = unresolved, seen: frozenset = frozenset()
211
+ ) -> tuple[list, list[dict]] | None:
212
+ """The values a schema allows when it lists every one (``enum``, ``const``, a ``oneOf`` /
213
+ ``anyOf`` of those with a ``null`` branch allowing None, or the values every listing ``allOf``
214
+ branch shares), with each labelled ``const``'s ``title``; None when it also admits values it
215
+ does not list."""
216
+ node, seen = resolve(schema, seen)
217
+ if isinstance(node.get("enum"), list):
218
+ return list(node["enum"]), []
219
+ if "const" in node:
220
+ label = node.get("title")
221
+ return [node["const"]], ([{"value": node["const"], "label": label}] if isinstance(label, str) else [])
222
+ if node.get("allOf") and not (node.get("oneOf") or node.get("anyOf")):
223
+ return _shared_values(node["allOf"], resolve, seen)
224
+ branches = node.get("oneOf") or node.get("anyOf")
225
+ if not isinstance(branches, list) or not branches:
226
+ return None
227
+ values: list = []
228
+ labels: list[dict] = []
229
+ for branch in branches:
230
+ if schema_types(branch, resolve, seen) == ("null",):
231
+ values.append(None)
232
+ continue
233
+ allowed = allowed_values(branch, resolve, seen)
234
+ if allowed is None:
235
+ return None
236
+ values += allowed[0]
237
+ labels += allowed[1]
238
+ return (values, labels) if [value for value in values if value is not None] else None
172
239
 
173
240
 
174
- def _field_type(field_schema: Any) -> str | None:
175
- if not isinstance(field_schema, dict):
241
+ def _shared_values(branches: list, resolve: Resolve, seen: frozenset) -> tuple[list, list[dict]] | None:
242
+ listed = [allowed for branch in branches if (allowed := allowed_values(branch, resolve, seen)) is not None]
243
+ if not listed:
176
244
  return None
177
- kind = field_schema.get("type")
178
- if isinstance(kind, list):
179
- # A nullable field is `["string", "null"]` in JSON Schema; one readable type, not the list.
180
- return " | ".join(str(part) for part in kind)
181
- if kind is None and isinstance(field_schema.get("$ref"), str):
182
- return field_schema["$ref"].rsplit("/", 1)[-1]
183
- return kind if isinstance(kind, str) else None
245
+ values = [value for value in listed[0][0] if all(value in other[0] for other in listed[1:])]
246
+ labels = [label for _, branch_labels in listed for label in branch_labels if label["value"] in values]
247
+ labels = [label for index, label in enumerate(labels) if label not in labels[:index]]
248
+ return (values, labels) if values else None
249
+
250
+
251
+ def schema_fields(schema: Any, resolve: Resolve = unresolved) -> list[FieldType]:
252
+ """The fields of one entity schema (``properties`` + ``required``), each typed by the JSON
253
+ type words it admits and, when it lists them all, its allowed values: the one reading
254
+ ``gateway worlds describe`` reports and every CSV import casts by."""
255
+ node, _ = resolve(schema, frozenset())
256
+ required = set(node.get("required") or [])
257
+ return [
258
+ FieldType(
259
+ name,
260
+ _type_words(schema_types(field_schema, resolve)),
261
+ name in required,
262
+ _allowed_tuple(allowed_values(field_schema, resolve)),
263
+ schema_format(field_schema, resolve),
264
+ )
265
+ for name, field_schema in (node.get("properties") or {}).items()
266
+ ]
184
267
 
185
268
 
186
- def _field_enum(field_schema: Any, defs: dict) -> tuple | None:
187
- if not isinstance(field_schema, dict):
269
+ def _type_words(types: tuple[str, ...]) -> str | None:
270
+ if UNFOLLOWED in types:
188
271
  return None
189
- branches = field_schema.get("anyOf") or field_schema.get("oneOf")
190
- if isinstance(branches, list):
191
- return _branches_enum(branches, defs)
192
- ref = field_schema.get("$ref")
193
- target = defs.get(ref[len("#/$defs/") :]) if isinstance(ref, str) and ref.startswith("#/$defs/") else field_schema
194
- values = target.get("enum") if isinstance(target, dict) else None
195
- return tuple(values) if isinstance(values, list) else None
272
+ return " | ".join(sorted(types, key=lambda word: MEMBERS.index(word) if word in MEMBERS else len(MEMBERS))) or None
273
+
274
+
275
+ def _allowed_tuple(allowed: tuple[list, list[dict]] | None) -> tuple | None:
276
+ return tuple(allowed[0]) if allowed is not None else None
196
277
 
197
278
 
198
- def _branches_enum(branches: list, defs: dict) -> tuple | None:
199
- """A nullable enum (``anyOf: [{$ref: Enum}, {type: null}]``) allows the enum's values and null."""
200
- values = [value for branch in branches for value in (_field_enum(branch, defs) or ())]
201
- nullable = any(isinstance(branch, dict) and branch.get("type") == "null" for branch in branches)
202
- return tuple(values) + ((None,) if nullable else ()) if values else None
279
+ def schema_format(schema: Any, resolve: Resolve = unresolved, seen: frozenset = frozenset()) -> str | None:
280
+ """The ``format`` a schema names, through references and the first ``anyOf`` / ``oneOf`` branch
281
+ that names one."""
282
+ node, seen = resolve(schema, seen)
283
+ if isinstance(node.get("format"), str):
284
+ return node["format"]
285
+ branches = node.get("anyOf") or node.get("oneOf") or []
286
+ return next((found for branch in branches if (found := schema_format(branch, resolve, seen)) is not None), None)
203
287
 
204
288
 
205
289
  def world_fields(world: dict) -> dict[str, list[FieldType]]:
206
- """Every entity's fields as a world.json document declares them (the ``$defs`` entry its
207
- ``schema.$ref`` names, or an inline ``properties``), sorted by entity name — the field
208
- list ``gateway worlds describe`` reports and a CSV import casts by."""
290
+ """Every entity's fields as an authored world.json declares them, following its own ``$defs``
291
+ only, sorted by entity name: what describe reports when the world's schemas cannot be resolved."""
209
292
  gateway = world.get("x-gateway") if isinstance(world, dict) else None
210
293
  entities = (gateway.get("entities") or {}) if isinstance(gateway, dict) else {}
211
- defs = world.get("$defs") or {}
212
- fields: dict[str, list[FieldType]] = {}
213
- for name, entity in sorted(entities.items()):
214
- definition = _definition(world, entity)
215
- required = set(definition.get("required") or [])
216
- properties = definition.get("properties") or {}
217
- fields[name] = [
218
- FieldType(field_name, _field_type(field_schema), field_name in required, _field_enum(field_schema, defs))
219
- for field_name, field_schema in properties.items()
220
- ]
221
- return fields
222
-
223
-
224
- def world_casters(world: dict) -> EntityCasters:
225
- """:func:`casters_of` for a world.json document."""
226
- return casters_of(world_fields(world))
227
-
228
-
229
- def schema_fields(schema: Any) -> list[FieldType]:
230
- """The fields of one resolved entity schema (``properties`` + ``required``)."""
231
- if not isinstance(schema, dict):
232
- return []
233
- required = set(schema.get("required") or [])
234
- return [
235
- FieldType(name, _field_type(field_schema), name in required)
236
- for name, field_schema in (schema.get("properties") or {}).items()
237
- ]
294
+ resolve = LocalDefinitions(world.get("$defs"))
295
+ return {
296
+ name: schema_fields(entity.get("schema") if isinstance(entity, dict) else None, resolve)
297
+ for name, entity in sorted(entities.items())
298
+ }
238
299
 
239
300
 
240
301
  def contract_casters(entities: dict) -> EntityCasters:
241
302
  """:func:`casters_of` for a compiled contract's ``entities`` (each carries its resolved
242
- ``schema``) — the local twin of :func:`world_casters`."""
243
- return casters_of({name: schema_fields(entity.get("schema")) for name, entity in entities.items()})
303
+ ``schema``): the local twin of :func:`described_casters`."""
304
+ return casters_of(
305
+ {
306
+ name: schema_fields(entity.get("schema"), LocalDefinitions((entity.get("schema") or {}).get("$defs")))
307
+ for name, entity in entities.items()
308
+ }
309
+ )
244
310
 
245
311
 
246
312
  def tree_casters(root: str | Path) -> EntityCasters:
@@ -9,6 +9,12 @@ from pathlib import Path
9
9
  from typing import Any
10
10
 
11
11
  from .._toml import tomllib
12
+ from .shape_declarations import (
13
+ DECLARATION_MEMBERS,
14
+ EntityDeclarations,
15
+ answer_declarations,
16
+ check_generated_sequences,
17
+ )
12
18
  from .tree_import import PUBLICATION_FILE_BYTES
13
19
  from .validation import (
14
20
  FIELD_NAME,
@@ -21,6 +27,7 @@ from .validation import (
21
27
  digest,
22
28
  encoded,
23
29
  fail,
30
+ json_pointer_parts,
24
31
  local_definition,
25
32
  members,
26
33
  nonempty,
@@ -92,20 +99,6 @@ def quote(value: str) -> str:
92
99
  return '"' + value.replace('"', '""') + '"'
93
100
 
94
101
 
95
- def json_pointer_parts(value: str, location: str, *, code: str) -> list[str]:
96
- if not value.startswith("/"):
97
- return [value]
98
- parts = []
99
- for part in value[1:].split("/"):
100
- if re.search(r"~(?![01])", part):
101
- fail(code, "Invalid JSON Pointer escape in field path", location)
102
- decoded = part.replace("~1", "/").replace("~0", "~")
103
- if '"' in decoded:
104
- fail(code, "Quoted property names are unsupported in key paths", location)
105
- parts.append(decoded)
106
- return parts
107
-
108
-
109
102
  def field_schema(schema: dict, field: str, location: str, *, code: str = "key") -> dict:
110
103
  parts = json_pointer_parts(field, location, code=code)
111
104
 
@@ -469,7 +462,7 @@ def _build(bundle: Path, resolver: Resolver) -> Contract:
469
462
  seen.add(name.lower())
470
463
  members(
471
464
  entity,
472
- {"schema", "primary_key", "unique", "relationships"},
465
+ {"schema", "primary_key", "unique", "relationships", *DECLARATION_MEMBERS},
473
466
  {"schema", "primary_key"},
474
467
  location,
475
468
  )
@@ -540,6 +533,8 @@ def _build(bundle: Path, resolver: Resolver) -> Contract:
540
533
  "location": location,
541
534
  }
542
535
  warnings.extend(cycles.unreached(document.get("$defs", {}), "world.json"))
536
+ payloads = {name: entity["schema"] for name, entity in compiled.items()}
537
+ EntityDeclarations(entities, payloads, "world.json#/x-gateway/entities").check()
543
538
  for name, entity in compiled.items():
544
539
  for rel in entity["relationships"]:
545
540
  location = f"{entity['location']}/relationships"
@@ -897,12 +892,16 @@ def bind_connection(bundle: Path, contract: Contract) -> None:
897
892
  spec_path = bundle / "connector.toml"
898
893
  if not spec_path.is_file():
899
894
  return
900
- from .connector import parse_spec
895
+ from .connector import spec_from
896
+ from .validation import parse_toml
901
897
 
902
- spec = parse_spec(spec_path.read_text(encoding="utf-8"))
898
+ raw = parse_toml(spec_path.read_text(encoding="utf-8"))
899
+ spec = spec_from(raw)
903
900
  spec.check_entities(contract.entities)
904
901
  if spec.webhooks is not None:
905
902
  spec.webhooks.check_contract(contract.entities)
903
+ answer_declarations(raw)
904
+ check_generated_sequences(raw, json.loads((bundle / ROOT).read_text(encoding="utf-8")))
906
905
 
907
906
 
908
907
  def check_bundle(bundle: str | Path) -> Contract:
@@ -53,7 +53,7 @@ CREATE TABLE benchmark_conversation_events (scenario_id TEXT NOT NULL, user_turn
53
53
  _FICLONE = 0x40049409
54
54
 
55
55
 
56
- def _reflink(source: Path, destination: Path) -> bool:
56
+ def reflink(source: Path, destination: Path) -> bool:
57
57
  try:
58
58
  import fcntl
59
59
 
@@ -175,7 +175,7 @@ class WorldDatabase(ABC):
175
175
  destination.parent.mkdir(parents=True, exist_ok=True)
176
176
  if destination.exists() and destination.samefile(source):
177
177
  raise shutil.SameFileError(f"{source} and {destination} are the same file")
178
- if not _reflink(source, destination):
178
+ if not reflink(source, destination):
179
179
  shutil.copyfile(source, destination)
180
180
 
181
181
  @classmethod