@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,1007 @@
1
+ import type {
2
+ TChatCompletionChunk,
3
+ TChatGptProviderOptions,
4
+ TServerSearchCall,
5
+ } from "@openllmsh/sdk/protocol";
6
+ import type { TReasoningItem } from "../../adapters/messages/reasoning-signature";
7
+ import { buildReasoningItem } from "../../adapters/messages/reasoning-signature";
8
+ import { canonicalToolNameOf } from "../../lib/responses-namespace";
9
+ import { UpstreamStreamError } from "../../lib/streaming/upstream-error";
10
+
11
+ // runtime-only: Responses API events arrive as freeform JSON dicts. We
12
+ // hand-discriminate on the `type` field. A typed Schema would have to
13
+ // enumerate every Responses API event the chatgpt.com endpoint emits,
14
+ // which drifts often — Schema.Unknown + structural checks is more
15
+ // resilient and matches LiteLLM's `chunk_parser` strategy.
16
+ export type TChatGptStreamEvent = Record<string, unknown>;
17
+
18
+ // runtime-only: per-stream state. We track whether we have observed
19
+ // any tool-call output item so that the final `response.completed`
20
+ // event can choose `finish_reason: "tool_calls"` even when the
21
+ // terminal event's `response.output` payload omits the tool-call
22
+ // entries (which we have seen in practice on `gpt-5.x-codex`).
23
+ //
24
+ // `reasoningItems` collects every `reasoning` output item (keyed by its
25
+ // `id`, insertion-ordered) as it streams. Codex emits these with
26
+ // `encrypted_content` when the request set
27
+ // `include: ["reasoning.encrypted_content"]`; they MUST be echoed back
28
+ // next turn or the model loops forever.
29
+ //
30
+ // Codex output order is `reasoning` → `function_call`, and the reasoning
31
+ // item's full `encrypted_content` lands on its `response.output_item.done`
32
+ // BEFORE the function call streams. We emit `delta.reasoning_items` right
33
+ // there so the Anthropic adapter can attach the `signature` to the
34
+ // still-open thinking block (Anthropic requires `signature_delta` to be
35
+ // the thinking block's last delta, before any tool_use block opens).
36
+ // `response.completed` re-folds `response.output[]` as a fallback for
37
+ // responses that omit per-item `.done`. `emittedReasoningIds` dedupes so
38
+ // a given item round-trips exactly once. Mirrors litellm
39
+ // `transformation.py:1321-1356`.
40
+ /** Runtime-only options that accompany a ChatGPT stream after request encoding. */
41
+ export type TChatGptStreamOptions = TChatGptProviderOptions & {
42
+ /** Lossy outbound tool-name rewrites, keyed by the name Responses emits. */
43
+ readonly toolNameMap?: ReadonlyMap<string, string>;
44
+ };
45
+
46
+ export type TChatGptStreamState = {
47
+ /** Stable Chat Completions id for the whole stream. Minted once. */
48
+ id: string;
49
+ /** Unix seconds, minted once — OpenAI keeps `created` stable across chunks. */
50
+ created: number;
51
+ hasToolCall: boolean;
52
+ reasoningItems: Map<string, TReasoningItem>;
53
+ emittedReasoningIds: Set<string>;
54
+ /**
55
+ * `output_index`es that received ≥1 `function_call_arguments.delta`.
56
+ * Some Codex backends (the "codex-spark" case) emit the completed
57
+ * arguments ONLY via `function_call_arguments.done` /
58
+ * `output_item.done` with NO `.delta` events. Without finalizing
59
+ * from `.done`, the tool call reaches the model with empty `{}`
60
+ * arguments → tool fails → the model re-issues it → loop. We must
61
+ * emit the `.done` arguments, but ONLY when no `.delta` already
62
+ * streamed them (else the accumulator double-concatenates and the
63
+ * JSON corrupts). Ref: litellm Responses transformation; langchainjs#8049.
64
+ */
65
+ argsStreamedIndexes: Set<number>;
66
+ /** `output_index`es whose authoritative `.done` args were emitted. */
67
+ argsFinalizedIndexes: Set<number>;
68
+ /** `output_index`es whose tool-call `id` already went out on a delta. */
69
+ toolIdEmittedIndexes: Set<number>;
70
+ /** `output_index`es whose tool-call `name` already went out on a delta. */
71
+ toolNameEmittedIndexes: Set<number>;
72
+ /** Tool `call_id`/`id` values already emitted, so terminal `output[]` cannot re-open them at a different index. */
73
+ emittedToolCallIds: Set<string>;
74
+ /**
75
+ * `web_search_call` entries are lifecycle split (`search` + `open_page`) and
76
+ * must be coalesced by id so one logical source-search counts as one request.
77
+ */
78
+ serverSearchById: Map<
79
+ string,
80
+ {
81
+ query: string;
82
+ queries?: ReadonlyArray<string>;
83
+ results: ReadonlyArray<{ url: string }>;
84
+ }
85
+ >;
86
+ /** Present only when request encoding had to rewrite a client tool name. */
87
+ readonly toolNameMap?: ReadonlyMap<string, string>;
88
+ };
89
+
90
+ export const newChatGptStreamState = (
91
+ options: TChatGptStreamOptions,
92
+ ): TChatGptStreamState => ({
93
+ id: `chatcmpl-${crypto.randomUUID()}`,
94
+ created: Math.floor(Date.now() / 1000),
95
+ hasToolCall: false,
96
+ reasoningItems: new Map(),
97
+ emittedReasoningIds: new Set(),
98
+ argsStreamedIndexes: new Set(),
99
+ argsFinalizedIndexes: new Set(),
100
+ toolIdEmittedIndexes: new Set(),
101
+ toolNameEmittedIndexes: new Set(),
102
+ emittedToolCallIds: new Set(),
103
+ serverSearchById: new Map(),
104
+ ...(options.toolNameMap !== undefined && options.toolNameMap.size > 0
105
+ ? { toolNameMap: options.toolNameMap }
106
+ : {}),
107
+ });
108
+
109
+ /**
110
+ * Emit the authoritative complete `arguments` for a function call that
111
+ * streamed no `.delta`s. Returns null when the args already streamed
112
+ * (or were already finalized, or are empty) so we never double-count.
113
+ */
114
+ const finalizeToolArgs = (
115
+ state: TChatGptStreamState,
116
+ outputIndex: number,
117
+ args: string,
118
+ options: TChatGptStreamOptions,
119
+ ): TChatCompletionChunk | null => {
120
+ if (
121
+ args.length === 0 ||
122
+ state.argsStreamedIndexes.has(outputIndex) ||
123
+ state.argsFinalizedIndexes.has(outputIndex)
124
+ ) {
125
+ return null;
126
+ }
127
+ state.argsFinalizedIndexes.add(outputIndex);
128
+ state.hasToolCall = true;
129
+ return {
130
+ ...baseChunk(state, options),
131
+ choices: [
132
+ {
133
+ index: 0,
134
+ delta: {
135
+ tool_calls: [
136
+ {
137
+ index: outputIndex,
138
+ type: "function",
139
+ function: { arguments: args },
140
+ },
141
+ ],
142
+ },
143
+ finish_reason: null,
144
+ },
145
+ ],
146
+ };
147
+ };
148
+
149
+ const captureReasoningItem = (
150
+ state: TChatGptStreamState,
151
+ item: Record<string, unknown>,
152
+ ): TReasoningItem | null => {
153
+ if (stringField(item, "type") !== "reasoning") return null;
154
+ const id = stringField(item, "id") ?? "";
155
+ const built = buildReasoningItem(
156
+ id,
157
+ stringField(item, "encrypted_content") ?? null,
158
+ item.summary,
159
+ );
160
+ // `output_item.added` carries no `encrypted_content`; `.done` /
161
+ // `response.completed` do. Last write wins so the final (complete)
162
+ // item — the one with the resumable blob — is what we round-trip.
163
+ state.reasoningItems.set(id, built);
164
+ return built;
165
+ };
166
+
167
+ /** Reasoning items captured but not yet emitted, in insertion order. */
168
+ const drainUnemittedReasoning = (
169
+ state: TChatGptStreamState,
170
+ ): TReasoningItem[] => {
171
+ const out: TReasoningItem[] = [];
172
+ for (const [id, item] of state.reasoningItems) {
173
+ if (state.emittedReasoningIds.has(id)) continue;
174
+ state.emittedReasoningIds.add(id);
175
+ out.push(item);
176
+ }
177
+ return out;
178
+ };
179
+
180
+ const baseChunk = (
181
+ state: TChatGptStreamState,
182
+ options: TChatGptStreamOptions,
183
+ ): Pick<TChatCompletionChunk, "id" | "object" | "created" | "model"> => ({
184
+ id: state.id,
185
+ object: "chat.completion.chunk",
186
+ created: state.created,
187
+ model: options.providerModelId,
188
+ });
189
+
190
+ const stringField = (
191
+ obj: Record<string, unknown>,
192
+ key: string,
193
+ ): string | undefined => {
194
+ const v = obj[key];
195
+ return typeof v === "string" ? v : undefined;
196
+ };
197
+
198
+ const numberField = (
199
+ obj: Record<string, unknown>,
200
+ key: string,
201
+ ): number | undefined => {
202
+ const v = obj[key];
203
+ return typeof v === "number" ? v : undefined;
204
+ };
205
+
206
+ const objectField = (
207
+ obj: Record<string, unknown>,
208
+ key: string,
209
+ ): Record<string, unknown> | undefined => {
210
+ const v = obj[key];
211
+ return v !== null && typeof v === "object" && !Array.isArray(v)
212
+ ? (v as Record<string, unknown>)
213
+ : undefined;
214
+ };
215
+
216
+ const arrayField = (
217
+ obj: Record<string, unknown>,
218
+ key: string,
219
+ ): Array<unknown> | undefined => {
220
+ const v = obj[key];
221
+ return Array.isArray(v) ? v : undefined;
222
+ };
223
+
224
+ const stringArrayField = (
225
+ obj: Record<string, unknown>,
226
+ key: string,
227
+ ): ReadonlyArray<string> | undefined => {
228
+ const values = arrayField(obj, key);
229
+ if (values === undefined) return undefined;
230
+ const strings = values.filter(
231
+ (value): value is string => typeof value === "string",
232
+ );
233
+ return strings.length > 0 ? strings : undefined;
234
+ };
235
+
236
+ // apply_patch arrives as a dedicated `apply_patch`/`apply_patch_call` item OR
237
+ // as a `custom_tool_call` NAMED `apply_patch` (Codex). `custom_tool_call` is
238
+ // NOT itself an apply_patch marker — a bare `custom_tool_call` is an ordinary
239
+ // client tool call (see `isCustomToolCallItem`); classifying every one as
240
+ // apply_patch leaked xAI/Grok client tools to the client as an unexecutable
241
+ // apply_patch (→ the tool, e.g. `Task`/`Agent`, never ran). The `name`
242
+ // fallback below still catches a real apply_patch custom_tool_call.
243
+ const APPLY_PATCH_ITEM_TYPES = new Set(["apply_patch", "apply_patch_call"]);
244
+
245
+ const stringifyJson = (value: unknown): string => {
246
+ if (typeof value === "string") return value;
247
+ return JSON.stringify(value ?? {});
248
+ };
249
+
250
+ const applyPatchOperation = (
251
+ item: Record<string, unknown>,
252
+ ): unknown | undefined =>
253
+ item.operation ?? item.input ?? item.arguments ?? item.action;
254
+
255
+ const isApplyPatchItem = (item: Record<string, unknown>): boolean => {
256
+ const type = stringField(item, "type");
257
+ if (type !== undefined && APPLY_PATCH_ITEM_TYPES.has(type)) return true;
258
+ const name = stringField(item, "name");
259
+ return name === "apply_patch" && applyPatchOperation(item) !== undefined;
260
+ };
261
+
262
+ // A `custom_tool_call` that is NOT an apply_patch and NOT an x-search server
263
+ // trace is an ordinary client tool call — its arguments ride the JSON `input`
264
+ // string (not `arguments`), mirroring CLIProxyAPI's `xaiCustomToolCallArguments`.
265
+ const isCustomToolCallItem = (item: Record<string, unknown>): boolean =>
266
+ stringField(item, "type") === "custom_tool_call";
267
+
268
+ const isToolCallItem = (item: Record<string, unknown>): boolean =>
269
+ stringField(item, "type") === "function_call" ||
270
+ isCustomToolCallItem(item) ||
271
+ isApplyPatchItem(item);
272
+
273
+ // ─── provider-executed server search items ───────────────────────────
274
+ // Two Responses-wire shapes report a SERVER-side search the provider ran
275
+ // inside the turn (never a client tool call):
276
+ // - `web_search_call` (OpenAI-native; xAI's grok proxy emits it with the
277
+ // query AND `action.sources` urls on `output_item.done`), and
278
+ // - grok's X/Twitter search — `custom_tool_call` items named `x_*`
279
+ // (`x_semantic_search` / `x_keyword_search`), status "completed", with
280
+ // the query in the item's JSON `input`. These MUST be recognised before
281
+ // the apply_patch/custom-tool classification, or they'd leak to the
282
+ // client as an unexecutable apply_patch tool call.
283
+ // Both map onto the canonical `server_search_calls` carrier, so the client
284
+ // wires re-encode them exactly like Codex hosted search.
285
+
286
+ /** xAI's X-search item names, pinned from the live probe. An EXPLICIT
287
+ * whitelist (not an `x_` prefix match): a Codex client's own passthrough
288
+ * custom tool that happens to start with `x_` must keep ordinary client-tool
289
+ * semantics. A new xAI search item name must be added here to be recognised
290
+ * (unlisted ones degrade to client-tool handling, never silently vanish). */
291
+ const X_SEARCH_TOOL_NAMES: ReadonlySet<string> = new Set([
292
+ "x_semantic_search",
293
+ "x_keyword_search",
294
+ ]);
295
+
296
+ const isServerSearchItem = (item: Record<string, unknown>): boolean => {
297
+ const type = stringField(item, "type");
298
+ if (type === "web_search_call") return true;
299
+ return (
300
+ type === "custom_tool_call" &&
301
+ X_SEARCH_TOOL_NAMES.has(stringField(item, "name") ?? "")
302
+ );
303
+ };
304
+
305
+ /**
306
+ * Decode a COMPLETED server-search item. Codex represents one logical query as
307
+ * a `search` item followed by one or more `open_page` items with distinct ids.
308
+ * The caller attaches those page URLs to the preceding search instead of
309
+ * emitting page operations as new searches, keeping Claude Code's count useful.
310
+ */
311
+ type TServerSearchItem =
312
+ | {
313
+ kind: "search";
314
+ id: string;
315
+ query: string;
316
+ queries?: ReadonlyArray<string>;
317
+ results: ReadonlyArray<{ url: string }>;
318
+ }
319
+ | { kind: "open_page"; url: string }
320
+ | { kind: "immediate"; call: TServerSearchCall };
321
+
322
+ const serverSearchOfItem = (
323
+ item: Record<string, unknown>,
324
+ ): TServerSearchItem | null => {
325
+ if (!isServerSearchItem(item)) return null;
326
+ const type = stringField(item, "type");
327
+ if (type === "web_search_call") {
328
+ const action = objectField(item, "action");
329
+ if (action === undefined) return null;
330
+ const url = stringField(action, "url");
331
+ if (url !== undefined) return { kind: "open_page", url };
332
+ const id = stringField(item, "id") ?? stringField(item, "call_id");
333
+ if (id === undefined) return null;
334
+ const query =
335
+ stringField(action, "query") ??
336
+ stringField(item, "query") ??
337
+ stringArrayField(action, "queries")?.[0] ??
338
+ "";
339
+ const queries = stringArrayField(action, "queries");
340
+ const sources = arrayField(action, "sources");
341
+ const results =
342
+ sources === undefined
343
+ ? []
344
+ : sources.flatMap((source): Array<{ url: string }> => {
345
+ const url =
346
+ source !== null && typeof source === "object"
347
+ ? stringField(source as Record<string, unknown>, "url")
348
+ : undefined;
349
+ return url === undefined ? [] : [{ url }];
350
+ });
351
+ return { kind: "search", id, query, queries, results };
352
+ }
353
+ const id = stringField(item, "id") ?? stringField(item, "call_id");
354
+ if (id === undefined) return null;
355
+ // x_* custom tool — query rides the JSON `input` string.
356
+ let query = "";
357
+ try {
358
+ const input = JSON.parse(stringField(item, "input") ?? "{}") as {
359
+ readonly query?: unknown;
360
+ };
361
+ if (typeof input.query === "string") query = input.query;
362
+ } catch {
363
+ // Unparseable input — report the search with an empty query.
364
+ }
365
+ return { kind: "immediate", call: { id, query } };
366
+ };
367
+
368
+ const toolCallId = (item: Record<string, unknown>): string | undefined =>
369
+ stringField(item, "call_id") ?? stringField(item, "id");
370
+
371
+ const toolCallName = (item: Record<string, unknown>): string | undefined =>
372
+ isApplyPatchItem(item)
373
+ ? "apply_patch"
374
+ : (() => {
375
+ const name = stringField(item, "name");
376
+ return name === undefined
377
+ ? undefined
378
+ : canonicalToolNameOf(name, item.namespace);
379
+ })();
380
+
381
+ type TToolCallDelta = NonNullable<
382
+ NonNullable<
383
+ TChatCompletionChunk["choices"][number]["delta"]["tool_calls"]
384
+ >[number]
385
+ >;
386
+
387
+ /** Id/name that have not yet been emitted for this `output_index`. Marks them emitted. */
388
+ const takeUnemittedToolIdentity = (
389
+ state: TChatGptStreamState,
390
+ outputIndex: number,
391
+ item: Record<string, unknown>,
392
+ ): { id?: string; name?: string } => {
393
+ const callId = toolCallId(item);
394
+ const emittedName = toolCallName(item);
395
+ const name =
396
+ emittedName !== undefined
397
+ ? (state.toolNameMap?.get(emittedName) ?? emittedName)
398
+ : undefined;
399
+ const out: { id?: string; name?: string } = {};
400
+ if (callId !== undefined && !state.toolIdEmittedIndexes.has(outputIndex)) {
401
+ state.toolIdEmittedIndexes.add(outputIndex);
402
+ state.emittedToolCallIds.add(callId);
403
+ out.id = callId;
404
+ }
405
+ if (name !== undefined && !state.toolNameEmittedIndexes.has(outputIndex)) {
406
+ state.toolNameEmittedIndexes.add(outputIndex);
407
+ out.name = name;
408
+ }
409
+ return out;
410
+ };
411
+
412
+ const toolCallDelta = (
413
+ outputIndex: number,
414
+ identity: { id?: string; name?: string },
415
+ args: string,
416
+ ): TToolCallDelta => ({
417
+ index: outputIndex,
418
+ ...(identity.id !== undefined ? { id: identity.id } : {}),
419
+ type: "function",
420
+ function: {
421
+ ...(identity.name !== undefined ? { name: identity.name } : {}),
422
+ arguments: args,
423
+ },
424
+ });
425
+
426
+ /**
427
+ * A `custom_tool_call`'s arguments ride the JSON `input`, not `arguments`.
428
+ * Coerce to a JSON-**object** string so the canonical tool call carries valid
429
+ * `arguments` (mirrors CLIProxyAPI `xaiCustomToolCallArguments`): a valid JSON
430
+ * OBJECT passes through; any other value (array, scalar, non-JSON text) is
431
+ * wrapped as `{"input": <value>}`; empty / absent → `{}`. Never returns `""`,
432
+ * so a parameterless custom tool call still finalizes (empty args would be
433
+ * skipped by {@link finalizeToolArgs} and the tool would never emit). Arrays
434
+ * are NOT passed through — Anthropic tool input must be an object.
435
+ */
436
+ const isPlainObject = (v: unknown): boolean =>
437
+ v !== null && typeof v === "object" && !Array.isArray(v);
438
+
439
+ const customToolCallArguments = (item: Record<string, unknown>): string => {
440
+ const raw = item.input;
441
+ if (raw === undefined || raw === null) return "{}";
442
+ if (typeof raw === "string") {
443
+ const trimmed = raw.trim();
444
+ if (trimmed.length === 0) return "{}";
445
+ try {
446
+ const parsed: unknown = JSON.parse(trimmed);
447
+ if (isPlainObject(parsed)) return trimmed;
448
+ } catch {
449
+ // not JSON — wrap the text below
450
+ }
451
+ return JSON.stringify({ input: raw });
452
+ }
453
+ if (isPlainObject(raw)) return JSON.stringify(raw);
454
+ return JSON.stringify({ input: raw });
455
+ };
456
+
457
+ const toolCallArguments = (item: Record<string, unknown>): string => {
458
+ if (isApplyPatchItem(item)) return stringifyJson(applyPatchOperation(item));
459
+ if (isCustomToolCallItem(item)) return customToolCallArguments(item);
460
+ return stringField(item, "arguments") ?? "";
461
+ };
462
+
463
+ /** Emit a completed or max-token-truncated canonical terminal chunk. */
464
+ const terminalChunk = (
465
+ response: Record<string, unknown> | undefined,
466
+ state: TChatGptStreamState,
467
+ options: TChatGptStreamOptions,
468
+ truncated: boolean,
469
+ ): TChatCompletionChunk => {
470
+ // Prefer per-stream state: we already counted every
471
+ // `response.output_item.added` tool item and every
472
+ // `response.function_call_arguments.delta` as we walked the stream, so we
473
+ // don't depend on whatever shape the terminal event chooses to ship
474
+ // `response.output[]` in. Fall back to a structural check on
475
+ // `response.output[]` so single-event unit tests still observe the correct
476
+ // finish_reason.
477
+ let hasToolCall = state.hasToolCall;
478
+ if (!hasToolCall) {
479
+ const output = response !== undefined ? response.output : undefined;
480
+ if (Array.isArray(output)) {
481
+ for (const item of output) {
482
+ if (
483
+ item !== null &&
484
+ typeof item === "object" &&
485
+ // A server-search item (grok x_* custom_tool_call) is NOT a client
486
+ // tool call — it must not flip the turn to "tool_calls".
487
+ !isServerSearchItem(item as Record<string, unknown>) &&
488
+ isToolCallItem(item as Record<string, unknown>)
489
+ ) {
490
+ hasToolCall = true;
491
+ break;
492
+ }
493
+ }
494
+ }
495
+ }
496
+
497
+ // Fold any reasoning items that only appeared in the terminal
498
+ // `response.output[]` snapshot (some gpt-5.x-codex responses omit the
499
+ // per-item `.done` event). Mirrors litellm 1321-1356.
500
+ const terminalOutput = response !== undefined ? response.output : undefined;
501
+ if (Array.isArray(terminalOutput)) {
502
+ for (const item of terminalOutput) {
503
+ if (item !== null && typeof item === "object" && !Array.isArray(item)) {
504
+ captureReasoningItem(state, item as Record<string, unknown>);
505
+ }
506
+ }
507
+ }
508
+ const reasoningItems = drainUnemittedReasoning(state);
509
+ const serverSearchCalls = [...state.serverSearchById.entries()].map(
510
+ ([id, search]): TServerSearchCall => ({
511
+ id,
512
+ query: search.query,
513
+ ...(search.queries !== undefined ? { queries: [...search.queries] } : {}),
514
+ ...(search.results.length > 0 ? { results: [...search.results] } : {}),
515
+ }),
516
+ );
517
+ state.serverSearchById.clear();
518
+
519
+ let usage: TChatCompletionChunk["usage"] | undefined;
520
+ const usageRaw =
521
+ response !== undefined ? objectField(response, "usage") : undefined;
522
+ if (usageRaw !== undefined) {
523
+ const inTok = numberField(usageRaw, "input_tokens") ?? 0;
524
+ const outTok = numberField(usageRaw, "output_tokens") ?? 0;
525
+ const inDetails = objectField(usageRaw, "input_tokens_details");
526
+ const outDetails = objectField(usageRaw, "output_tokens_details");
527
+ const cached =
528
+ inDetails !== undefined
529
+ ? numberField(inDetails, "cached_tokens")
530
+ : undefined;
531
+ const reasoning =
532
+ outDetails !== undefined
533
+ ? numberField(outDetails, "reasoning_tokens")
534
+ : undefined;
535
+ usage = {
536
+ prompt_tokens: inTok,
537
+ completion_tokens: outTok,
538
+ total_tokens: inTok + outTok,
539
+ ...(cached !== undefined
540
+ ? { prompt_tokens_details: { cached_tokens: cached } }
541
+ : {}),
542
+ ...(reasoning !== undefined
543
+ ? { completion_tokens_details: { reasoning_tokens: reasoning } }
544
+ : {}),
545
+ };
546
+ }
547
+
548
+ const terminalToolCalls: TToolCallDelta[] = [];
549
+ if (Array.isArray(terminalOutput)) {
550
+ terminalOutput.forEach((raw, outputIndex) => {
551
+ if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
552
+ return;
553
+ }
554
+ const item = raw as Record<string, unknown>;
555
+ if (isServerSearchItem(item) || !isToolCallItem(item)) return;
556
+ const existingId = toolCallId(item);
557
+ if (
558
+ existingId !== undefined &&
559
+ state.emittedToolCallIds.has(existingId)
560
+ ) {
561
+ return;
562
+ }
563
+ const identity = takeUnemittedToolIdentity(state, outputIndex, item);
564
+ const alreadyArgs =
565
+ state.argsStreamedIndexes.has(outputIndex) ||
566
+ state.argsFinalizedIndexes.has(outputIndex);
567
+ const args = alreadyArgs ? "" : toolCallArguments(item);
568
+ if (
569
+ identity.id === undefined &&
570
+ identity.name === undefined &&
571
+ args.length === 0
572
+ ) {
573
+ return;
574
+ }
575
+ if (args.length > 0) {
576
+ state.argsFinalizedIndexes.add(outputIndex);
577
+ }
578
+ state.hasToolCall = true;
579
+ hasToolCall = true;
580
+ terminalToolCalls.push(toolCallDelta(outputIndex, identity, args));
581
+ });
582
+ }
583
+
584
+ return {
585
+ ...baseChunk(state, options),
586
+ choices: [
587
+ {
588
+ index: 0,
589
+ delta: {
590
+ ...(reasoningItems.length > 0
591
+ ? { reasoning_items: reasoningItems }
592
+ : {}),
593
+ ...(serverSearchCalls.length > 0
594
+ ? { server_search_calls: serverSearchCalls }
595
+ : {}),
596
+ ...(terminalToolCalls.length > 0
597
+ ? { tool_calls: terminalToolCalls }
598
+ : {}),
599
+ },
600
+ finish_reason: truncated
601
+ ? "length"
602
+ : hasToolCall
603
+ ? "tool_calls"
604
+ : "stop",
605
+ },
606
+ ],
607
+ ...(usage !== undefined ? { usage } : {}),
608
+ };
609
+ };
610
+
611
+ /**
612
+ * Translate one Responses API streaming event into one ChatCompletion
613
+ * chunk. Returns null for events we ignore (heartbeats, `response.created`
614
+ * once we've already emitted role, etc.).
615
+ *
616
+ * Mirrors `OpenAiResponsesToChatCompletionStreamIterator
617
+ * .translate_responses_chunk_to_openai_stream` from
618
+ * `completion_extras/litellm_responses_transformation/transformation.py:1090-1378`.
619
+ */
620
+ export const chatGptEventToChunk = (
621
+ event: TChatGptStreamEvent,
622
+ state: TChatGptStreamState,
623
+ options: TChatGptStreamOptions,
624
+ ): TChatCompletionChunk | null => {
625
+ const type = stringField(event, "type");
626
+ if (type === undefined) return null;
627
+
628
+ if (type === "response.created") {
629
+ return {
630
+ ...baseChunk(state, options),
631
+ choices: [
632
+ {
633
+ index: 0,
634
+ delta: { role: "assistant", content: "" },
635
+ finish_reason: null,
636
+ },
637
+ ],
638
+ };
639
+ }
640
+
641
+ if (type === "response.output_text.delta") {
642
+ const delta = stringField(event, "delta");
643
+ if (delta === undefined) return null;
644
+ return {
645
+ ...baseChunk(state, options),
646
+ choices: [{ index: 0, delta: { content: delta }, finish_reason: null }],
647
+ };
648
+ }
649
+
650
+ if (
651
+ type === "response.reasoning_summary_text.delta" ||
652
+ type === "response.reasoning_summary_text.done"
653
+ ) {
654
+ const delta =
655
+ type === "response.reasoning_summary_text.done"
656
+ ? (stringField(event, "text") ?? stringField(event, "delta"))
657
+ : stringField(event, "delta");
658
+ if (delta === undefined || delta.length === 0) return null;
659
+ return {
660
+ ...baseChunk(state, options),
661
+ choices: [
662
+ {
663
+ index: 0,
664
+ delta: {
665
+ reasoning_content: delta,
666
+ // Empty array is the signed-channel marker (not a
667
+ // reasoning item). The messages adapter holds this
668
+ // summary for a thinking block instead of dumping it
669
+ // as a visible ⏺ prompt. Kimi-style hops never set
670
+ // this field and still dump unsigned reasoning as text.
671
+ reasoning_items: [],
672
+ },
673
+ finish_reason: null,
674
+ },
675
+ ],
676
+ };
677
+ }
678
+
679
+ if (type === "response.output_item.done") {
680
+ const item = objectField(event, "item");
681
+ // Provider-executed server search completed — surface it on the
682
+ // canonical carrier BEFORE any tool-call/reasoning handling (an x_*
683
+ // custom_tool_call would otherwise classify as apply_patch and leak to
684
+ // the client as an unexecutable tool call). Reasoning drains on the
685
+ // next event as usual — search items never carry reasoning.
686
+ if (item !== undefined) {
687
+ const search = serverSearchOfItem(item);
688
+ if (search !== null) {
689
+ if (search.kind === "immediate") {
690
+ return {
691
+ ...baseChunk(state, options),
692
+ choices: [
693
+ {
694
+ index: 0,
695
+ delta: { server_search_calls: [search.call] },
696
+ finish_reason: null,
697
+ },
698
+ ],
699
+ };
700
+ }
701
+ if (search.kind === "search") {
702
+ // Grok supplies sources on the same item, so it is immediately
703
+ // self-contained. Codex search items wait for trailing open_page
704
+ // lifecycle entries; terminal emission prevents one count per URL.
705
+ if (search.results.length > 0) {
706
+ return {
707
+ ...baseChunk(state, options),
708
+ choices: [
709
+ {
710
+ index: 0,
711
+ delta: {
712
+ server_search_calls: [
713
+ {
714
+ id: search.id,
715
+ query: search.query,
716
+ ...(search.queries !== undefined
717
+ ? { queries: [...search.queries] }
718
+ : {}),
719
+ results: [...search.results],
720
+ },
721
+ ],
722
+ },
723
+ finish_reason: null,
724
+ },
725
+ ],
726
+ };
727
+ }
728
+ state.serverSearchById.set(search.id, {
729
+ query: search.query,
730
+ queries: search.queries,
731
+ results: [],
732
+ });
733
+ return null;
734
+ }
735
+ const pending = [...state.serverSearchById.entries()].at(-1);
736
+ if (pending !== undefined) {
737
+ const [id, call] = pending;
738
+ state.serverSearchById.set(id, {
739
+ ...call,
740
+ results: [...call.results, { url: search.url }],
741
+ });
742
+ }
743
+ return null;
744
+ }
745
+ }
746
+ if (item !== undefined) captureReasoningItem(state, item);
747
+ const drained = drainUnemittedReasoning(state);
748
+ // Codex-spark: the completed function call lands here with its full
749
+ // `arguments` (or, for a `custom_tool_call`, its JSON `input`) and never
750
+ // sent a `.delta`. Finalize so the tool isn't invoked with empty input
751
+ // (→ tool error → re-issue → loop). This MUST run even when a reasoning
752
+ // item drained on the SAME event: a pending reasoning item completing
753
+ // just before the function call's `.done` (grok interleaves reasoning
754
+ // summaries with tool calls) previously early-returned the reasoning and
755
+ // DROPPED the tool args, so the sub-agent (`Task`/`Agent`) never spawned.
756
+ // Both ride ONE chunk (a delta may carry reasoning_items + tool_calls).
757
+ const outputIndex = numberField(event, "output_index") ?? 0;
758
+ let toolCalls: TToolCallDelta[] | undefined;
759
+ if (
760
+ item !== undefined &&
761
+ isToolCallItem(item) &&
762
+ !isServerSearchItem(item)
763
+ ) {
764
+ const identity = takeUnemittedToolIdentity(state, outputIndex, item);
765
+ const argsChunk = isApplyPatchItem(item)
766
+ ? null
767
+ : finalizeToolArgs(
768
+ state,
769
+ outputIndex,
770
+ toolCallArguments(item),
771
+ options,
772
+ );
773
+ const args =
774
+ argsChunk?.choices[0]?.delta.tool_calls?.[0]?.function?.arguments ?? "";
775
+ if (
776
+ identity.id !== undefined ||
777
+ identity.name !== undefined ||
778
+ args.length > 0
779
+ ) {
780
+ state.hasToolCall = true;
781
+ toolCalls = [toolCallDelta(outputIndex, identity, args)];
782
+ }
783
+ }
784
+ if (drained.length > 0 || toolCalls !== undefined) {
785
+ return {
786
+ ...baseChunk(state, options),
787
+ choices: [
788
+ {
789
+ index: 0,
790
+ delta: {
791
+ ...(drained.length > 0 ? { reasoning_items: drained } : {}),
792
+ ...(toolCalls !== undefined ? { tool_calls: toolCalls } : {}),
793
+ },
794
+ finish_reason: null,
795
+ },
796
+ ],
797
+ };
798
+ }
799
+ return null;
800
+ }
801
+
802
+ if (type === "response.function_call_arguments.done") {
803
+ const outputIndex = numberField(event, "output_index") ?? 0;
804
+ const nestedItem = objectField(event, "item");
805
+ const identityItem: Record<string, unknown> = {
806
+ ...(nestedItem ?? {}),
807
+ ...(stringField(event, "call_id") !== undefined
808
+ ? { call_id: stringField(event, "call_id") }
809
+ : {}),
810
+ ...(stringField(event, "name") !== undefined
811
+ ? { name: stringField(event, "name") }
812
+ : {}),
813
+ ...(stringField(event, "namespace") !== undefined
814
+ ? { namespace: stringField(event, "namespace") }
815
+ : {}),
816
+ };
817
+ const identity = takeUnemittedToolIdentity(
818
+ state,
819
+ outputIndex,
820
+ identityItem,
821
+ );
822
+ const doneArgs =
823
+ stringField(event, "arguments") ??
824
+ (nestedItem !== undefined ? toolCallArguments(nestedItem) : "");
825
+ const argsChunk = finalizeToolArgs(state, outputIndex, doneArgs, options);
826
+ const args =
827
+ argsChunk?.choices[0]?.delta.tool_calls?.[0]?.function?.arguments ?? "";
828
+ if (
829
+ identity.id === undefined &&
830
+ identity.name === undefined &&
831
+ argsChunk === null
832
+ ) {
833
+ return null;
834
+ }
835
+ state.hasToolCall = true;
836
+ return {
837
+ ...baseChunk(state, options),
838
+ choices: [
839
+ {
840
+ index: 0,
841
+ delta: {
842
+ tool_calls: [toolCallDelta(outputIndex, identity, args)],
843
+ },
844
+ finish_reason: null,
845
+ },
846
+ ],
847
+ };
848
+ }
849
+
850
+ if (type === "response.output_item.added") {
851
+ const item = objectField(event, "item");
852
+ if (item === undefined) return null;
853
+ // A server-search item OPENING is pure lifecycle noise (its query is
854
+ // still empty) — and it must not open a client tool call.
855
+ if (isServerSearchItem(item)) return null;
856
+ captureReasoningItem(state, item);
857
+ if (!isToolCallItem(item)) return null;
858
+ state.hasToolCall = true;
859
+ const outputIndex = numberField(event, "output_index") ?? 0;
860
+ const identity = takeUnemittedToolIdentity(state, outputIndex, item);
861
+ const args = isApplyPatchItem(item) ? toolCallArguments(item) : "";
862
+ if (args.length > 0) {
863
+ state.argsFinalizedIndexes.add(outputIndex);
864
+ }
865
+ return {
866
+ ...baseChunk(state, options),
867
+ choices: [
868
+ {
869
+ index: 0,
870
+ delta: {
871
+ tool_calls: [toolCallDelta(outputIndex, identity, args)],
872
+ },
873
+ finish_reason: null,
874
+ },
875
+ ],
876
+ };
877
+ }
878
+
879
+ if (type === "response.function_call_arguments.delta") {
880
+ const delta = stringField(event, "delta");
881
+ if (delta === undefined) return null;
882
+ state.hasToolCall = true;
883
+ const outputIndex = numberField(event, "output_index") ?? 0;
884
+ state.argsStreamedIndexes.add(outputIndex);
885
+ return {
886
+ ...baseChunk(state, options),
887
+ choices: [
888
+ {
889
+ index: 0,
890
+ delta: {
891
+ tool_calls: [
892
+ {
893
+ index: outputIndex,
894
+ type: "function",
895
+ function: { arguments: delta },
896
+ },
897
+ ],
898
+ },
899
+ finish_reason: null,
900
+ },
901
+ ],
902
+ };
903
+ }
904
+
905
+ const response = objectField(event, "response");
906
+ const incomplete =
907
+ response !== undefined
908
+ ? objectField(response, "incomplete_details")
909
+ : undefined;
910
+ const isCompletedAlias =
911
+ type === "response.completed" || type === "response.done";
912
+ const incompleteReason =
913
+ incomplete !== undefined ? stringField(incomplete, "reason") : undefined;
914
+ const responseStatus =
915
+ response !== undefined ? stringField(response, "status") : undefined;
916
+ const responseError =
917
+ response !== undefined ? objectField(response, "error") : undefined;
918
+ // Hitting the configured output limit is a well-formed partial turn, not an
919
+ // upstream failure. Clients can resume it only when they receive an honest
920
+ // `finish_reason: "length"` terminal chunk.
921
+ if (incompleteReason === "max_output_tokens") {
922
+ if (type === "response.incomplete" || isCompletedAlias) {
923
+ return terminalChunk(response, state, options, true);
924
+ }
925
+ }
926
+
927
+ // `response.failed`, error, and incomplete reasons other than the configured
928
+ // output limit mean the upstream gave up mid-stream. Throw so the runner
929
+ // converts them into an SSE error frame for streaming clients and a 502
930
+ // envelope for non-streaming clients. `response.done` is an alias of
931
+ // `response.completed`; a failed/incomplete-shaped payload on either must
932
+ // NOT become a success terminal.
933
+ const aliasIsFailure =
934
+ isCompletedAlias &&
935
+ (responseStatus === "failed" ||
936
+ responseError !== undefined ||
937
+ (incompleteReason !== undefined &&
938
+ incompleteReason !== "max_output_tokens"));
939
+ if (
940
+ type === "response.failed" ||
941
+ type === "response.incomplete" ||
942
+ type === "error" ||
943
+ aliasIsFailure
944
+ ) {
945
+ const errorObj =
946
+ objectField(event, "error") ??
947
+ (response !== undefined ? objectField(response, "error") : undefined);
948
+ // `error` events carry top-level `code`/`message` (Responses spec);
949
+ // non-max-token `response.incomplete` events carry
950
+ // `response.incomplete_details.reason`. An EMPTY string field is treated
951
+ // as absent so the next fallback runs (a `""` message/code would otherwise
952
+ // win the chain and blank the diagnostic).
953
+ const nonEmpty = (s: string | undefined): string | undefined =>
954
+ s !== undefined && s.length > 0 ? s : undefined;
955
+ const message =
956
+ (errorObj !== undefined
957
+ ? nonEmpty(stringField(errorObj, "message"))
958
+ : undefined) ??
959
+ nonEmpty(stringField(event, "message")) ??
960
+ (incomplete !== undefined
961
+ ? nonEmpty(stringField(incomplete, "reason"))
962
+ : undefined) ??
963
+ `upstream chatgpt ${type}`;
964
+ const code =
965
+ (errorObj !== undefined
966
+ ? nonEmpty(stringField(errorObj, "type"))
967
+ : undefined) ??
968
+ (errorObj !== undefined
969
+ ? nonEmpty(stringField(errorObj, "code"))
970
+ : undefined) ??
971
+ nonEmpty(stringField(event, "code")) ??
972
+ type;
973
+ // Typed so downstream error handling can tell "the vendor reported an
974
+ // error" apart from "we could not decode the stream" (issue #274 —
975
+ // the web-search accumulate path used to flatten both into a generic
976
+ // 502 that discarded the vendor's reason).
977
+ throw new UpstreamStreamError(code, `${code}: ${message}`);
978
+ }
979
+
980
+ if (isCompletedAlias) {
981
+ return terminalChunk(response, state, options, false);
982
+ }
983
+
984
+ // response.in_progress / response.content_part.* / response.created
985
+ // tail / etc — ignore.
986
+ return null;
987
+ };
988
+
989
+ /**
990
+ * Semantic-end predicate for Responses SSE. Convert the event first; the
991
+ * shared decode driver closes the canonical stream and cancels the source
992
+ * when this returns true so Messages/Astra do not wait for transport EOF.
993
+ * Failed / non-max-token incomplete events still throw from
994
+ * `chatGptEventToChunk` and take the error path.
995
+ */
996
+ export const isChatGptResponsesTerminalEvent = (
997
+ event: TChatGptStreamEvent,
998
+ ): boolean => {
999
+ const type = event.type;
1000
+ return (
1001
+ type === "response.completed" ||
1002
+ type === "response.done" ||
1003
+ type === "response.incomplete" ||
1004
+ type === "response.failed" ||
1005
+ type === "error"
1006
+ );
1007
+ };