@withgateway/sdk 0.3.1 → 0.4.0

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 (176) hide show
  1. package/README.md +8 -6
  2. package/dist/cli.js +4372 -2265
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +4362 -2256
  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 +259 -58
  9. package/dist/files/index.js.map +1 -1
  10. package/dist/files/index.mjs +249 -50
  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 +124 -11
  15. package/dist/hooks/index.js.map +1 -1
  16. package/dist/hooks/index.mjs +124 -11
  17. package/dist/hooks/index.mjs.map +1 -1
  18. package/dist/{index-C3UzD0G3.d.mts → index-CDPQBsU5.d.mts} +19 -3
  19. package/dist/{index-C3UzD0G3.d.ts → index-CDPQBsU5.d.ts} +19 -3
  20. package/dist/{index-CBqbB_0J.d.ts → index-DUHmS74p.d.ts} +1 -1
  21. package/dist/{index-D-AMnAMa.d.mts → index-mJhG3vZU.d.mts} +1 -1
  22. package/dist/index.d.mts +5 -5
  23. package/dist/index.d.ts +5 -5
  24. package/dist/index.js +2240 -789
  25. package/dist/index.js.map +1 -1
  26. package/dist/index.mjs +2150 -739
  27. package/dist/index.mjs.map +1 -1
  28. package/dist/{media-CbcAfQvd.d.mts → media-BIApiPzS.d.mts} +21 -2
  29. package/dist/{media-CbcAfQvd.d.ts → media-BIApiPzS.d.ts} +21 -2
  30. package/dist/traces/index.d.mts +1 -1
  31. package/dist/traces/index.d.ts +1 -1
  32. package/dist/traces/index.js +253 -52
  33. package/dist/traces/index.js.map +1 -1
  34. package/dist/traces/index.mjs +243 -44
  35. package/dist/traces/index.mjs.map +1 -1
  36. package/dist/tracing/index.d.mts +2 -2
  37. package/dist/tracing/index.d.ts +2 -2
  38. package/dist/tracing/index.js +75 -13
  39. package/dist/tracing/index.js.map +1 -1
  40. package/dist/tracing/index.mjs +75 -13
  41. package/dist/tracing/index.mjs.map +1 -1
  42. package/dist/worlds/index.d.mts +893 -482
  43. package/dist/worlds/index.d.ts +893 -482
  44. package/dist/worlds/index.js +1968 -669
  45. package/dist/worlds/index.js.map +1 -1
  46. package/dist/worlds/index.mjs +1960 -662
  47. package/dist/worlds/index.mjs.map +1 -1
  48. package/package.json +1 -1
  49. package/runtime/gatewaysdk/environment/_bundle.py +2 -27
  50. package/runtime/gatewaysdk/environment/_materialize.py +48 -88
  51. package/runtime/gatewaysdk/environment/_world.py +155 -237
  52. package/runtime/gatewaysdk/environment/backing.py +133 -0
  53. package/runtime/gatewaysdk/environment/core.py +2 -17
  54. package/runtime/gatewaysdk/environment/legacy_sqlite.py +288 -0
  55. package/runtime/gatewaysdk/environment/reward_keys.py +25 -0
  56. package/runtime/gatewaysdk/environment/runtime.py +8 -13
  57. package/runtime/gatewaysdk/environment/schema/__init__.py +4 -4
  58. package/runtime/gatewaysdk/environment/schema/admin_routes.py +86 -0
  59. package/runtime/gatewaysdk/environment/schema/admission.py +174 -0
  60. package/runtime/gatewaysdk/environment/schema/api.py +347 -892
  61. package/runtime/gatewaysdk/environment/schema/assertions.py +458 -0
  62. package/runtime/gatewaysdk/environment/schema/batch.py +44 -39
  63. package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +17 -5
  64. package/runtime/gatewaysdk/environment/schema/cache_layout.py +5 -0
  65. package/runtime/gatewaysdk/environment/schema/call_capture.py +309 -0
  66. package/runtime/gatewaysdk/environment/schema/call_log.py +503 -0
  67. package/runtime/gatewaysdk/environment/schema/call_redaction.py +526 -0
  68. package/runtime/gatewaysdk/environment/schema/cast.py +15 -35
  69. package/runtime/gatewaysdk/environment/schema/compiler.py +334 -158
  70. package/runtime/gatewaysdk/environment/schema/conform.py +14 -39
  71. package/runtime/gatewaysdk/environment/schema/connector.py +113 -211
  72. package/runtime/gatewaysdk/environment/schema/connectors/confluence/connector.toml +1 -12
  73. package/runtime/gatewaysdk/environment/schema/connectors/github/connector.toml +1 -0
  74. package/runtime/gatewaysdk/environment/schema/connectors/servicenow/connector.toml +2 -5
  75. package/runtime/gatewaysdk/environment/schema/cors.py +54 -0
  76. package/runtime/gatewaysdk/environment/schema/credentials.py +313 -8
  77. package/runtime/gatewaysdk/environment/schema/data.py +60 -216
  78. package/runtime/gatewaysdk/environment/schema/database/__init__.py +24 -0
  79. package/runtime/gatewaysdk/environment/schema/database/audit.py +121 -0
  80. package/runtime/gatewaysdk/environment/schema/database/base.py +936 -0
  81. package/runtime/gatewaysdk/environment/schema/database/budget.py +33 -0
  82. package/runtime/gatewaysdk/environment/schema/database/connections.py +101 -0
  83. package/runtime/gatewaysdk/environment/schema/database/engines.py +8 -0
  84. package/runtime/gatewaysdk/environment/schema/database/guard.py +215 -0
  85. package/runtime/gatewaysdk/environment/schema/database/ingest.py +154 -0
  86. package/runtime/gatewaysdk/environment/schema/database/matching.py +58 -0
  87. package/runtime/gatewaysdk/environment/schema/database/provenance.py +30 -0
  88. package/runtime/gatewaysdk/environment/schema/database/reads.py +169 -0
  89. package/runtime/gatewaysdk/environment/schema/database/rows.py +53 -0
  90. package/runtime/gatewaysdk/environment/schema/database/runtime_rows.py +39 -0
  91. package/runtime/gatewaysdk/environment/schema/database/sqlite.py +393 -0
  92. package/runtime/gatewaysdk/environment/schema/declared_routes.py +210 -0
  93. package/runtime/gatewaysdk/environment/schema/domain_migration.py +236 -0
  94. package/runtime/gatewaysdk/environment/schema/door.py +899 -0
  95. package/runtime/gatewaysdk/environment/schema/envelope.py +227 -0
  96. package/runtime/gatewaysdk/environment/schema/extract.py +6 -13
  97. package/runtime/gatewaysdk/environment/schema/grading.py +90 -103
  98. package/runtime/gatewaysdk/environment/schema/handler_errors.py +163 -12
  99. package/runtime/gatewaysdk/environment/schema/host.py +237 -1795
  100. package/runtime/gatewaysdk/environment/schema/host_control.py +144 -0
  101. package/runtime/gatewaysdk/environment/schema/host_handoff.py +370 -0
  102. package/runtime/gatewaysdk/environment/schema/host_loops.py +97 -0
  103. package/runtime/gatewaysdk/environment/schema/host_owners.py +121 -0
  104. package/runtime/gatewaysdk/environment/schema/host_proxy.py +111 -0
  105. package/runtime/gatewaysdk/environment/schema/host_requests.py +6 -0
  106. package/runtime/gatewaysdk/environment/schema/host_session.py +126 -0
  107. package/runtime/gatewaysdk/environment/schema/host_surfaces.py +79 -21
  108. package/runtime/gatewaysdk/environment/schema/host_transfers.py +127 -0
  109. package/runtime/gatewaysdk/environment/schema/host_versions.py +242 -0
  110. package/runtime/gatewaysdk/environment/schema/host_workers.py +577 -0
  111. package/runtime/gatewaysdk/environment/schema/journal.py +437 -0
  112. package/runtime/gatewaysdk/environment/schema/lanes.py +53 -0
  113. package/runtime/gatewaysdk/environment/schema/ledger_spill.py +828 -0
  114. package/runtime/gatewaysdk/environment/schema/local.py +58 -170
  115. package/runtime/gatewaysdk/environment/schema/mapping.py +5 -25
  116. package/runtime/gatewaysdk/environment/schema/openapi_import.py +112 -73
  117. package/runtime/gatewaysdk/environment/schema/openapi_paging.py +147 -0
  118. package/runtime/gatewaysdk/environment/schema/openapi_payloads.py +288 -0
  119. package/runtime/gatewaysdk/environment/schema/openapi_routes.py +97 -102
  120. package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +113 -30
  121. package/runtime/gatewaysdk/environment/schema/platform.py +137 -187
  122. package/runtime/gatewaysdk/environment/schema/platform_import.py +2 -3
  123. package/runtime/gatewaysdk/environment/schema/platform_query.py +61 -5
  124. package/runtime/gatewaysdk/environment/schema/primary_key.py +61 -0
  125. package/runtime/gatewaysdk/environment/schema/proof.py +19 -12
  126. package/runtime/gatewaysdk/environment/schema/request_body.py +238 -0
  127. package/runtime/gatewaysdk/environment/schema/request_ledger.py +958 -0
  128. package/runtime/gatewaysdk/environment/schema/route_bindings.py +25 -3
  129. package/runtime/gatewaysdk/environment/schema/route_miss.py +54 -0
  130. package/runtime/gatewaysdk/environment/schema/runtime.py +178 -308
  131. package/runtime/gatewaysdk/environment/schema/served_names.py +58 -0
  132. package/runtime/gatewaysdk/environment/schema/session_files.py +275 -0
  133. package/runtime/gatewaysdk/environment/schema/session_move.py +275 -0
  134. package/runtime/gatewaysdk/environment/schema/skills/agents/connector-template-author.md +5 -1
  135. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +10 -11
  136. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +49 -16
  137. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +39 -9
  138. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +27 -27
  139. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +33 -33
  140. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +13 -7
  141. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +49 -1
  142. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +182 -0
  143. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/openapi-import.md +50 -21
  144. package/runtime/gatewaysdk/environment/schema/slack.py +4 -8
  145. package/runtime/gatewaysdk/environment/schema/snapshot.py +516 -140
  146. package/runtime/gatewaysdk/environment/schema/spill_files.py +228 -0
  147. package/runtime/gatewaysdk/environment/schema/store_contract.py +8 -14
  148. package/runtime/gatewaysdk/environment/schema/tasks.py +267 -276
  149. package/runtime/gatewaysdk/environment/schema/tools_world.py +146 -242
  150. package/runtime/gatewaysdk/environment/schema/ui.py +24 -5
  151. package/runtime/gatewaysdk/environment/schema/ui_static/app.js +100 -130
  152. package/runtime/gatewaysdk/environment/schema/ui_static/index.html +1 -8
  153. package/runtime/gatewaysdk/environment/schema/validation.py +235 -41
  154. package/runtime/gatewaysdk/environment/schema/verbs.py +32 -36
  155. package/runtime/gatewaysdk/environment/schema/worker.py +6 -4
  156. package/runtime/gatewaysdk/environment/schema/workers.py +345 -96
  157. package/runtime/gatewaysdk/environment/schema/world_host.py +953 -0
  158. package/runtime/gatewaysdk/environment/schema/world_sql.py +81 -0
  159. package/runtime/gatewaysdk/environment/schema/world_tests.py +80 -50
  160. package/runtime/gatewaysdk/environment/score.py +57 -0
  161. package/runtime/gatewaysdk/environment/secret_values.py +36 -0
  162. package/runtime/gatewaysdk/environment/world.py +43 -4
  163. package/runtime/gatewaysdk/environment/world_session_contract.py +46 -5
  164. package/skills/agents/connector-template-author.md +5 -1
  165. package/skills/benchmarks-getting-started/SKILL.md +10 -11
  166. package/skills/connector-schema-authoring/SKILL.md +49 -16
  167. package/skills/connector-schema-authoring/connector-worlds.md +142 -11
  168. package/skills/connector-schema-authoring/world-schema.md +103 -51
  169. package/skills/world-data-ingestion/ROWS.md +39 -9
  170. package/skills/world-data-ingestion/SKILL.md +27 -27
  171. package/skills/worlds-getting-started/SKILL.md +33 -33
  172. package/skills/worlds-getting-started/references/cli-mcp-map.md +13 -7
  173. package/skills/worlds-getting-started/references/gotchas.md +49 -1
  174. package/skills/worlds-getting-started/references/journal-checks.md +182 -0
  175. package/skills/worlds-getting-started/references/openapi-import.md +50 -21
  176. package/runtime/gatewaysdk/environment/schema/store.py +0 -1013
