@providerkit/core 0.30.0 → 0.31.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 (132) hide show
  1. package/README.md +33 -5
  2. package/THIRD_PARTY_NOTICES +144 -0
  3. package/dist/auth/chatgpt-models.js.map +1 -1
  4. package/dist/auth/oauth.d.ts.map +1 -1
  5. package/dist/auth/oauth.js.map +1 -1
  6. package/dist/capability.js.map +1 -1
  7. package/dist/context.d.ts +4 -3
  8. package/dist/context.d.ts.map +1 -1
  9. package/dist/context.js +19 -5
  10. package/dist/context.js.map +1 -1
  11. package/dist/decisions.js.map +1 -1
  12. package/dist/errors.d.ts.map +1 -1
  13. package/dist/errors.js.map +1 -1
  14. package/dist/fallback.d.ts +3 -0
  15. package/dist/fallback.d.ts.map +1 -1
  16. package/dist/fallback.js +9 -5
  17. package/dist/fallback.js.map +1 -1
  18. package/dist/gate.js.map +1 -1
  19. package/dist/hosted/anthropic.d.ts +30 -0
  20. package/dist/hosted/anthropic.d.ts.map +1 -0
  21. package/dist/hosted/anthropic.js +465 -0
  22. package/dist/hosted/anthropic.js.map +1 -0
  23. package/dist/hosted/gemini.d.ts +22 -0
  24. package/dist/hosted/gemini.d.ts.map +1 -0
  25. package/dist/hosted/gemini.js +440 -0
  26. package/dist/hosted/gemini.js.map +1 -0
  27. package/dist/hosted/openai.d.ts +33 -0
  28. package/dist/hosted/openai.d.ts.map +1 -0
  29. package/dist/hosted/openai.js +107 -0
  30. package/dist/hosted/openai.js.map +1 -0
  31. package/dist/hosted/responses.d.ts +28 -0
  32. package/dist/hosted/responses.d.ts.map +1 -0
  33. package/dist/hosted/responses.js +358 -0
  34. package/dist/hosted/responses.js.map +1 -0
  35. package/dist/hosted/shared.d.ts +107 -0
  36. package/dist/hosted/shared.d.ts.map +1 -0
  37. package/dist/hosted/shared.js +264 -0
  38. package/dist/hosted/shared.js.map +1 -0
  39. package/dist/hosted/types.d.ts +191 -0
  40. package/dist/hosted/types.d.ts.map +1 -0
  41. package/dist/hosted/types.js +10 -0
  42. package/dist/hosted/types.js.map +1 -0
  43. package/dist/hosted.d.ts +33 -0
  44. package/dist/hosted.d.ts.map +1 -0
  45. package/dist/hosted.js +61 -0
  46. package/dist/hosted.js.map +1 -0
  47. package/dist/index.d.ts +8 -7
  48. package/dist/index.d.ts.map +1 -1
  49. package/dist/index.js +8 -7
  50. package/dist/index.js.map +1 -1
  51. package/dist/key-pool.d.ts.map +1 -1
  52. package/dist/key-pool.js.map +1 -1
  53. package/dist/presets.d.ts +2 -2
  54. package/dist/presets.d.ts.map +1 -1
  55. package/dist/providers/anthropic.d.ts +75 -1
  56. package/dist/providers/anthropic.d.ts.map +1 -1
  57. package/dist/providers/anthropic.js +207 -135
  58. package/dist/providers/anthropic.js.map +1 -1
  59. package/dist/providers/factory.d.ts +10 -0
  60. package/dist/providers/factory.d.ts.map +1 -1
  61. package/dist/providers/factory.js +31 -23
  62. package/dist/providers/factory.js.map +1 -1
  63. package/dist/providers/gemini.d.ts +123 -1
  64. package/dist/providers/gemini.d.ts.map +1 -1
  65. package/dist/providers/gemini.js +114 -54
  66. package/dist/providers/gemini.js.map +1 -1
  67. package/dist/providers/hosted-codecs.d.ts +10 -0
  68. package/dist/providers/hosted-codecs.d.ts.map +1 -0
  69. package/dist/providers/hosted-codecs.js +8 -0
  70. package/dist/providers/hosted-codecs.js.map +1 -0
  71. package/dist/providers/openai.d.ts +69 -0
  72. package/dist/providers/openai.d.ts.map +1 -1
  73. package/dist/providers/openai.js +38 -14
  74. package/dist/providers/openai.js.map +1 -1
  75. package/dist/providers/responses.d.ts +123 -0
  76. package/dist/providers/responses.d.ts.map +1 -1
  77. package/dist/providers/responses.js +57 -22
  78. package/dist/providers/responses.js.map +1 -1
  79. package/dist/providers/speech-factory.js.map +1 -1
  80. package/dist/registry.d.ts +3 -0
  81. package/dist/registry.d.ts.map +1 -1
  82. package/dist/registry.js +8 -4
  83. package/dist/registry.js.map +1 -1
  84. package/dist/retry.js.map +1 -1
  85. package/dist/speech-core.d.ts.map +1 -1
  86. package/dist/speech-core.js.map +1 -1
  87. package/dist/tools.d.ts.map +1 -1
  88. package/dist/tools.js.map +1 -1
  89. package/dist/transcription-core.d.ts.map +1 -1
  90. package/dist/transcription-core.js.map +1 -1
  91. package/dist/transport.js.map +1 -1
  92. package/dist/turn.d.ts +10 -1
  93. package/dist/turn.d.ts.map +1 -1
  94. package/dist/turn.js +53 -1
  95. package/dist/turn.js.map +1 -1
  96. package/dist/types.d.ts +51 -0
  97. package/dist/types.d.ts.map +1 -1
  98. package/dist/types.js.map +1 -1
  99. package/dist/usage.d.ts +10 -1
  100. package/dist/usage.d.ts.map +1 -1
  101. package/dist/usage.js +40 -2
  102. package/dist/usage.js.map +1 -1
  103. package/dist/watchdog.d.ts +6 -0
  104. package/dist/watchdog.d.ts.map +1 -1
  105. package/dist/watchdog.js +10 -2
  106. package/dist/watchdog.js.map +1 -1
  107. package/package.json +10 -5
  108. package/src/context.ts +21 -5
  109. package/src/fallback.ts +21 -6
  110. package/src/hosted/anthropic.ts +512 -0
  111. package/src/hosted/gemini.ts +510 -0
  112. package/src/hosted/openai.ts +137 -0
  113. package/src/hosted/responses.ts +420 -0
  114. package/src/hosted/shared.ts +341 -0
  115. package/src/hosted/types.ts +214 -0
  116. package/src/hosted.ts +101 -0
  117. package/src/index.ts +64 -7
  118. package/src/providers/anthropic.ts +252 -143
  119. package/src/providers/factory.ts +127 -82
  120. package/src/providers/gemini.ts +184 -60
  121. package/src/providers/hosted-codecs.ts +29 -0
  122. package/src/providers/openai.ts +52 -15
  123. package/src/providers/responses.ts +93 -24
  124. package/src/registry.ts +14 -4
  125. package/src/turn.ts +55 -1
  126. package/src/types.ts +62 -1
  127. package/src/usage.ts +32 -2
  128. package/src/watchdog.ts +12 -2
  129. package/dist/jev.d.ts +0 -123
  130. package/dist/jev.d.ts.map +0 -1
  131. package/dist/jev.js +0 -278
  132. package/dist/jev.js.map +0 -1
