@openllmsh/sdk 0.0.0-stage → 2.10.12-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.
Files changed (245) hide show
  1. package/ARCHITECTURE.md +43 -0
  2. package/LICENSE +202 -0
  3. package/README.md +142 -2
  4. package/assets/openllm-light.svg +18 -0
  5. package/assets/openllm.svg +18 -0
  6. package/client/chat.ts +140 -0
  7. package/client/devices.ts +269 -0
  8. package/client/http.ts +72 -0
  9. package/client/index.ts +129 -0
  10. package/client/relay-mux.ts +547 -0
  11. package/client/types.ts +51 -0
  12. package/client/vault.ts +239 -0
  13. package/connect/chat.ts +58 -0
  14. package/connect/client.ts +240 -0
  15. package/connect/config.ts +47 -0
  16. package/connect/errors.ts +121 -0
  17. package/connect/index.ts +23 -0
  18. package/connect/oauth.ts +265 -0
  19. package/connect/routes.ts +234 -0
  20. package/connect/store.ts +107 -0
  21. package/mcp/handle.ts +24 -0
  22. package/mcp/index.ts +76 -0
  23. package/mcp/server.ts +319 -0
  24. package/mcp/tools/marketplace.ts +439 -0
  25. package/mcp/tools/memory-client.ts +297 -0
  26. package/mcp/tools/memory-config.ts +32 -0
  27. package/mcp/tools/memory.ts +369 -0
  28. package/mcp/tools/model-priority.ts +88 -0
  29. package/mcp/tools/openllm.ts +883 -0
  30. package/mcp/types.ts +28 -0
  31. package/openapi/call.ts +90 -0
  32. package/openapi/index.ts +8 -0
  33. package/openapi/openapi.json +80213 -0
  34. package/openapi/operations.ts +2075 -0
  35. package/package.json +39 -4
  36. package/protocol/CONTRIBUTING.md +21 -0
  37. package/protocol/README.md +134 -0
  38. package/protocol/access.ts +186 -0
  39. package/protocol/agent-prompt-text.ts +32 -0
  40. package/protocol/agent.ts +991 -0
  41. package/protocol/api-key-syntax.ts +105 -0
  42. package/protocol/assets/openllm-light.svg +18 -0
  43. package/protocol/assets/openllm.svg +18 -0
  44. package/protocol/audio.ts +29 -0
  45. package/protocol/auth.ts +142 -0
  46. package/protocol/changelog.ts +155 -0
  47. package/protocol/chat.ts +458 -0
  48. package/protocol/client-registry.ts +356 -0
  49. package/protocol/config.ts +345 -0
  50. package/protocol/control-channel.ts +115 -0
  51. package/protocol/cooldown-reason.ts +78 -0
  52. package/protocol/cost.ts +10 -0
  53. package/protocol/daemon-port.ts +31 -0
  54. package/protocol/daemon.ts +1524 -0
  55. package/protocol/default-chains.ts +66 -0
  56. package/protocol/device-state.ts +85 -0
  57. package/protocol/doctor-report-local.ts +443 -0
  58. package/protocol/doctor-report-policy.ts +119 -0
  59. package/protocol/doctor-report.ts +947 -0
  60. package/protocol/errors.ts +14 -0
  61. package/protocol/execution-selection.ts +141 -0
  62. package/protocol/hop-grant.ts +33 -0
  63. package/protocol/image-edit-parse.ts +263 -0
  64. package/protocol/images.ts +298 -0
  65. package/protocol/index.ts +74 -0
  66. package/protocol/inference-headers.ts +3 -0
  67. package/protocol/keepalive.ts +69 -0
  68. package/protocol/local-auth.ts +300 -0
  69. package/protocol/local-device-control.ts +133 -0
  70. package/protocol/local-provider.ts +288 -0
  71. package/protocol/local-session.ts +118 -0
  72. package/protocol/marketplace.ts +187 -0
  73. package/protocol/media-attempt.ts +81 -0
  74. package/protocol/media-bytes.ts +28 -0
  75. package/protocol/media-default.ts +357 -0
  76. package/protocol/media-dimensions.ts +132 -0
  77. package/protocol/media-input.ts +61 -0
  78. package/protocol/media-model.ts +142 -0
  79. package/protocol/media-option-issue.ts +90 -0
  80. package/protocol/media-types.ts +70 -0
  81. package/protocol/model-match.ts +1051 -0
  82. package/protocol/model-settings.ts +327 -0
  83. package/protocol/models.ts +767 -0
  84. package/protocol/mux.ts +722 -0
  85. package/protocol/plan-surface.ts +59 -0
  86. package/protocol/provider-models.ts +16 -0
  87. package/protocol/provider-status.ts +206 -0
  88. package/protocol/provider-tier.ts +67 -0
  89. package/protocol/provider-usage.ts +263 -0
  90. package/protocol/providers.ts +901 -0
  91. package/protocol/public-usage-index.ts +354 -0
  92. package/protocol/realtime-generated.ts +31 -0
  93. package/protocol/realtime.ts +324 -0
  94. package/protocol/registry-pointer.ts +118 -0
  95. package/protocol/relay.ts +702 -0
  96. package/protocol/replay-session.ts +11 -0
  97. package/protocol/responses.ts +280 -0
  98. package/protocol/semver.ts +182 -0
  99. package/protocol/setup-mode.ts +22 -0
  100. package/protocol/sha256-hex.ts +98 -0
  101. package/protocol/stats.ts +406 -0
  102. package/protocol/streaming.ts +19 -0
  103. package/protocol/subscription-daemon-floors.ts +33 -0
  104. package/protocol/subscription-provider-compat.ts +104 -0
  105. package/protocol/subscription-provider.ts +32 -0
  106. package/protocol/team-grant.ts +17 -0
  107. package/protocol/team-shareable.ts +61 -0
  108. package/protocol/transcription-encoding.ts +76 -0
  109. package/protocol/url-locality-dns.ts +37 -0
  110. package/protocol/url-locality.ts +288 -0
  111. package/protocol/usage-snapshots.ts +9 -0
  112. package/protocol/vendor-cli-install.ts +29 -0
  113. package/protocol/video-job-plan.ts +50 -0
  114. package/protocol/videos.ts +227 -0
  115. package/tsconfig.json +14 -0
  116. package/tunnel/ARCHITECTURE.md +111 -0
  117. package/tunnel/LICENSE +33 -0
  118. package/tunnel/README.md +45 -0
  119. package/tunnel/assets/openllm-light.svg +18 -0
  120. package/tunnel/assets/openllm.svg +18 -0
  121. package/tunnel/channel-envelope.ts +139 -0
  122. package/tunnel/codec.ts +191 -0
  123. package/tunnel/device-anchor.ts +229 -0
  124. package/tunnel/device-control.ts +118 -0
  125. package/tunnel/device-grant.ts +173 -0
  126. package/tunnel/fleet.ts +77 -0
  127. package/tunnel/index.ts +22 -0
  128. package/tunnel/mux.ts +580 -0
  129. package/tunnel/peer-link.ts +390 -0
  130. package/tunnel/rtc-auth.ts +415 -0
  131. package/tunnel/rtc-duplex.ts +187 -0
  132. package/tunnel/rtc-ice.ts +136 -0
  133. package/tunnel/secure.ts +1298 -0
  134. package/tunnel/stream-reset-error.ts +14 -0
  135. package/tunnel/streams.ts +1430 -0
  136. package/tunnel/team-grant.ts +302 -0
  137. package/tunnel/wire-bytes.ts +102 -0
  138. package/vault/ARCHITECTURE.md +470 -0
  139. package/vault/LICENSE +33 -0
  140. package/vault/api-key.ts +190 -0
  141. package/vault/argon2.ts +106 -0
  142. package/vault/cli-auth-seal.ts +157 -0
  143. package/vault/cred-seal.ts +146 -0
  144. package/vault/credential.ts +55 -0
  145. package/vault/crypto.ts +210 -0
  146. package/vault/daemon-attest.ts +229 -0
  147. package/vault/derive.ts +113 -0
  148. package/vault/device-access.ts +87 -0
  149. package/vault/device-anchor.ts +185 -0
  150. package/vault/device-control.ts +174 -0
  151. package/vault/handoff.ts +396 -0
  152. package/vault/index.ts +21 -0
  153. package/vault/passkey.ts +243 -0
  154. package/vault/phrase.ts +65 -0
  155. package/vault/pin.ts +153 -0
  156. package/vault/public-key-seal.ts +131 -0
  157. package/vault/seed.ts +272 -0
  158. package/vault/team.ts +355 -0
  159. package/vault/vault-item.ts +131 -0
  160. package/vault/vault-migrate-digest.ts +29 -0
  161. package/vault/wrapped.ts +77 -0
  162. package/wire/ARCHITECTURE.md +90 -0
  163. package/wire/CONTRIBUTING.md +19 -0
  164. package/wire/LICENSE +33 -0
  165. package/wire/README.md +51 -0
  166. package/wire/adapters/messages/anthropic-map.ts +37 -0
  167. package/wire/adapters/messages/index.ts +7 -0
  168. package/wire/adapters/messages/reasoning-from-items.ts +38 -0
  169. package/wire/adapters/messages/reasoning-signature.ts +243 -0
  170. package/wire/adapters/messages/request.ts +574 -0
  171. package/wire/adapters/messages/response.ts +215 -0
  172. package/wire/adapters/messages/streaming.ts +1027 -0
  173. package/wire/adapters/messages/usage.ts +43 -0
  174. package/wire/adapters/responses/index.ts +3 -0
  175. package/wire/adapters/responses/request.ts +395 -0
  176. package/wire/adapters/responses/response.ts +88 -0
  177. package/wire/adapters/responses/streaming.ts +344 -0
  178. package/wire/assets/openllm-light.svg +18 -0
  179. package/wire/assets/openllm.svg +18 -0
  180. package/wire/features/account-rank.ts +166 -0
  181. package/wire/features/compaction/compact-request.ts +862 -0
  182. package/wire/features/compaction/compaction-text.ts +43 -0
  183. package/wire/features/context-demote.ts +47 -0
  184. package/wire/features/context-overflow-strategy.ts +26 -0
  185. package/wire/features/context-skip.ts +170 -0
  186. package/wire/features/conversation-affinity.ts +144 -0
  187. package/wire/features/max-tokens-backfill.ts +141 -0
  188. package/wire/features/model-caps.ts +53 -0
  189. package/wire/features/model-settings.ts +24 -0
  190. package/wire/features/output-limit-clamp.ts +64 -0
  191. package/wire/features/quota-gate.ts +85 -0
  192. package/wire/index.ts +44 -0
  193. package/wire/lib/attempt-outcome.ts +43 -0
  194. package/wire/lib/canonical/content-part.ts +38 -0
  195. package/wire/lib/canonical/count-tokens-capability.ts +138 -0
  196. package/wire/lib/canonical/encoding-select.ts +82 -0
  197. package/wire/lib/canonical/image-signature.ts +202 -0
  198. package/wire/lib/canonical/image-sse.ts +216 -0
  199. package/wire/lib/canonical/message.ts +43 -0
  200. package/wire/lib/canonical/token-estimate.ts +266 -0
  201. package/wire/lib/encrypted-content.ts +66 -0
  202. package/wire/lib/error-class.ts +154 -0
  203. package/wire/lib/error-envelope.ts +56 -0
  204. package/wire/lib/forwarded-headers.ts +180 -0
  205. package/wire/lib/provider-error-rules.ts +48 -0
  206. package/wire/lib/refusal.ts +38 -0
  207. package/wire/lib/responses-apply-patch.ts +104 -0
  208. package/wire/lib/responses-namespace.ts +53 -0
  209. package/wire/lib/secret-scrub.ts +101 -0
  210. package/wire/lib/streaming/accumulate.ts +221 -0
  211. package/wire/lib/streaming/finish-reason.ts +33 -0
  212. package/wire/lib/streaming/peek.ts +154 -0
  213. package/wire/lib/streaming/provider-decode.ts +259 -0
  214. package/wire/lib/streaming/response-stream.ts +71 -0
  215. package/wire/lib/streaming/sse.ts +699 -0
  216. package/wire/lib/streaming/strip-tool-calls.ts +95 -0
  217. package/wire/lib/streaming/upstream-error.ts +58 -0
  218. package/wire/lib/strip-subagent-isolation.ts +284 -0
  219. package/wire/lib/thinking-signature.ts +156 -0
  220. package/wire/lib/token-ruler/bpe-core.ts +426 -0
  221. package/wire/lib/token-ruler/index.ts +2 -0
  222. package/wire/lib/token-ruler/ruler.ts +79 -0
  223. package/wire/lib/token-ruler/vocab/claude-ranks.ts +16 -0
  224. package/wire/lib/token-ruler/vocab/claude.ts +22 -0
  225. package/wire/lib/token-ruler/vocab/o200k-ranks.ts +18 -0
  226. package/wire/lib/token-ruler/vocab/o200k.ts +19 -0
  227. package/wire/lib/tool-name-map.ts +271 -0
  228. package/wire/lib/tool-schema.ts +353 -0
  229. package/wire/lib/usage-observer.ts +125 -0
  230. package/wire/providers/anthropic/adaptive-thinking.ts +291 -0
  231. package/wire/providers/anthropic/beta-headers.ts +165 -0
  232. package/wire/providers/anthropic/index.ts +10 -0
  233. package/wire/providers/anthropic/request.ts +607 -0
  234. package/wire/providers/anthropic/response.ts +155 -0
  235. package/wire/providers/anthropic/streaming.ts +315 -0
  236. package/wire/providers/anthropic/web-search-domains.ts +49 -0
  237. package/wire/providers/chatgpt/common.ts +136 -0
  238. package/wire/providers/chatgpt/index.ts +9 -0
  239. package/wire/providers/chatgpt/request.ts +959 -0
  240. package/wire/providers/chatgpt/streaming.ts +1007 -0
  241. package/wire/providers/chatgpt/web-search.ts +63 -0
  242. package/wire/providers/grok/web-search.ts +87 -0
  243. package/wire/providers/kimi/web-search.ts +145 -0
  244. package/wire/providers/upstream-deny.ts +355 -0
  245. package/wire/providers/upstream-request.ts +619 -0
