@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
@@ -7,8 +7,18 @@ from pathlib import Path
7
7
 
8
8
  SCHEMA_PACKAGE = Path(__file__).parent
9
9
  ENVIRONMENT_PACKAGE = SCHEMA_PACKAGE.parent
10
- # Modules outside `schema/` that its modules import; copied beside them so `main.py` resolves them.
11
- SIBLING_MODULES = ("_toml.py", "world_session_contract.py")
10
+ SIBLING_MODULES = (
11
+ "_toml.py",
12
+ "backing.py",
13
+ "errors.py",
14
+ "legacy_sqlite.py",
15
+ "reward_keys.py",
16
+ "score.py",
17
+ "secret_values.py",
18
+ "world.py",
19
+ "world_session_contract.py",
20
+ )
21
+ SUBPACKAGES = ("database",)
12
22
 
13
23
 
14
24
  def stage_runtime_package(server: Path) -> Path:
@@ -18,9 +28,11 @@ def stage_runtime_package(server: Path) -> Path:
18
28
  for package_dir in ("gatewaysdk", "gatewaysdk/environment"):
19
29
  (server / package_dir / "__init__.py").write_text("")
20
30
  for name in SIBLING_MODULES:
21
- shutil.copy(
22
- ENVIRONMENT_PACKAGE / name, server / "gatewaysdk" / "environment" / name
23
- )
31
+ shutil.copy(ENVIRONMENT_PACKAGE / name, server / "gatewaysdk" / "environment" / name)
24
32
  for module in sorted(SCHEMA_PACKAGE.glob("*.py")):
25
33
  shutil.copy(module, package / module.name)
34
+ for name in SUBPACKAGES:
35
+ (package / name).mkdir()
36
+ for module in sorted((SCHEMA_PACKAGE / name).glob("*.py")):
37
+ shutil.copy(module, package / name / module.name)
26
38
  return package
