@alvin0/ai-agent-sdk-protocol-responses 0.1.9 → 0.1.11

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/dist/index.js CHANGED
@@ -1,7 +1,7 @@
1
1
  import { CONTEXT_WINDOW_EXCEEDED_CODE, MODEL_ERROR_CODES, ModelError, QUOTA_EXCEEDED_CODE, ToolCallId, isJsonValue, isNativeToolSchema } from "@alvin0/ai-agent-sdk-core";
2
2
 
3
- //#region src/serialize.ts
4
- /** Read the reasoning state back off a block, tolerating anything unexpected. */
3
+ //#region src/request-content.ts
4
+ const DEFAULT_DOCUMENT_FILENAME = "document.pdf";
5
5
  function reasoningStateOf(value) {
6
6
  if (typeof value !== "object" || value === null) return {};
7
7
  const state = value;
@@ -33,8 +33,6 @@ function imagePart(block) {
33
33
  ...detail === void 0 ? {} : { detail }
34
34
  };
35
35
  }
36
- /** Fallback file name for an inline document, since the API infers type from it. */
37
- const DEFAULT_DOCUMENT_FILENAME = "document.pdf";
38
36
  function documentPart(block) {
39
37
  if (block.source.kind === "file") return {
40
38
  type: "input_file",
@@ -50,7 +48,6 @@ function documentPart(block) {
50
48
  file_data: `data:${block.source.mediaType};base64,${block.source.data}`
51
49
  };
52
50
  }
53
- /** Convert one content block to a request-side content part. */
54
51
  function contentPart(block, role) {
55
52
  if (block.type === "text") {
56
53
  if (role !== "assistant") return {
@@ -67,92 +64,115 @@ function contentPart(block, role) {
67
64
  if (block.type === "image") return imagePart(block);
68
65
  if (block.type === "document") return documentPart(block);
69
66
  }
70
- /** Render a tool result's blocks as the wire's polymorphic `output` value. */
71
67
  function toolResultOutput(blocks) {
72
68
  if (!blocks.some((block) => block.type === "image" || block.type === "document")) return blocks.filter((block) => block.type === "text").map((block) => block.text).join("\n");
73
69
  return blocks.map((block) => contentPart(block, "user")).filter((part) => part !== void 0);
74
70
  }
75
- /**
76
- * Expand one message into zero or more wire items, appending them in order.
77
- *
78
- * Content parts accumulate into a single message item, which is FLUSHED whenever
79
- * a block appears that has to become its own top-level item. That flushing is
80
- * what preserves "spoke, then called a tool, then spoke again" as three items in
81
- * the right order instead of collapsing it.
82
- */
71
+ function nativeReplayItem(value) {
72
+ if (typeof value !== "object" || value === null) return void 0;
73
+ const item = value;
74
+ if (item.type === "web_search_call") return {
75
+ type: "web_search_call",
76
+ ...typeof item.id === "string" ? { id: item.id } : {},
77
+ ...typeof item.status === "string" ? { status: item.status } : {},
78
+ ...item.action === void 0 ? {} : { action: structuredClone(item.action) }
79
+ };
80
+ if (item.type === "image_generation_call") return imageReplayItem(item);
81
+ }
82
+ function imageReplayItem(item) {
83
+ return {
84
+ type: "image_generation_call",
85
+ ...typeof item.id === "string" ? { id: item.id } : {},
86
+ ...typeof item.status === "string" ? { status: item.status } : {},
87
+ ...typeof item.result === "string" || item.result === null ? { result: item.result } : {}
88
+ };
89
+ }
90
+
91
+ //#endregion
92
+ //#region src/request-messages.ts
93
+ /** Flush content at standalone-item boundaries to preserve conversation order. */
83
94
  function appendMessage(message, items, dialectMessagePhase) {
84
- const role = message.role === "assistant" ? "assistant" : "user";
85
- let parts = [];
86
- let phase;
87
- const flush = () => {
88
- if (parts.length === 0) return;
89
- items.push({
90
- type: "message",
91
- role,
92
- content: parts,
93
- ...role === "assistant" && dialectMessagePhase && phase !== void 0 ? { phase: phase === "final-answer" ? "final_answer" : phase } : {}
94
- });
95
- parts = [];
96
- phase = void 0;
97
- };
98
- for (const block of message.content) switch (block.type) {
99
- case "text":
100
- case "image":
101
- case "document": {
102
- if (block.type === "text" && block.phase !== void 0 && phase !== void 0 && phase !== block.phase) flush();
103
- if (block.type === "text" && block.phase !== void 0) phase = block.phase;
104
- const part = contentPart(block, role);
105
- if (part !== void 0) parts.push(part);
106
- break;
107
- }
108
- case "reasoning": {
109
- flush();
110
- const state = reasoningStateOf(block.providerState);
111
- if (state.id === void 0 && state.encryptedContent === void 0) break;
112
- const summary = state.summary !== void 0 && state.summary.length > 0 ? state.summary : block.text.length > 0 ? [block.text] : [];
113
- items.push({
114
- type: "reasoning",
115
- ...state.id === void 0 ? {} : { id: state.id },
116
- summary: summary.map((text) => ({
117
- type: "summary_text",
118
- text
119
- })),
120
- ...state.encryptedContent === void 0 ? {} : { encrypted_content: state.encryptedContent }
121
- });
122
- break;
123
- }
95
+ const state = {
96
+ role: message.role === "assistant" ? "assistant" : "user",
97
+ parts: [],
98
+ phase: void 0,
99
+ items,
100
+ dialectMessagePhase
101
+ };
102
+ for (const block of message.content) if (block.type === "text" || block.type === "image" || block.type === "document") appendContent(block, state);
103
+ else appendControl(block, state);
104
+ flushMessage(state);
105
+ }
106
+ function flushMessage(state) {
107
+ if (state.parts.length === 0) return;
108
+ state.items.push({
109
+ type: "message",
110
+ role: state.role,
111
+ content: state.parts,
112
+ ...state.role === "assistant" && state.dialectMessagePhase && state.phase !== void 0 ? { phase: state.phase === "final-answer" ? "final_answer" : state.phase } : {}
113
+ });
114
+ state.parts = [];
115
+ state.phase = void 0;
116
+ }
117
+ function appendContent(block, state) {
118
+ if (block.type === "text" && block.phase !== void 0 && state.phase !== void 0 && state.phase !== block.phase) flushMessage(state);
119
+ if (block.type === "text" && block.phase !== void 0) state.phase = block.phase;
120
+ const part = contentPart(block, state.role);
121
+ if (part !== void 0) state.parts.push(part);
122
+ }
123
+ function appendControl(block, state) {
124
+ switch (block.type) {
125
+ case "reasoning":
126
+ flushMessage(state);
127
+ appendReasoning(block, state.items);
128
+ return;
124
129
  case "tool-call":
125
- flush();
126
- items.push({
130
+ flushMessage(state);
131
+ state.items.push({
127
132
  type: "function_call",
128
133
  call_id: block.id,
129
134
  name: block.name,
130
135
  arguments: block.arguments.length > 0 ? block.arguments : "{}"
131
136
  });
132
- break;
137
+ return;
133
138
  case "tool-result":
134
- flush();
135
- items.push({
139
+ flushMessage(state);
140
+ state.items.push({
136
141
  type: "function_call_output",
137
142
  call_id: block.toolCallId,
138
143
  output: toolResultOutput(block.content)
139
144
  });
140
- break;
145
+ return;
141
146
  case "native-tool-call": {
142
- flush();
147
+ flushMessage(state);
143
148
  const replay = nativeReplayItem(block.providerState);
144
- if (replay !== void 0) items.push(replay);
145
- break;
149
+ if (replay !== void 0) state.items.push(replay);
150
+ return;
146
151
  }
152
+ default: return;
147
153
  }
148
- flush();
149
154
  }
150
- /** Collect the system prompt from the request plus any system-role messages. */
151
- function instructionsOf(request) {
152
- const fromMessages = request.options.messages.filter((message) => message.role === "system").flatMap((message) => message.content).filter((block) => block.type === "text").map((block) => block.text);
153
- return (request.options.system === void 0 ? fromMessages : [request.options.system, ...fromMessages]).join("\n\n");
155
+ function appendReasoning(block, items) {
156
+ const state = reasoningStateOf(block.providerState);
157
+ if (state.id === void 0 && state.encryptedContent === void 0) return;
158
+ const summary = reasoningSummary(state, block.text);
159
+ items.push({
160
+ type: "reasoning",
161
+ ...state.id === void 0 ? {} : { id: state.id },
162
+ summary: summary.map((text) => ({
163
+ type: "summary_text",
164
+ text
165
+ })),
166
+ ...state.encryptedContent === void 0 ? {} : { encrypted_content: state.encryptedContent }
167
+ });
154
168
  }
155
- /** Map the neutral tool-choice vocabulary onto this API's. */
169
+ function reasoningSummary(state, text) {
170
+ if (state.summary !== void 0 && state.summary.length > 0) return state.summary;
171
+ return text.length > 0 ? [text] : [];
172
+ }
173
+
174
+ //#endregion
175
+ //#region src/serialize-options.ts
156
176
  function toolChoiceOf(choice) {
157
177
  if (typeof choice === "string") return choice;
158
178
  if (choice.type === "native") return { type: nativeWireType(choice.name) };
@@ -161,7 +181,6 @@ function toolChoiceOf(choice) {
161
181
  name: choice.name
162
182
  };
163
183
  }
164
- /** Map a tool schema; `strict: false` because caller schemas are not vetted. */
165
184
  function functionTool(tool) {
166
185
  return {
167
186
  type: "function",
@@ -215,86 +234,74 @@ function textControls(format, dialect) {
215
234
  strict: true
216
235
  } };
217
236
  }
218
- function nativeReplayItem(value) {
219
- if (typeof value !== "object" || value === null) return void 0;
220
- const item = value;
221
- if (item.type === "web_search_call") return {
222
- type: "web_search_call",
223
- ...typeof item.id === "string" ? { id: item.id } : {},
224
- ...typeof item.status === "string" ? { status: item.status } : {},
225
- ...item.action === void 0 ? {} : { action: structuredClone(item.action) }
237
+ function toolsOptions(request) {
238
+ const options = request.options;
239
+ const tools = options.tools === void 0 || options.tools.length === 0 ? void 0 : options.tools.map(toolOf);
240
+ return {
241
+ ...tools === void 0 ? {} : {
242
+ tools,
243
+ parallel_tool_calls: true
244
+ },
245
+ ...options.toolChoice === void 0 ? {} : { tool_choice: toolChoiceOf(options.toolChoice) }
226
246
  };
227
- if (item.type === "image_generation_call") return {
228
- type: "image_generation_call",
229
- ...typeof item.id === "string" ? { id: item.id } : {},
230
- ...typeof item.status === "string" ? { status: item.status } : {},
231
- ...typeof item.result === "string" || item.result === null ? { result: item.result } : {}
247
+ }
248
+ function reasoningOptions(request, dialect) {
249
+ const effort = request.options.reasoningEffort;
250
+ if (effort === void 0 && dialect.reasoningSummary === void 0) return {};
251
+ return { reasoning: {
252
+ ...effort === void 0 ? {} : { effort: String(effort) },
253
+ ...dialect.reasoningSummary === void 0 ? {} : { summary: dialect.reasoningSummary }
254
+ } };
255
+ }
256
+ function dialectOptions(request, dialect) {
257
+ const text = textControls(request.options.outputFormat, dialect);
258
+ return {
259
+ ...text === void 0 ? {} : { text },
260
+ ...dialect.store === void 0 ? {} : { store: dialect.store },
261
+ ...dialect.include.length === 0 ? {} : { include: [...dialect.include] },
262
+ ...dialect.promptCacheKey === void 0 ? {} : { prompt_cache_key: dialect.promptCacheKey },
263
+ ...dialect.maxOutputTokens && request.maxTokens !== void 0 ? { max_output_tokens: request.maxTokens } : {}
232
264
  };
233
265
  }
234
- /**
235
- * Build the Responses request body.
236
- * @param request - the resolved request, model, and connection.
237
- * @param dialect - which optional fields this endpoint accepts.
238
- * @returns the wire body, ready to serialize.
239
- */
266
+ function samplingOptions(request, dialect) {
267
+ const options = request.options;
268
+ return {
269
+ ...dialect.sampling && options.temperature !== void 0 ? { temperature: options.temperature } : {},
270
+ ...dialect.sampling && options.topP !== void 0 ? { top_p: options.topP } : {}
271
+ };
272
+ }
273
+
274
+ //#endregion
275
+ //#region src/serialize.ts
276
+ function instructionsOf(request) {
277
+ const fromMessages = request.options.messages.filter((message) => message.role === "system").flatMap((message) => message.content).filter((block) => block.type === "text").map((block) => block.text);
278
+ return (request.options.system === void 0 ? fromMessages : [request.options.system, ...fromMessages]).join("\n\n");
279
+ }
240
280
  function serializeResponsesRequest(request, dialect) {
241
- const { options } = request;
242
281
  const input = [];
243
- for (const message of options.messages) {
282
+ for (const message of request.options.messages) {
244
283
  if (message.role === "system") continue;
245
284
  appendMessage(message, input, dialect.messagePhase === true);
246
285
  }
247
286
  const instructions = instructionsOf(request);
248
- const tools = options.tools === void 0 || options.tools.length === 0 ? void 0 : options.tools.map(toolOf);
249
- const text = textControls(options.outputFormat, dialect);
250
287
  return {
251
- model: options.model,
288
+ model: request.options.model,
252
289
  ...instructions.length === 0 ? {} : { instructions },
253
290
  input,
254
- ...tools === void 0 ? {} : { tools },
255
- ...options.toolChoice === void 0 ? {} : { tool_choice: toolChoiceOf(options.toolChoice) },
256
- ...tools === void 0 ? {} : { parallel_tool_calls: true },
257
- ...options.reasoningEffort === void 0 && dialect.reasoningSummary === void 0 ? {} : { reasoning: {
258
- ...options.reasoningEffort === void 0 ? {} : { effort: String(options.reasoningEffort) },
259
- ...dialect.reasoningSummary === void 0 ? {} : { summary: dialect.reasoningSummary }
260
- } },
261
- ...text === void 0 ? {} : { text },
262
- ...dialect.store === void 0 ? {} : { store: dialect.store },
263
- stream: true,
264
- ...dialect.include.length === 0 ? {} : { include: [...dialect.include] },
265
- ...dialect.promptCacheKey === void 0 ? {} : { prompt_cache_key: dialect.promptCacheKey },
266
- ...dialect.maxOutputTokens && request.maxTokens !== void 0 ? { max_output_tokens: request.maxTokens } : {},
267
- ...dialect.sampling && options.temperature !== void 0 ? { temperature: options.temperature } : {},
268
- ...dialect.sampling && options.topP !== void 0 ? { top_p: options.topP } : {}
291
+ ...toolsOptions(request),
292
+ ...reasoningOptions(request, dialect),
293
+ ...dialectOptions(request, dialect),
294
+ ...samplingOptions(request, dialect),
295
+ stream: true
269
296
  };
270
297
  }
271
298
 
272
299
  //#endregion
273
- //#region src/translate.ts
274
- /**
275
- * Responses API SSE events to the SDK's chunk protocol.
276
- *
277
- * Two design notes worth reading before changing anything here.
278
- *
279
- * First, block correlation is keyed on `item_id`, not on the provider's
280
- * `output_index`. Item ids are stable and present on every delta event, whereas
281
- * index fields vary by event type, so keying on the id and assigning our OWN
282
- * indices in first-seen order is both simpler and closer to what our protocol
283
- * promises.
284
- *
285
- * Second, reasoning state is carried on the reasoning BLOCK
286
- * (`ReasoningBlock.providerState`) rather than in the stream's `replayState`
287
- * envelope. The envelope has to stay positionally aligned with emitted blocks and
288
- * is discarded whole when it drifts; attaching the state to the block it belongs
289
- * to cannot drift, and it survives assembly for free.
290
- *
291
- * @module ai-agent-sdk/providers/responses/translate
292
- */
300
+ //#region src/stream-items.ts
293
301
  function textPhase(value) {
294
302
  if (value === "commentary") return "commentary";
295
303
  if (value === "final_answer") return "final-answer";
296
304
  }
297
- /** Map an output item's wire type onto one of our block types. */
298
305
  function itemKind(type) {
299
306
  switch (type) {
300
307
  case "message": return "text";
@@ -330,7 +337,6 @@ function textAnnotations(item) {
330
337
  });
331
338
  });
332
339
  }
333
- /** Collect the text of a done item's `content` array. */
334
340
  function itemText(item) {
335
341
  const content = item.content;
336
342
  if (!Array.isArray(content)) return "";
@@ -340,7 +346,6 @@ function itemText(item) {
340
346
  return typeof record.text === "string" ? record.text : "";
341
347
  }).join("");
342
348
  }
343
- /** Collect the summary paragraphs of a done reasoning item. */
344
349
  function itemSummary(item) {
345
350
  const summary = item.summary;
346
351
  if (!Array.isArray(summary)) return [];
@@ -350,24 +355,87 @@ function itemSummary(item) {
350
355
  return typeof record.text === "string" ? record.text : "";
351
356
  }).filter((text) => text.length > 0);
352
357
  }
353
- /**
354
- * Normalize usage, honouring the SDK's disjoint-count convention.
355
- *
356
- * This API reports `input_tokens` as the TOTAL input and
357
- * `input_tokens_details.cached_tokens` as a subset of it. Our convention is that
358
- * the three input figures are disjoint and sum to what is billed, so the cached
359
- * portion is subtracted back out here. Skip that and every cost estimate
360
- * double-counts cache hits.
361
- */
358
+ function doneBlock(item, open, imageMediaType) {
359
+ switch (open.kind) {
360
+ case "text": return doneText(item, open);
361
+ case "reasoning": return doneReasoning(item, open);
362
+ case "tool-call": return doneTool(item, open);
363
+ case "native-tool-call": return doneNative(item, open, imageMediaType);
364
+ default: return;
365
+ }
366
+ }
367
+ function doneText(item, open) {
368
+ const text = itemText(item);
369
+ const phase = textPhase(item.phase) ?? open.phase;
370
+ return {
371
+ type: "text",
372
+ text: text.length > 0 ? text : open.text,
373
+ ...phase === void 0 ? {} : { phase },
374
+ ...textAnnotations(item).length === 0 ? {} : { annotations: textAnnotations(item) }
375
+ };
376
+ }
377
+ function doneReasoning(item, open) {
378
+ const summary = itemSummary(item);
379
+ const state = {
380
+ ...typeof item.id === "string" ? { id: item.id } : {},
381
+ ...typeof item.encrypted_content === "string" ? { encryptedContent: item.encrypted_content } : {},
382
+ ...summary.length > 0 ? { summary } : {}
383
+ };
384
+ return {
385
+ type: "reasoning",
386
+ text: summary.length > 0 ? summary.join("\n\n") : open.text,
387
+ providerState: state
388
+ };
389
+ }
390
+ function doneTool(item, open) {
391
+ const args = typeof item.arguments === "string" && item.arguments.length > 0 ? item.arguments : open.args;
392
+ return {
393
+ type: "tool-call",
394
+ id: ToolCallId(item.call_id ?? open.callId),
395
+ name: item.name ?? open.name,
396
+ arguments: args.length > 0 ? args : "{}"
397
+ };
398
+ }
399
+ function doneNative(item, open, imageMediaType) {
400
+ const content = open.nativeName === "image-generation" && typeof item.result === "string" && item.result.length > 0 ? [{
401
+ type: "image",
402
+ source: {
403
+ kind: "base64",
404
+ mediaType: imageMediaType,
405
+ data: item.result
406
+ }
407
+ }] : [];
408
+ return {
409
+ type: "native-tool-call",
410
+ id: item.id ?? open.callId,
411
+ name: open.nativeName,
412
+ ...typeof item.status === "string" ? { status: item.status } : {},
413
+ ...isJsonValue(item.action) ? { arguments: item.action } : {},
414
+ content,
415
+ providerState: item
416
+ };
417
+ }
418
+ function kindToBlockType(kind) {
419
+ return kind;
420
+ }
421
+ function requestedImageMediaType(request) {
422
+ const tool = request?.options.tools?.find((candidate) => "type" in candidate && candidate.type === "native" && candidate.name === "image-generation");
423
+ if (tool === void 0 || !("format" in tool)) return "image/png";
424
+ if (tool.format === "jpeg") return "image/jpeg";
425
+ if (tool.format === "webp") return "image/webp";
426
+ return "image/png";
427
+ }
428
+
429
+ //#endregion
430
+ //#region src/stream-usage.ts
362
431
  function mapUsage(usage) {
363
432
  const source = usage;
364
433
  const details = recordOrUndefined(source.input_tokens_details);
365
- const outputDetails = recordOrUndefined(source.output_tokens_details);
366
434
  const rawInput = source.input_tokens;
367
435
  const outputTokens = source.output_tokens;
368
436
  const cacheRead = details?.cached_tokens;
369
437
  const cacheWrite = details?.cache_write_tokens;
370
- const reasoning = outputDetails?.reasoning_tokens;
438
+ const reasoning = reasoningCounter(source);
371
439
  const totalTokens = source.total_tokens;
372
440
  if (![
373
441
  rawInput,
@@ -380,17 +448,28 @@ function mapUsage(usage) {
380
448
  const normalized = {
381
449
  ...outputTokens === void 0 ? {} : { outputTokens },
382
450
  ...totalTokens === void 0 ? {} : { totalTokens },
383
- ...cacheRead === void 0 || cacheRead === 0 ? {} : { cacheReadTokens: cacheRead },
384
- ...cacheWrite === void 0 || cacheWrite === 0 ? {} : { cacheWriteTokens: cacheWrite },
385
- ...reasoning === void 0 || reasoning === 0 ? {} : { reasoningTokens: reasoning }
451
+ ...omittedCounter(cacheRead) ? {} : { cacheReadTokens: cacheRead },
452
+ ...omittedCounter(cacheWrite) ? {} : { cacheWriteTokens: cacheWrite },
453
+ ...omittedCounter(reasoning) ? {} : { reasoningTokens: reasoning }
386
454
  };
387
- if (rawInput !== void 0) normalized.inputTokens = typeof rawInput === "number" && (cacheRead === void 0 || typeof cacheRead === "number") ? rawInput - (cacheRead ?? 0) : rawInput;
455
+ if (rawInput !== void 0) normalized.inputTokens = disjointInput(rawInput, cacheRead);
388
456
  return normalized;
389
457
  }
390
458
  function recordOrUndefined(value) {
391
459
  return typeof value === "object" && value !== null ? value : void 0;
392
460
  }
393
- /** Codes that mean "do not retry this"; everything else stays retryable. */
461
+ function omittedCounter(value) {
462
+ return value === void 0 || value === 0;
463
+ }
464
+ function disjointInput(rawInput, cacheRead) {
465
+ return typeof rawInput === "number" && (cacheRead === void 0 || typeof cacheRead === "number") ? rawInput - (cacheRead ?? 0) : rawInput;
466
+ }
467
+ function reasoningCounter(source) {
468
+ return recordOrUndefined(source.output_tokens_details)?.reasoning_tokens;
469
+ }
470
+
471
+ //#endregion
472
+ //#region src/stream-errors.ts
394
473
  const TERMINAL_ERROR_CODES = Object.freeze({
395
474
  context_length_exceeded: CONTEXT_WINDOW_EXCEEDED_CODE,
396
475
  insufficient_quota: QUOTA_EXCEEDED_CODE,
@@ -400,7 +479,6 @@ const TERMINAL_ERROR_CODES = Object.freeze({
400
479
  misalignment_policy_violation: MODEL_ERROR_CODES.INVALID_REQUEST,
401
480
  rate_limit_exceeded: MODEL_ERROR_CODES.RATE_LIMIT
402
481
  });
403
- /** Turn a `response.failed` payload into a typed, correctly classified error. */
404
482
  function failedError(response, displayName) {
405
483
  const error = response?.error ?? void 0;
406
484
  const code = error?.code ?? error?.type;
@@ -408,11 +486,6 @@ function failedError(response, displayName) {
408
486
  const mapped = code === void 0 ? void 0 : TERMINAL_ERROR_CODES[code];
409
487
  return new ModelError(message, mapped ?? MODEL_ERROR_CODES.SERVER, {});
410
488
  }
411
- /**
412
- * What little a bare `response.failed` does carry. Under load Codex fails a
413
- * response with no error body at all; the response id and status are then the
414
- * only facts that let an operator match the failure to the provider's side.
415
- */
416
489
  function failureContext(response, code) {
417
490
  return ` (${[
418
491
  code === void 0 ? "no error detail" : `code ${code}`,
@@ -420,250 +493,244 @@ function failureContext(response, code) {
420
493
  ...typeof response?.status === "string" && /^[\w-]{1,32}$/.test(response.status) ? [`status ${response.status}`] : []
421
494
  ].join(", ")})`;
422
495
  }
423
- /** Build the authoritative block for a completed item. */
424
- function doneBlock(item, open, imageMediaType) {
425
- switch (open.kind) {
426
- case "text": {
427
- const text = itemText(item);
428
- const phase = textPhase(item.phase) ?? open.phase;
429
- return {
430
- type: "text",
431
- text: text.length > 0 ? text : open.text,
432
- ...phase === void 0 ? {} : { phase },
433
- ...textAnnotations(item).length === 0 ? {} : { annotations: textAnnotations(item) }
434
- };
435
- }
436
- case "reasoning": {
437
- const summary = itemSummary(item);
438
- const state = {
439
- ...typeof item.id === "string" ? { id: item.id } : {},
440
- ...typeof item.encrypted_content === "string" ? { encryptedContent: item.encrypted_content } : {},
441
- ...summary.length > 0 ? { summary } : {}
442
- };
443
- return {
444
- type: "reasoning",
445
- text: summary.length > 0 ? summary.join("\n\n") : open.text,
446
- providerState: state
447
- };
448
- }
449
- case "tool-call": {
450
- const args = typeof item.arguments === "string" && item.arguments.length > 0 ? item.arguments : open.args;
451
- return {
452
- type: "tool-call",
453
- id: ToolCallId(item.call_id ?? open.callId),
454
- name: item.name ?? open.name,
455
- arguments: args.length > 0 ? args : "{}"
456
- };
457
- }
458
- case "native-tool-call": {
459
- const content = open.nativeName === "image-generation" && typeof item.result === "string" && item.result.length > 0 ? [{
460
- type: "image",
461
- source: {
462
- kind: "base64",
463
- mediaType: imageMediaType,
464
- data: item.result
465
- }
466
- }] : [];
467
- return {
468
- type: "native-tool-call",
469
- id: item.id ?? open.callId,
470
- name: open.nativeName,
471
- ...typeof item.status === "string" ? { status: item.status } : {},
472
- ...isJsonValue(item.action) ? { arguments: item.action } : {},
473
- content,
474
- providerState: item
475
- };
476
- }
496
+
497
+ //#endregion
498
+ //#region src/stream-events.ts
499
+ function* translateEvent(state, event, displayName) {
500
+ switch (event.type) {
501
+ case "response.output_item.added":
502
+ yield* itemAdded(state, event);
503
+ return;
504
+ case "response.output_item.done":
505
+ yield* itemDone(state, event);
506
+ return;
507
+ case "response.completed":
508
+ yield* completed(state, event);
509
+ return;
510
+ case "response.incomplete":
511
+ yield* incomplete(event, displayName);
512
+ return;
513
+ case "response.failed":
514
+ yield* failed(event, displayName);
515
+ return;
516
+ case "error":
517
+ yield* inlineError(event, displayName);
518
+ return;
519
+ default:
520
+ yield* deltaEvent(state, event);
521
+ return;
522
+ }
523
+ }
524
+ function* itemAdded(state, event) {
525
+ const item = event.item;
526
+ const id = item?.id ?? event.item_id;
527
+ const kind = itemKind(item?.type);
528
+ if (item === void 0 || id === void 0 || kind === void 0) return;
529
+ if (state.open.has(id)) return;
530
+ const entry = createOpenItem(state, item, {
531
+ id,
532
+ kind
533
+ });
534
+ state.open.set(id, entry);
535
+ if (kind === "tool-call") state.sawToolCall = true;
536
+ yield {
537
+ type: "block-start",
538
+ index: entry.index,
539
+ blockType: kindToBlockType(kind)
540
+ };
541
+ }
542
+ function* textDelta(state, event) {
543
+ const entry = event.item_id === void 0 ? void 0 : state.open.get(event.item_id);
544
+ if (entry === void 0 || event.delta === void 0) return;
545
+ entry.text += event.delta;
546
+ yield {
547
+ type: "text-delta",
548
+ index: entry.index,
549
+ text: event.delta,
550
+ ...entry.phase === void 0 ? {} : { phase: entry.phase }
551
+ };
552
+ }
553
+ function* summaryDelta(state, event) {
554
+ const entry = event.item_id === void 0 ? void 0 : state.open.get(event.item_id);
555
+ if (entry === void 0 || event.delta === void 0) return;
556
+ const separator = entry.summaryIndex !== void 0 && event.summary_index !== void 0 && event.summary_index !== entry.summaryIndex ? "\n\n" : "";
557
+ entry.summaryIndex = event.summary_index;
558
+ const text = `${separator}${event.delta}`;
559
+ entry.text += text;
560
+ yield {
561
+ type: "reasoning-delta",
562
+ index: entry.index,
563
+ text
564
+ };
565
+ }
566
+ function* reasoningDelta(state, event) {
567
+ const entry = event.item_id === void 0 ? void 0 : state.open.get(event.item_id);
568
+ if (entry === void 0 || event.delta === void 0) return;
569
+ entry.text += event.delta;
570
+ yield {
571
+ type: "reasoning-delta",
572
+ index: entry.index,
573
+ text: event.delta
574
+ };
575
+ }
576
+ function* toolDelta(state, event) {
577
+ const entry = event.item_id === void 0 ? void 0 : state.open.get(event.item_id);
578
+ if (entry === void 0 || event.delta === void 0) return;
579
+ entry.args += event.delta;
580
+ yield {
581
+ type: "tool-call-delta",
582
+ index: entry.index,
583
+ id: ToolCallId(entry.callId),
584
+ ...entry.name.length > 0 ? { name: entry.name } : {},
585
+ argumentsDelta: event.delta
586
+ };
587
+ }
588
+ function* partialImage(state, event) {
589
+ const itemId = event.item_id;
590
+ const entry = itemId === void 0 ? void 0 : state.open.get(itemId);
591
+ if (itemId === void 0 || entry === void 0 || event.partial_image_b64 === void 0) return;
592
+ yield {
593
+ type: "image-delta",
594
+ index: entry.index,
595
+ itemId,
596
+ data: event.partial_image_b64,
597
+ mediaType: state.imageMediaType,
598
+ ...event.partial_image_index === void 0 ? {} : { partialIndex: event.partial_image_index }
599
+ };
600
+ }
601
+ function* itemDone(state, event) {
602
+ const item = event.item;
603
+ const id = item?.id ?? event.item_id;
604
+ const entry = id === void 0 ? void 0 : state.open.get(id);
605
+ if (item === void 0 || entry === void 0) return;
606
+ const block = doneBlock(item, entry, state.imageMediaType);
607
+ if (block !== void 0) yield {
608
+ type: "block-end",
609
+ index: entry.index,
610
+ block
611
+ };
612
+ }
613
+ function* completed(state, event) {
614
+ const usage = event.response?.usage ?? void 0;
615
+ const mapped = usage === void 0 ? void 0 : mapUsage(usage);
616
+ if (mapped !== void 0) yield {
617
+ type: "usage",
618
+ usage: mapped
619
+ };
620
+ yield {
621
+ type: "finish",
622
+ reason: state.sawToolCall ? { kind: "tool-calls" } : { kind: "stop" }
623
+ };
624
+ }
625
+ function* incomplete(event, displayName) {
626
+ const usage = event.response?.usage ?? void 0;
627
+ const mapped = usage === void 0 ? void 0 : mapUsage(usage);
628
+ if (mapped !== void 0) yield {
629
+ type: "usage",
630
+ usage: mapped
631
+ };
632
+ const why = event.response?.incomplete_details?.reason;
633
+ if (why === "max_output_tokens") {
634
+ yield {
635
+ type: "finish",
636
+ reason: { kind: "max-tokens" }
637
+ };
638
+ return;
639
+ }
640
+ throw new ModelError(`${displayName} returned an incomplete response (${why ?? "unknown reason"})`, MODEL_ERROR_CODES.SERVER);
641
+ }
642
+ function* failed(event, displayName) {
643
+ const usage = event.response?.usage ?? void 0;
644
+ const mapped = usage === void 0 ? void 0 : mapUsage(usage);
645
+ if (mapped !== void 0) yield {
646
+ type: "usage",
647
+ usage: mapped
648
+ };
649
+ throw failedError(event.response, displayName);
650
+ }
651
+ function* inlineError(event, displayName) {
652
+ const inline = {
653
+ ...event.code === void 0 ? {} : { code: event.code },
654
+ ...event.message === void 0 ? {} : { message: event.message }
655
+ };
656
+ throw failedError({ error: inline }, displayName);
657
+ }
658
+ function* deltaEvent(state, event) {
659
+ switch (event.type) {
660
+ case "response.output_text.delta":
661
+ yield* textDelta(state, event);
662
+ return;
663
+ case "response.reasoning_summary_text.delta":
664
+ yield* summaryDelta(state, event);
665
+ return;
666
+ case "response.reasoning_text.delta":
667
+ yield* reasoningDelta(state, event);
668
+ return;
669
+ case "response.function_call_arguments.delta":
670
+ yield* toolDelta(state, event);
671
+ return;
672
+ case "response.image_generation_call.partial_image":
673
+ yield* partialImage(state, event);
674
+ return;
477
675
  default: return;
478
676
  }
479
677
  }
678
+ function createOpenItem(state, item, identity) {
679
+ const { id, kind } = identity;
680
+ return {
681
+ index: state.nextIndex++,
682
+ kind,
683
+ text: "",
684
+ args: "",
685
+ callId: item.call_id ?? id,
686
+ name: item.name ?? "",
687
+ nativeName: nativeName(item.type),
688
+ summaryIndex: void 0,
689
+ phase: textPhase(item.phase)
690
+ };
691
+ }
692
+
693
+ //#endregion
694
+ //#region src/translate.ts
480
695
  /**
481
- * Translate one Responses SSE stream.
696
+ * Responses API SSE events to the SDK's chunk protocol.
482
697
  *
483
- * Owns termination. This API sends no `[DONE]` sentinel: the stream ends on
484
- * `response.completed`, `response.failed`, or `response.incomplete`, and a body
485
- * that ends without one of those was truncated — which is a failure, not an
486
- * empty success, because a truncated turn cannot be trusted.
487
- * @param events - decoded SSE events.
488
- * @param displayName - provider name, used in diagnostics.
489
- * @returns the chunk stream.
698
+ * Two design notes worth reading before changing anything here.
699
+ *
700
+ * First, block correlation is keyed on `item_id`, not on the provider's
701
+ * `output_index`. Item ids are stable and present on every delta event, whereas
702
+ * index fields vary by event type, so keying on the id and assigning our OWN
703
+ * indices in first-seen order is both simpler and closer to what our protocol
704
+ * promises.
705
+ *
706
+ * Second, reasoning state is carried on the reasoning BLOCK
707
+ * (`ReasoningBlock.providerState`) rather than in the stream's `replayState`
708
+ * envelope. The envelope has to stay positionally aligned with emitted blocks and
709
+ * is discarded whole when it drifts; attaching the state to the block it belongs
710
+ * to cannot drift, and it survives assembly for free.
711
+ *
712
+ * @module ai-agent-sdk/providers/responses/translate
490
713
  */
491
714
  async function* translateResponsesStream(events, displayName, request) {
492
- const open = /* @__PURE__ */ new Map();
493
- let nextIndex = 0;
494
- let sawToolCall = false;
495
- let terminated = false;
496
- const imageMediaType = requestedImageMediaType(request);
715
+ const state = {
716
+ open: /* @__PURE__ */ new Map(),
717
+ nextIndex: 0,
718
+ sawToolCall: false,
719
+ imageMediaType: requestedImageMediaType(request)
720
+ };
497
721
  for await (const raw of events) {
498
- let event;
499
- try {
500
- event = JSON.parse(raw.data);
501
- } catch (error) {
502
- throw new ModelError(`${displayName} sent a malformed stream event`, MODEL_ERROR_CODES.MALFORMED_RESPONSE, { cause: error });
503
- }
504
- switch (event.type) {
505
- case "response.output_item.added": {
506
- const item = event.item;
507
- const id = item?.id ?? event.item_id;
508
- const kind = itemKind(item?.type);
509
- if (item === void 0 || id === void 0 || kind === void 0) break;
510
- if (open.has(id)) break;
511
- const entry = {
512
- index: nextIndex++,
513
- kind,
514
- text: "",
515
- args: "",
516
- callId: item.call_id ?? id,
517
- name: item.name ?? "",
518
- nativeName: nativeName(item.type),
519
- summaryIndex: void 0,
520
- phase: textPhase(item.phase)
521
- };
522
- open.set(id, entry);
523
- if (kind === "tool-call") sawToolCall = true;
524
- yield {
525
- type: "block-start",
526
- index: entry.index,
527
- blockType: kindToBlockType(kind)
528
- };
529
- break;
530
- }
531
- case "response.output_text.delta": {
532
- const entry = event.item_id === void 0 ? void 0 : open.get(event.item_id);
533
- if (entry === void 0 || event.delta === void 0) break;
534
- entry.text += event.delta;
535
- yield {
536
- type: "text-delta",
537
- index: entry.index,
538
- text: event.delta,
539
- ...entry.phase === void 0 ? {} : { phase: entry.phase }
540
- };
541
- break;
542
- }
543
- case "response.reasoning_summary_text.delta": {
544
- const entry = event.item_id === void 0 ? void 0 : open.get(event.item_id);
545
- if (entry === void 0 || event.delta === void 0) break;
546
- const separator = entry.summaryIndex !== void 0 && event.summary_index !== void 0 && event.summary_index !== entry.summaryIndex ? "\n\n" : "";
547
- entry.summaryIndex = event.summary_index;
548
- const text = `${separator}${event.delta}`;
549
- entry.text += text;
550
- yield {
551
- type: "reasoning-delta",
552
- index: entry.index,
553
- text
554
- };
555
- break;
556
- }
557
- case "response.reasoning_text.delta": {
558
- const entry = event.item_id === void 0 ? void 0 : open.get(event.item_id);
559
- if (entry === void 0 || event.delta === void 0) break;
560
- entry.text += event.delta;
561
- yield {
562
- type: "reasoning-delta",
563
- index: entry.index,
564
- text: event.delta
565
- };
566
- break;
567
- }
568
- case "response.function_call_arguments.delta": {
569
- const entry = event.item_id === void 0 ? void 0 : open.get(event.item_id);
570
- if (entry === void 0 || event.delta === void 0) break;
571
- entry.args += event.delta;
572
- yield {
573
- type: "tool-call-delta",
574
- index: entry.index,
575
- id: ToolCallId(entry.callId),
576
- ...entry.name.length > 0 ? { name: entry.name } : {},
577
- argumentsDelta: event.delta
578
- };
579
- break;
580
- }
581
- case "response.image_generation_call.partial_image": {
582
- const itemId = event.item_id;
583
- const entry = itemId === void 0 ? void 0 : open.get(itemId);
584
- if (itemId === void 0 || entry === void 0 || event.partial_image_b64 === void 0) break;
585
- yield {
586
- type: "image-delta",
587
- index: entry.index,
588
- itemId,
589
- data: event.partial_image_b64,
590
- mediaType: imageMediaType,
591
- ...event.partial_image_index === void 0 ? {} : { partialIndex: event.partial_image_index }
592
- };
593
- break;
594
- }
595
- case "response.output_item.done": {
596
- const item = event.item;
597
- const id = item?.id ?? event.item_id;
598
- const entry = id === void 0 ? void 0 : open.get(id);
599
- if (item === void 0 || entry === void 0) break;
600
- const block = doneBlock(item, entry, imageMediaType);
601
- if (block !== void 0) yield {
602
- type: "block-end",
603
- index: entry.index,
604
- block
605
- };
606
- break;
607
- }
608
- case "response.completed": {
609
- const usage = event.response?.usage ?? void 0;
610
- const mapped = usage === void 0 ? void 0 : mapUsage(usage);
611
- if (mapped !== void 0) yield {
612
- type: "usage",
613
- usage: mapped
614
- };
615
- yield {
616
- type: "finish",
617
- reason: sawToolCall ? { kind: "tool-calls" } : { kind: "stop" }
618
- };
619
- terminated = true;
620
- return;
621
- }
622
- case "response.incomplete": {
623
- const usage = event.response?.usage ?? void 0;
624
- const mapped = usage === void 0 ? void 0 : mapUsage(usage);
625
- if (mapped !== void 0) yield {
626
- type: "usage",
627
- usage: mapped
628
- };
629
- const why = event.response?.incomplete_details?.reason;
630
- if (why === "max_output_tokens") {
631
- yield {
632
- type: "finish",
633
- reason: { kind: "max-tokens" }
634
- };
635
- terminated = true;
636
- return;
637
- }
638
- throw new ModelError(`${displayName} returned an incomplete response (${why ?? "unknown reason"})`, MODEL_ERROR_CODES.SERVER);
639
- }
640
- case "response.failed": {
641
- const usage = event.response?.usage ?? void 0;
642
- const mapped = usage === void 0 ? void 0 : mapUsage(usage);
643
- if (mapped !== void 0) yield {
644
- type: "usage",
645
- usage: mapped
646
- };
647
- throw failedError(event.response, displayName);
648
- }
649
- case "error": throw failedError({ error: {
650
- ...event.code === void 0 ? {} : { code: event.code },
651
- ...event.message === void 0 ? {} : { message: event.message }
652
- } }, displayName);
653
- }
722
+ const event = parseEvent(raw, displayName);
723
+ yield* translateEvent(state, event, displayName);
724
+ if (event.type === "response.completed" || event.type === "response.incomplete") return;
654
725
  }
655
- if (!terminated) throw new ModelError(`${displayName} stream ended before the response completed`, MODEL_ERROR_CODES.STREAM_CLOSED);
726
+ throw new ModelError(`${displayName} stream ended before the response completed`, MODEL_ERROR_CODES.STREAM_CLOSED);
656
727
  }
657
- /** Our block-type tag for one item kind. */
658
- function kindToBlockType(kind) {
659
- return kind;
660
- }
661
- function requestedImageMediaType(request) {
662
- const tool = request?.options.tools?.find((candidate) => "type" in candidate && candidate.type === "native" && candidate.name === "image-generation");
663
- if (tool === void 0 || !("format" in tool)) return "image/png";
664
- if (tool.format === "jpeg") return "image/jpeg";
665
- if (tool.format === "webp") return "image/webp";
666
- return "image/png";
728
+ function parseEvent(raw, displayName) {
729
+ try {
730
+ return JSON.parse(raw.data);
731
+ } catch (error) {
732
+ throw new ModelError(`${displayName} sent a malformed stream event`, MODEL_ERROR_CODES.MALFORMED_RESPONSE, { cause: error });
733
+ }
667
734
  }
668
735
 
669
736
  //#endregion