@providerkit/core 0.27.1 → 0.28.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 (84) hide show
  1. package/README.md +15 -0
  2. package/dist/auth/with-token.d.ts +3 -1
  3. package/dist/auth/with-token.d.ts.map +1 -1
  4. package/dist/auth/with-token.js +23 -4
  5. package/dist/auth/with-token.js.map +1 -1
  6. package/dist/errors.d.ts +2 -0
  7. package/dist/errors.d.ts.map +1 -1
  8. package/dist/errors.js +6 -0
  9. package/dist/errors.js.map +1 -1
  10. package/dist/fallback.d.ts +6 -4
  11. package/dist/fallback.d.ts.map +1 -1
  12. package/dist/fallback.js +13 -7
  13. package/dist/fallback.js.map +1 -1
  14. package/dist/index.d.ts +1 -1
  15. package/dist/index.d.ts.map +1 -1
  16. package/dist/index.js +3 -1
  17. package/dist/index.js.map +1 -1
  18. package/dist/key-pool.d.ts.map +1 -1
  19. package/dist/key-pool.js +3 -5
  20. package/dist/key-pool.js.map +1 -1
  21. package/dist/presets.d.ts +50 -0
  22. package/dist/presets.d.ts.map +1 -1
  23. package/dist/presets.js +82 -0
  24. package/dist/presets.js.map +1 -1
  25. package/dist/providers/anthropic.d.ts.map +1 -1
  26. package/dist/providers/anthropic.js +2 -1
  27. package/dist/providers/anthropic.js.map +1 -1
  28. package/dist/providers/factory.js +4 -1
  29. package/dist/providers/factory.js.map +1 -1
  30. package/dist/providers/gemini-speech.d.ts +25 -0
  31. package/dist/providers/gemini-speech.d.ts.map +1 -0
  32. package/dist/providers/gemini-speech.js +172 -0
  33. package/dist/providers/gemini-speech.js.map +1 -0
  34. package/dist/providers/gemini.d.ts.map +1 -1
  35. package/dist/providers/gemini.js +4 -1
  36. package/dist/providers/gemini.js.map +1 -1
  37. package/dist/providers/openai-speech.d.ts +23 -0
  38. package/dist/providers/openai-speech.d.ts.map +1 -0
  39. package/dist/providers/openai-speech.js +86 -0
  40. package/dist/providers/openai-speech.js.map +1 -0
  41. package/dist/providers/openai.d.ts.map +1 -1
  42. package/dist/providers/openai.js +2 -1
  43. package/dist/providers/openai.js.map +1 -1
  44. package/dist/providers/responses.d.ts.map +1 -1
  45. package/dist/providers/responses.js +2 -1
  46. package/dist/providers/responses.js.map +1 -1
  47. package/dist/providers/speech-factory.d.ts +35 -0
  48. package/dist/providers/speech-factory.d.ts.map +1 -0
  49. package/dist/providers/speech-factory.js +47 -0
  50. package/dist/providers/speech-factory.js.map +1 -0
  51. package/dist/speech-core.d.ts +184 -0
  52. package/dist/speech-core.d.ts.map +1 -0
  53. package/dist/speech-core.js +349 -0
  54. package/dist/speech-core.js.map +1 -0
  55. package/dist/speech.d.ts +6 -0
  56. package/dist/speech.d.ts.map +1 -0
  57. package/dist/speech.js +12 -0
  58. package/dist/speech.js.map +1 -0
  59. package/dist/transport.d.ts +42 -0
  60. package/dist/transport.d.ts.map +1 -1
  61. package/dist/transport.js +154 -11
  62. package/dist/transport.js.map +1 -1
  63. package/dist/types.d.ts +10 -0
  64. package/dist/types.d.ts.map +1 -1
  65. package/dist/types.js.map +1 -1
  66. package/package.json +6 -1
  67. package/src/auth/with-token.ts +24 -7
  68. package/src/errors.ts +7 -0
  69. package/src/fallback.ts +40 -18
  70. package/src/index.ts +14 -1
  71. package/src/key-pool.ts +38 -37
  72. package/src/presets.ts +113 -0
  73. package/src/providers/anthropic.ts +8 -1
  74. package/src/providers/factory.ts +4 -1
  75. package/src/providers/gemini-speech.ts +232 -0
  76. package/src/providers/gemini.ts +10 -1
  77. package/src/providers/openai-speech.ts +125 -0
  78. package/src/providers/openai.ts +8 -1
  79. package/src/providers/responses.ts +8 -1
  80. package/src/providers/speech-factory.ts +85 -0
  81. package/src/speech-core.ts +507 -0
  82. package/src/speech.ts +24 -0
  83. package/src/transport.ts +185 -11
  84. package/src/types.ts +10 -0