@@ -0,0 +1,5 @@
1
+ """The directories a World Host keeps under its cache root, each cleared or filled by the host itself."""
2
+
3
+ SESSIONS_DIR = "sessions"
4
+ VERSIONS_DIR = "versions"
5
+ WORKERS_DIR = "workers"
@@ -0,0 +1,309 @@
1
+ """What the world request ledger keeps of one request a session's world answered: the
2
+ request's headers and each body's first :data:`CAPTURE_BYTES` as text, beside the
3
+ body's size as it went over the wire (``bodyBytes``) and whether the text was cut
4
+ (``truncated``).
5
+
6
+ A JSON body is kept as the call log keeps a request (:class:`CallRedaction`): a
7
+ credential by its name or its shape reads ``[redacted]``, and only the part of the
8
+ body the capture keeps is walked, so a large answer costs no more than its first
9
+ :data:`CAPTURE_BYTES`. A request's body is what the world read (a form's fields
10
+ included), redacted and written as JSON, so its text is not the wire's bytes; a
11
+ body the world did not read (a GET's) is not kept and reads ``truncated``. A body
12
+ answered as bytes is kept as its text when its first :data:`CAPTURE_BYTES` are UTF-8
13
+ and not at all when they are not (``body: null`` beside its size). Every body kept,
14
+ JSON or text, is scrubbed of the secrets it embeds before it is cut
15
+ (:meth:`CallRedaction.scrub`: the session's credential as sent and percent-encoded,
16
+ the value of a query parameter the world's ``[auth]`` carries a secret in, a JSON Web
17
+ Token), read :data:`~.call_redaction.SCRUB_MARGIN` past the cut so a secret across it
18
+ is seen whole; text the capture did not read to its end keeps nothing within that
19
+ margin of where it stopped. Header values are kept only under names that
20
+ say what they are (:meth:`CallRedaction.headers`), and each content type is its
21
+ first :data:`CONTENT_TYPE_CHARS` characters, the request's read from its kept
22
+ header.
23
+
24
+ A tool called by name is an exchange too: its arguments are the request's body and
25
+ its answer the response's, each as JSON. An exchange the request ledger's outbox sheds
26
+ (:class:`~.request_ledger.RequestOutbox`) keeps its sizes and status and gives up its
27
+ headers, text and content types, each body then ``truncated``.
28
+
29
+ The answer as the ledger keeps it is the answer as it goes on the wire
30
+ (:class:`ServedAnswer`), written by every world server (:class:`WorldRequestHandler`); a HEAD is
31
+ kept as the GET it mirrors, whose body the wire leaves off.
32
+ """
33
+
34
+ from __future__ import annotations
35
+
36
+ import json
37
+ from dataclasses import dataclass, replace
38
+ from http.server import BaseHTTPRequestHandler
39
+ from typing import Any
40
+
41
+ from ..world_session_contract import REQUEST_BODY_CAPTURE_BYTES
42
+ from .call_redaction import SCRUB_MARGIN, CallRedaction
43
+
44
+ CAPTURE_BYTES = REQUEST_BODY_CAPTURE_BYTES
45
+ CONTENT_TYPE_CHARS = 256
46
+ JSON_TYPE = "application/json"
47
+ _MAX_CUT_CHARACTER = 3
48
+
49
+
50
+ def _utf8(head: bytes, cut: bool) -> str | None:
51
+ """``head`` as text, or None when it is not UTF-8. A head cut from a longer body
52
+ may end inside a character, whose bytes are let go; a whole body is text only
53
+ when every byte of it is."""
54
+ for trim in range(_MAX_CUT_CHARACTER + 1 if cut else 1):
55
+ try:
56
+ return head[: len(head) - trim].decode("utf-8")
57
+ except UnicodeDecodeError:
58
+ continue
59
+ return None
60
+
61
+
62
+ def _utf8_lead(head: bytes) -> int:
63
+ """How many leading bytes of ``head`` are UTF-8."""
64
+ try:
65
+ head.decode("utf-8")
66
+ except UnicodeDecodeError as error:
67
+ return error.start
68
+ return len(head)
69
+
70
+
71
+ def _typed(content_type: Any) -> str | None:
72
+ return None if content_type is None else str(content_type)[:CONTENT_TYPE_CHARS]
73
+
74
+
75
+ @dataclass(frozen=True)
76
+ class ServedAnswer:
77
+ """One ``WorldApp`` answer as it goes on the wire: nothing for a 204 or a
78
+ ``None``, bytes as they are, anything else as JSON labelled
79
+ ``application/json`` (an error ``error_content_type``) unless the answer named
80
+ its own type."""
81
+
82
+ headers: dict[str, str]
83
+ payload: bytes
84
+
85
+ @classmethod
86
+ def of(cls, status: int, body: Any, extra: dict[str, str] | None, error_content_type: str) -> ServedAnswer:
87
+ headers = dict(extra or {})
88
+ if status == 204 or body is None:
89
+ return cls(headers, b"")
90
+ if isinstance(body, bytes):
91
+ return cls(headers, body)
92
+ labelled = {"Content-Type": error_content_type if status >= 400 else "application/json", **headers}
93
+ return cls(labelled, json.dumps(body, ensure_ascii=False).encode("utf-8"))
94
+
95
+ @property
96
+ def content_type(self) -> str | None:
97
+ return next((value for name, value in self.headers.items() if name.lower() == "content-type"), None)
98
+
99
+
100
+ def send_response(
101
+ handler: BaseHTTPRequestHandler, status: int, body: Any, extra: dict[str, str] | None, error_content_type: str
102
+ ) -> None:
103
+ """Write one ``WorldApp`` answer to a request handler's socket."""
104
+ answer = ServedAnswer.of(status, body, extra, error_content_type)
105
+ handler.send_response(status)
106
+ for name, value in answer.headers.items():
107
+ handler.send_header(name, value)
108
+ handler.send_header("Content-Length", str(len(answer.payload)))
109
+ handler.end_headers()
110
+ write_body(handler, answer.payload)
111
+
112
+
113
+ def write_body(handler: BaseHTTPRequestHandler, payload: bytes) -> None:
114
+ """An answer's body, left off the wire for a HEAD, whose headers are the GET's."""
115
+ if handler.command != "HEAD":
116
+ handler.wfile.write(payload)
117
+
118
+
119
+ class WorldRequestHandler(BaseHTTPRequestHandler):
120
+ """The methods every world server answers, each through :meth:`_dispatch`: HEAD as the GET
121
+ it mirrors (:func:`write_body` leaves its body off), OPTIONS as the world answers it. A
122
+ request the standard library refuses before any of them (another method, a malformed
123
+ request line) is answered in JSON, never the library's HTML page. No request is
124
+ access-logged: a query-auth world's key rides the request line."""
125
+
126
+ def _dispatch(self, method: str) -> None:
127
+ raise NotImplementedError
128
+
129
+ def log_message(self, format: str, *args: object) -> None:
130
+ pass
131
+
132
+ def send_error(self, code: int, message: str | None = None, explain: str | None = None) -> None:
133
+ self.close_connection = True
134
+ reason = self.responses.get(code, ("error",))[0]
135
+ send_response(self, code, {"error": reason}, {"Connection": "close"}, JSON_TYPE)
136
+
137
+ def do_GET(self) -> None:
138
+ self._dispatch("GET")
139
+
140
+ def do_HEAD(self) -> None:
141
+ self._dispatch("GET")
142
+
143
+ def do_POST(self) -> None:
144
+ self._dispatch("POST")
145
+
146
+ def do_PUT(self) -> None:
147
+ self._dispatch("PUT")
148
+
149
+ def do_PATCH(self) -> None:
150
+ self._dispatch("PATCH")
151
+
152
+ def do_DELETE(self) -> None:
153
+ self._dispatch("DELETE")
154
+
155
+ def do_OPTIONS(self) -> None:
156
+ self._dispatch("OPTIONS")
157
+
158
+
159
+ @dataclass(frozen=True)
160
+ class Served:
161
+ """What the request ledger reads of one route request beyond what the call log
162
+ keeps: the headers the world read, the body's size as it arrived, the
163
+ answer's own headers, how the world labels an error, and the session's token,
164
+ which no kept header may carry."""
165
+
166
+ headers: dict[str, str]
167
+ body_bytes: int
168
+ extra: dict[str, str] | None
169
+ error_content_type: str
170
+ secret: str | None
171
+ read_body: bool = True
172
+
173
+
174
+ @dataclass(frozen=True)
175
+ class CapturedBody:
176
+ """One body as the request ledger keeps it (module docstring); ``size`` is None
177
+ for a value that could not be written as JSON."""
178
+
179
+ content_type: str | None
180
+ size: int | None
181
+ text: str | None = None
182
+ truncated: bool = False
183
+
184
+ @classmethod
185
+ def of_request(cls, body: Any, served: Served, content_type: Any, redaction: CallRedaction) -> CapturedBody:
186
+ typed, size = _typed(content_type), served.body_bytes
187
+ if size == 0:
188
+ return cls(typed, 0)
189
+ if not served.read_body:
190
+ return cls(typed, size, None, True)
191
+ return cls.of_value(body, size, typed, redaction)
192
+
193
+ @classmethod
194
+ def of_answer(cls, status: int, answer: Any, served: Served, redaction: CallRedaction) -> CapturedBody:
195
+ try:
196
+ wire = ServedAnswer.of(status, answer, served.extra, served.error_content_type)
197
+ except (RecursionError, TypeError, ValueError):
198
+ return cls(None, None, None, True)
199
+ size, content_type = len(wire.payload), _typed(wire.content_type)
200
+ if size == 0:
201
+ return cls(content_type, 0)
202
+ if isinstance(answer, bytes):
203
+ return cls.of_bytes(wire.payload, content_type, redaction)
204
+ return cls.of_value(answer, size, content_type, redaction)
205
+
206
+ @classmethod
207
+ def of_document(cls, value: Any, redaction: CallRedaction) -> CapturedBody:
208
+ """A tool's arguments or answer: the JSON it is, its size as JSON."""
209
+ if value is None:
210
+ return cls(None, 0)
211
+ try:
212
+ size = len(json.dumps(value, ensure_ascii=False).encode("utf-8", "replace"))
213
+ except (RecursionError, TypeError, ValueError):
214
+ return cls(JSON_TYPE, None, None, True)
215
+ return cls.of_value(value, size, JSON_TYPE, redaction)
216
+
217
+ @classmethod
218
+ def of_bytes(cls, payload: bytes, content_type: str | None, redaction: CallRedaction) -> CapturedBody:
219
+ """A body answered as bytes (module docstring): the UTF-8 text of its first
220
+ :data:`CAPTURE_BYTES` and :data:`SCRUB_MARGIN` more, scrubbed, then cut."""
221
+ head = payload[: CAPTURE_BYTES + SCRUB_MARGIN]
222
+ lead = _utf8_lead(head)
223
+ whole = lead == len(payload)
224
+ if lead < (len(payload) if len(payload) <= CAPTURE_BYTES else CAPTURE_BYTES - _MAX_CUT_CHARACTER):
225
+ return cls(_typed(content_type), len(payload))
226
+ scrubbed = redaction.scrub(head[:lead].decode("utf-8")).encode("utf-8")
227
+ limit = CAPTURE_BYTES if whole else max(0, min(CAPTURE_BYTES, len(scrubbed) - SCRUB_MARGIN))
228
+ cut = not whole or len(scrubbed) > CAPTURE_BYTES
229
+ return cls(_typed(content_type), len(payload), _utf8(scrubbed[:limit], cut), cut)
230
+
231
+ @classmethod
232
+ def of_value(cls, value: Any, size: int, content_type: str | None, redaction: CallRedaction) -> CapturedBody:
233
+ try:
234
+ kept, cut = redaction.prefix(value, CAPTURE_BYTES)
235
+ text = redaction.scrub(json.dumps(kept, ensure_ascii=False))
236
+ except (RecursionError, TypeError, ValueError):
237
+ return cls(content_type, size, None, True)
238
+ encoded = text.encode("utf-8", "replace")
239
+ longer = len(encoded) > CAPTURE_BYTES
240
+ return cls(content_type, size, _utf8(encoded[:CAPTURE_BYTES], longer), cut or longer)
241
+
242
+ @classmethod
243
+ def from_json(cls, data: dict) -> CapturedBody:
244
+ return cls(data.get("contentType"), data.get("bodyBytes"), data.get("body"), bool(data.get("truncated")))
245
+
246
+ def shed(self) -> CapturedBody:
247
+ return replace(self, text=None, content_type=None, truncated=self.truncated or self.text is not None)
248
+
249
+ @property
250
+ def charge(self) -> int:
251
+ return len(self.text or "") + len(self.content_type or "")
252
+
253
+ def as_json(self) -> dict:
254
+ return {
255
+ "body": self.text,
256
+ "bodyBytes": self.size,
257
+ "truncated": self.truncated,
258
+ "contentType": self.content_type,
259
+ }
260
+
261
+
262
+ @dataclass(frozen=True)
263
+ class Exchange:
264
+ """One HTTP request a session's world answered and the answer it gave, as
265
+ the request ledger keeps them."""
266
+
267
+ headers: dict[str, str]
268
+ request: CapturedBody
269
+ status: int
270
+ response: CapturedBody
271
+
272
+ @classmethod
273
+ def of(cls, served: Served, body: Any, status: int, answer: Any, redaction: CallRedaction) -> Exchange:
274
+ headers = redaction.headers(served.headers, served.secret, CAPTURE_BYTES)
275
+ return cls(
276
+ headers,
277
+ CapturedBody.of_request(body, served, headers.get("content-type"), redaction),
278
+ status,
279
+ CapturedBody.of_answer(status, answer, served, redaction),
280
+ )
281
+
282
+ @classmethod
283
+ def of_tool(cls, args: Any, status: int, answer: Any, redaction: CallRedaction) -> Exchange:
284
+ """A tool called by name: its arguments are what was asked, its answer what came back."""
285
+ return cls({}, CapturedBody.of_document(args, redaction), status, CapturedBody.of_document(answer, redaction))
286
+
287
+ @classmethod
288
+ def from_json(cls, data: dict) -> Exchange:
289
+ request, response = data.get("request") or {}, data.get("response") or {}
290
+ return cls(
291
+ dict(request.get("headers") or {}),
292
+ CapturedBody.from_json(request),
293
+ int(response.get("status") or 0),
294
+ CapturedBody.from_json(response),
295
+ )
296
+
297
+ def shed(self) -> Exchange:
298
+ return Exchange({}, self.request.shed(), self.status, self.response.shed())
299
+
300
+ @property
301
+ def charge(self) -> int:
302
+ held = sum(len(name) + len(str(value)) for name, value in self.headers.items())
303
+ return held + self.request.charge + self.response.charge
304
+
305
+ def as_json(self) -> dict:
306
+ return {
307
+ "request": {"headers": self.headers, **self.request.as_json()},
308
+ "response": {"status": self.status, **self.response.as_json()},
309
+ }