@buildanagent/gateway 0.0.0-stage → 0.1.0-alpha.1

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 (126) hide show
  1. package/LICENSE +52 -0
  2. package/LICENSE-APACHE +202 -0
  3. package/LICENSE-MIT +21 -0
  4. package/README.md +305 -2
  5. package/dist/adapters/anthropic/adapter.d.ts +25 -0
  6. package/dist/adapters/anthropic/adapter.js +183 -0
  7. package/dist/adapters/anthropic/adapter.js.map +1 -0
  8. package/dist/adapters/anthropic/failure.d.ts +27 -0
  9. package/dist/adapters/anthropic/failure.js +53 -0
  10. package/dist/adapters/anthropic/failure.js.map +1 -0
  11. package/dist/adapters/anthropic/index.d.ts +3 -0
  12. package/dist/adapters/anthropic/index.js +3 -0
  13. package/dist/adapters/anthropic/index.js.map +1 -0
  14. package/dist/adapters/anthropic/request.d.ts +53 -0
  15. package/dist/adapters/anthropic/request.js +250 -0
  16. package/dist/adapters/anthropic/request.js.map +1 -0
  17. package/dist/adapters/anthropic/response.d.ts +38 -0
  18. package/dist/adapters/anthropic/response.js +237 -0
  19. package/dist/adapters/anthropic/response.js.map +1 -0
  20. package/dist/adapters/anthropic/usage.d.ts +26 -0
  21. package/dist/adapters/anthropic/usage.js +39 -0
  22. package/dist/adapters/anthropic/usage.js.map +1 -0
  23. package/dist/adapters/openai-chat/adapter.d.ts +18 -0
  24. package/dist/adapters/openai-chat/adapter.js +86 -0
  25. package/dist/adapters/openai-chat/adapter.js.map +1 -0
  26. package/dist/adapters/openai-chat/compat.d.ts +58 -0
  27. package/dist/adapters/openai-chat/compat.js +19 -0
  28. package/dist/adapters/openai-chat/compat.js.map +1 -0
  29. package/dist/adapters/openai-chat/failure.d.ts +32 -0
  30. package/dist/adapters/openai-chat/failure.js +40 -0
  31. package/dist/adapters/openai-chat/failure.js.map +1 -0
  32. package/dist/adapters/openai-chat/index.d.ts +4 -0
  33. package/dist/adapters/openai-chat/index.js +3 -0
  34. package/dist/adapters/openai-chat/index.js.map +1 -0
  35. package/dist/adapters/openai-chat/request.d.ts +47 -0
  36. package/dist/adapters/openai-chat/request.js +227 -0
  37. package/dist/adapters/openai-chat/request.js.map +1 -0
  38. package/dist/adapters/openai-chat/response.d.ts +22 -0
  39. package/dist/adapters/openai-chat/response.js +203 -0
  40. package/dist/adapters/openai-chat/response.js.map +1 -0
  41. package/dist/adapters/openai-chat/usage.d.ts +22 -0
  42. package/dist/adapters/openai-chat/usage.js +25 -0
  43. package/dist/adapters/openai-chat/usage.js.map +1 -0
  44. package/dist/adapters/strict-schema.d.ts +67 -0
  45. package/dist/adapters/strict-schema.js +269 -0
  46. package/dist/adapters/strict-schema.js.map +1 -0
  47. package/dist/adapters/wire.d.ts +98 -0
  48. package/dist/adapters/wire.js +187 -0
  49. package/dist/adapters/wire.js.map +1 -0
  50. package/dist/catalog.d.ts +65 -0
  51. package/dist/catalog.js +145 -0
  52. package/dist/catalog.js.map +1 -0
  53. package/dist/catalog.json +120 -0
  54. package/dist/classify.d.ts +25 -0
  55. package/dist/classify.js +37 -0
  56. package/dist/classify.js.map +1 -0
  57. package/dist/complete.d.ts +9 -0
  58. package/dist/complete.js +13 -0
  59. package/dist/complete.js.map +1 -0
  60. package/dist/cost.d.ts +44 -0
  61. package/dist/cost.js +132 -0
  62. package/dist/cost.js.map +1 -0
  63. package/dist/create-model.d.ts +7 -0
  64. package/dist/create-model.js +81 -0
  65. package/dist/create-model.js.map +1 -0
  66. package/dist/errors.d.ts +17 -0
  67. package/dist/errors.js +24 -0
  68. package/dist/errors.js.map +1 -0
  69. package/dist/index.d.ts +19 -0
  70. package/dist/index.js +17 -0
  71. package/dist/index.js.map +1 -0
  72. package/dist/middleware.d.ts +11 -0
  73. package/dist/middleware.js +22 -0
  74. package/dist/middleware.js.map +1 -0
  75. package/dist/names.d.ts +72 -0
  76. package/dist/names.js +175 -0
  77. package/dist/names.js.map +1 -0
  78. package/dist/provider-config.d.ts +15 -0
  79. package/dist/provider-config.js +23 -0
  80. package/dist/provider-config.js.map +1 -0
  81. package/dist/request-dump.d.ts +28 -0
  82. package/dist/request-dump.js +52 -0
  83. package/dist/request-dump.js.map +1 -0
  84. package/dist/request-policy.d.ts +18 -0
  85. package/dist/request-policy.js +27 -0
  86. package/dist/request-policy.js.map +1 -0
  87. package/dist/retry.d.ts +33 -0
  88. package/dist/retry.js +219 -0
  89. package/dist/retry.js.map +1 -0
  90. package/dist/runtime-types.d.ts +112 -0
  91. package/dist/runtime-types.js +2 -0
  92. package/dist/runtime-types.js.map +1 -0
  93. package/dist/spec.d.ts +67 -0
  94. package/dist/spec.js +2 -0
  95. package/dist/spec.js.map +1 -0
  96. package/dist/sse.d.ts +15 -0
  97. package/dist/sse.js +73 -0
  98. package/dist/sse.js.map +1 -0
  99. package/dist/stream-contract.d.ts +23 -0
  100. package/dist/stream-contract.js +101 -0
  101. package/dist/stream-contract.js.map +1 -0
  102. package/dist/testing/guards.d.ts +16 -0
  103. package/dist/testing/guards.js +48 -0
  104. package/dist/testing/guards.js.map +1 -0
  105. package/dist/testing/index.d.ts +12 -0
  106. package/dist/testing/index.js +13 -0
  107. package/dist/testing/index.js.map +1 -0
  108. package/dist/testing/mock-transport.d.ts +49 -0
  109. package/dist/testing/mock-transport.js +101 -0
  110. package/dist/testing/mock-transport.js.map +1 -0
  111. package/dist/testing/random.d.ts +3 -0
  112. package/dist/testing/random.js +13 -0
  113. package/dist/testing/random.js.map +1 -0
  114. package/dist/testing/setup.d.ts +1 -0
  115. package/dist/testing/setup.js +12 -0
  116. package/dist/testing/setup.js.map +1 -0
  117. package/dist/transform-messages.d.ts +32 -0
  118. package/dist/transform-messages.js +291 -0
  119. package/dist/transform-messages.js.map +1 -0
  120. package/dist/types.d.ts +143 -0
  121. package/dist/types.js +6 -0
  122. package/dist/types.js.map +1 -0
  123. package/dist/usage.d.ts +16 -0
  124. package/dist/usage.js +31 -0
  125. package/dist/usage.js.map +1 -0
  126. package/package.json +50 -3