@@ -0,0 +1,458 @@
1
+ import { Schema as S } from "effect";
2
+
3
+ /**
4
+ * OpenAI-compatible reasoning effort. Shared by chat `reasoning_effort`
5
+ * and Responses `reasoning.effort` so Codex values like `xhigh` decode
6
+ * on both inbound surfaces. Downstream providers may still clamp.
7
+ */
8
+ export const ReasoningEffort = S.Literals([
9
+ "minimal",
10
+ "low",
11
+ "medium",
12
+ "high",
13
+ "xhigh",
14
+ "max",
15
+ "none",
16
+ ]);
17
+ export type TReasoningEffort = S.Schema.Type<typeof ReasoningEffort>;
18
+
19
+ const FunctionCall = S.Struct({
20
+ name: S.String,
21
+ arguments: S.String,
22
+ });
23
+
24
+ const ToolCall = S.Struct({
25
+ id: S.String,
26
+ type: S.Literals(["function"]),
27
+ function: FunctionCall,
28
+ });
29
+ export type TToolCall = S.Schema.Type<typeof ToolCall>;
30
+
31
+ /**
32
+ * Prompt-cache breakpoint. OpenAI-format clients (and LiteLLM's
33
+ * `ChatCompletionCachedContent`) mark a content block / message / tool
34
+ * with `cache_control: {type:"ephemeral"}` to make everything up to and
35
+ * including it a cacheable prefix on the Anthropic wire. Dropping it
36
+ * silently disables prompt caching → ~10x token cost on agent loops.
37
+ */
38
+ const CacheControl = S.Struct({ type: S.Literals(["ephemeral"]) });
39
+ export type TCacheControl = S.Schema.Type<typeof CacheControl>;
40
+
41
+ const TextPart = S.Struct({
42
+ type: S.Literals(["text"]),
43
+ text: S.String,
44
+ cache_control: S.optional(S.NullOr(CacheControl)),
45
+ });
46
+
47
+ const ImageUrlPart = S.Struct({
48
+ type: S.Literals(["image_url"]),
49
+ image_url: S.Struct({
50
+ url: S.String,
51
+ detail: S.optional(S.Literals(["auto", "low", "high"])),
52
+ }),
53
+ cache_control: S.optional(S.NullOr(CacheControl)),
54
+ });
55
+
56
+ const InputAudioPart = S.Struct({
57
+ type: S.Literals(["input_audio"]),
58
+ input_audio: S.Struct({
59
+ data: S.String,
60
+ format: S.Literals(["wav", "mp3"]),
61
+ }),
62
+ });
63
+
64
+ /**
65
+ * OpenAI-native file attachment (PDFs etc.). `file_data` is a data URL
66
+ * (`data:<mime>;base64,<b64>`); `file_id` references a provider-side
67
+ * uploaded file. `url` is a public file URL and is treated as a clean-context
68
+ * document carrier (no bytes are placed on the request body).
69
+ * The canonical carrier for Anthropic `document` blocks on
70
+ * cross-provider hops.
71
+ */
72
+ const FilePart = S.Struct({
73
+ type: S.Literals(["file"]),
74
+ file: S.Struct({
75
+ file_data: S.optional(S.String),
76
+ file_id: S.optional(S.String),
77
+ filename: S.optional(S.String),
78
+ url: S.optional(S.String),
79
+ }),
80
+ cache_control: S.optional(S.NullOr(CacheControl)),
81
+ });
82
+ export type TFilePart = S.Schema.Type<typeof FilePart>;
83
+
84
+ const ContentPart = S.Union([TextPart, ImageUrlPart, InputAudioPart, FilePart]);
85
+
86
+ const MessageContent = S.Union([S.String, S.Array(ContentPart)]);
87
+
88
+ const SystemMessage = S.Struct({
89
+ role: S.Literals(["system"]),
90
+ content: MessageContent,
91
+ name: S.optional(S.String),
92
+ cache_control: S.optional(S.NullOr(CacheControl)),
93
+ });
94
+
95
+ const UserMessage = S.Struct({
96
+ role: S.Literals(["user"]),
97
+ content: MessageContent,
98
+ name: S.optional(S.String),
99
+ cache_control: S.optional(S.NullOr(CacheControl)),
100
+ });
101
+
102
+ /**
103
+ * One PROVIDER-executed (hosted/server-side) web search that ran inside the
104
+ * upstream turn — e.g. Codex hosted `web_search` on a chatgpt native hop.
105
+ * Canonical and wire-neutral: client wires re-encode it (Anthropic →
106
+ * `server_tool_use` + `web_search_tool_result` blocks and
107
+ * `usage.server_tool_use.web_search_requests`). The gateway never executes
108
+ * anything to produce one of these — it only REPORTS what the provider did;
109
+ * result contents stay provider-internal (only the queries are visible).
110
+ */
111
+ export const ServerSearchCall = S.Struct({
112
+ /** Provider item id (e.g. Codex `ws_…`) — becomes the block id. */
113
+ id: S.String,
114
+ /** The primary query the provider searched. */
115
+ query: S.String,
116
+ /** Fan-out queries when the provider reports them (Codex `action.queries`). */
117
+ queries: S.optional(S.Array(S.String)),
118
+ /** Source links when the provider reports them (grok `action.sources`) —
119
+ * re-encoded as the search block's result items so clients get real URLs. */
120
+ results: S.optional(
121
+ S.Array(S.Struct({ url: S.String, title: S.optional(S.String) })),
122
+ ),
123
+ });
124
+ export type TServerSearchCall = S.Schema.Type<typeof ServerSearchCall>;
125
+
126
+ /**
127
+ * Response-only assistant fields the decoder used to discard: `annotations`
128
+ * (web-search URL citations) and `audio` (the audio output object, or on a
129
+ * replayed turn the `{id}` reference to it).
130
+ *
131
+ * Typed as `S.Unknown` ON PURPOSE. Modelling their exact shapes would make the
132
+ * decoder STRICTER than the baseline it replaces: today an unknown value in
133
+ * either field is stripped and the request is served, whereas a literal/struct
134
+ * schema would turn the same body into a 400. Preserving the value is the
135
+ * whole fix — validating it is not this gateway's job, and a new rejection on
136
+ * a previously-served request is a regression whatever the spec says.
137
+ */
138
+ const AssistantMessage = S.Struct({
139
+ role: S.Literals(["assistant"]),
140
+ content: S.optional(S.NullOr(MessageContent)),
141
+ name: S.optional(S.String),
142
+ tool_calls: S.optional(S.Array(ToolCall)),
143
+ refusal: S.optional(S.NullOr(S.String)),
144
+ /** Hosted web-search citations — carried, never validated (see above). */
145
+ annotations: S.optional(S.Unknown),
146
+ /** Audio output / audio history reference — carried, never validated. */
147
+ audio: S.optional(S.Unknown),
148
+ /** LiteLLM / OpenAI Responses → chat stream (`reasoning_content` deltas). */
149
+ reasoning_content: S.optional(S.NullishOr(S.String)),
150
+ /** Terminal `response.completed` reasoning round-trip (LiteLLM `Delta.reasoning_items`). */
151
+ reasoning_items: S.optional(S.NullishOr(S.Array(S.Unknown))),
152
+ /** Provider-executed hosted web searches this turn (see `ServerSearchCall`).
153
+ * Optional on inbound history replay too — the gateway emits it, so it must
154
+ * also decode on the way back in (#181). */
155
+ server_search_calls: S.optional(S.NullishOr(S.Array(ServerSearchCall))),
156
+ cache_control: S.optional(S.NullOr(CacheControl)),
157
+ });
158
+
159
+ const ToolMessage = S.Struct({
160
+ role: S.Literals(["tool"]),
161
+ content: MessageContent,
162
+ tool_call_id: S.String,
163
+ cache_control: S.optional(S.NullOr(CacheControl)),
164
+ });
165
+
166
+ export const ChatMessage = S.Union([
167
+ SystemMessage,
168
+ UserMessage,
169
+ AssistantMessage,
170
+ ToolMessage,
171
+ ]);
172
+ export type TChatMessage = S.Schema.Type<typeof ChatMessage>;
173
+
174
+ const FunctionDef = S.Struct({
175
+ name: S.String,
176
+ description: S.optional(S.String),
177
+ parameters: S.optional(S.Unknown),
178
+ strict: S.optional(S.Boolean),
179
+ });
180
+
181
+ const Tool = S.Struct({
182
+ type: S.Literals(["function"]),
183
+ function: FunctionDef,
184
+ cache_control: S.optional(S.NullOr(CacheControl)),
185
+ });
186
+
187
+ const ToolChoiceLiteral = S.Literals(["none", "auto", "required"]);
188
+
189
+ const ToolChoiceFunction = S.Struct({
190
+ type: S.Literals(["function"]),
191
+ function: S.Struct({ name: S.String }),
192
+ });
193
+
194
+ const ToolChoice = S.Union([ToolChoiceLiteral, ToolChoiceFunction]);
195
+
196
+ const ResponseFormat = S.Union([
197
+ S.Struct({ type: S.Literals(["text"]) }),
198
+ S.Struct({ type: S.Literals(["json_object"]) }),
199
+ S.Struct({
200
+ type: S.Literals(["json_schema"]),
201
+ json_schema: S.Struct({
202
+ name: S.String,
203
+ description: S.optional(S.String),
204
+ schema: S.optional(S.Unknown),
205
+ strict: S.optional(S.Boolean),
206
+ }),
207
+ }),
208
+ ]);
209
+
210
+ export const ChatCompletionRequest = S.Struct({
211
+ model: S.String,
212
+ messages: S.Array(ChatMessage),
213
+ temperature: S.optional(S.Number),
214
+ top_p: S.optional(S.Number),
215
+ top_k: S.optional(S.Number),
216
+ n: S.optional(S.Number),
217
+ stream: S.optional(S.Boolean),
218
+ stop: S.optional(S.Union([S.String, S.Array(S.String)])),
219
+ max_tokens: S.optional(S.Number),
220
+ max_completion_tokens: S.optional(S.Number),
221
+ presence_penalty: S.optional(S.Number),
222
+ frequency_penalty: S.optional(S.Number),
223
+ logit_bias: S.optional(S.Record(S.String, S.Number)),
224
+ logprobs: S.optional(S.Boolean),
225
+ top_logprobs: S.optional(S.Number),
226
+ seed: S.optional(S.Number),
227
+ user: S.optional(S.String),
228
+ tools: S.optional(S.Array(Tool)),
229
+ tool_choice: S.optional(ToolChoice),
230
+ parallel_tool_calls: S.optional(S.Boolean),
231
+ /**
232
+ * Opaque carrier for the inbound Responses-API `tools` array (Codex's
233
+ * built-in tools: `custom` apply_patch, `web_search`, `image_generation`,
234
+ * `tool_search`, alongside `function` tools). Canonical models only function
235
+ * tools, so a Responses→chatgpt round-trip (Codex → daemon → chatgpt.com)
236
+ * would otherwise lose them; this carries the ORIGINAL set verbatim and
237
+ * `toChatGptRequest` re-emits it. Set by `fromResponsesRequest`, read ONLY by
238
+ * `toChatGptRequest`, and STRIPPED before every openai-family upstream (it is
239
+ * not a real OpenAI field). Mirrors `reasoning_items` (opaque Responses
240
+ * carrier). See `@openllmsh/sdk/wire/adapters/responses`.
241
+ */
242
+ responses_tools: S.optional(S.Array(S.Unknown)),
243
+ /**
244
+ * Opaque carrier for leading Responses-API `input` items with
245
+ * `type:"additional_tools"`. Codex v0.147 puts harness-owned namespace and
246
+ * custom tools here, not in top-level `tools`; their position and payload are
247
+ * part of the upstream contract. `fromResponsesRequest` preserves the whole
248
+ * item and `toChatGptRequest` prepends it back to `input`, while every
249
+ * non-ChatGPT upstream strips this carrier.
250
+ */
251
+ responses_additional_tools: S.optional(S.Array(S.Unknown)),
252
+ /**
253
+ * Opaque Responses `client_metadata`, currently used to carry Codex's
254
+ * authoritative Responses-Lite marker. It is restored only for the ChatGPT
255
+ * wire and stripped before every other upstream.
256
+ */
257
+ responses_client_metadata: S.optional(S.Unknown),
258
+ stream_options: S.optional(
259
+ S.Struct({
260
+ include_usage: S.optional(S.Boolean),
261
+ /**
262
+ * Stream obfuscation (pinned spec). Padding characters on each delta to
263
+ * normalise payload sizes against a size side-channel. Modelled so a
264
+ * caller that DISABLES it keeps that choice — silently dropping it
265
+ * re-enabled a mitigation the caller explicitly turned off.
266
+ */
267
+ include_obfuscation: S.optional(S.Unknown),
268
+ }),
269
+ ),
270
+ response_format: S.optional(ResponseFormat),
271
+ /**
272
+ * Documented Chat Completions parameters the decoder previously dropped, so
273
+ * an explicit caller choice never reached the upstream that honours it. Each
274
+ * is verified present on the pinned `openai/openai-openapi` surface
275
+ * (`tests/helpers/fixtures/openai-chat-surface.json`); the conformance suite
276
+ * `tests/protocol/openai-chat-surface.test.ts` records a disposition for
277
+ * every one and fails when the spec grows a field with no entry.
278
+ *
279
+ * ALL typed `S.Unknown`, deliberately. The gap being fixed is that these
280
+ * values were DISCARDED, not that they were unvalidated — and a literal or
281
+ * struct schema would make the decoder stricter than the baseline it
282
+ * replaces, turning bodies that are served today into 400s. Carrying the
283
+ * value verbatim fixes the loss without moving the acceptance boundary; the
284
+ * upstream that owns each parameter remains the one that validates it.
285
+ *
286
+ * They are carried, not interpreted: `finalizeUpstreamBody`'s per-wire deny
287
+ * decides which survive a given hop, and `droppedSignalParams` reports the
288
+ * rest on `x-openllm-dropped-params` rather than letting them vanish.
289
+ */
290
+ service_tier: S.optional(S.Unknown),
291
+ store: S.optional(S.Unknown),
292
+ verbosity: S.optional(S.Unknown),
293
+ safety_identifier: S.optional(S.Unknown),
294
+ prompt_cache_retention: S.optional(S.Unknown),
295
+ web_search_options: S.optional(S.Unknown),
296
+ modalities: S.optional(S.Unknown),
297
+ audio: S.optional(S.Unknown),
298
+ prediction: S.optional(S.Unknown),
299
+ // Full OpenAI-compatible enum (matches LiteLLM's accepted set so we
300
+ // can translate the same range of efforts that `gpt-5` / Claude
301
+ // canonical clients ship). `none` explicitly disables thinking.
302
+ reasoning_effort: S.optional(ReasoningEffort),
303
+ metadata: S.optional(S.Record(S.String, S.String)),
304
+ /**
305
+ * OpenAI prompt-cache routing hint. A stable value across the turns of one
306
+ * conversation routes them to the same cache machine, raising the cache-hit
307
+ * rate (and, for subscription providers like Codex, cutting quota burn). A
308
+ * real OpenAI field — forwarded verbatim to openai-family upstreams and
309
+ * emitted by `toChatGptRequest` for the chatgpt/Codex wire (synthesized from
310
+ * the conversation prefix when the caller doesn't supply one). Set by
311
+ * `fromResponsesRequest` when a Codex client already carries it.
312
+ */
313
+ prompt_cache_key: S.optional(S.String),
314
+ });
315
+ export type TChatCompletionRequest = S.Schema.Type<
316
+ typeof ChatCompletionRequest
317
+ >;
318
+
319
+ export const Usage = S.Struct({
320
+ prompt_tokens: S.Number,
321
+ completion_tokens: S.Number,
322
+ total_tokens: S.Number,
323
+ prompt_tokens_details: S.optional(
324
+ S.Struct({
325
+ cached_tokens: S.optional(S.Number),
326
+ cache_creation_tokens: S.optional(S.Number),
327
+ audio_tokens: S.optional(S.Number),
328
+ }),
329
+ ),
330
+ completion_tokens_details: S.optional(
331
+ S.Struct({
332
+ reasoning_tokens: S.optional(S.Number),
333
+ audio_tokens: S.optional(S.Number),
334
+ accepted_prediction_tokens: S.optional(S.Number),
335
+ rejected_prediction_tokens: S.optional(S.Number),
336
+ }),
337
+ ),
338
+ });
339
+ export type TUsage = S.Schema.Type<typeof Usage>;
340
+
341
+ const FinishReason = S.Literals([
342
+ "stop",
343
+ "length",
344
+ "content_filter",
345
+ "tool_calls",
346
+ "function_call",
347
+ ]);
348
+
349
+ const ChatChoice = S.Struct({
350
+ index: S.Number,
351
+ message: AssistantMessage,
352
+ finish_reason: S.NullOr(FinishReason),
353
+ logprobs: S.optional(S.NullOr(S.Unknown)),
354
+ });
355
+
356
+ export const ChatCompletionResponse = S.Struct({
357
+ id: S.String,
358
+ object: S.Literals(["chat.completion"]),
359
+ created: S.Number,
360
+ model: S.String,
361
+ choices: S.Array(ChatChoice),
362
+ usage: Usage,
363
+ system_fingerprint: S.optional(S.NullOr(S.String)),
364
+ /**
365
+ * Response metadata the decoder previously discarded. `service_tier` is the
366
+ * tier that ACTUALLY served the request (it can differ from the requested
367
+ * one, which is the only way a caller learns their `priority` request was
368
+ * served on `default`); `moderation` carries moderated-completion results;
369
+ * `metadata` echoes the request's key/value map. Opaque `moderation` on
370
+ * purpose — it is OpenAI's own result object and the gateway re-emits it
371
+ * verbatim rather than modelling a surface it does not interpret.
372
+ */
373
+ service_tier: S.optional(S.Unknown),
374
+ metadata: S.optional(S.Unknown),
375
+ moderation: S.optional(S.Unknown),
376
+ });
377
+ export type TChatCompletionResponse = S.Schema.Type<
378
+ typeof ChatCompletionResponse
379
+ >;
380
+
381
+ // OpenAI-compatible providers (Alibaba DashScope / qwen, Kimi, etc.)
382
+ // don't strictly follow OpenAI's wire shape: continuation chunks may
383
+ // omit `finish_reason` entirely and set every "this isn't set this
384
+ // chunk" field to `null` (rather than dropping the key). If we treat
385
+ // these as schema violations the chunk is silently dropped at the
386
+ // `providerEventStream` decoder and the tool-call argument fragment it
387
+ // was carrying is lost — observed in prod as `Edit` / `Bash` called
388
+ // with missing required parameters (`command`, `file_path`, …) and
389
+ // `/compact` failing with "no valid text content" when the only
390
+ // surviving chunk is the terminal one.
391
+ //
392
+ // `S.NullishOr(X)` ≡ `X | null | undefined` and pairs with
393
+ // `S.optional(...)` to accept (1) absent, (2) explicit-null, and
394
+ // (3) the wanted type. Every nullable-by-OpenAI field uses it.
395
+ const ChatChunkDelta = S.Struct({
396
+ role: S.optional(S.NullishOr(S.Literals(["assistant"]))),
397
+ content: S.optional(S.NullishOr(S.String)),
398
+ tool_calls: S.optional(
399
+ S.NullishOr(
400
+ S.Array(
401
+ S.Struct({
402
+ index: S.Number,
403
+ id: S.optional(S.NullishOr(S.String)),
404
+ type: S.optional(
405
+ S.NullishOr(S.Literals(["function", "builtin_function"])),
406
+ ),
407
+ function: S.optional(
408
+ S.NullishOr(
409
+ S.Struct({
410
+ name: S.optional(S.NullishOr(S.String)),
411
+ arguments: S.optional(S.NullishOr(S.String)),
412
+ }),
413
+ ),
414
+ ),
415
+ }),
416
+ ),
417
+ ),
418
+ ),
419
+ refusal: S.optional(S.NullishOr(S.String)),
420
+ reasoning_content: S.optional(S.NullishOr(S.String)),
421
+ reasoning_items: S.optional(S.NullishOr(S.Array(S.Unknown))),
422
+ /** Provider-executed hosted web searches, emitted once per completed
423
+ * provider search item (see `ServerSearchCall`). */
424
+ server_search_calls: S.optional(S.NullishOr(S.Array(ServerSearchCall))),
425
+ });
426
+
427
+ const ChatChunkChoice = S.Struct({
428
+ index: S.Number,
429
+ delta: ChatChunkDelta,
430
+ // `finish_reason` is *optional* on continuation chunks for many
431
+ // OpenAI-compatible providers (qwen3-coder, kimi, ...) — only the
432
+ // terminal chunk carries it. `S.optional(S.NullishOr(...))` lets it
433
+ // be absent, null, or a real reason without dropping the chunk.
434
+ finish_reason: S.optional(S.NullishOr(FinishReason)),
435
+ logprobs: S.optional(S.NullishOr(S.Unknown)),
436
+ });
437
+
438
+ export const ChatCompletionChunk = S.Struct({
439
+ id: S.String,
440
+ object: S.Literals(["chat.completion.chunk"]),
441
+ created: S.Number,
442
+ model: S.String,
443
+ choices: S.Array(ChatChunkChoice),
444
+ usage: S.optional(S.NullOr(Usage)),
445
+ system_fingerprint: S.optional(S.NullOr(S.String)),
446
+ /**
447
+ * Per-chunk metadata the decoder previously discarded. `obfuscation` is the
448
+ * side-channel padding string the caller opted into via
449
+ * `stream_options.include_obfuscation` — re-emitting it is what makes that
450
+ * opt-in real end to end, since a mitigation the gateway strips is no
451
+ * mitigation. `service_tier` / `moderation` mirror the non-streaming
452
+ * response.
453
+ */
454
+ obfuscation: S.optional(S.Unknown),
455
+ service_tier: S.optional(S.Unknown),
456
+ moderation: S.optional(S.Unknown),
457
+ });
458
+ export type TChatCompletionChunk = S.Schema.Type<typeof ChatCompletionChunk>;