package/src/key-pool.ts CHANGED
@@ -13,7 +13,7 @@
13
13
  // error propagates untouched: a transient 503 must not switch a single-key
14
14
  // deployment off for a minute, where the caller's own retry is the whole
15
15
  // recovery there is.
16
- import { isTransient, ProviderError } from "./errors.ts";
16
+ import { isTransient, ProviderError, validateMaxAttempts } from "./errors.ts";
17
17
  import type { ErrorKind } from "./errors.ts";
18
18
  import type {
19
19
  ChatMessage,
@@ -135,9 +135,7 @@ export class KeyPool {
135
135
  opts: KeyPoolCallOptions = {},
136
136
  ): Promise<T> {
137
137
  const { maxAttempts } = opts;
138
- if (maxAttempts !== undefined && (!Number.isInteger(maxAttempts) || maxAttempts < 1)) {
139
- throw new RangeError("KeyPool maxAttempts must be a positive integer");
140
- }
138
+ validateMaxAttempts(maxAttempts);
141
139
  const candidates = this.candidates(this.now());
142
140
  if (candidates.length === 0) throw this.noneAvailable();
143
141
 
@@ -260,41 +258,44 @@ export function withKeyPool(pool: KeyPool, factory: (apiKey: string) => Provider
260
258
  tools: ToolDefinition[],
261
259
  opts: StreamOptions = {},
262
260
  ): AsyncIterable<ProviderChunk> {
263
- const opened = await pool.with(async (apiKey) => {
264
- // One AbortController per attempt, chained to the caller's own signal
265
- // (retry.ts's rule). Finalizing a generator is not cancellation:
266
- // `return()` unwinds the adapter down to `streamSse`'s finalizer, which
267
- // only releases the reader's lock — the response body stays live and
268
- // the request is never aborted. Without this controller an abandoned
269
- // attempt keeps the provider generating the rest of the answer, holding
270
- // a connection and a concurrency slot on the very key the pool is
271
- // rotating away from.
272
- const controller = new AbortController();
273
- const onAbort = () => controller.abort(opts.signal?.reason);
274
- if (opts.signal?.aborted) onAbort();
275
- else opts.signal?.addEventListener("abort", onAbort, { once: true });
261
+ const opened = await pool.with(
262
+ async (apiKey) => {
263
+ // One AbortController per attempt, chained to the caller's own signal
264
+ // (retry.ts's rule). Finalizing a generator is not cancellation:
265
+ // `return()` unwinds the adapter down to `streamSse`'s finalizer, which
266
+ // only releases the reader's lock — the response body stays live and
267
+ // the request is never aborted. Without this controller an abandoned
268
+ // attempt keeps the provider generating the rest of the answer, holding
269
+ // a connection and a concurrency slot on the very key the pool is
270
+ // rotating away from.
271
+ const controller = new AbortController();
272
+ const onAbort = () => controller.abort(opts.signal?.reason);
273
+ if (opts.signal?.aborted) onAbort();
274
+ else opts.signal?.addEventListener("abort", onAbort, { once: true });
276
275
 
277
- const stream = factory(apiKey).createStream(messages, tools, {
278
- ...opts,
279
- signal: controller.signal,
280
- });
281
- const iterator = stream[Symbol.asyncIterator]();
282
- const release = async () => {
283
- opts.signal?.removeEventListener("abort", onAbort);
284
- await close(iterator);
285
- controller.abort();
286
- };
276
+ const stream = factory(apiKey).createStream(messages, tools, {
277
+ ...opts,
278
+ signal: controller.signal,
279
+ });
280
+ const iterator = stream[Symbol.asyncIterator]();
281
+ const release = async () => {
282
+ opts.signal?.removeEventListener("abort", onAbort);
283
+ await close(iterator);
284
+ controller.abort();
285
+ };
287
286
 
288
- try {
289
- return { iterator, first: await iterator.next(), release };
290
- } catch (err) {
291
- // The request failed under the pool, which is about to try the next
292
- // key: release this attempt before a second one opens against the
293
- // same rate limit.
294
- await release();
295
- throw err;
296
- }
297
- });
287
+ try {
288
+ return { iterator, first: await iterator.next(), release };
289
+ } catch (err) {
290
+ // The request failed under the pool, which is about to try the next
291
+ // key: release this attempt before a second one opens against the
292
+ // same rate limit.
293
+ await release();
294
+ throw err;
295
+ }
296
+ },
297
+ { maxAttempts: opts.maxAttempts },
298
+ );
298
299
 
299
300
  const { iterator, first, release } = opened;
300
301
  try {
package/src/presets.ts CHANGED
@@ -19,6 +19,7 @@
19
19
  * Point createOpenAIProvider's baseUrl at your resource instead.
20
20
  */
21
21
  import type { ImageLimits } from "./image.ts";
22
+ import type { SpeechFormat, SpeechShape } from "./speech-core.ts";
22
23
 
23
24
  export type PresetShape = "anthropic" | "openai" | "responses" | "gemini";
24
25
 
@@ -51,6 +52,33 @@ export interface PresetRoute {
51
52
  auth?: PresetAuth;
52
53
  }
53
54
 
55
+ /**
56
+ * What a preset's endpoint can do besides chat: make speech. Absent means it
57
+ * cannot, or that nobody has read its documentation yet. `createSpeechProvider`
58
+ * (from `@providerkit/core/speech`) is what reads this.
59
+ *
60
+ * These are facts about the vendor's own host. A caller who points the preset at
61
+ * another host with `baseUrl` gets none of the defaults below, because a default
62
+ * model or voice belongs to the host that documented it.
63
+ */
64
+ export interface PresetSpeech {
65
+ shape: SpeechShape;
66
+ /** Defaults to the preset's own `baseUrl`. */
67
+ baseUrl?: string;
68
+ /** Only when the vendor documents one. */
69
+ defaultModel?: string;
70
+ /** Representative model ids, as in `ProviderPreset.models`. */
71
+ models?: readonly string[];
72
+ /** A default voice, only when one voice works on every listed model. */
73
+ defaultVoice?: string;
74
+ /** The vendor's full voice list, only when it publishes one. */
75
+ voices?: readonly string[];
76
+ /** The vendor's documented text limit. Absent: the package's 4,096. */
77
+ maxInputChars?: number;
78
+ /** For a host whose accepted formats do not include "wav". */
79
+ defaultFormat?: SpeechFormat;
80
+ }
81
+
54
82
  export interface ProviderPreset {
55
83
  /** Adapter wire format. */
56
84
  shape: PresetShape;
@@ -106,6 +134,8 @@ export interface ProviderPreset {
106
134
  /** OpenAI shape: never send `temperature` or `top_p`, for an endpoint that
107
135
  * fixes its own sampling and answers the fields with an error. */
108
136
  noSampling?: boolean;
137
+ /** Text to speech on this endpoint. See `PresetSpeech`. */
138
+ speech?: PresetSpeech;
109
139
  }
110
140
 
111
141
  export const PROVIDER_PRESETS = {
@@ -123,6 +153,34 @@ export const PROVIDER_PRESETS = {
123
153
  auth: "key",
124
154
  defaultModel: "gpt-5.6-sol",
125
155
  models: ["gpt-5.6-sol", "gpt-5.5-pro", "gpt-5.4-mini"],
156
+ // Source: OpenAI's speech reference and text-to-speech guide, read 2026-11-02.
157
+ // OpenAI shuts all three models down on 2027-01-06 (its deprecations page), and
158
+ // names a Realtime model as the replacement, which `/audio/speech` cannot reach.
159
+ // After that date this row is useful only for OpenAI-compatible servers reached
160
+ // through `baseUrl`. Remove the OpenAI ids then.
161
+ speech: {
162
+ shape: "openai",
163
+ defaultModel: "gpt-4o-mini-tts",
164
+ models: ["gpt-4o-mini-tts", "tts-1", "tts-1-hd"],
165
+ // `alloy` works on all three models. `tts-1` and `tts-1-hd` take only nine of the thirteen.
166
+ defaultVoice: "alloy",
167
+ voices: [
168
+ "alloy",
169
+ "ash",
170
+ "ballad",
171
+ "coral",
172
+ "echo",
173
+ "fable",
174
+ "onyx",
175
+ "nova",
176
+ "sage",
177
+ "shimmer",
178
+ "verse",
179
+ "marin",
180
+ "cedar",
181
+ ],
182
+ maxInputChars: 4096,
183
+ },
126
184
  },
127
185
  google: {
128
186
  // Native Generative Language REST — the adapter authenticates with
@@ -132,6 +190,51 @@ export const PROVIDER_PRESETS = {
132
190
  auth: "key",
133
191
  defaultModel: "gemini-3.1-pro-preview",
134
192
  models: ["gemini-3.1-pro-preview", "gemini-3.8-flash", "gemini-flash-latest"],
193
+ // Source: Google's speech generation guide, read 2026-11-02. Only the default
194
+ // model has run against the live API; the lite id comes from the guide. The guide
195
+ // also names `gemini-3.1-flash-tts-preview` (it says that model answered headerless
196
+ // PCM by default, which a wav request refuses as `bad_audio` after the charge) and
197
+ // `gemini-2.5-pro-preview-tts`. Both stay out of `models` until the probe has run
198
+ // them; a caller can still pass either id as `model`, with `format: "pcm"`.
199
+ speech: {
200
+ shape: "gemini",
201
+ defaultModel: "gemini-3.8-flash-tts",
202
+ models: ["gemini-3.8-flash-tts", "gemini-3.8-flash-lite-tts"],
203
+ defaultVoice: "Kore",
204
+ // The guide's thirty prebuilt voices, in its order.
205
+ voices: [
206
+ "Zephyr",
207
+ "Puck",
208
+ "Charon",
209
+ "Kore",
210
+ "Fenrir",
211
+ "Leda",
212
+ "Orus",
213
+ "Aoede",
214
+ "Callirrhoe",
215
+ "Autonoe",
216
+ "Enceladus",
217
+ "Iapetus",
218
+ "Umbriel",
219
+ "Algieba",
220
+ "Despina",
221
+ "Erinome",
222
+ "Algenib",
223
+ "Rasalgethi",
224
+ "Laomedeia",
225
+ "Achernar",
226
+ "Alnilam",
227
+ "Schedar",
228
+ "Gacrux",
229
+ "Pulcherrima",
230
+ "Achird",
231
+ "Zubenelgenubi",
232
+ "Vindemiatrix",
233
+ "Sadachbia",
234
+ "Sadaltager",
235
+ "Sulafat",
236
+ ],
237
+ },
135
238
  },
136
239
  /** Gemini behind its OpenAI-compatible route, for codebases
137
240
  * that only speak the openai shape. */
@@ -165,6 +268,13 @@ export const PROVIDER_PRESETS = {
165
268
  "x-ai/grok-4.6",
166
269
  "openai/gpt-5.6-luna-pro",
167
270
  ],
271
+ // Source: OpenRouter's text-to-speech guide, read 2026-11-02. It takes mp3 or pcm
272
+ // (its own default is pcm), and some models take only one: Gemini TTS and HeyGen
273
+ // answer 400 to mp3, MiniMax to pcm. This row asks for mp3, so a Gemini TTS model
274
+ // here needs `format: "pcm"`, and a pcm reply states no sample rate. No default
275
+ // model or voice: both depend on the speech model chosen, and
276
+ // `GET /api/v1/models?output_modalities=speech` lists them.
277
+ speech: { shape: "openai", defaultFormat: "mp3" },
168
278
  },
169
279
  groq: {
170
280
  shape: "openai",
@@ -723,3 +833,6 @@ export type ProviderPresetId = keyof typeof PROVIDER_PRESETS;
723
833
 
724
834
  /** Every valid preset id. The factory's unknown-id error lists these. */
725
835
  export const PRESET_IDS = Object.keys(PROVIDER_PRESETS) as ProviderPresetId[];
836
+
837
+ /** The presets that can speak, for a screen that offers exactly those. */
838
+ export const SPEECH_PRESET_IDS = PRESET_IDS.filter((id) => "speech" in PROVIDER_PRESETS[id]);
@@ -1,6 +1,12 @@
1
1
  // Anthropic-shape adapter — SSE from POST /v1/messages.
2
2
  import { repairHistory } from "../context.ts";
3
- import { fileRefused, ProviderError, streamCut, streamError } from "../errors.ts";
3
+ import {
4
+ fileRefused,
5
+ ProviderError,
6
+ streamCut,
7
+ streamError,
8
+ validateMaxAttempts,
9
+ } from "../errors.ts";
4
10
  import { schemaPrompt, toAnthropicToolSchema } from "../schema.ts";
5
11
  import { parseToolArgs, settleToolCalls, type ToolCallIdentity } from "../tool-args.ts";
6
12
  import { streamSse, apiUrl, parseFrame } from "../transport.ts";
@@ -422,6 +428,7 @@ export function createAnthropicProvider(config: AnthropicConfig): Provider {
422
428
  tools: ToolDefinition[],
423
429
  opts: StreamOptions = {},
424
430
  ): AsyncIterable<ProviderChunk> {
431
+ validateMaxAttempts(opts.maxAttempts);
425
432
  const model = opts.model ?? config.model;
426
433
  const maxTokens = opts.maxTokens ?? config.maxTokens ?? DEFAULT_MAX_TOKENS;
427
434
  const effort = opts.effort ?? config.effort;
@@ -10,7 +10,7 @@
10
10
  // `effort` passes through to the adapter unchanged — the per-endpoint
11
11
  // thinking dialects (Z.ai's explicit disabled marker, OpenRouter's floors)
12
12
  // are the adapters' knowledge, and this factory must not re-derive them.
13
- import { ProviderError } from "../errors.ts";
13
+ import { ProviderError, validateMaxAttempts } from "../errors.ts";
14
14
  import { createAnthropicProvider } from "./anthropic.ts";
15
15
  import { createGeminiProvider } from "./gemini.ts";
16
16
  import { createOpenAIProvider } from "./openai.ts";
@@ -360,6 +360,8 @@ function wrapOpenCodeZen(
360
360
  return {
361
361
  ...baseProvider,
362
362
  async *createStream(messages, tools, opts = {}) {
363
+ const { maxAttempts } = opts;
364
+ validateMaxAttempts(maxAttempts);
363
365
  const activeModel = opts.model ?? defaultModel;
364
366
  const free = isZenFreeModel(activeModel);
365
367
  const ses = await forgeOpenCodeSessionId(opts.sessionId ?? instanceSessionId);
@@ -431,6 +433,7 @@ function wrapOpenCodeZen(
431
433
  // and refuse a stale key with 401. Retry anonymously when that happens.
432
434
  if (
433
435
  free &&
436
+ maxAttempts !== 1 &&
434
437
  !startAnonymous &&
435
438
  !emitted &&
436
439
  err instanceof ProviderError &&
@@ -0,0 +1,232 @@
1
+ // The Gemini speech wire: POST /v1beta/interactions, JSON in, JSON out with the audio
2
+ // as base64. One request per call; speech-core.ts says why.
3
+ //
4
+ // The request is the one an adopter has already run against the live API. Fields it
5
+ // has not proven are not sent: `mime_type` rides only on a raw PCM request, and
6
+ // `scripts/probe-speech.ts` is how a maintainer settles the rest with a real key.
7
+ import {
8
+ asRecord,
9
+ decodeBase64,
10
+ describeAudio,
11
+ inBandFailure,
12
+ prepareSpeech,
13
+ resolveLimits,
14
+ synthesizeOnce,
15
+ unusable,
16
+ type SpeechFormat,
17
+ type SpeechLimits,
18
+ type SpeechProvider,
19
+ type SpeechUsage,
20
+ } from "../speech-core.ts";
21
+ import { apiUrl, postBytes, versionedPath } from "../transport.ts";
22
+
23
+ export interface GeminiSpeechConfig extends SpeechLimits {
24
+ apiKey: string;
25
+ model: string;
26
+ /** Default `https://generativelanguage.googleapis.com`. */
27
+ baseUrl?: string;
28
+ /** Default `/v1beta/interactions`. */
29
+ path?: string;
30
+ /** The preset id. Names the provider in errors and on `SpeechProvider.id`. Default "google". */
31
+ id?: string;
32
+ /** Used when a call names no voice. */
33
+ voice?: string;
34
+ /** "wav" (the default) or "pcm". Gemini makes no other format. */
35
+ format?: SpeechFormat;
36
+ /**
37
+ * Caps the audio tokens generated. Not sent unless set. Whether a TTS model
38
+ * honours the cap is unmeasured; the text limit is the real bound on cost.
39
+ */
40
+ maxOutputTokens?: number;
41
+ headers?: Record<string, string>;
42
+ /** Swapped in tests, or to route through a proxy. Defaults to global fetch. */
43
+ fetchImpl?: typeof fetch;
44
+ }
45
+
46
+ const FORMATS: readonly SpeechFormat[] = ["wav", "pcm"];
47
+
48
+ /** The rate a raw PCM request asks for, and the only one this adapter asks for. */
49
+ const PCM_RATE = 24_000;
50
+
51
+ const count = (value: unknown): number | undefined =>
52
+ typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
53
+
54
+ /**
55
+ * The provider's own token counts, or nothing. Counts that do not add up are
56
+ * dropped whole: a wrong number in a ledger is worse than a missing one.
57
+ */
58
+ function readUsage(raw: unknown): SpeechUsage | undefined {
59
+ const usage = asRecord(raw);
60
+ const input = count(usage?.total_input_tokens);
61
+ const output = count(usage?.total_output_tokens);
62
+ const total = count(usage?.total_tokens);
63
+ if (input === undefined || output === undefined || total === undefined) return undefined;
64
+ if (!Number.isSafeInteger(input + output) || total < input + output) return undefined;
65
+ let cached = 0;
66
+ if (usage?.total_cached_tokens !== undefined) {
67
+ const reported = count(usage.total_cached_tokens);
68
+ if (reported === undefined || reported > input) return undefined;
69
+ cached = reported;
70
+ }
71
+ return {
72
+ inputTokens: input,
73
+ cachedInputTokens: cached,
74
+ outputTokens: output,
75
+ totalTokens: total,
76
+ };
77
+ }
78
+
79
+ export function createGeminiSpeechProvider(config: GeminiSpeechConfig): SpeechProvider {
80
+ const id = config.id ?? "google";
81
+ const provider = `speech:${id}`;
82
+ const baseUrl = config.baseUrl ?? "https://generativelanguage.googleapis.com";
83
+ const limits = resolveLimits(config);
84
+ if (config.maxOutputTokens !== undefined && (count(config.maxOutputTokens) ?? 0) < 1) {
85
+ throw new RangeError("[providerkit] maxOutputTokens must be a positive integer");
86
+ }
87
+ // The reply is JSON with the audio as base64: four characters for every three bytes,
88
+ // plus a bounded envelope around it.
89
+ const maxBase64 = Math.ceil(limits.maxAudioBytes / 3) * 4;
90
+ return {
91
+ id,
92
+ model: config.model,
93
+ async synthesize(request) {
94
+ const { text, voice, format } = prepareSpeech(provider, request, {
95
+ apiKey: config.apiKey,
96
+ voice: config.voice,
97
+ format: config.format,
98
+ maxInputChars: limits.maxInputChars,
99
+ formats: FORMATS,
100
+ });
101
+ return synthesizeOnce(provider, limits.timeoutMs, request, async (signal) => {
102
+ const { bytes, contentType } = await postBytes({
103
+ url: apiUrl(baseUrl, config.path ?? versionedPath(baseUrl, "/interactions", "v1beta")),
104
+ headers: {
105
+ ...(config.apiKey ? { "x-goog-api-key": config.apiKey } : {}),
106
+ ...config.headers,
107
+ },
108
+ body: {
109
+ model: config.model,
110
+ // Do not keep the person's text on the provider's side.
111
+ store: false,
112
+ input: [{ type: "user_input", content: [{ type: "text", text }] }],
113
+ response_format:
114
+ format === "pcm"
115
+ ? { type: "audio", mime_type: "audio/l16", sample_rate: PCM_RATE }
116
+ : { type: "audio" },
117
+ generation_config: {
118
+ ...(config.maxOutputTokens ? { max_output_tokens: config.maxOutputTokens } : {}),
119
+ // ponytail: Google's speech guide writes `speech_config`, its API reference writes
120
+ // `structured_speech_config`. This is the spelling that has run live. One field is
121
+ // the whole fix if the probe ever shows it stale.
122
+ speech_config: [{ voice }],
123
+ },
124
+ },
125
+ provider,
126
+ signal,
127
+ redirect: "error",
128
+ maxBytes: maxBase64 + 64 * 1024,
129
+ redactErrors: true,
130
+ ...(config.fetchImpl ? { fetchImpl: config.fetchImpl } : {}),
131
+ });
132
+ const envelope = contentType === "application/json" ? parseEnvelope(bytes) : undefined;
133
+ if (!envelope)
134
+ throw unusable(provider, "unknown", "bad_audio", "the reply is not a JSON object");
135
+ // From here on the provider has answered, so it has billed: every failure
136
+ // below carries the usage it stated.
137
+ const usage = readUsage(envelope.usage);
138
+ if (envelope.error !== undefined) throw inBandFailure(provider, envelope, usage);
139
+ const status = envelope.status;
140
+ if (status === "incomplete") {
141
+ throw unusable(
142
+ provider,
143
+ "invalid",
144
+ "incomplete",
145
+ "the audio stopped before it finished: shorten the text or raise maxOutputTokens",
146
+ usage,
147
+ );
148
+ }
149
+ if (status === "failed" || status === "cancelled") {
150
+ const reported = Array.isArray(envelope.errors) ? envelope.errors[0] : undefined;
151
+ throw reported !== undefined
152
+ ? inBandFailure(provider, reported, usage)
153
+ : unusable(provider, "unknown", status, `the interaction ${status}`, usage);
154
+ }
155
+ if (status !== "completed") {
156
+ throw unusable(
157
+ provider,
158
+ "unknown",
159
+ "unexpected_status",
160
+ "the interaction did not complete",
161
+ usage,
162
+ );
163
+ }
164
+ const block = lastAudioBlock(envelope);
165
+ if (!block)
166
+ throw unusable(provider, "overload", "empty_audio", "the reply holds no audio", usage);
167
+ // A link instead of data is refused and never fetched: a reply must not choose
168
+ // which address this package calls next.
169
+ if (typeof block.data !== "string" || block.data === "") {
170
+ throw unusable(
171
+ provider,
172
+ "unknown",
173
+ "bad_audio",
174
+ "the audio block has no inline data",
175
+ usage,
176
+ );
177
+ }
178
+ const tooLarge = () =>
179
+ unusable(
180
+ provider,
181
+ "invalid",
182
+ "response_too_large",
183
+ "the audio is larger than the limit",
184
+ usage,
185
+ );
186
+ if (block.data.length > maxBase64) throw tooLarge();
187
+ const audio = decodeBase64(block.data);
188
+ if (!audio)
189
+ throw unusable(provider, "unknown", "bad_audio", "the audio is not valid base64", usage);
190
+ if (audio.byteLength > limits.maxAudioBytes) throw tooLarge();
191
+ const result = describeAudio(provider, audio, format, {
192
+ model: config.model,
193
+ voice,
194
+ characters: text.length,
195
+ ...(usage ? { usage } : {}),
196
+ // Raw PCM has no header. The rate was in the request, and the block may state
197
+ // the channel count. ponytail: these two block field names come from the API
198
+ // reference and are unverified, which is why a wrong value is ignored.
199
+ ...(format === "pcm" ? { sampleRate: count(block.sample_rate) || PCM_RATE } : {}),
200
+ ...(format === "pcm" && count(block.channels) ? { channels: count(block.channels) } : {}),
201
+ });
202
+ signal.throwIfAborted();
203
+ return result;
204
+ });
205
+ },
206
+ };
207
+ }
208
+
209
+ /** The last audio block across the `model_output` steps wins: an earlier invalid block
210
+ * is never preferred over it. */
211
+ function lastAudioBlock(envelope: Record<string, unknown>): Record<string, unknown> | undefined {
212
+ const steps: unknown[] = Array.isArray(envelope.steps) ? envelope.steps : [];
213
+ let block: Record<string, unknown> | undefined;
214
+ for (const step of steps) {
215
+ const record = asRecord(step);
216
+ if (record?.type !== "model_output" || !Array.isArray(record.content)) continue;
217
+ const parts: unknown[] = record.content;
218
+ for (const part of parts) {
219
+ const candidate = asRecord(part);
220
+ if (candidate?.type === "audio") block = candidate;
221
+ }
222
+ }
223
+ return block;
224
+ }
225
+
226
+ function parseEnvelope(bytes: Uint8Array): Record<string, unknown> | undefined {
227
+ try {
228
+ return asRecord(JSON.parse(new TextDecoder().decode(bytes)));
229
+ } catch {
230
+ return undefined;
231
+ }
232
+ }
@@ -6,7 +6,13 @@
6
6
  // wire rather than @google/genai, because this package ships zero dependencies
7
7
  // and the SDK is a Node-shaped one.
8
8
  import { repairHistory } from "../context.ts";
9
- import { ProviderError, streamCut, streamError, type ErrorKind } from "../errors.ts";
9
+ import {
10
+ ProviderError,
11
+ streamCut,
12
+ streamError,
13
+ validateMaxAttempts,
14
+ type ErrorKind,
15
+ } from "../errors.ts";
10
16
  import { schemaPrompt, toAntigravityToolSchema, toGeminiToolSchema } from "../schema.ts";
11
17
  import { parseToolArgs, settleToolCalls } from "../tool-args.ts";
12
18
  import { streamSse, apiUrl } from "../transport.ts";
@@ -413,6 +419,8 @@ export function createGeminiProvider(config: GeminiConfig): Provider {
413
419
  tools: ToolDefinition[],
414
420
  opts: StreamOptions = {},
415
421
  ): AsyncIterable<ProviderChunk> {
422
+ const { maxAttempts } = opts;
423
+ validateMaxAttempts(maxAttempts);
416
424
  const effort = opts.effort ?? config.effort;
417
425
  const maxTokens = opts.maxTokens ?? config.maxTokens;
418
426
  // Repaired first: a result with no call, or a call with no result, is a
@@ -690,6 +698,7 @@ export function createGeminiProvider(config: GeminiConfig): Provider {
690
698
  } catch (err) {
691
699
  const canFallback =
692
700
  !emitted &&
701
+ maxAttempts !== 1 &&
693
702
  baseIdx === 0 &&
694
703
  bases.length > 1 &&
695
704
  err instanceof ProviderError &&