package/LICENSE ADDED
@@ -0,0 +1,52 @@
1
+ buildanagent is open source under five licence terms, one for each kind of
2
+ content in the repository.
3
+
4
+ Code: Apache-2.0 OR MIT, at your option
5
+ Scripts (scripts/), our packages (packages/), the verification harnesses and
6
+ their examples (verify/), the book's code and figure generators (apps/manual/),
7
+ the CI workflows (.github/), the configuration files, and the code blocks in
8
+ the agent skills (.agents/skills/) are licensed under either of
9
+
10
+ * the Apache License, Version 2.0 (LICENSE-APACHE), or
11
+ * the MIT License (LICENSE-MIT).
12
+
13
+ SPDX-License-Identifier: Apache-2.0 OR MIT
14
+
15
+ Code from the garment engineering textbook: Apache-2.0 only
16
+ Some files in apps/manual/ are copied or adapted from the owner's garment
17
+ engineering textbook (tajistudios/garment-engineering-textbook), with the
18
+ owner's permission. Those files are licensed under the Apache License,
19
+ Version 2.0 (LICENSE-APACHE) only, not under the MIT option above. Each one
20
+ opens with a header comment that names its source and this licence, and
21
+ THIRD-PARTY-NOTICES.md lists each file with its source path and commit.
22
+
23
+ SPDX-License-Identifier: Apache-2.0
24
+
25
+ Documentation: CC BY 4.0
26
+ The documents under docs/, the book's prose and figures (apps/manual/), the
27
+ READMEs, the prose of the agent skills (.agents/skills/) and AGENTS.md are
28
+ licensed under the Creative Commons Attribution 4.0 International licence
29
+ (LICENSE-DOCS).
30
+
31
+ SPDX-License-Identifier: CC-BY-4.0
32
+
33
+ The book's fonts: SIL Open Font License 1.1
34
+ The font files under apps/manual/public/fonts/ are subsets of Instrument
35
+ Serif, Literata and Google Sans Code, and are not ours. They stay under the
36
+ SIL Open Font License, Version 1.1, whose text ships as OFL.txt beside each
37
+ family's files. THIRD-PARTY-NOTICES.md lists each family, its source commit
38
+ and how the subsets are named.
39
+
40
+ SPDX-License-Identifier: OFL-1.1
41
+
42
+ Mirrored third-party docs: their own licences
43
+ The upstream documentation mirrored under docs/reference/*/source/ is not ours.
44
+ Each mirror keeps its upstream licence file, and its _manifest.json records
45
+ the source repository and the tag or commit it was copied from.
46
+ THIRD-PARTY-NOTICES.md lists every mirror and its licence.
47
+
48
+ Copyright (c) 2026 The buildanagent contributors (named agent-speak until
49
+ 2026-11-19).
50
+
51
+ Contributions to this repository are accepted under the same terms: code
52
+ under Apache-2.0 OR MIT, documentation under CC BY 4.0.
package/LICENSE-APACHE ADDED
@@ -0,0 +1,202 @@
1
+
2
+ Apache License
3
+ Version 2.0, January 2004
4
+ http://www.apache.org/licenses/
5
+
6
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
7
+
8
+ 1. Definitions.
9
+
10
+ "License" shall mean the terms and conditions for use, reproduction,
11
+ and distribution as defined by Sections 1 through 9 of this document.
12
+
13
+ "Licensor" shall mean the copyright owner or entity authorized by
14
+ the copyright owner that is granting the License.
15
+
16
+ "Legal Entity" shall mean the union of the acting entity and all
17
+ other entities that control, are controlled by, or are under common
18
+ control with that entity. For the purposes of this definition,
19
+ "control" means (i) the power, direct or indirect, to cause the
20
+ direction or management of such entity, whether by contract or
21
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
22
+ outstanding shares, or (iii) beneficial ownership of such entity.
23
+
24
+ "You" (or "Your") shall mean an individual or Legal Entity
25
+ exercising permissions granted by this License.
26
+
27
+ "Source" form shall mean the preferred form for making modifications,
28
+ including but not limited to software source code, documentation
29
+ source, and configuration files.
30
+
31
+ "Object" form shall mean any form resulting from mechanical
32
+ transformation or translation of a Source form, including but
33
+ not limited to compiled object code, generated documentation,
34
+ and conversions to other media types.
35
+
36
+ "Work" shall mean the work of authorship, whether in Source or
37
+ Object form, made available under the License, as indicated by a
38
+ copyright notice that is included in or attached to the work
39
+ (an example is provided in the Appendix below).
40
+
41
+ "Derivative Works" shall mean any work, whether in Source or Object
42
+ form, that is based on (or derived from) the Work and for which the
43
+ editorial revisions, annotations, elaborations, or other modifications
44
+ represent, as a whole, an original work of authorship. For the purposes
45
+ of this License, Derivative Works shall not include works that remain
46
+ separable from, or merely link (or bind by name) to the interfaces of,
47
+ the Work and Derivative Works thereof.
48
+
49
+ "Contribution" shall mean any work of authorship, including
50
+ the original version of the Work and any modifications or additions
51
+ to that Work or Derivative Works thereof, that is intentionally
52
+ submitted to Licensor for inclusion in the Work by the copyright owner
53
+ or by an individual or Legal Entity authorized to submit on behalf of
54
+ the copyright owner. For the purposes of this definition, "submitted"
55
+ means any form of electronic, verbal, or written communication sent
56
+ to the Licensor or its representatives, including but not limited to
57
+ communication on electronic mailing lists, source code control systems,
58
+ and issue tracking systems that are managed by, or on behalf of, the
59
+ Licensor for the purpose of discussing and improving the Work, but
60
+ excluding communication that is conspicuously marked or otherwise
61
+ designated in writing by the copyright owner as "Not a Contribution."
62
+
63
+ "Contributor" shall mean Licensor and any individual or Legal Entity
64
+ on behalf of whom a Contribution has been received by Licensor and
65
+ subsequently incorporated within the Work.
66
+
67
+ 2. Grant of Copyright License. Subject to the terms and conditions of
68
+ this License, each Contributor hereby grants to You a perpetual,
69
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
70
+ copyright license to reproduce, prepare Derivative Works of,
71
+ publicly display, publicly perform, sublicense, and distribute the
72
+ Work and such Derivative Works in Source or Object form.
73
+
74
+ 3. Grant of Patent License. Subject to the terms and conditions of
75
+ this License, each Contributor hereby grants to You a perpetual,
76
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
77
+ (except as stated in this section) patent license to make, have made,
78
+ use, offer to sell, sell, import, and otherwise transfer the Work,
79
+ where such license applies only to those patent claims licensable
80
+ by such Contributor that are necessarily infringed by their
81
+ Contribution(s) alone or by combination of their Contribution(s)
82
+ with the Work to which such Contribution(s) was submitted. If You
83
+ institute patent litigation against any entity (including a
84
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
85
+ or a Contribution incorporated within the Work constitutes direct
86
+ or contributory patent infringement, then any patent licenses
87
+ granted to You under this License for that Work shall terminate
88
+ as of the date such litigation is filed.
89
+
90
+ 4. Redistribution. You may reproduce and distribute copies of the
91
+ Work or Derivative Works thereof in any medium, with or without
92
+ modifications, and in Source or Object form, provided that You
93
+ meet the following conditions:
94
+
95
+ (a) You must give any other recipients of the Work or
96
+ Derivative Works a copy of this License; and
97
+
98
+ (b) You must cause any modified files to carry prominent notices
99
+ stating that You changed the files; and
100
+
101
+ (c) You must retain, in the Source form of any Derivative Works
102
+ that You distribute, all copyright, patent, trademark, and
103
+ attribution notices from the Source form of the Work,
104
+ excluding those notices that do not pertain to any part of
105
+ the Derivative Works; and
106
+
107
+ (d) If the Work includes a "NOTICE" text file as part of its
108
+ distribution, then any Derivative Works that You distribute must
109
+ include a readable copy of the attribution notices contained
110
+ within such NOTICE file, excluding those notices that do not
111
+ pertain to any part of the Derivative Works, in at least one
112
+ of the following places: within a NOTICE text file distributed
113
+ as part of the Derivative Works; within the Source form or
114
+ documentation, if provided along with the Derivative Works; or,
115
+ within a display generated by the Derivative Works, if and
116
+ wherever such third-party notices normally appear. The contents
117
+ of the NOTICE file are for informational purposes only and
118
+ do not modify the License. You may add Your own attribution
119
+ notices within Derivative Works that You distribute, alongside
120
+ or as an addendum to the NOTICE text from the Work, provided
121
+ that such additional attribution notices cannot be construed
122
+ as modifying the License.
123
+
124
+ You may add Your own copyright statement to Your modifications and
125
+ may provide additional or different license terms and conditions
126
+ for use, reproduction, or distribution of Your modifications, or
127
+ for any such Derivative Works as a whole, provided Your use,
128
+ reproduction, and distribution of the Work otherwise complies with
129
+ the conditions stated in this License.
130
+
131
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
132
+ any Contribution intentionally submitted for inclusion in the Work
133
+ by You to the Licensor shall be under the terms and conditions of
134
+ this License, without any additional terms or conditions.
135
+ Notwithstanding the above, nothing herein shall supersede or modify
136
+ the terms of any separate license agreement you may have executed
137
+ with Licensor regarding such Contributions.
138
+
139
+ 6. Trademarks. This License does not grant permission to use the trade
140
+ names, trademarks, service marks, or product names of the Licensor,
141
+ except as required for reasonable and customary use in describing the
142
+ origin of the Work and reproducing the content of the NOTICE file.
143
+
144
+ 7. Disclaimer of Warranty. Unless required by applicable law or
145
+ agreed to in writing, Licensor provides the Work (and each
146
+ Contributor provides its Contributions) on an "AS IS" BASIS,
147
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
148
+ implied, including, without limitation, any warranties or conditions
149
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
150
+ PARTICULAR PURPOSE. You are solely responsible for determining the
151
+ appropriateness of using or redistributing the Work and assume any
152
+ risks associated with Your exercise of permissions under this License.
153
+
154
+ 8. Limitation of Liability. In no event and under no legal theory,
155
+ whether in tort (including negligence), contract, or otherwise,
156
+ unless required by applicable law (such as deliberate and grossly
157
+ negligent acts) or agreed to in writing, shall any Contributor be
158
+ liable to You for damages, including any direct, indirect, special,
159
+ incidental, or consequential damages of any character arising as a
160
+ result of this License or out of the use or inability to use the
161
+ Work (including but not limited to damages for loss of goodwill,
162
+ work stoppage, computer failure or malfunction, or any and all
163
+ other commercial damages or losses), even if such Contributor
164
+ has been advised of the possibility of such damages.
165
+
166
+ 9. Accepting Warranty or Additional Liability. While redistributing
167
+ the Work or Derivative Works thereof, You may choose to offer,
168
+ and charge a fee for, acceptance of support, warranty, indemnity,
169
+ or other liability obligations and/or rights consistent with this
170
+ License. However, in accepting such obligations, You may act only
171
+ on Your own behalf and on Your sole responsibility, not on behalf
172
+ of any other Contributor, and only if You agree to indemnify,
173
+ defend, and hold each Contributor harmless for any liability
174
+ incurred by, or claims asserted against, such Contributor by reason
175
+ of your accepting any such warranty or additional liability.
176
+
177
+ END OF TERMS AND CONDITIONS
178
+
179
+ APPENDIX: How to apply the Apache License to your work.
180
+
181
+ To apply the Apache License to your work, attach the following
182
+ boilerplate notice, with the fields enclosed by brackets "[]"
183
+ replaced with your own identifying information. (Don't include
184
+ the brackets!) The text should be enclosed in the appropriate
185
+ comment syntax for the file format. We also recommend that a
186
+ file or class name and description of purpose be included on the
187
+ same "printed page" as the copyright notice for easier
188
+ identification within third-party archives.
189
+
190
+ Copyright [yyyy] [name of copyright owner]
191
+
192
+ Licensed under the Apache License, Version 2.0 (the "License");
193
+ you may not use this file except in compliance with the License.
194
+ You may obtain a copy of the License at
195
+
196
+ http://www.apache.org/licenses/LICENSE-2.0
197
+
198
+ Unless required by applicable law or agreed to in writing, software
199
+ distributed under the License is distributed on an "AS IS" BASIS,
200
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
201
+ See the License for the specific language governing permissions and
202
+ limitations under the License.
package/LICENSE-MIT ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 The buildanagent contributors (named agent-speak until 2026-11-19)
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,306 @@
1
- # Temporary Holding Version
1
+ # @buildanagent/gateway
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The gateway lets your agent call any model through one transcript and one stream format, so switching providers never changes your agent code. Use it directly to call a model, or through `@buildanagent/sdk`, which runs the agent loop on top of it.
4
+
5
+ As of November 2026 the package holds the transcript types, the stream checker, `complete()`, `createModel()` with its retries and middleware, the price catalog that puts a cost on every message, the tool-name rule, the Anthropic Messages and OpenAI-compatible Chat Completions adapters, and `transformMessages()`, which prepares a transcript for the model you send it to.
6
+
7
+ ## Install the alpha with `pnpm add @buildanagent/gateway@alpha`
8
+
9
+ Every release is an alpha until the first stable one, and npm serves the alphas under the `alpha` dist-tag:
10
+
11
+ ```bash
12
+ pnpm add @buildanagent/gateway@alpha
13
+ ```
14
+
15
+ Name the tag. A plain `pnpm add @buildanagent/gateway` installs `0.0.0-bootstrap.0`, a deprecated placeholder, because `latest` stays on it until the first stable release. The package needs Node 22 or later.
16
+
17
+ ## A conversation is a list of messages you own
18
+
19
+ A conversation is a list of `Message`s: user messages, assistant messages and tool results. Their content is a short list of blocks (`text`, `reasoning`, `image` and `tool_call`), so your code never handles a provider's wire format. A reasoning block may carry a signature that only the model that wrote it accepts.
20
+
21
+ Every `AssistantMessage` records its model, why it stopped (`stopReason`), any typed `error`, its `Usage` and its `Cost`. `Usage` has no field named `input`, because providers disagree on whether input includes cached tokens. The uncached part is `uncachedInput`, and `totalInput()` adds the cache reads and cache writes to it. `Cost.total` is `null` when the price is unknown, never a guessed zero. When a provider sends no usage for a response, its `Usage` has `unreported: true`: the counts are then incomplete, and the gateway prices the response as unknown. An adapter you write can build such a record with `unreportedUsage()`.
22
+
23
+ ## A transcript recorded on one model replays on another
24
+
25
+ You can start a conversation on one model and continue it on another, even from another provider. Before each request, `transformMessages()` turns your transcript into one that the target model accepts:
26
+
27
+ ```ts
28
+ const messages = transformMessages(transcript, model.ref, model.caps);
29
+ ```
30
+
31
+ The pass returns a new array and leaves your transcript as it was, so you keep the full record. It gives the same answer for the same transcript every time, and running it on its own output changes nothing. It changes five things:
32
+
33
+ - **Failed turns.** It leaves out every assistant message that stopped with `"error"` or `"aborted"`, and the tool results that answer its calls. A resumed call then asks the model again instead of building on a half-written answer.
34
+ - **Reasoning.** For a model that does not reason (`caps.reasoning` is `false`), the pass drops every reasoning block. Otherwise it drops reasoning that another provider wrote and removes any signature the target cannot check, because a reasoning signature is valid only for the provider, and often only for the model, that wrote it. An Anthropic target gets every Anthropic-signed thinking block exactly as recorded, empty ones included, and no unsigned reasoning. Another target keeps the text of reasoning it cannot verify, unless the text is empty.
35
+ - **Images.** For a model that takes no images (`caps.images` is `false`), each image becomes a short text note.
36
+ - **Tool-call ids.** Each id must be 1 to 64 letters, digits, `_` or `-`, and must not repeat. The pass rewrites any id that breaks the rule and updates the result that answers it.
37
+ - **Tool results.** Each result moves next to the call it answers, even when it was recorded after a later turn, and a result that answers no call is dropped. When several calls share an id, a result goes to the newest waiting call from a completed turn. It goes to a failed turn's call, and is dropped with that turn, only when no completed turn's call is waiting. A call that never got a result gets a synthetic one with `isError: true`, because providers reject a call left unanswered.
38
+
39
+ The pass also keeps every message to a shape both providers accept. It removes reasoning and tool calls from user messages, removes empty text blocks, and drops any message left with no content. It merges user messages that end up next to each other into one, and does the same for assistant messages. A merged assistant message keeps the later message's stop reason, usage and cost. If the earlier message has text or tool calls, the pass drops the later message's reasoning, so no reasoning block ends up after a block it did not follow before. When your transcript has a user message, the output starts with one: if the pass empties the first user message, a short `(continued)` note takes its place. A transcript left with nothing to send becomes `[]`.
40
+
41
+ When an Anthropic target must lose a reasoning block, the pass also drops every reasoning block before it, so the blocks it keeps are the newest unbroken run. As the transcript grows, a later drop can remove older thinking, but only ever as a leading run. Anthropic's thinking documentation allows exactly that: outside tool use, a request may omit prior turns' thinking, "but not a block between two that you keep" ([Thinking](https://platform.claude.com/docs/en/build-with-claude/thinking), linked from [Extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking), as of November 2026). The same page says the API drops, without billing, the thinking blocks a target model cannot read, and uses each block's signature to verify that Claude wrote it. It does not say what happens to an unsigned thinking block; the pass drops those blocks on the reading that they cannot pass that check (unverified). Other targets check no such order, so they lose only the blocks they cannot accept.
42
+
43
+ ## Every stream follows one rule
44
+
45
+ A provider adapter implements one method, `stream()`. The stream it returns follows four rules:
46
+
47
+ 1. `start` comes first, once.
48
+ 2. Each content block runs `*_start`, then any number of `*_delta`, then `*_end`, and keeps one kind.
49
+ 3. Exactly one terminal event, `done` or `error`, ends the stream.
50
+ 4. An error terminal has `stopReason` `"error"` or `"aborted"` and carries the content and usage so far. A `done` terminal has neither stop reason, and every block it started has ended.
51
+
52
+ A `warning` event may come anywhere between `start` and the terminal. It reports something the call survived, such as an option the provider would reject, with a snake_case `code` and a `message`. A warning is not output, so the gateway still retries a call that has only warned. A retry does not repeat a warning that an earlier attempt streamed with the same code and message.
53
+
54
+ This check reads a stream and throws a `StreamContractError` at the first broken rule:
55
+
56
+ ```ts
57
+ import { assertStreamContract } from "@buildanagent/gateway/testing";
58
+
59
+ const events = await assertStreamContract(adapter.stream(model, context, {}));
60
+ ```
61
+
62
+ `complete()` folds a stream into its terminal message. It returns an error terminal's message instead of throwing, so a failed call still gives you its partial content and usage.
63
+
64
+ ## A model is an adapter object plus a model id
65
+
66
+ `createModel()` binds one adapter to one model id. You always pass the adapter as an object that you made with your own API key, so a bare id such as `"claude-x"` is a type error and the gateway never guesses a provider:
67
+
68
+ ```ts
69
+ const model = createModel({ adapter, id: "my-model", catalog });
70
+ const message = await model.complete(context);
71
+ ```
72
+
73
+ `model.stream()` yields the adapter's events, and `model.complete()` folds them into the final message. `model.caps` holds the context window, the output limit, and whether the model takes images and reasoning. The gateway reads these caps from the model's catalog entry. For a model the catalog lacks, it uses the adapter's default caps, and it refuses a model that has neither.
74
+
75
+ ## Every message carries its cost, priced from a catalog you can replace
76
+
77
+ The gateway prices each response from the price catalog, so every `AssistantMessage` arrives with a `cost`. The catalog lists each model's rates in USD per million tokens for every token class: uncached input, cache reads, 5-minute and 1-hour cache writes, and output. Reasoning tokens are part of output, so they cost the output rate. The cost's `basis` tells you where its number came from:
78
+
79
+ - `"provider"`: the adapter reported a total the provider billed, and that total wins over the catalog.
80
+ - `"catalog"`: the gateway multiplied each token class by its catalog rate, and `catalogAsOf` gives the date those rates were copied.
81
+ - `"unknown"`: the catalog doesn't list the model, or the provider never reported the usage, so `total` is `null`. Usage goes unreported when a request fails before any response arrives, when a stream throws or breaks off before its usage arrives, and when a reply ends without the usage chunk a server should send. A failed request's usage is unreported because the request may have reached the provider before the connection broke. The gateway never guesses a zero, because a budget that counts an unknown price as free never stops. An HTTP error response is the one failure that counts as zero tokens, because the provider sent an error instead of a reply.
82
+
83
+ A retried call's cost sums its attempts, and the sum takes the weakest basis among them. It is `"unknown"` if any attempt's cost is unknown, and `"catalog"`, with `catalogAsOf`, if any attempt was priced from the catalog. It is `"provider"` only when the provider billed every attempt.
84
+
85
+ Some models charge more for long prompts. Their entries list several rate tiers, and each request pays the tier its total input selects, cache reads and writes included. The gateway prices each attempt of a call on its own before it adds them up, so a retried call pays each request's own tier. `model.price(usage)` applies the same rates to one request's usage.
86
+
87
+ `createModel()` uses the catalog that ships with the package, `defaultCatalog`, unless you pass your own. A catalog you pass replaces the shipped one, so spread the shipped entries into it to keep them:
88
+
89
+ ```ts
90
+ import { createModel, defaultCatalog, parseCatalog } from "@buildanagent/gateway";
91
+
92
+ const catalog = parseCatalog({ models: [...defaultCatalog.models, myEntry] });
93
+ const model = createModel({ adapter, id: "my-model", catalog });
94
+ ```
95
+
96
+ Each entry records its rate tiers, `contextWindow`, `maxOutputTokens`, the `asOf` date it was copied, and the provider page each number came from. `contextWindow` is the most input one request can send, so a model whose page caps input below its full window, such as `gpt-5.4-mini`, records the input cap. `parseCatalog()` checks a catalog read from JSON and throws a `GatewayError` with code `invalid_catalog` that names the first bad field. `createModel()` runs the same check on a catalog you pass, so a typed catalog with tiers out of order or a negative rate throws too.
97
+
98
+ Prices change often, so refresh the shipped catalog before every minor release. Copy each number from the provider's own pricing and model pages, record each page in the entry's `sources`, and set `asOf` to the day you copied them. The repository's CI warns about any shipped entry older than 90 days, and `staleCatalogEntries(catalog, now)` runs the same check on a catalog you maintain.
99
+
100
+ ## You can project a call's cost before you send it
101
+
102
+ `projectCallCost(model, context, options)` returns the most the next call can cost, so a budget can stop a run before the call that would cross its cap. It prices every input token at the highest input rate in its tier, the uncached rate or either cache-write rate, and the full output limit at the output rate: the call's `maxOutputTokens`, or else the model's. The input comes from `estimateInputTokens(context)`. When an earlier assistant message in the context reports its usage, the estimate starts from that request's input and output and adds the messages that came after it. A retried call's `usage` sums every attempt, so the estimate reads its `lastAttemptUsage`, the usage of the one request that produced the message. Otherwise it estimates the whole context from its length in characters. The estimate assumes the system prompt and tools are unchanged since that request, so grow them and the growth goes uncounted. Otherwise each estimate errs high, so a budget errs towards stopping.
103
+
104
+ A caller that holds a token count instead of a `ModelContext` calls `projectCost({ inputTokens, maxOutputTokens }, entry)` directly, with an entry from `findCatalogEntry()`. Both functions use one formula, so they return the same cost for the same tokens.
105
+
106
+ ## One caching option covers every provider
107
+
108
+ The `cacheRetention` stream option sets how long the provider keeps the prompt cache: `"none"`, `"short"` or `"long"`. The gateway passes it to the adapter unchanged, and each adapter maps it to its provider's own cache controls. Leave it out to keep the adapter's default, which is `"short"` for both adapters. OpenAI caches prompts on its own, so the OpenAI-compatible adapter acts on the option only for a model whose flags allow explicit breakpoints or extended retention.
109
+
110
+ ## One tool name works with every provider
111
+
112
+ A tool name must be 1 to 64 characters from `A-Z`, `a-z`, `0-9`, `_` and `-`. This canonical rule is the strictest intersection of the first providers' rules: OpenAI Chat Completions allows 64 characters, and Anthropic Messages allows the same characters at up to 128. [`src/names.md`](src/names.md) lists each provider's rule with its source and the date it was checked, as of November 2026. Names from other sources follow the same rule, so an MCP tool is named `mcp__<server>__<tool>`.
113
+
114
+ `assertCanonicalName(name)` throws a `GatewayError` with code `invalid_tool_name` for a name that breaks the rule. Call it when you define a tool, so a bad name fails there rather than when a provider rejects the request:
115
+
116
+ ```ts
117
+ import { assertCanonicalName } from "@buildanagent/gateway";
118
+
119
+ assertCanonicalName("lookup_customer"); // passes
120
+ assertCanonicalName("lookup customer"); // throws: the space is not allowed
121
+ ```
122
+
123
+ An adapter turns each tool name into its provider's wire name with a `ToolNameMap`, and turns the names the model sends back into your tool names. Build one with `createToolNameMap(rule, names)`, passing the run's tool names, and keep it for the whole run, so every request sends the same wire names and the prompt cache stays valid. `sanitize(name)` gives a tool's wire name, and `restore(wireName)` reverses it. For a name the map never issued, `restore()` returns `undefined`, so a tool the model invented never reaches one of your tools.
124
+
125
+ The map changes a name only when it must. A name the rule accepts keeps itself. Any other name has its disallowed characters replaced by `_`, is cut to fit, and ends in `_` and an 8-digit hash of the name. If that wire name is taken, the map salts the hash: it hashes the name with an attempt counter, counting up until the wire name is free. Because neither provider says whether names are case-sensitive, the map also never issues two wire names that differ only in case. Of two such names passed up front, the one that sorts later is salted. The map sorts the names you pass up front, so their wire names depend only on that set, not on its order. A name that `sanitize()` first sees later keeps itself if the rule accepts it and no issued wire name matches it, ignoring case. Otherwise the map salts it, because the earlier wire name may already have been sent. Every name keeps the wire name it gets first.
126
+
127
+ `TOOL_NAME_RULES` holds the rules of the two first wire protocols. Every canonical name meets both, so with these providers `sanitize()` changes only a name that differs in case alone from another. The map matters for a provider with a stricter rule: pass its `ToolNameRule` to `createToolNameMap()`.
128
+
129
+ ## The Anthropic adapter speaks the Messages API at version 2026-10-21
130
+
131
+ `anthropic({ apiKey })` from `@buildanagent/gateway/anthropic` returns an adapter for Anthropic's Messages API. It calls `fetch` through your `transport`, posts to `{baseURL}/v1/messages`, streams every response, and sends `anthropic-version: 2026-10-21` on every request ([migration to 2026-10-21](https://platform.claude.com/docs/en/api/migration-2026-10-21), as of November 2026):
132
+
133
+ ```ts
134
+ import { createModel } from "@buildanagent/gateway";
135
+ import { anthropic } from "@buildanagent/gateway/anthropic";
136
+
137
+ const model = createModel({ adapter: anthropic({ apiKey }), id: "claude-opus-5-5" });
138
+ ```
139
+
140
+ Version 2026-10-21 returns a 400 for `temperature`, `top_p` or `top_k` at any value, so the adapter never sends them. When you set one, the call streams a `warning` with code `unsupported_option` instead. The same version rejects a `document` block in an assistant message and `citations` on a user text block; the transcript has neither, and the adapter reports the 400 as a `fatal` error if a body you rewrite adds one.
141
+
142
+ Each request runs `transformMessages()` first, so a transcript from any model can be sent. The adapter keeps signed Anthropic thinking in the transcript even for a model whose caps say it does not reason, because the API checks a thinking block against its signature; the caps decide only whether the request asks for thinking. Tool results become `tool_result` blocks, and the results of one turn share one user message. Tool names pass through a `ToolNameMap`, and the names the model sends back are restored.
143
+
144
+ Each tool goes out with `strict: true` when its schema allows it: the adapter adds `additionalProperties: false` to every object and removes the keywords strict mode rejects, such as `minimum` and `maxLength` ([structured outputs, JSON Schema limitations](https://platform.claude.com/docs/en/build-with-claude/structured-outputs), as of November 2026). Optional properties stay optional, because strict mode accepts them, so the model never sends a `null` that lowering added. Two kinds of tool go out without `strict`. The first has a schema strict mode cannot express, such as an object that declares neither `properties` nor `additionalProperties`. The second would push the request past its limits of 20 strict tools, 24 optional properties or 16 union-typed parameters. The SDK still validates every call against your original schema.
145
+
146
+ Caching puts up to three breakpoints, on the system prompt, the last tool and the last block of the last user message, below the API's limit of four. `"short"` asks for the 5-minute cache, `"long"` for the 1-hour cache, and `"none"` sends no breakpoint ([prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching), as of November 2026).
147
+
148
+ ### Usage maps into the four token classes, and the catalog prices it
149
+
150
+ The [Messages API reference](https://platform.claude.com/docs/en/api/messages/create) (as of November 2026) defines total input as the sum of `input_tokens`, `cache_creation_input_tokens` and `cache_read_input_tokens`, so each field maps to one class:
151
+
152
+ | Anthropic `usage` field | `Usage` field |
153
+ | --- | --- |
154
+ | `input_tokens` | `uncachedInput` |
155
+ | `cache_read_input_tokens` | `cacheRead` |
156
+ | `cache_creation.ephemeral_5m_input_tokens` | `cacheWrite["5m"]` |
157
+ | `cache_creation.ephemeral_1h_input_tokens` | `cacheWrite["1h"]` |
158
+ | `output_tokens` | `output` |
159
+ | `output_tokens_details.thinking_tokens` | `reasoning` |
160
+
161
+ Reasoning is counted inside output. The reference calls `output_tokens` "the inclusive, authoritative total used for billing" and says `thinking_tokens` is "always ≤ `output_tokens`". When streaming, `thinking_tokens` arrives only on the final `message_delta` ([extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking), as of November 2026), and the adapter reads it there. A response that reports cache writes without the TTL split counts them at the TTL the request asked for. A stream that sends no usage at all has unreported usage. So does a reply that streams content but never gets a `message_delta` with `output_tokens`, whether it finishes, breaks off or ends in an `error` event. The reason is that `message_start` reports only the first few output tokens, and the final count arrives on `message_delta` ([streaming](https://platform.claude.com/docs/en/build-with-claude/streaming), as of November 2026). A stream that fails before any content block keeps the counts `message_start` reported, because the model produced no output after them.
162
+
163
+ Responses carry no billed price, as of November 2026: the reference's `usage` object holds token counts only. The adapter therefore reports an unknown cost, and `createModel()` prices the usage from the catalog.
164
+
165
+ ### Stop reasons and errors map onto the gateway's
166
+
167
+ `end_turn`, `stop_sequence` and `pause_turn` end with `"stop"`. `pause_turn` adds a `warning`: the provider paused a long-running server-tool turn, and because the adapter drops server-tool blocks, it cannot resume that turn. `tool_use` ends with `"tool_calls"`. `max_tokens` and `model_context_window_exceeded` end with `"length"`, and a tool call cut off by the limit keeps its partial JSON as a string in `input`. A `refusal` ends in a `fatal` error that names the refusal's category.
168
+
169
+ A failed request ends in an `error` terminal, never a throw. The adapter reads the error body's `error.type`, `error.message` and `error.details.error_code`, and `classifyError()` sorts it into the four kinds. An error event inside a stream that already returned 200 classifies like the HTTP status its type stands for, so a mid-stream `overloaded_error` is `retryable` and the gateway retries it while no content has arrived ([errors](https://platform.claude.com/docs/en/api/errors), as of November 2026).
170
+
171
+ ### A changed transcript before a thinking block gets one retry
172
+
173
+ Anthropic's current models check each thinking block you send back against everything before it, and a block fails the check when `system`, `tools` or an earlier message changed after the model wrote it ([prefix checks](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking/prefix-checks), as of November 2026). The adapter handles both outcomes the page describes:
174
+
175
+ - **A 200 that let a failed block through.** Every request sends the `thinking-binding-controls-2026-08-01` beta header, so the response lists each such block in `input_transformations`. Each `thinking_mismatch_allowed` entry becomes a `warning` with code `thinking_mismatch_allowed`.
176
+ - **A 400 that says a block "is bound to a different conversation".** The adapter streams a `warning` with code `thinking_prefix_mismatch` and sends the request once more with `thinking.block_binding.prefix_mismatch_behavior: "drop_block"`. The API applies that setting only to the request that carries it, so the adapter sends it on every later request of the same conversation. If the retry fails the same way, the call ends in a `fatal` error with `code: "thinking_prefix_mismatch"`.
177
+
178
+ The adapter recognises a conversation by a hash of its system prompt and the text of its first message, so two conversations that share both share the `drop_block` setting. The hash records that a message holds an image but not the image's data, so two first messages that differ only in an image also match. Pass `providerOptions: { anthropic: { conversationId } }` to name each conversation yourself, which keeps them apart and also keeps one alive when compaction rewrites its first message. The adapter remembers the 1,000 most recently used conversations that need `drop_block`; one it has forgotten pays one more 400 and is remembered again.
179
+
180
+ `providerOptions.anthropic.extraBody` adds fields to the request body, such as `thinking: { display: "summarized" }` to stream readable reasoning. It cannot change the fields the adapter sets itself: `model`, `max_tokens`, `stream`, `system`, `messages`, `tools` and, for a model with `reasoning: true`, `thinking.type`. An `extraBody` that sets one keeps the adapter's value and streams a `warning` with code `unsupported_option` that names it.
181
+
182
+ The adapter reads the model's caps from `options.caps`, which `createModel()` sets from its catalog, your own catalog included. A `Model`'s options, `ModelCallOptions`, have no `caps` field, and a `caps` passed anyway is replaced. For a model with `reasoning: true`, the adapter sends `thinking: { type: "adaptive" }`. A model the catalog lacks gets the adapter's default caps, which send no thinking setting, so the model's own default applies; a direct `adapter.stream()` call without `caps` gets the same defaults.
183
+
184
+ Headers in `config.headers` are sent with lower-case names. An `anthropic-beta` header is merged with the adapter's beta, and an `x-api-key` or `authorization` header is dropped, so `apiKey` stays the only key sent.
185
+
186
+ ## The OpenAI-compatible adapter speaks Chat Completions to OpenAI and to servers that copy it
187
+
188
+ `openaiChat({ apiKey })` from `@buildanagent/gateway/openai-chat` returns an adapter for OpenAI's Chat Completions API. Many other servers speak the same API, so one adapter serves them too. It calls `fetch` through your `transport`, posts to `{baseURL}/chat/completions`, streams every response, and sends your key as `Authorization: Bearer <apiKey>`. The `baseURL` defaults to `https://api.openai.com/v1`. For another server, set `baseURL`, set `provider` to the name its models have in your catalog, and describe how the server differs with `compat`:
189
+
190
+ ```ts
191
+ import { createModel } from "@buildanagent/gateway";
192
+ import { openaiChat } from "@buildanagent/gateway/openai-chat";
193
+
194
+ const model = createModel({ adapter: openaiChat({ apiKey }), id: "gpt-5.4-mini" });
195
+
196
+ const local = openaiChat({
197
+ apiKey: localKey,
198
+ baseURL: "http://127.0.0.1:8000/v1",
199
+ provider: "local",
200
+ compat: { maxTokensField: "max_tokens" },
201
+ });
202
+ ```
203
+
204
+ The wire format follows OpenAI's [Chat Completions reference](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create) and the types of its TypeScript SDK, [openai-node v7.49.0](https://github.com/openai/openai-node/tree/v7.49.0) (commit `272a6de`), both as of November 2026. The error handling follows OpenAI's [error-code guide](https://developers.openai.com/api/docs/guides/error-codes), except for `context_length_exceeded`: that page doesn't list it, so its wording is unverified.
205
+
206
+ Each request runs `transformMessages()` first, so a transcript from any model can be sent. The body asks for a final usage chunk with `stream_options: { include_usage: true }`, and it sets `max_completion_tokens` from the call's `maxOutputTokens` or the model's caps. The system prompt goes first as a `system` message. Tool calls become an assistant message's `tool_calls`, and each result becomes a `tool` message. A `tool` message holds only text and has no error field. A failed result's text therefore starts with `Error: `, and a result's images follow the turn's results in one user message. The transcript's reasoning is never sent, because a Chat Completions message has no field for it.
207
+
208
+ Each tool goes out with `strict: true` when its schema allows it. Strict mode makes the model follow the schema exactly, so the adapter lists every property in `required` and lets each optional one also be `null`. It also adds `additionalProperties: false` to every object. It keeps the constraints OpenAI's [supported schemas](https://developers.openai.com/api/docs/guides/structured-outputs#supported-schemas) list, such as `minimum`, `pattern` and `maxItems`, and removes the others, such as `maxLength`. When the model answers with `null` for an optional field whose schema does not allow `null`, the adapter removes the field before the call reaches validation, so your tool sees the field left out, as the model meant; inside an `anyOf`, it follows the branch the value fits. The SDK still validates every call against your original schema.
209
+
210
+ A schema strict mode cannot express goes out unchanged without `strict`. Three kinds of schema fall back this way:
211
+
212
+ - a schema whose root is not `type: "object"`;
213
+ - a schema that uses `not`, `allOf`, `prefixItems`, `if`/`then`/`else` or a `dependent*` keyword;
214
+ - a schema over one of OpenAI's size limits, such as 5,000 properties, 10 levels of nesting, 1,000 enum values or 120,000 characters of names and values.
215
+
216
+ ### Compat flags describe how a server differs from OpenAI
217
+
218
+ `compat` sets flags for every model behind the adapter, and `modelCompat` sets them for single models by id, flag by flag over `compat`. Each default is what OpenAI's own API accepts:
219
+
220
+ | Flag | Default | Set it when |
221
+ | --- | --- | --- |
222
+ | `maxTokensField` | `"max_completion_tokens"` | the server reads only `max_tokens` |
223
+ | `systemRole` | `"system"` | the model wants the system prompt as a `developer` message |
224
+ | `streamUsage` | `true` | the server rejects `stream_options`; its replies then report no usage, so their cost is unknown |
225
+ | `strictTools` | `true` | the server rejects `strict` tools |
226
+ | `temperature` | `true` | the model rejects `temperature`; a `temperature` you set then streams a `warning` instead |
227
+ | `cacheBreakpoints` | `false` | the model takes explicit cache breakpoints, as OpenAI's do from `gpt-5.6` |
228
+ | `promptCacheRetention` | `false` | the model offers 24-hour retention through `prompt_cache_retention` |
229
+
230
+ `providerOptions.openaiChat.extraBody` adds fields to the request body, such as `reasoning_effort`, `prompt_cache_key` or `parallel_tool_calls`. It cannot change the fields the adapter sets itself: `model`, `stream`, `stream_options`, `messages`, `tools`, `max_completion_tokens` and `max_tokens`. An `extraBody` value for one of them is not sent, and the call streams a `warning` with code `unsupported_option`.
231
+
232
+ ### Caching follows the model's flags
233
+
234
+ OpenAI caches the start of every prompt on its own, so by default the adapter sends no caching field, whatever `cacheRetention` says. A model with `cacheBreakpoints` gets explicit breakpoints on the system prompt and the newest user or tool message, with the default 30-minute lifetime. `"none"` sends `prompt_cache_options: { mode: "explicit" }` with no breakpoint, which turns caching off. Chat Completions accepts only `"30m"` as `prompt_cache_options.ttl`, and OpenAI's [prompt caching guide](https://developers.openai.com/api/docs/guides/prompt-caching) offers the 12-hour lifetime in the Responses API only, as of November 2026. So `"long"` sends 30-minute breakpoints and streams a `warning`. A model with `promptCacheRetention` gets `prompt_cache_retention: "24h"` for `"long"`.
235
+
236
+ ### Usage maps into the four token classes, and reasoning is counted inside output
237
+
238
+ A chat completion's `usage` counts the whole prompt in `prompt_tokens`, with the cached and the newly written tokens as parts of it. OpenAI's prompt caching guide computes ordinary input as the input tokens less both, and so does the adapter:
239
+
240
+ | Chat Completions `usage` field | `Usage` field |
241
+ | --- | --- |
242
+ | `prompt_tokens` − `cached_tokens` − `cache_write_tokens` | `uncachedInput` |
243
+ | `prompt_tokens_details.cached_tokens` | `cacheRead` |
244
+ | `prompt_tokens_details.cache_write_tokens` | `cacheWrite["5m"]` |
245
+ | `completion_tokens` | `output` |
246
+ | `completion_tokens_details.reasoning_tokens` | `reasoning` |
247
+
248
+ Reasoning is counted inside output: `max_completion_tokens` bounds "visible output tokens and reasoning tokens" together, and the reference says rejected prediction tokens are, "like reasoning tokens", counted in the completion tokens for billing.
249
+
250
+ A reply that ends without the usage chunk has unreported usage, so `createModel()` prices it as unknown. That happens when a server ignores `stream_options`, when `streamUsage` is off, or when a stream fails before the chunk arrives.
251
+
252
+ Chat Completions writes only 30-minute cache entries, so every write counts under `"5m"`, the key for the short cache-write rate, and an OpenAI catalog entry stores its 30-minute rate there. Models before `gpt-5.6` add no cache-write charge, so for `gpt-5.4-mini` that rate is the uncached input rate.
253
+
254
+ Responses carry no billed price, as of November 2026: the usage object holds token counts only. The adapter therefore reports an unknown cost, and `createModel()` prices the usage from the catalog.
255
+
256
+ ### Stop reasons and errors map onto the gateway's
257
+
258
+ `stop` ends with `"stop"`, `tool_calls` with `"tool_calls"`, and `length` with `"length"`, where a tool call cut off by the limit keeps its partial JSON as a string in `input`. A server that ends a reply holding tool calls with `stop` still yields `"tool_calls"`. A `content_filter` finish, or a reply that streams a `refusal`, ends in a `fatal` error with the content that arrived. A compatible server that streams reasoning text as `reasoning_content` or `reasoning` gets an unsigned reasoning block; OpenAI's own models stream none.
259
+
260
+ A failed request ends in an `error` terminal, never a throw. The adapter reads the body's `error.message`, `error.type` and `error.code`, and `classifyError()` sorts it by status, code and type. A billing 429 is `quota`, because retrying won't restore access. Its code names the cause, such as `credit_balance_exhausted` or `project_spend_limit_exceeded`, and its type can be `insufficient_quota`. `context_length_exceeded` is `overflow`. Other 429s, `slow_down` among them, and 5xx errors are `retryable`, and the rest are `fatal`. An error chunk inside a stream that already returned 200 has no status, so it classifies by its type, and a `server_error` is retried while no content has arrived. A stream that closes after its finish reason but without `[DONE]` ends normally, because some compatible servers never send `[DONE]`.
261
+
262
+ Headers in `config.headers` are sent with lower-case names. An `authorization`, `api-key` or `x-api-key` header is dropped, so `apiKey` stays the only key sent. A model the catalog lacks gets the adapter's default caps, which send no images and assume no reasoning.
263
+
264
+ ## Your key is the only key the gateway sends
265
+
266
+ Every adapter takes a `ProviderConfig` whose `apiKey` you pass in. The gateway never reads a key from the environment and never falls back to another credential, so a key left in your shell cannot reach a provider. An adapter made without a key, or with an empty one, throws a `GatewayError` with code `missing_api_key` before it sends anything.
267
+
268
+ ## Retries happen only before the model streams output
269
+
270
+ A call that fails before the model has streamed any content is retried twice by default. The first retry waits 2 seconds and the second waits 4, and each retry streams a `retry` event with the attempt number, the delay and the error. Each wait doubles and is capped at 60 seconds. Set `retries` to change the count, or to 0 to turn retries off.
271
+
272
+ When the provider says how long to wait, the gateway waits at least that long, up to the same 60-second cap. Both adapters read the error response's `retry-after` header, in seconds or as an HTTP date counted from the response's `date` header. They also read `retry-after-ms`, in milliseconds, which the official TypeScript SDKs read first. The hint goes on the message as `error.retryAfterMs`. Before a retry, the gateway waits for the longer of its backoff and the hint, and the `retry` event's `delayMs` shows that wait. Anthropic sends `retry-after` on some 429s ([rate limits](https://platform.claude.com/docs/en/api/rate-limits), as of November 2026). OpenAI sends it on 429s for a temporary rate limit and on 503s for an overloaded model. A hint never makes a `quota`, `overflow` or `fatal` error retryable.
273
+
274
+ A hint longer than the 60-second cap gets no retry. The call ends at once with the `retryable` error and its `retryAfterMs`, and streams no `retry` event, so your code can wait and call again. OpenAI's guide asks for this: when a server delay exceeds your maximum, stop retrying rather than retry sooner ([rate limits](https://developers.openai.com/api/docs/guides/rate-limits), as of November 2026).
275
+
276
+ Three rules keep a retry from doing harm. First, once a content event has reached you, the gateway never retries, because a second attempt would replay text you have already seen. Second, only errors of kind `retryable` are retried, such as a rate limit or an overloaded server. A `quota` error, a context `overflow` or a `fatal` error ends the call at once, because waiting will not fix it. Third, aborting the signal during a wait ends the stream at once with `stopReason: "aborted"`.
277
+
278
+ A failed attempt still costs tokens, so the final message's `usage` and `cost` add up every attempt, not only the last, and `lastAttemptUsage` keeps the last attempt's usage on its own. If any attempt's cost is unknown, the total is unknown too, and if any attempt's usage is unreported, the summed usage is unreported as well. An attempt whose stream threw reported no usage, so it adds no tokens, but its cost is unknown, because the request may have reached the provider and been billed before the stream failed.
279
+
280
+ An adapter whose stream throws, for example on a dropped connection, is treated like one that ends with an error. A failed fetch, or a response body cut off mid-stream, is retried, and any other throw ends the call with a `fatal` error event, so an adapter's failure never makes `stream()` throw. A throwing `onRequest` hook runs inside the attempt, so it also ends the call with a `fatal` error. A middleware that throws runs outside the call, so its error makes `stream()` throw.
281
+
282
+ Adapters sort a failed request into the four kinds, `retryable`, `quota`, `overflow` and `fatal`, with `classifyError()`, from its HTTP status and the provider's error code or message.
283
+
284
+ ## Middleware wraps every call, first one outermost
285
+
286
+ A `ModelMiddleware` can rewrite the request with `transformParams` and watch or change the events with `wrapStream`. With `middleware: [a, b]`, `a` runs first: its `transformParams` sees your request before `b`'s does, and its `wrapStream` wraps `b`'s. Middleware runs once per call, outside the retries, so a `wrapStream` sees the `retry` events too.
287
+
288
+ ## You can see the exact request of every attempt
289
+
290
+ `onPayload` in the stream options lets you inspect or replace the wire body just before an adapter sends it. Return the new body, or `undefined` to send the body unchanged.
291
+
292
+ `onRequest` in `createModel()` receives the full request just before each HTTP request is sent. An Anthropic attempt that retries with `drop_block` sends two HTTP requests, so it is dumped twice under the same attempt number. A `warning` that the adapter streams before it sends, such as the one for `temperature`, doesn't add a dump. Each dump holds the attempt number, the model, the context, the stream options and the wire body after `onPayload`. The dump is a copy, so changing the context after the call doesn't change what it shows. Log it when a step misbehaves, and you see what the provider saw.
293
+
294
+ ## Tests run offline
295
+
296
+ Start each test file with `import "@buildanagent/gateway/testing/setup"`. The setup blocks every request to a host other than your own machine, stops the run if a provider API key is set, and turns real model requests off. Your tests then never reach a real provider by accident.
297
+
298
+ To test an adapter's wire format, pass `mockTransport(api, script)` as its `transport`. The mock answers the n-th request with the n-th scripted response, splits each body into chunks of `chunkSize` bytes or at `splitAt` offsets, and records every request in `requests`. A request past the end of the script throws a `GatewayError` with code `unexpected_request`. `serverSentEvents(events)` writes a list of events as an Anthropic stream body, and `chatCompletionEvents(chunks)` writes Chat Completions chunks followed by `data: [DONE]`:
299
+
300
+ ```ts
301
+ import { mockTransport, serverSentEvents } from "@buildanagent/gateway/testing";
302
+
303
+ const transport = mockTransport("anthropic-messages", [{ body: serverSentEvents(events), chunkSize: 7 }]);
304
+ ```
305
+
306
+ Next: [@buildanagent/sdk](../sdk/README.md), which tests an agent against a scripted model.