@@ -1,7 +1,6 @@
1
1
  """What a failing handler answers — structured, classified, never a bare string.
2
2
 
3
- A tool call that raises inside ``tools/handlers.py`` is answered like the
4
- HTTP twin of the tool would answer:
3
+ A tool or a route whose handler raises is answered the same way on every door:
5
4
 
6
5
  * ``AttributeError`` / ``TypeError`` / ``NameError`` are the author's bug
7
6
  (``store.upsert`` on a store with no ``upsert``, a misspelled name, a
@@ -9,13 +8,28 @@ HTTP twin of the tool would answer:
9
8
  * Anything else is a failure inside the handler's own logic — status **500**,
10
9
  ``error: "engine"``.
11
10
 
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.
11
+ A route handler (or its ``[api].before`` gate) that answers without a status
12
+ from 200 to 599, with a header value HTTP cannot carry (outside latin-1), or
13
+ with a value JSON cannot carry (a ``datetime``, a set, NaN, an unpaired
14
+ surrogate) is the author's bug too, a 400; bytes go out as they are, under the
15
+ type the handler names. Every body carries ``detail`` (one line, bounded) and
16
+ ``handler`` (the function's name) so the caller knows which handler to fix
17
+ without reading a trace. A failure the host meets answering a request outside
18
+ any handler is a 500 ``engine`` without ``handler`` (:func:`request_failure_body`).
19
+ What no reply can carry (an unpaired surrogate, a NaN, an infinity) goes out as
20
+ text where the platform reads it (:func:`carried`).
14
21
  """