@@ -0,0 +1,510 @@
1
+ // Built-ins and grounding follow Vercel AI SDK (Apache-2.0), PydanticAI
2
+ // and TanStack (MIT). See THIRD_PARTY_NOTICES.
3
+ import { ProviderError } from "../errors.ts";
4
+ import {
5
+ hostedCounts,
6
+ hostedRefused,
7
+ hostedReplay,
8
+ HostedRecorder,
9
+ planHostedTools,
10
+ queryInput,
11
+ servedAt,
12
+ utf8Index,
13
+ isRecord,
14
+ } from "./shared.ts";
15
+ import type {
16
+ Citation,
17
+ HostedCallDelta,
18
+ HostedInput,
19
+ HostedTool,
20
+ HostedToolType,
21
+ Source,
22
+ } from "./types.ts";
23
+ import type {
24
+ GeminiConfig,
25
+ GeminiPart,
26
+ GeminiResponse,
27
+ GroundingSegment,
28
+ GroundingChunk,
29
+ GroundingMetadata,
30
+ } from "../providers/gemini.ts";
31
+ import type {
32
+ ChatMessage,
33
+ ToolCall,
34
+ ToolDefinition,
35
+ StreamOptions,
36
+ ProviderChunk,
37
+ TokenUsage,
38
+ } from "../types.ts";
39
+
40
+ /** The hosted types this wire has a shape for, and the fields it applies.
41
+ * Gemini's built-ins take no domain filter, use cap or location. */
42
+ const GEMINI_FIELDS: Partial<Record<HostedToolType, readonly string[]>> = {
43
+ web_search: [],
44
+ web_fetch: [],
45
+ code_execution: [],
46
+ file_search: ["storeIds", "maxResults"],
47
+ };
48
+ const GEMINI_SENDS = Object.keys(GEMINI_FIELDS);
49
+
50
+ /** One built-in tool on the wire. Shapes from Vercel's AI SDK (Apache-2.0),
51
+ * google-prepare-tools.ts:85-140. */
52
+ function geminiHostedTool(provider: string, tool: HostedTool): unknown {
53
+ switch (tool.type) {
54
+ case "web_search":
55
+ return { googleSearch: {} };
56
+ case "web_fetch":
57
+ return { urlContext: {} };
58
+ case "code_execution":
59
+ return { codeExecution: {} };
60
+ case "file_search":
61
+ return {
62
+ fileSearch: {
63
+ fileSearchStoreNames: tool.storeIds,
64
+ ...(tool.maxResults !== undefined ? { topK: tool.maxResults } : {}),
65
+ },
66
+ };
67
+ default:
68
+ // planHostedTools only passes the types in GEMINI_FIELDS.
69
+ throw new ProviderError(provider, "invalid", `${provider}: no Gemini shape for ${tool.type}`);
70
+ }
71
+ }
72
+
73
+ /** The seam's type for a server-side tool part (`toolCall`, `toolResponse`),
74
+ * by Gemini's `toolType` (TanStack ai-gemini text.ts:161-177, MIT). */
75
+ function serverToolType(toolType: string | undefined): HostedToolType | undefined {
76
+ if (!toolType) return undefined;
77
+ if (toolType.startsWith("GOOGLE_SEARCH")) return "web_search";
78
+ if (toolType === "URL_CONTEXT") return "web_fetch";
79
+ if (toolType === "CODE_EXECUTION") return "code_execution";
80
+ if (toolType === "FILE_SEARCH") return "file_search";
81
+ return undefined;
82
+ }
83
+
84
+ function serverToolUrls(args: Record<string, unknown> | undefined): string[] {
85
+ return [args?.url, ...(Array.isArray(args?.urls) ? args.urls : [])].filter(
86
+ (url): url is string => typeof url === "string" && !!url,
87
+ );
88
+ }
89
+
90
+ function serverToolInput(args: Record<string, unknown> | undefined): HostedInput {
91
+ if (!args) return {};
92
+ const text = (value: unknown) => (typeof value === "string" ? value : undefined);
93
+ const list = (value: unknown) =>
94
+ Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === "string") : [];
95
+ const search = queryInput([text(args.query), ...list(args.queries)]);
96
+ if (Object.keys(search).length > 0) return search;
97
+ const url = serverToolUrls(args)[0];
98
+ return url ? { url } : {};
99
+ }
100
+
101
+ // File Search can arrive as executable code with its result in grounding, not
102
+ // as a code run. Ported from PydanticAI (MIT), _FILE_SEARCH_QUERY_PATTERN.
103
+ const FILE_SEARCH_QUERY = /file_search\.query\(query=(["'])((?:\\.|(?!\1)[^\\])*)\1\)/;
104
+
105
+ /** Text fragments of one response Part, with its offset in the flat answer.
106
+ * Non-text Parts occupy empty slots so grounding's partIndex keeps its meaning. */
107
+ interface GeminiTextPart {
108
+ text: string;
109
+ at: number;
110
+ thought: boolean;
111
+ }
112
+
113
+ /**
114
+ * Where a grounding segment sits in the answer, as JS indices. Gemini counts
115
+ * in UTF-8 bytes, so the offsets are converted and then checked against the
116
+ * segment's own text. Google sometimes reports a segment a byte off; the text
117
+ * still places it when it occurs once. Otherwise the citation keeps its
118
+ * source and no span. Ported from PydanticAI (MIT), models/google.py:2347-2405.
119
+ */
120
+ function segmentSpan(
121
+ answer: string,
122
+ segment: GroundingSegment | undefined,
123
+ parts: readonly (GeminiTextPart | undefined)[],
124
+ ): { start: number; end: number } | undefined {
125
+ if (!segment?.text) return undefined;
126
+ const part = segment.partIndex === undefined ? undefined : parts[segment.partIndex];
127
+ // An explicit Part index never falls back to a different Part's words.
128
+ if (segment.partIndex !== undefined && (!part || part.thought)) return undefined;
129
+ const text = part?.text ?? answer;
130
+ const offset = part?.at ?? 0;
131
+ const said = segment.text;
132
+ const start = utf8Index(text, segment.startIndex ?? 0);
133
+ const end = utf8Index(text, segment.endIndex ?? 0);
134
+ if (start !== undefined && end !== undefined && start < end && text.slice(start, end) === said) {
135
+ return { start: offset + start, end: offset + end };
136
+ }
137
+ const at = text.indexOf(said);
138
+ return at !== -1 && text.indexOf(said, at + 1) === -1
139
+ ? { start: offset + at, end: offset + at + said.length }
140
+ : undefined;
141
+ }
142
+
143
+ /** A grounding chunk as a source: a web page, or a passage of a stored file. */
144
+ function chunkSource(chunk: GroundingChunk): Source | undefined {
145
+ if (chunk.web?.uri) {
146
+ return {
147
+ type: "url",
148
+ url: chunk.web.uri,
149
+ ...(chunk.web.title ? { title: chunk.web.title } : {}),
150
+ };
151
+ }
152
+ const context = chunk.retrievedContext;
153
+ if (!context) return undefined;
154
+ return {
155
+ type: "file",
156
+ ...(context.uri ? { url: context.uri } : {}),
157
+ ...(context.title ? { title: context.title } : {}),
158
+ ...(context.text ? { excerpt: context.text } : {}),
159
+ };
160
+ }
161
+
162
+ /** The first of each URL, in order: a page several supports cite is one
163
+ * source of the search, not several. */
164
+ function distinctSources(sources: readonly Source[]): Source[] {
165
+ const seen = new Set<string>();
166
+ return sources.filter((source) => {
167
+ const key = source.url ?? source.title ?? source.excerpt ?? "";
168
+ if (seen.has(key)) return false;
169
+ seen.add(key);
170
+ return true;
171
+ });
172
+ }
173
+
174
+ export const geminiHosted = {
175
+ plan(
176
+ config: GeminiConfig,
177
+ baseUrl: string,
178
+ id: string,
179
+ isAntigravity: boolean,
180
+ isGemini2: boolean,
181
+ tools: ToolDefinition[],
182
+ opts: StreamOptions,
183
+ ) {
184
+ let hosted = planHostedTools(
185
+ id,
186
+ {
187
+ name: "Gemini",
188
+ serves: isAntigravity
189
+ ? []
190
+ : (
191
+ config.servesHostedTools ??
192
+ servedAt(baseUrl, "generativelanguage.googleapis.com", [
193
+ "web_search",
194
+ "web_fetch",
195
+ "code_execution",
196
+ "file_search",
197
+ ])
198
+ ).filter((type) => GEMINI_SENDS.includes(type)),
199
+ fields: GEMINI_FIELDS,
200
+ // Gemini 2 runs built-in tools or function tools in one request, not
201
+ // both (Vercel warns and drops the functions, google-prepare-tools.ts:70-79).
202
+ refuse: () =>
203
+ isGemini2 && tools.length > 0
204
+ ? "Gemini 2 can't run hosted tools beside function tools. Use a Gemini 3 model, " +
205
+ "send the hosted tools on a call without function tools, or mark them optional."
206
+ : undefined,
207
+ },
208
+ opts,
209
+ );
210
+
211
+ // File Search cannot share a request with other built-ins (Google's
212
+ // File Search guide, limitations). Apply this after field refusals so an
213
+ // optional sibling never excuses a required tool's unsupported setting.
214
+ const fileSearch = hosted.find((tool) => tool.type === "file_search");
215
+ const otherHosted = hosted.filter((tool) => tool !== fileSearch);
216
+ if (fileSearch && otherHosted.length > 0) {
217
+ if (otherHosted.some((tool) => !tool.optional)) {
218
+ if (!fileSearch.optional) {
219
+ throw hostedRefused(
220
+ id,
221
+ "Gemini",
222
+ "file_search",
223
+ "File Search can't run beside other hosted tools. Send it on a separate call, " +
224
+ "or mark a conflicting tool optional.",
225
+ );
226
+ }
227
+ hosted = otherHosted;
228
+ } else {
229
+ hosted = [fileSearch];
230
+ }
231
+ }
232
+
233
+ return { hosted, tools: hosted.map((tool) => geminiHostedTool(id, tool)) };
234
+ },
235
+ replay(
236
+ message: Extract<ChatMessage, { role: "assistant" }>,
237
+ provider: string,
238
+ functionCallPart: (call: ToolCall) => unknown,
239
+ ): unknown[] | undefined {
240
+ return hostedReplay(message, provider)?.map((entry) => {
241
+ if ("call" in entry) return functionCallPart(entry.call);
242
+ if ("item" in entry) return entry.item;
243
+ return { text: entry.text };
244
+ });
245
+ },
246
+ stream(id: string, hosted: HostedTool[], isGemini2: boolean) {
247
+ const recorder = new HostedRecorder();
248
+ // The answer so far, thoughts left out: what grounding offsets count into.
249
+ let text = "";
250
+ const textParts: (GeminiTextPart | undefined)[] = [];
251
+ // The model turn's parts, for `hostedItems`: the built-in parts as they
252
+ // came, its text as `{ length }`, its function calls as `{ call }`.
253
+ const items: unknown[] = [];
254
+ const builtInParts = new Set<unknown>();
255
+ let recordedCalls = 0;
256
+ // The code run a result answers, and the server call a response does:
257
+ // Gemini pairs them by order. Each open call's part, so one that never
258
+ // got its result can leave the record.
259
+ let lastCode: string | undefined;
260
+ let lastServer: string | undefined;
261
+ const openParts = new Map<string, unknown>();
262
+ // Calls that late grounding or URL metadata fills, never a second run.
263
+ let searchIndex: number | undefined;
264
+ const fileSearches = new Map<string, number>();
265
+ const fetches = new Map<string, { index: number; urls: string[] }>();
266
+ // The last of each that the stream stated: Gemini repeats them as it goes.
267
+ let grounding: GroundingMetadata | undefined;
268
+ const searchQueries = new Set<string>();
269
+ let returnedWebSource = false;
270
+ let urlContext:
271
+ | { urlMetadata?: { retrievedUrl?: string; urlRetrievalStatus?: string }[] }
272
+ | undefined;
273
+ let lastUsage: TokenUsage | undefined;
274
+ const searched = hosted.some((tool) => tool.type === "web_search");
275
+ const fileSearched = hosted.some((tool) => tool.type === "file_search");
276
+ const withCounts = (usage: TokenUsage): TokenUsage => {
277
+ // Google bills unique non-empty queries on Gemini 3+, but only one
278
+ // grounded prompt on Gemini 2.5, and only when it returns a web source.
279
+ // Ported from PydanticAI (MIT), _set_web_search_usage.
280
+ const billableSearches = isGemini2
281
+ ? Number(searchQueries.size > 0 && returnedWebSource)
282
+ : searchQueries.size;
283
+ const hostedCalls = hostedCounts(
284
+ recorder.shown(),
285
+ searched && grounding ? { web_search: billableSearches } : undefined,
286
+ );
287
+ return hostedCalls ? { ...usage, hostedCalls } : usage;
288
+ };
289
+
290
+ // A built-in tool's part as its hosted delta (`delta` absent when the
291
+ // part changes no record), or undefined for any other part.
292
+ const builtIn = (part: GeminiPart, at: number): { delta?: HostedCallDelta } | undefined => {
293
+ if (part.executableCode) {
294
+ const { code, language } = part.executableCode;
295
+ const fileQuery = fileSearched && code?.match(FILE_SEARCH_QUERY);
296
+ const started = fileQuery
297
+ ? recorder.start(undefined, "file_search", at, {
298
+ query: fileQuery[2]!.replace(/\\([\\'"])/g, "$1"),
299
+ })
300
+ : recorder.start(undefined, "code_execution", at, {
301
+ ...(code ? { code } : {}),
302
+ ...(language ? { language: language.toLowerCase() } : {}),
303
+ });
304
+ if (fileQuery) fileSearches.set(started.id, started.index);
305
+ else lastCode = started.id;
306
+ openParts.set(started.id, part);
307
+ return { delta: started };
308
+ }
309
+ if (part.codeExecutionResult) {
310
+ const { outcome, output } = part.codeExecutionResult;
311
+ // OUTCOME_FAILED ran the program, and the program failed: that is
312
+ // its stderr, as a shell's non-zero exit is on Anthropic. A deadline,
313
+ // or an outcome nobody named, is the tool failing (invariant 7: data).
314
+ const ran = outcome === "OUTCOME_OK" || outcome === "OUTCOME_FAILED";
315
+ let said: { stdout: string } | { stderr: string } | undefined;
316
+ if (output) said = outcome === "OUTCOME_OK" ? { stdout: output } : { stderr: output };
317
+ const delta = recorder.end(lastCode, {
318
+ status: ran ? "completed" : "failed",
319
+ ...(said ? { output: said } : {}),
320
+ ...(ran ? {} : { error: outcome ?? "OUTCOME_UNSPECIFIED" }),
321
+ });
322
+ lastCode = undefined;
323
+ return delta ? { delta } : {};
324
+ }
325
+ if (part.toolCall) {
326
+ const type = serverToolType(part.toolCall.toolType);
327
+ if (!type) return {};
328
+ const started = recorder.start(
329
+ part.toolCall.id,
330
+ type,
331
+ at,
332
+ serverToolInput(part.toolCall.args),
333
+ );
334
+ lastServer = started.id;
335
+ openParts.set(started.id, part);
336
+ if (type === "web_search") searchIndex ??= started.index;
337
+ if (type === "file_search") fileSearches.set(started.id, started.index);
338
+ if (type === "web_fetch") {
339
+ fetches.set(started.id, {
340
+ index: started.index,
341
+ urls: serverToolUrls(part.toolCall.args),
342
+ });
343
+ }
344
+ return { delta: started };
345
+ }
346
+ if (part.toolResponse) {
347
+ const delta = recorder.end(part.toolResponse.id ?? lastServer, { status: "completed" });
348
+ lastServer = undefined;
349
+ return delta ? { delta } : {};
350
+ }
351
+ return undefined;
352
+ };
353
+
354
+ // The end of the turn, before its finish: grounding and URL context
355
+ // become records and citations now that the whole answer is known, a
356
+ // code run with no result fails, and the parts worth replaying go out.
357
+ function* closeTurn(): Generator<ProviderChunk> {
358
+ const deltas: HostedCallDelta[] = [];
359
+ const citations: Citation[] = [];
360
+ if (grounding) {
361
+ const sources = (grounding.groundingChunks ?? []).map(chunkSource);
362
+ for (const support of grounding.groundingSupports ?? []) {
363
+ const span = segmentSpan(text, support.segment, textParts);
364
+ for (const at of support.groundingChunkIndices ?? []) {
365
+ const source = sources[at];
366
+ if (source) citations.push({ source, ...(span ? { ...span, anchor: "claim" } : {}) });
367
+ }
368
+ }
369
+ const found = distinctSources(sources.filter((source) => source !== undefined));
370
+ const web = found.filter((source) => source.type === "url");
371
+ const files = found.filter((source) => source.type === "file");
372
+ const suggestions = grounding.searchEntryPoint?.renderedContent;
373
+ const queries = grounding.webSearchQueries ?? [];
374
+ // One search record for the whole answer, at its start: Gemini says
375
+ // only that it searched, after the answer it grounded.
376
+ if (searched && (web.length > 0 || queries.length > 0 || suggestions)) {
377
+ const output = {
378
+ ...(web.length > 0 ? { sources: web } : {}),
379
+ ...(suggestions ? { searchSuggestions: suggestions } : {}),
380
+ };
381
+ const input = queryInput(queries);
382
+ deltas.push(
383
+ searchIndex !== undefined
384
+ ? { index: searchIndex, output }
385
+ : recorder.whole(undefined, "web_search", 0, {
386
+ status: "completed",
387
+ ...(Object.keys(input).length > 0 ? { input } : {}),
388
+ output,
389
+ }),
390
+ );
391
+ }
392
+ if (fileSearched && files.length > 0) {
393
+ const result = { status: "completed" as const, output: { sources: files } };
394
+ if (fileSearches.size > 0) {
395
+ // Gemini 3 sends empty server responses; Gemini 2.5 exposes the
396
+ // query as executable code. Both get their passages here.
397
+ for (const [key, index] of fileSearches) {
398
+ deltas.push(recorder.end(key, result) ?? { index, output: result.output });
399
+ }
400
+ } else {
401
+ deltas.push(recorder.whole(undefined, "file_search", 0, result));
402
+ }
403
+ }
404
+ }
405
+ const retrieved = urlContext?.urlMetadata ?? [];
406
+ const matchedUrls = new Set<string>();
407
+ for (const [key, { index, urls }] of fetches) {
408
+ // One server invocation can fetch several URLs. Metadata is the
409
+ // authoritative result, even after an empty toolResponse completed it.
410
+ const results = retrieved.filter(
411
+ (entry) => entry.retrievedUrl && urls.includes(entry.retrievedUrl),
412
+ );
413
+ if (results.length === 0) continue;
414
+ const sources: Source[] = [];
415
+ const errors = new Set<string>();
416
+ for (const { retrievedUrl: url, urlRetrievalStatus: status } of results) {
417
+ if (!url) continue;
418
+ matchedUrls.add(url);
419
+ if (status === "URL_RETRIEVAL_STATUS_SUCCESS") sources.push({ type: "url", url });
420
+ else errors.add(status ?? "URL_RETRIEVAL_STATUS_UNSPECIFIED");
421
+ }
422
+ const result = {
423
+ status: errors.size > 0 ? ("failed" as const) : ("completed" as const),
424
+ ...(sources.length > 0 ? { output: { sources } } : {}),
425
+ ...(errors.size > 0 ? { error: [...errors].join(", ") } : {}),
426
+ };
427
+ deltas.push(recorder.end(key, result) ?? { index, ...result });
428
+ }
429
+ for (const { retrievedUrl: url, urlRetrievalStatus: status } of retrieved) {
430
+ if (!url || matchedUrls.has(url)) continue;
431
+ const ok = status === "URL_RETRIEVAL_STATUS_SUCCESS";
432
+ deltas.push(
433
+ recorder.whole(undefined, "web_fetch", 0, {
434
+ status: ok ? "completed" : "failed",
435
+ input: { url },
436
+ ...(ok
437
+ ? { output: { sources: [{ type: "url", url }] } }
438
+ : { error: status ?? "URL_RETRIEVAL_STATUS_UNSPECIFIED" }),
439
+ }),
440
+ );
441
+ }
442
+ const dropped = new Set([...recorder.unsettled()].map((key) => openParts.get(key)));
443
+ deltas.push(...recorder.settle());
444
+ if (deltas.length > 0) yield { type: "delta", hosted: deltas };
445
+ if (citations.length > 0) yield { type: "delta", citations };
446
+ const kept = items.filter((item) => !dropped.has(item));
447
+ if (kept.some((item) => builtInParts.has(item))) {
448
+ yield { type: "delta", hostedItems: { provider: id, items: kept } };
449
+ }
450
+ // The usage already sent predates the records above.
451
+ if (lastUsage && hostedCounts(recorder.shown())) {
452
+ yield { type: "usage", usage: withCounts(lastUsage) };
453
+ }
454
+ }
455
+
456
+ return {
457
+ candidate(candidate: NonNullable<GeminiResponse["candidates"]>[number]) {
458
+ if (candidate.groundingMetadata) {
459
+ grounding = candidate.groundingMetadata;
460
+ for (const query of grounding.webSearchQueries ?? []) {
461
+ if (query.trim()) searchQueries.add(query);
462
+ }
463
+ returnedWebSource ||= (grounding.groundingChunks ?? []).some(
464
+ (source) => !!source.web?.uri,
465
+ );
466
+ }
467
+ if (candidate.urlContextMetadata) urlContext = candidate.urlContextMetadata;
468
+ },
469
+ part(part: GeminiPart, partIndex: number, pendingLength: number) {
470
+ if (part.text !== undefined) {
471
+ const previous = textParts.at(-1);
472
+ const thought = !!part.thought;
473
+ // The first text Part may continue the preceding frame. A
474
+ // second Part in this frame, or a change of kind, starts anew.
475
+ if (partIndex === 0 && previous && previous.thought === thought) {
476
+ previous.text += part.text;
477
+ } else {
478
+ textParts.push({ text: part.text, at: text.length + pendingLength, thought });
479
+ }
480
+ if (part.thought) return;
481
+ // Streamed text is one part in many pieces: one placeholder.
482
+ const last = items.at(-1);
483
+ if (isRecord(last) && typeof last.length === "number" && !builtInParts.has(last)) {
484
+ last.length += part.text.length;
485
+ } else {
486
+ items.push({ length: part.text.length });
487
+ }
488
+ return;
489
+ }
490
+ textParts.push(undefined);
491
+ const ran = builtIn(part, text.length + pendingLength);
492
+ if (ran) {
493
+ items.push(part);
494
+ builtInParts.add(part);
495
+ return ran;
496
+ }
497
+ if (part.functionCall) items.push({ call: recordedCalls++ });
498
+ return;
499
+ },
500
+ text(content: string) {
501
+ text += content;
502
+ },
503
+ usage(usage: TokenUsage) {
504
+ lastUsage = usage;
505
+ return withCounts(usage);
506
+ },
507
+ close: closeTurn,
508
+ };
509
+ },
510
+ };
@@ -0,0 +1,137 @@
1
+ // Hosted Chat Completions shapes follow PydanticAI (MIT). See THIRD_PARTY_NOTICES.
2
+ import { codePointIndex, hostedCounts, planHostedTools, servedAt } from "./shared.ts";
3
+ import type { Citation, HostedTool, HostedToolType } from "./types.ts";
4
+ import type { OpenAIConfig, OpenAIChunk } from "../providers/openai.ts";
5
+ import type { ProviderChunk, StreamOptions } from "../types.ts";
6
+
7
+ /**
8
+ * Web search as this wire carries it. OpenRouter runs it as its own server
9
+ * tool, which takes every field (PydanticAI openrouter.py:840-853,1349-1355,
10
+ * MIT). OpenAI's search models take `web_search_options`, which has room for a
11
+ * location and nothing that restricts the search (PydanticAI
12
+ * openai/_chat_model.py:357-358,975-987).
13
+ */
14
+ function webSearchFields(openRouter: boolean): Partial<Record<HostedToolType, readonly string[]>> {
15
+ return {
16
+ web_search: openRouter
17
+ ? ["allowedDomains", "blockedDomains", "maxUses", "userLocation"]
18
+ : ["userLocation"],
19
+ };
20
+ }
21
+
22
+ function openRouterWebSearch(tool: Extract<HostedTool, { type: "web_search" }>): unknown {
23
+ return {
24
+ type: "openrouter:web_search",
25
+ parameters: {
26
+ ...(tool.userLocation
27
+ ? { user_location: { type: "approximate", ...tool.userLocation } }
28
+ : {}),
29
+ allowed_domains: tool.allowedDomains,
30
+ excluded_domains: tool.blockedDomains,
31
+ max_uses: tool.maxUses,
32
+ },
33
+ };
34
+ }
35
+
36
+ /** A chat annotation: OpenRouter's and OpenAI's search models nest it the same way. */
37
+ export interface ChatAnnotation {
38
+ type?: string;
39
+ url_citation?: {
40
+ url?: string;
41
+ title?: string;
42
+ start_index?: number;
43
+ end_index?: number;
44
+ content?: string;
45
+ };
46
+ }
47
+
48
+ /**
49
+ * A `url_citation` as a citation. Its offsets count code points and select the
50
+ * link the model wrote, so the span is kept only when it still contains the
51
+ * URL; otherwise the source stays and the span goes (PydanticAI
52
+ * openai/_citations.py:44-47,96-120, MIT).
53
+ */
54
+ function chatCitation(annotation: ChatAnnotation, text: string): Citation | undefined {
55
+ const cited = annotation.url_citation;
56
+ if (annotation.type !== "url_citation" || !cited?.url) return undefined;
57
+ const source = {
58
+ type: "url" as const,
59
+ url: cited.url,
60
+ ...(cited.title ? { title: cited.title } : {}),
61
+ ...(cited.content ? { excerpt: cited.content } : {}),
62
+ };
63
+ const start =
64
+ cited.start_index === undefined ? undefined : codePointIndex(text, cited.start_index);
65
+ const end = cited.end_index === undefined ? undefined : codePointIndex(text, cited.end_index);
66
+ return start !== undefined &&
67
+ end !== undefined &&
68
+ start < end &&
69
+ text.slice(start, end).includes(cited.url)
70
+ ? { source, start, end, anchor: "marker" }
71
+ : { source };
72
+ }
73
+
74
+ export const openaiHosted = {
75
+ plan(
76
+ config: OpenAIConfig,
77
+ baseUrl: string,
78
+ id: string,
79
+ model: string,
80
+ openRouter: boolean,
81
+ opts: StreamOptions,
82
+ ) {
83
+ // On OpenAI's own API only its search models search (PydanticAI
84
+ // profiles/openai.py:640-641).
85
+ const searches = model.includes("-search-preview") ? (["web_search"] as const) : [];
86
+ const hosted = planHostedTools(
87
+ id,
88
+ {
89
+ name: "OpenAI chat",
90
+ serves: (
91
+ config.servesHostedTools ??
92
+ (openRouter ? ["web_search"] : servedAt(baseUrl, "api.openai.com", searches))
93
+ ).filter((type) => type === "web_search"),
94
+ fields: webSearchFields(openRouter),
95
+ },
96
+ opts,
97
+ );
98
+ const webSearch = hosted.find(
99
+ (tool): tool is Extract<HostedTool, { type: "web_search" }> => tool.type === "web_search",
100
+ );
101
+ return {
102
+ active: hosted.length > 0,
103
+ tools: webSearch && openRouter ? [openRouterWebSearch(webSearch)] : [],
104
+ ...(webSearch && !openRouter
105
+ ? {
106
+ searchOptions: webSearch.userLocation
107
+ ? { user_location: { type: "approximate", approximate: webSearch.userLocation } }
108
+ : {},
109
+ }
110
+ : {}),
111
+ };
112
+ },
113
+ stream() {
114
+ // The answer so far, and the annotations on it, which are placed once
115
+ // the text they index is whole: at the finish. This wire states no
116
+ // record of the search itself, only what the answer cites and a count.
117
+ let text = "";
118
+ const annotations: ChatAnnotation[] = [];
119
+ function* cite(): Generator<ProviderChunk> {
120
+ const citations = annotations.splice(0).flatMap((annotation) => {
121
+ const citation = chatCitation(annotation, text);
122
+ return citation ? [citation] : [];
123
+ });
124
+ if (citations.length > 0) yield { type: "delta", citations };
125
+ }
126
+ return {
127
+ delta(delta: NonNullable<NonNullable<OpenAIChunk["choices"]>[number]["delta"]>) {
128
+ if (delta.content) text += delta.content;
129
+ if (delta.annotations?.length) annotations.push(...delta.annotations);
130
+ },
131
+ close: cite,
132
+ };
133
+ },
134
+ counts(usage: NonNullable<OpenAIChunk["usage"]>) {
135
+ return hostedCounts({ web_search: usage.server_tool_use_details?.web_search_requests });
136
+ },
137
+ };