@buildanagent/gateway 0.0.0-bootstrap.0 → 0.1.0-alpha.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.
- package/LICENSE +52 -0
- package/LICENSE-APACHE +202 -0
- package/LICENSE-MIT +21 -0
- package/README.md +298 -1
- package/dist/adapters/anthropic/adapter.d.ts +25 -0
- package/dist/adapters/anthropic/adapter.js +183 -0
- package/dist/adapters/anthropic/adapter.js.map +1 -0
- package/dist/adapters/anthropic/failure.d.ts +20 -0
- package/dist/adapters/anthropic/failure.js +46 -0
- package/dist/adapters/anthropic/failure.js.map +1 -0
- package/dist/adapters/anthropic/index.d.ts +3 -0
- package/dist/adapters/anthropic/index.js +3 -0
- package/dist/adapters/anthropic/index.js.map +1 -0
- package/dist/adapters/anthropic/request.d.ts +53 -0
- package/dist/adapters/anthropic/request.js +250 -0
- package/dist/adapters/anthropic/request.js.map +1 -0
- package/dist/adapters/anthropic/response.d.ts +31 -0
- package/dist/adapters/anthropic/response.js +212 -0
- package/dist/adapters/anthropic/response.js.map +1 -0
- package/dist/adapters/anthropic/usage.d.ts +26 -0
- package/dist/adapters/anthropic/usage.js +39 -0
- package/dist/adapters/anthropic/usage.js.map +1 -0
- package/dist/adapters/openai-chat/adapter.d.ts +18 -0
- package/dist/adapters/openai-chat/adapter.js +86 -0
- package/dist/adapters/openai-chat/adapter.js.map +1 -0
- package/dist/adapters/openai-chat/compat.d.ts +58 -0
- package/dist/adapters/openai-chat/compat.js +19 -0
- package/dist/adapters/openai-chat/compat.js.map +1 -0
- package/dist/adapters/openai-chat/failure.d.ts +25 -0
- package/dist/adapters/openai-chat/failure.js +33 -0
- package/dist/adapters/openai-chat/failure.js.map +1 -0
- package/dist/adapters/openai-chat/index.d.ts +4 -0
- package/dist/adapters/openai-chat/index.js +3 -0
- package/dist/adapters/openai-chat/index.js.map +1 -0
- package/dist/adapters/openai-chat/request.d.ts +47 -0
- package/dist/adapters/openai-chat/request.js +227 -0
- package/dist/adapters/openai-chat/request.js.map +1 -0
- package/dist/adapters/openai-chat/response.d.ts +22 -0
- package/dist/adapters/openai-chat/response.js +203 -0
- package/dist/adapters/openai-chat/response.js.map +1 -0
- package/dist/adapters/openai-chat/usage.d.ts +19 -0
- package/dist/adapters/openai-chat/usage.js +22 -0
- package/dist/adapters/openai-chat/usage.js.map +1 -0
- package/dist/adapters/strict-schema.d.ts +67 -0
- package/dist/adapters/strict-schema.js +269 -0
- package/dist/adapters/strict-schema.js.map +1 -0
- package/dist/adapters/wire.d.ts +77 -0
- package/dist/adapters/wire.js +137 -0
- package/dist/adapters/wire.js.map +1 -0
- package/dist/catalog.d.ts +65 -0
- package/dist/catalog.js +145 -0
- package/dist/catalog.js.map +1 -0
- package/dist/catalog.json +120 -0
- package/dist/classify.d.ts +25 -0
- package/dist/classify.js +37 -0
- package/dist/classify.js.map +1 -0
- package/dist/complete.d.ts +9 -0
- package/dist/complete.js +13 -0
- package/dist/complete.js.map +1 -0
- package/dist/cost.d.ts +42 -0
- package/dist/cost.js +122 -0
- package/dist/cost.js.map +1 -0
- package/dist/create-model.d.ts +7 -0
- package/dist/create-model.js +81 -0
- package/dist/create-model.js.map +1 -0
- package/dist/errors.d.ts +17 -0
- package/dist/errors.js +24 -0
- package/dist/errors.js.map +1 -0
- package/dist/index.d.ts +19 -0
- package/dist/index.js +17 -0
- package/dist/index.js.map +1 -0
- package/dist/middleware.d.ts +11 -0
- package/dist/middleware.js +22 -0
- package/dist/middleware.js.map +1 -0
- package/dist/names.d.ts +72 -0
- package/dist/names.js +175 -0
- package/dist/names.js.map +1 -0
- package/dist/provider-config.d.ts +15 -0
- package/dist/provider-config.js +23 -0
- package/dist/provider-config.js.map +1 -0
- package/dist/request-dump.d.ts +28 -0
- package/dist/request-dump.js +52 -0
- package/dist/request-dump.js.map +1 -0
- package/dist/request-policy.d.ts +18 -0
- package/dist/request-policy.js +27 -0
- package/dist/request-policy.js.map +1 -0
- package/dist/retry.d.ts +30 -0
- package/dist/retry.js +191 -0
- package/dist/retry.js.map +1 -0
- package/dist/runtime-types.d.ts +112 -0
- package/dist/runtime-types.js +2 -0
- package/dist/runtime-types.js.map +1 -0
- package/dist/spec.d.ts +67 -0
- package/dist/spec.js +2 -0
- package/dist/spec.js.map +1 -0
- package/dist/sse.d.ts +15 -0
- package/dist/sse.js +73 -0
- package/dist/sse.js.map +1 -0
- package/dist/stream-contract.d.ts +23 -0
- package/dist/stream-contract.js +101 -0
- package/dist/stream-contract.js.map +1 -0
- package/dist/testing/guards.d.ts +16 -0
- package/dist/testing/guards.js +48 -0
- package/dist/testing/guards.js.map +1 -0
- package/dist/testing/index.d.ts +12 -0
- package/dist/testing/index.js +13 -0
- package/dist/testing/index.js.map +1 -0
- package/dist/testing/mock-transport.d.ts +49 -0
- package/dist/testing/mock-transport.js +101 -0
- package/dist/testing/mock-transport.js.map +1 -0
- package/dist/testing/random.d.ts +3 -0
- package/dist/testing/random.js +13 -0
- package/dist/testing/random.js.map +1 -0
- package/dist/testing/setup.d.ts +1 -0
- package/dist/testing/setup.js +12 -0
- package/dist/testing/setup.js.map +1 -0
- package/dist/transform-messages.d.ts +32 -0
- package/dist/transform-messages.js +291 -0
- package/dist/transform-messages.js.map +1 -0
- package/dist/types.d.ts +130 -0
- package/dist/types.js +6 -0
- package/dist/types.js.map +1 -0
- package/dist/usage.d.ts +8 -0
- package/dist/usage.js +20 -0
- package/dist/usage.js.map +1 -0
- package/package.json +53 -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,300 @@
|
|
|
1
1
|
# @buildanagent/gateway
|
|
2
2
|
|
|
3
|
-
|
|
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.
|
|
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 an attempt's stream threw before it reported usage, so `total` is `null`. The gateway never guesses a zero, because a budget that counts an unknown price as free never stops.
|
|
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.
|
|
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 |
|
|
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
|
+
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.
|
|
251
|
+
|
|
252
|
+
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.
|
|
253
|
+
|
|
254
|
+
### Stop reasons and errors map onto the gateway's
|
|
255
|
+
|
|
256
|
+
`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.
|
|
257
|
+
|
|
258
|
+
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]`.
|
|
259
|
+
|
|
260
|
+
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.
|
|
261
|
+
|
|
262
|
+
## Your key is the only key the gateway sends
|
|
263
|
+
|
|
264
|
+
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.
|
|
265
|
+
|
|
266
|
+
## Retries happen only before the model streams output
|
|
267
|
+
|
|
268
|
+
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.
|
|
269
|
+
|
|
270
|
+
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"`.
|
|
271
|
+
|
|
272
|
+
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. 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.
|
|
273
|
+
|
|
274
|
+
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.
|
|
275
|
+
|
|
276
|
+
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.
|
|
277
|
+
|
|
278
|
+
## Middleware wraps every call, first one outermost
|
|
279
|
+
|
|
280
|
+
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.
|
|
281
|
+
|
|
282
|
+
## You can see the exact request of every attempt
|
|
283
|
+
|
|
284
|
+
`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.
|
|
285
|
+
|
|
286
|
+
`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.
|
|
287
|
+
|
|
288
|
+
## Tests run offline
|
|
289
|
+
|
|
290
|
+
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.
|
|
291
|
+
|
|
292
|
+
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]`:
|
|
293
|
+
|
|
294
|
+
```ts
|
|
295
|
+
import { mockTransport, serverSentEvents } from "@buildanagent/gateway/testing";
|
|
296
|
+
|
|
297
|
+
const transport = mockTransport("anthropic-messages", [{ body: serverSentEvents(events), chunkSize: 7 }]);
|
|
298
|
+
```
|
|
299
|
+
|
|
300
|
+
Next: [@buildanagent/sdk](../sdk/README.md), which tests an agent against a scripted model.
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
import type { ProviderConfig } from "../../runtime-types.js";
|
|
2
|
+
import type { ModelAdapter } from "../../spec.js";
|
|
3
|
+
/** The Messages API version every request pins. */
|
|
4
|
+
export declare const ANTHROPIC_VERSION = "2026-10-21";
|
|
5
|
+
/** The beta that adds `thinking.block_binding` and the response's `input_transformations`. */
|
|
6
|
+
export declare const THINKING_BINDING_BETA = "thinking-binding-controls-2026-08-01";
|
|
7
|
+
/**
|
|
8
|
+
* Creates an adapter for Anthropic's Messages API. Every request goes to `{baseURL}/v1/messages` through
|
|
9
|
+
* `config.transport`, streams its response, and sends `anthropic-version: 2026-10-21` and the key from
|
|
10
|
+
* `config.apiKey`, which is the only key it sends. Throws a `GatewayError` with code `missing_api_key` when the key
|
|
11
|
+
* is missing or empty.
|
|
12
|
+
*
|
|
13
|
+
* The model's caps come from `options.caps`, which `createModel()` sets; a direct call without them uses
|
|
14
|
+
* `defaultCaps`. Caller headers from `config.headers` are sent with lower-case names; a caller `anthropic-beta` is
|
|
15
|
+
* merged with the adapter's beta, and a caller `x-api-key` or `authorization` is dropped.
|
|
16
|
+
*
|
|
17
|
+
* `providerOptions.anthropic` takes a `conversationId`, which marks requests of one conversation, and an `extraBody`,
|
|
18
|
+
* whose fields join the request body wherever the adapter sets no field of the same name. Without a
|
|
19
|
+
* `conversationId`, the adapter tells conversations apart by their system prompt and the text of their first
|
|
20
|
+
* message, so conversations that share both also share the `drop_block` setting; pass a `conversationId` for each
|
|
21
|
+
* conversation to keep them apart. The
|
|
22
|
+
* adapter remembers the last 1,000 conversations that needed `drop_block`. `temperature`, `top_p` and `top_k` are
|
|
23
|
+
* never sent, because this API version rejects them; the call streams a `warning` instead.
|
|
24
|
+
*/
|
|
25
|
+
export declare function anthropic(config: ProviderConfig): ModelAdapter;
|