15
22
 
16
23
  from __future__ import annotations
17
24
 
18
- #: The exception classes that mark a handler bug rather than a runtime failure.
25
+ import json
26
+ import math
27
+ import re
28
+ import sys
29
+ from typing import Any, Callable
30
+
31
+ from .validation import ContractError, fail
32
+
19
33
  HANDLER_BUG_ERRORS: tuple[type[BaseException], ...] = (
20
34
  AttributeError,
21
35
  TypeError,
@@ -23,6 +37,8 @@ HANDLER_BUG_ERRORS: tuple[type[BaseException], ...] = (
23
37
  )
24
38
 
25
39
  _DETAIL_LIMIT = 2000
40
+ _FIELD_LIMIT = 256
41
+ _SURROGATE = re.compile("[\ud800-\udfff]")
26
42
 
27
43
 
28
44
  def _detail(error: BaseException) -> str:
@@ -30,15 +46,150 @@ def _detail(error: BaseException) -> str:
30
46
  return text[:_DETAIL_LIMIT]
31
47
 
32
48
 
33
- def handler_bug_body(handler: str, error: BaseException) -> dict:
49
+ def handler_bug_body(handler: str, error: BaseException, about: str = "") -> dict:
34
50
  """The 400 body for a handler-authored bug."""
35
- return {"error": "handler", "detail": _detail(error), "handler": handler}
51
+ return {"error": "handler", "detail": f"{about}{_detail(error)}"[:_DETAIL_LIMIT], "handler": handler}
52
+
53
+
54
+ def log_line(message: str) -> None:
55
+ """One line on the host's stderr, which is its pod's log."""
56
+ print(f"world host: {message}", file=sys.stderr, flush=True)
57
+
58
+
59
+ def log_request_failure(error: BaseException, method: str, path: str) -> None:
60
+ """One stderr line for a failure met answering a request: its class, the
61
+ method and the path's first segment only, since a later one can be a credential."""
62
+ segment = path.lstrip("/").split("/", 1)[0]
63
+ log_line(f"{type(error).__name__} on {method} /{segment}")
64
+
65
+
66
+ def log_contract_refusal(world: str, operation: str, error: ContractError) -> None:
67
+ """One stderr line for a write the contract refused, whose caller is answered the world's
68
+ declared ``invalid`` alone: the rule and where it applies, bounded and ``repr``-escaped, never a
69
+ value. Where it applies is the contract's schema path, or, for a value JSON cannot hold, the
70
+ body's own path to it, so a key the caller chose can appear, escaped; ``path`` is never logged."""
71
+ rule = str(error.detail.get("code") or "")[:_FIELD_LIMIT]
72
+ where = str(error.detail.get("schema_path") or "")[:_FIELD_LIMIT]
73
+ log_line(f"{world}: {operation} refused by the contract: {rule!r} at {where!r}")
74
+
75
+
76
+ def request_failure_body(error: BaseException) -> dict:
77
+ """The 500 body for a failure met answering a request, outside any handler."""
78
+ return {"error": "engine", "detail": f"{type(error).__name__}: {_detail(error)}"[:_DETAIL_LIMIT]}
36
79
 
37
80
 
38
81
  def engine_failure_body(handler: str, error: BaseException) -> dict:
39
82
  """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
- }
83
+ return {**request_failure_body(error), "handler": handler}
84
+
85
+
86
+ def failure_answer(handler: str, error: Exception) -> tuple[int, dict]:
87
+ """A handler's raise as its ``(status, body)``: its author's bug or the engine's failure."""
88
+ if isinstance(error, HANDLER_BUG_ERRORS):
89
+ return 400, handler_bug_body(handler, error)
90
+ return 500, engine_failure_body(handler, error)
91
+
92
+
93
+ def unencodable(body: Any) -> Exception | None:
94
+ """Why a body cannot go out as JSON, or None when it can (bytes go out as they are)."""
95
+ if isinstance(body, bytes):
96
+ return None
97
+ try:
98
+ json.dumps(body, ensure_ascii=False, allow_nan=False).encode("utf-8")
99
+ except (TypeError, ValueError, RecursionError) as error:
100
+ return error
101
+ return None
102
+
103
+
104
+ def _unsendable_header(headers: dict[str, str] | None) -> Exception | None:
105
+ try:
106
+ for name, value in (headers or {}).items():
107
+ f"{name}: {value}".encode("latin-1")
108
+ except UnicodeEncodeError as error:
109
+ return error
110
+ return None
111
+
112
+
113
+ def unencodable_answer(handler: str, response: tuple) -> tuple[int, dict] | None:
114
+ """The 400 for a handler answer the wire cannot carry, or None when it can."""
115
+ status, body, headers = response
116
+ if isinstance(status, bool) or not isinstance(status, int) or not 200 <= status <= 599:
117
+ return 400, handler_bug_body(handler, ValueError(f"an answer names a status from 200 to 599, not {status!r}"))
118
+ header = _unsendable_header(headers)
119
+ if header is not None:
120
+ return 400, handler_bug_body(handler, header, "a header is not latin-1: ")
121
+ error = unencodable(body)
122
+ return None if error is None else (400, handler_bug_body(handler, error, "the answer is not JSON: "))
123
+
124
+
125
+ def carried_scalar(value: Any) -> Any:
126
+ """A scalar as a JSON reply can carry it: an unpaired surrogate as U+FFFD,
127
+ a NaN or an infinity as ``"NaN"``, ``"Infinity"`` or ``"-Infinity"``."""
128
+ if isinstance(value, str):
129
+ return _SURROGATE.sub("\ufffd", value)
130
+ if isinstance(value, float) and not math.isfinite(value):
131
+ return "NaN" if math.isnan(value) else ("Infinity" if value > 0 else "-Infinity")
132
+ return value
133
+
134
+
135
+ def carried(value: Any) -> Any:
136
+ """``value`` as a JSON reply can carry it (:func:`carried_scalar`, keys
137
+ included); a value too deep to walk goes out as it is."""
138
+ try:
139
+ return _carried_tree(value)
140
+ except RecursionError:
141
+ return value
142
+
143
+
144
+ def _carried_tree(value: Any) -> Any:
145
+ if isinstance(value, dict):
146
+ return {carried_scalar(str(key)): _carried_tree(item) for key, item in value.items()}
147
+ if isinstance(value, list):
148
+ return [_carried_tree(item) for item in value]
149
+ return carried_scalar(value)
150
+
151
+
152
+ def normalize_answer(result: Any, default_status: int | None) -> Any:
153
+ """What a handler (or the gate) hands back, as ``(status, body, headers)``.
154
+
155
+ A handler returns a body, ``(status, body)`` or ``(status, body, headers)``;
156
+ the gate returns ``None`` to let the request through or one of those to stop it."""
157
+ if result is None and default_status is None:
158
+ return None
159
+ if (
160
+ isinstance(result, tuple)
161
+ and len(result) in (2, 3)
162
+ and isinstance(result[0], int)
163
+ and not isinstance(result[0], bool)
164
+ ):
165
+ status, body = result[0], result[1]
166
+ extra = result[2] if len(result) == 3 else None
167
+ if extra is not None and not (
168
+ isinstance(extra, dict) and all(isinstance(k, str) and isinstance(v, str) for k, v in extra.items())
169
+ ):
170
+ fail("handlers", "A handler's headers are a mapping of header names to strings", "/api/handlers")
171
+ if isinstance(body, bytes) and not any(k.lower() == "content-type" for k in extra or {}):
172
+ fail("handlers", "A handler answering bytes names the Content-Type in its headers", "/api/handlers")
173
+ return status, body, extra
174
+ return default_status, result, None
175
+
176
+
177
+ def handled_answer(name: str, handler: Callable[..., Any], request: tuple, default_status: int | None) -> Any:
178
+ """A handler's answer, or the answer for how it failed (``handler_errors``):
179
+ a raise is its 400 or 500, an answer of the wrong shape or one JSON cannot
180
+ carry its 400. A refusal the contract raises while the handler runs
181
+ (``ContractError``) is the route's to answer."""
182
+ try:
183
+ result = handler(*request)
184
+ except ContractError:
185
+ raise
186
+ except Exception as error:
187
+ return (*failure_answer(name, error), None)
188
+ try:
189
+ response = normalize_answer(result, default_status)
190
+ except ContractError as error:
191
+ return 400, handler_bug_body(name, error), None
192
+ if response is None:
193
+ return None
194
+ refused = unencodable_answer(name, response)
195
+ return response if refused is None else (*refused, None)