@providerkit/core 0.30.0 → 0.32.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 (137) hide show
  1. package/README.md +101 -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/otel.d.ts +26 -0
  54. package/dist/otel.d.ts.map +1 -0
  55. package/dist/otel.js +263 -0
  56. package/dist/otel.js.map +1 -0
  57. package/dist/presets.d.ts +2 -2
  58. package/dist/presets.d.ts.map +1 -1
  59. package/dist/providers/anthropic.d.ts +75 -1
  60. package/dist/providers/anthropic.d.ts.map +1 -1
  61. package/dist/providers/anthropic.js +207 -135
  62. package/dist/providers/anthropic.js.map +1 -1
  63. package/dist/providers/factory.d.ts +10 -0
  64. package/dist/providers/factory.d.ts.map +1 -1
  65. package/dist/providers/factory.js +31 -23
  66. package/dist/providers/factory.js.map +1 -1
  67. package/dist/providers/gemini.d.ts +123 -1
  68. package/dist/providers/gemini.d.ts.map +1 -1
  69. package/dist/providers/gemini.js +114 -54
  70. package/dist/providers/gemini.js.map +1 -1
  71. package/dist/providers/hosted-codecs.d.ts +10 -0
  72. package/dist/providers/hosted-codecs.d.ts.map +1 -0
  73. package/dist/providers/hosted-codecs.js +8 -0
  74. package/dist/providers/hosted-codecs.js.map +1 -0
  75. package/dist/providers/openai.d.ts +69 -0
  76. package/dist/providers/openai.d.ts.map +1 -1
  77. package/dist/providers/openai.js +38 -14
  78. package/dist/providers/openai.js.map +1 -1
  79. package/dist/providers/responses.d.ts +123 -0
  80. package/dist/providers/responses.d.ts.map +1 -1
  81. package/dist/providers/responses.js +57 -22
  82. package/dist/providers/responses.js.map +1 -1
  83. package/dist/providers/speech-factory.js.map +1 -1
  84. package/dist/registry.d.ts +3 -0
  85. package/dist/registry.d.ts.map +1 -1
  86. package/dist/registry.js +8 -4
  87. package/dist/registry.js.map +1 -1
  88. package/dist/retry.js.map +1 -1
  89. package/dist/speech-core.d.ts.map +1 -1
  90. package/dist/speech-core.js.map +1 -1
  91. package/dist/tools.d.ts.map +1 -1
  92. package/dist/tools.js.map +1 -1
  93. package/dist/transcription-core.d.ts.map +1 -1
  94. package/dist/transcription-core.js.map +1 -1
  95. package/dist/transport.js.map +1 -1
  96. package/dist/turn.d.ts +10 -1
  97. package/dist/turn.d.ts.map +1 -1
  98. package/dist/turn.js +53 -1
  99. package/dist/turn.js.map +1 -1
  100. package/dist/types.d.ts +51 -0
  101. package/dist/types.d.ts.map +1 -1
  102. package/dist/types.js.map +1 -1
  103. package/dist/usage.d.ts +10 -1
  104. package/dist/usage.d.ts.map +1 -1
  105. package/dist/usage.js +40 -2
  106. package/dist/usage.js.map +1 -1
  107. package/dist/watchdog.d.ts +6 -0
  108. package/dist/watchdog.d.ts.map +1 -1
  109. package/dist/watchdog.js +10 -2
  110. package/dist/watchdog.js.map +1 -1
  111. package/package.json +19 -5
  112. package/src/context.ts +21 -5
  113. package/src/fallback.ts +21 -6
  114. package/src/hosted/anthropic.ts +512 -0
  115. package/src/hosted/gemini.ts +510 -0
  116. package/src/hosted/openai.ts +137 -0
  117. package/src/hosted/responses.ts +420 -0
  118. package/src/hosted/shared.ts +341 -0
  119. package/src/hosted/types.ts +214 -0
  120. package/src/hosted.ts +101 -0
  121. package/src/index.ts +64 -7
  122. package/src/otel.ts +306 -0
  123. package/src/providers/anthropic.ts +252 -143
  124. package/src/providers/factory.ts +127 -82
  125. package/src/providers/gemini.ts +184 -60
  126. package/src/providers/hosted-codecs.ts +29 -0
  127. package/src/providers/openai.ts +52 -15
  128. package/src/providers/responses.ts +93 -24
  129. package/src/registry.ts +14 -4
  130. package/src/turn.ts +55 -1
  131. package/src/types.ts +62 -1
  132. package/src/usage.ts +32 -2
  133. package/src/watchdog.ts +12 -2
  134. package/dist/jev.d.ts +0 -123
  135. package/dist/jev.d.ts.map +0 -1
  136. package/dist/jev.js +0 -278
  137. package/dist/jev.js.map +0 -1
@@ -5,6 +5,11 @@
5
5
  // its own chain of thought on the next turn. Written straight against the REST
6
6
  // wire rather than @google/genai, because this package ships zero dependencies
7
7
  // and the SDK is a Node-shaped one.
8
+ //
9
+ // Built-in tool shapes, parts and grounding fields follow Vercel's AI SDK
10
+ // (Apache-2.0, Copyright 2023 Vercel, Inc.: google-prepare-tools.ts,
11
+ // google-language-model.ts, convert-to-google-messages.ts); the byte offsets
12
+ // and segment checks follow PydanticAI (MIT). See THIRD_PARTY_NOTICES.
8
13
  import { repairHistory } from "../context.ts";
9
14
  import {
10
15
  ProviderError,
@@ -13,10 +18,12 @@ import {
13
18
  validateMaxAttempts,
14
19
  type ErrorKind,
15
20
  } from "../errors.ts";
21
+ import type { HostedToolType } from "../hosted/types.ts";
22
+ import { refuseHostedTools, type HostedCodecs } from "./hosted-codecs.ts";
16
23
  import { schemaPrompt, toAntigravityToolSchema, toGeminiToolSchema } from "../schema.ts";
17
24
  import { parseToolArgs, settleToolCalls } from "../tool-args.ts";
18
25
  import { streamSse, apiUrl, type FetchLike } from "../transport.ts";
19
- import { withConfiguredFallbacks, type ProviderFallbackConfig } from "../fallback.ts";
26
+ import { configuredFallbacks, type ProviderFallbackConfig } from "../fallback.ts";
20
27
  import type {
21
28
  ChatMessage,
22
29
  Effort,
@@ -25,6 +32,8 @@ import type {
25
32
  Provider,
26
33
  ProviderChunk,
27
34
  StreamOptions,
35
+ TokenUsage,
36
+ ToolCall,
28
37
  ToolCallDelta,
29
38
  ToolChoice,
30
39
  ToolDefinition,
@@ -64,6 +73,15 @@ export interface GeminiConfig extends ProviderFallbackConfig {
64
73
  maxTokens?: number;
65
74
  fetchImpl?: FetchLike;
66
75
  headers?: Record<string, string>;
76
+ /**
77
+ * For providers imported from `@providerkit/core/hosted`.
78
+ * The hosted tools this endpoint runs. Defaults to web search, web fetch,
79
+ * code execution and file search on the Gemini API
80
+ * (generativelanguage.googleapis.com), and to none anywhere else. Vertex
81
+ * and the gateways differ, and one that ignores a tool answers unsearched
82
+ * without saying so. Antigravity runs none.
83
+ */
84
+ servesHostedTools?: readonly HostedToolType[];
67
85
  }
68
86
 
69
87
  const DEFAULT_BASE_URL = "https://generativelanguage.googleapis.com";
@@ -193,6 +211,16 @@ function parseArgs(json: string): Record<string, unknown> {
193
211
  return parseToolArgs(json);
194
212
  }
195
213
 
214
+ function functionCallPart(call: ToolCall): unknown {
215
+ return {
216
+ functionCall: { id: call.id, name: call.name, args: parseArgs(call.arguments) },
217
+ // Replayed verbatim: this is the model's own reasoning token, and without
218
+ // it the next turn starts from a chain of thought that no longer includes
219
+ // the call it just made.
220
+ ...(call.thoughtSignature ? { thoughtSignature: call.thoughtSignature } : {}),
221
+ };
222
+ }
223
+
196
224
  /** Same rule for a tool RESULT, which `functionResponse.response` also requires
197
225
  * as an object. Plain text (the common case) rides under `output`. */
198
226
  function toResponseObject(content: string): Record<string, unknown> {
@@ -219,8 +247,25 @@ function toResponseObject(content: string): Record<string, unknown> {
219
247
  * that the response count does not match the call count. The responses go
220
248
  * first, in call order, and the run's images follow them all, the way the
221
249
  * OpenAI dialect places them.
250
+ *
251
+ * A model turn that ran built-in tools goes back to `provider`, the one that
252
+ * made it, as the parts it came in: the code and its result, the server
253
+ * tool's call and response with their thought signatures, which Gemini needs
254
+ * returned unchanged when built-ins and functions share a turn.
222
255
  */
223
- export function toGeminiContents(messages: readonly ChatMessage[]): {
256
+ export function toGeminiContents(
257
+ messages: readonly ChatMessage[],
258
+ provider?: string,
259
+ ): { system?: string; contents: GeminiContent[] } {
260
+ return geminiContents(messages, provider);
261
+ }
262
+
263
+ /** @internal Hosted replay stays outside the plain converter. */
264
+ export function geminiContents(
265
+ messages: readonly ChatMessage[],
266
+ provider?: string,
267
+ replay?: HostedCodecs["gemini"]["replay"],
268
+ ): {
224
269
  system?: string;
225
270
  contents: GeminiContent[];
226
271
  } {
@@ -253,17 +298,15 @@ export function toGeminiContents(messages: readonly ChatMessage[]): {
253
298
  break;
254
299
 
255
300
  case "assistant": {
301
+ const replayed =
302
+ provider === undefined ? undefined : replay?.(message, provider, functionCallPart);
303
+ if (replayed) {
304
+ contents.push({ role: "model", parts: replayed });
305
+ break;
306
+ }
256
307
  const parts: unknown[] = [];
257
308
  if (message.content) parts.push({ text: message.content });
258
- for (const call of message.toolCalls ?? []) {
259
- parts.push({
260
- functionCall: { id: call.id, name: call.name, args: parseArgs(call.arguments) },
261
- // Replayed verbatim: this is the model's own reasoning token, and
262
- // without it the next turn starts from a chain of thought that
263
- // no longer includes the call it just made.
264
- ...(call.thoughtSignature ? { thoughtSignature: call.thoughtSignature } : {}),
265
- });
266
- }
309
+ for (const call of message.toolCalls ?? []) parts.push(functionCallPart(call));
267
310
  // An assistant turn with neither text nor calls has no representation
268
311
  // here, and an empty `parts` is a 400.
269
312
  if (parts.length > 0) contents.push({ role: "model", parts });
@@ -369,12 +412,39 @@ function mapFinishReason(provider: string, reason: string): FinishReason {
369
412
  }
370
413
  }
371
414
 
372
- interface GeminiPart {
415
+ export interface GeminiPart {
373
416
  text?: string;
374
417
  /** Marks the parts that are the model's reasoning. Absent on the answer. */
375
418
  thought?: boolean;
376
419
  thoughtSignature?: string;
377
420
  functionCall?: { id?: string; name?: string; args?: Record<string, unknown> };
421
+ /** Code the code execution tool ran, and what came of it, paired by order. */
422
+ executableCode?: { language?: string; code?: string };
423
+ codeExecutionResult?: { outcome?: string; output?: string };
424
+ /** A built-in tool's call and response, on Gemini 3 with function tools. */
425
+ toolCall?: { id?: string; toolType?: string; args?: Record<string, unknown> };
426
+ toolResponse?: { id?: string; toolType?: string; response?: unknown };
427
+ }
428
+
429
+ export interface GroundingSegment {
430
+ /** Offsets count UTF-8 bytes in the named Part, or the answer when absent. */
431
+ partIndex?: number;
432
+ startIndex?: number;
433
+ endIndex?: number;
434
+ text?: string;
435
+ }
436
+
437
+ export interface GroundingChunk {
438
+ web?: { uri?: string; title?: string };
439
+ retrievedContext?: { uri?: string; title?: string; text?: string };
440
+ }
441
+
442
+ /** What a grounded answer read, and which of its sentences each source backs. */
443
+ export interface GroundingMetadata {
444
+ webSearchQueries?: string[];
445
+ groundingChunks?: GroundingChunk[];
446
+ groundingSupports?: { segment?: GroundingSegment; groundingChunkIndices?: number[] }[];
447
+ searchEntryPoint?: { renderedContent?: string };
378
448
  }
379
449
 
380
450
  /** Google's `google.rpc.Status`: an HTTP `code`, the canonical `status` name,
@@ -386,16 +456,20 @@ interface GeminiStatus {
386
456
  details?: unknown;
387
457
  }
388
458
 
389
- interface GeminiResponse {
459
+ export interface GeminiResponse {
390
460
  candidates?: {
391
461
  content?: { parts?: GeminiPart[] };
392
462
  finishReason?: string;
463
+ groundingMetadata?: GroundingMetadata;
464
+ urlContextMetadata?: { urlMetadata?: { retrievedUrl?: string; urlRetrievalStatus?: string }[] };
393
465
  }[];
394
466
  usageMetadata?: {
395
467
  promptTokenCount?: number;
396
468
  candidatesTokenCount?: number;
397
469
  thoughtsTokenCount?: number;
398
470
  cachedContentTokenCount?: number;
471
+ /** The prompt the built-in tools' results added, billed as input. */
472
+ toolUsePromptTokenCount?: number;
399
473
  };
400
474
  /** Present only on the in-band failure below. Never on a real candidate. */
401
475
  error?: GeminiStatus;
@@ -404,6 +478,11 @@ interface GeminiResponse {
404
478
  }
405
479
 
406
480
  export function createGeminiProvider(config: GeminiConfig): Provider {
481
+ return geminiProvider(config);
482
+ }
483
+
484
+ /** @internal Shared by the plain and hosted entry points. */
485
+ export function geminiProvider(config: GeminiConfig, codecs?: HostedCodecs): Provider {
407
486
  const baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;
408
487
  const id = config.id ?? "gemini";
409
488
  const isAntigravity = id === "antigravity";
@@ -421,11 +500,16 @@ export function createGeminiProvider(config: GeminiConfig): Provider {
421
500
  ): AsyncIterable<ProviderChunk> {
422
501
  const { maxAttempts } = opts;
423
502
  validateMaxAttempts(maxAttempts);
503
+ if (!codecs) refuseHostedTools(id, opts, messages);
424
504
  const effort = opts.effort ?? config.effort;
425
505
  const maxTokens = opts.maxTokens ?? config.maxTokens;
426
506
  // Repaired first: a result with no call, or a call with no result, is a
427
507
  // 400 that loses the turn. See repairHistory.
428
- const { system, contents } = toGeminiContents(repairHistory(messages).messages);
508
+ const { system, contents } = geminiContents(
509
+ repairHistory(messages).messages,
510
+ id,
511
+ codecs?.gemini.replay,
512
+ );
429
513
 
430
514
  // A model id copied out of Gemini's docs is often already `models/…`, and
431
515
  // the doubled segment 404s as "model not found" — a confusing way to
@@ -436,6 +520,15 @@ export function createGeminiProvider(config: GeminiConfig): Provider {
436
520
  // Not `!isGemini3`: `gemini-flash-latest` and models newer than 3 are not
437
521
  // Gemini 3 either, and they must get a level.
438
522
  const isGemini2 = /gemini-2/i.test(model);
523
+ const hosted = codecs?.gemini.plan(
524
+ config,
525
+ baseUrl,
526
+ id,
527
+ isAntigravity,
528
+ isGemini2,
529
+ tools,
530
+ opts,
531
+ );
439
532
 
440
533
  const generationConfig: Record<string, unknown> = {};
441
534
  if (maxTokens !== undefined) generationConfig.maxOutputTokens = maxTokens;
@@ -460,9 +553,10 @@ export function createGeminiProvider(config: GeminiConfig): Provider {
460
553
  // outright with `400 "Function calling with a response mime type:
461
554
  // 'application/json' is unsupported"`, so the prompt is the only way a
462
555
  // schema travels beside tools there. Gemini 3 serves both, and there the
463
- // setting is the caller's measured preference.
556
+ // setting is the caller's measured preference. A built-in tool is a tool
557
+ // here too: the prompt is the one route that works beside it everywhere.
464
558
  const promptCarried =
465
- tools.length > 0 &&
559
+ (tools.length > 0 || (hosted?.tools.length ?? 0) > 0) &&
466
560
  ((opts.jsonWithTools ?? config.jsonWithTools) === "prompt" || !isGemini3);
467
561
  if (opts.json && !promptCarried) {
468
562
  generationConfig.responseMimeType = "application/json";
@@ -490,34 +584,51 @@ export function createGeminiProvider(config: GeminiConfig): Provider {
490
584
  ...(opts.json && promptCarried ? [{ text: schemaPrompt(opts.json.schema) }] : []),
491
585
  ];
492
586
  if (systemParts.length > 0) request.systemInstruction = { parts: systemParts };
493
- if (tools.length > 0) {
494
- // Gemini has no switch for one call per turn. Sending the request
495
- // anyway would hand back the parallel calls the caller ruled out.
496
- if (opts.parallelToolCalls === false) {
497
- throw new ProviderError(
498
- id,
499
- "invalid",
500
- `${id}: Gemini can't limit a turn to one tool call. Leave parallelToolCalls unset ` +
501
- "for Gemini models, or run the calls it returns one at a time.",
502
- );
503
- }
587
+ // Gemini has no switch for one call per turn. Sending the request anyway
588
+ // would hand back the parallel calls the caller ruled out.
589
+ if (tools.length > 0 && opts.parallelToolCalls === false) {
590
+ throw new ProviderError(
591
+ id,
592
+ "invalid",
593
+ `${id}: Gemini can't limit a turn to one tool call. Leave parallelToolCalls unset ` +
594
+ "for Gemini models, or run the calls it returns one at a time.",
595
+ );
596
+ }
597
+ const builtIns = hosted?.tools ?? [];
598
+ if (tools.length > 0 || builtIns.length > 0) {
504
599
  request.tools = [
505
- {
506
- functionDeclarations: tools.map((tool) => ({
507
- name: tool.name,
508
- description: tool.description,
509
- // Antigravity (Cloud Code Assist) still expects the OpenAPI-subset
510
- // `parameters` field; the Gemini API and OpenCode Zen take standard
511
- // JSON Schema in `parametersJsonSchema` (cc-proxy 0.2.8).
512
- ...(isAntigravity
513
- ? { parameters: toAntigravityToolSchema(tool.inputSchema) }
514
- : { parametersJsonSchema: toGeminiToolSchema(tool.inputSchema) }),
515
- })),
516
- },
600
+ ...(tools.length > 0
601
+ ? [
602
+ {
603
+ functionDeclarations: tools.map((tool) => ({
604
+ name: tool.name,
605
+ description: tool.description,
606
+ // Antigravity (Cloud Code Assist) still expects the OpenAPI-subset
607
+ // `parameters` field; the Gemini API and OpenCode Zen take standard
608
+ // JSON Schema in `parametersJsonSchema` (cc-proxy 0.2.8).
609
+ ...(isAntigravity
610
+ ? { parameters: toAntigravityToolSchema(tool.inputSchema) }
611
+ : { parametersJsonSchema: toGeminiToolSchema(tool.inputSchema) }),
612
+ })),
613
+ },
614
+ ]
615
+ : []),
616
+ ...builtIns,
517
617
  ];
618
+ }
619
+ if (tools.length > 0) {
518
620
  // Pointless without declarations, and Gemini 400s on a tool config that
519
- // names a function it was never given.
520
- const toolConfig = toToolConfig(opts.toolChoice);
621
+ // names a function it was never given. Built-ins beside functions need
622
+ // the mode that lets both run and the server's own calls streamed back,
623
+ // which then go back with the turn (google-prepare-tools.ts:187-231).
624
+ // A forced choice never gets here with built-ins: it is refused.
625
+ const toolConfig =
626
+ builtIns.length > 0
627
+ ? {
628
+ functionCallingConfig: { mode: "VALIDATED" },
629
+ includeServerSideToolInvocations: true,
630
+ }
631
+ : toToolConfig(opts.toolChoice);
521
632
  if (toolConfig) request.toolConfig = toolConfig;
522
633
  }
523
634
 
@@ -571,6 +682,7 @@ export function createGeminiProvider(config: GeminiConfig): Provider {
571
682
  let callIndex = 0;
572
683
  let finished = false;
573
684
  let emitted = false;
685
+ const hostedStream = codecs?.gemini.stream(id, hosted?.hosted ?? [], isGemini2);
574
686
 
575
687
  for (let baseIdx = 0; baseIdx < bases.length; baseIdx++) {
576
688
  const currentBase = bases[baseIdx]!;
@@ -615,33 +727,43 @@ export function createGeminiProvider(config: GeminiConfig): Provider {
615
727
  if (chunk.usageMetadata) {
616
728
  const usage = chunk.usageMetadata;
617
729
  emitted = true;
618
- yield {
619
- type: "usage",
620
- usage: {
621
- inputTokens: usage.promptTokenCount ?? 0,
622
- // Thoughts bill as OUTPUT, and Gemini reports them OUTSIDE
623
- // candidatesTokenCount — leaving them out undercounts a thinking
624
- // turn by most of what it cost.
625
- outputTokens: (usage.candidatesTokenCount ?? 0) + (usage.thoughtsTokenCount ?? 0),
626
- cachedInputTokens: usage.cachedContentTokenCount ?? 0,
627
- ...(usage.thoughtsTokenCount !== undefined
628
- ? { reasoningTokens: usage.thoughtsTokenCount }
629
- : {}),
630
- },
730
+ const tokenUsage: TokenUsage = {
731
+ // What the built-in tools' results added to the prompt bills as
732
+ // input too, and Gemini reports it apart
733
+ // (Vercel convert-google-usage.ts:31-36).
734
+ inputTokens: (usage.promptTokenCount ?? 0) + (usage.toolUsePromptTokenCount ?? 0),
735
+ // Thoughts bill as OUTPUT, and Gemini reports them OUTSIDE
736
+ // candidatesTokenCount, so leaving them out undercounts a thinking
737
+ // turn by most of what it cost.
738
+ outputTokens: (usage.candidatesTokenCount ?? 0) + (usage.thoughtsTokenCount ?? 0),
739
+ cachedInputTokens: usage.cachedContentTokenCount ?? 0,
740
+ ...(usage.thoughtsTokenCount !== undefined
741
+ ? { reasoningTokens: usage.thoughtsTokenCount }
742
+ : {}),
631
743
  };
744
+ yield { type: "usage", usage: hostedStream?.usage(tokenUsage) ?? tokenUsage };
632
745
  }
633
746
 
634
747
  const candidate = chunk.candidates?.[0];
635
748
  if (!candidate) continue;
749
+ hostedStream?.candidate(candidate);
636
750
 
637
- // One chunk can carry several parts of each kind. They are coalesced
638
- // per kind so the seam sees one reasoning delta and one content delta
639
- // per chunk, in that order, rather than interleaved fragments.
751
+ // Coalesce text per frame, but emit hosted work at once: validating
752
+ // a later function call can throw, and must never hide a paid run
753
+ // from retry and fallback (invariant 19).
640
754
  let reasoning = "";
641
755
  let content = "";
642
756
  const toolCalls: ToolCallDelta[] = [];
643
- for (const part of candidate.content?.parts ?? []) {
644
- if (part.text) {
757
+ for (const [partIndex, part] of (candidate.content?.parts ?? []).entries()) {
758
+ const ran = hostedStream?.part(part, partIndex, content.length);
759
+ if (ran) {
760
+ if (ran.delta) {
761
+ emitted = true;
762
+ yield { type: "delta", hosted: [ran.delta] };
763
+ }
764
+ continue;
765
+ }
766
+ if (part.text !== undefined) {
645
767
  if (part.thought) reasoning += part.text;
646
768
  else content += part.text;
647
769
  continue;
@@ -670,6 +792,7 @@ export function createGeminiProvider(config: GeminiConfig): Provider {
670
792
  }
671
793
  if (content) {
672
794
  emitted = true;
795
+ hostedStream?.text(content);
673
796
  yield { type: "delta", content };
674
797
  }
675
798
  if (toolCalls.length > 0) {
@@ -683,6 +806,7 @@ export function createGeminiProvider(config: GeminiConfig): Provider {
683
806
  const finishReason = mapFinishReason(id, candidate.finishReason);
684
807
  finished = true;
685
808
  emitted = true;
809
+ if (hostedStream) yield* hostedStream.close();
686
810
  yield {
687
811
  type: "finish",
688
812
  // Gemini routinely reports STOP on a turn that called tools, and a
@@ -718,5 +842,5 @@ export function createGeminiProvider(config: GeminiConfig): Provider {
718
842
  },
719
843
  };
720
844
 
721
- return withConfiguredFallbacks(provider, config);
845
+ return configuredFallbacks(provider, config, codecs);
722
846
  }
@@ -0,0 +1,29 @@
1
+ import { ProviderError } from "../errors.ts";
2
+ import type { ChatMessage, StreamOptions } from "../types.ts";
3
+
4
+ /** Internal wiring only. Type imports never pull the codecs into plain chat. */
5
+ export interface HostedCodecs {
6
+ anthropic: typeof import("../hosted/anthropic.ts").anthropicHosted;
7
+ responses: typeof import("../hosted/responses.ts").responsesHosted;
8
+ gemini: typeof import("../hosted/gemini.ts").geminiHosted;
9
+ openai: typeof import("../hosted/openai.ts").openaiHosted;
10
+ }
11
+
12
+ export function refuseHostedTools(
13
+ provider: string,
14
+ opts: StreamOptions,
15
+ messages: readonly ChatMessage[],
16
+ ): void {
17
+ if (
18
+ opts.hostedTools?.length ||
19
+ messages.some(
20
+ (message) => message.role === "assistant" && message.hostedItems?.provider === provider,
21
+ )
22
+ ) {
23
+ throw new ProviderError(
24
+ provider,
25
+ "invalid",
26
+ `${provider}: hosted tools need the opt-in provider. Import its constructor from @providerkit/core/hosted.`,
27
+ );
28
+ }
29
+ }
@@ -11,6 +11,8 @@ import {
11
11
  streamError,
12
12
  validateMaxAttempts,
13
13
  } from "../errors.ts";
14
+ import type { HostedToolType } from "../hosted/types.ts";
15
+ import { refuseHostedTools, type HostedCodecs } from "./hosted-codecs.ts";
14
16
  import { streamSse, apiUrl, parseFrame, type FetchLike } from "../transport.ts";
15
17
  import { settleToolCalls, type ToolCallIdentity } from "../tool-args.ts";
16
18
  import { attributionHeaders } from "../attribution.ts";
@@ -28,7 +30,7 @@ import type {
28
30
  } from "../types.ts";
29
31
  import { toDataUri } from "../types.ts";
30
32
  import { isStrictSchema, schemaPrompt } from "../schema.ts";
31
- import { withConfiguredFallbacks, type ProviderFallbackConfig } from "../fallback.ts";
33
+ import { configuredFallbacks, type ProviderFallbackConfig } from "../fallback.ts";
32
34
 
33
35
  export interface OpenAIConfig extends ProviderFallbackConfig {
34
36
  apiKey: string;
@@ -139,6 +141,16 @@ export interface OpenAIConfig extends ProviderFallbackConfig {
139
141
  noSampling?: boolean;
140
142
  /** Default `service_tier` for every call; `StreamOptions.serviceTier` wins. */
141
143
  serviceTier?: ServiceTier;
144
+ /**
145
+ * For providers imported from `@providerkit/core/hosted`.
146
+ * The hosted tools this endpoint runs. This wire has one, web search.
147
+ * Defaults to it on openrouter.ai, which runs it as its own server tool,
148
+ * and on api.openai.com for the `-search-preview` models, and to none
149
+ * anywhere else: a gateway that ignores the tool answers unsearched
150
+ * without saying so. A host other than OpenRouter that runs it is sent
151
+ * OpenAI's `web_search_options`.
152
+ */
153
+ servesHostedTools?: readonly HostedToolType[];
142
154
  }
143
155
 
144
156
  const DEFAULT_BASE_URL = "https://api.openai.com";
@@ -476,7 +488,7 @@ export function toOpenAIMessages(messages: readonly ChatMessage[], provider = "o
476
488
  return out;
477
489
  }
478
490
 
479
- interface OpenAIChunk {
491
+ export interface OpenAIChunk {
480
492
  choices?: {
481
493
  delta?: {
482
494
  content?: string | null;
@@ -484,6 +496,8 @@ interface OpenAIChunk {
484
496
  reasoning?: string | null;
485
497
  /** OpenRouter's normalized reasoning payload, on the final delta. */
486
498
  reasoning_details?: unknown[];
499
+ /** The sources a searched answer cites. */
500
+ annotations?: import("../hosted/openai.ts").ChatAnnotation[];
487
501
  tool_calls?: {
488
502
  index?: number;
489
503
  id?: string;
@@ -507,6 +521,8 @@ interface OpenAIChunk {
507
521
  cost?: unknown;
508
522
  is_byok?: boolean;
509
523
  cost_details?: { upstream_inference_cost?: unknown } | null;
524
+ /** The server tool calls OpenRouter ran for the turn. */
525
+ server_tool_use_details?: { web_search_requests?: number } | null;
510
526
  } | null;
511
527
  /** Present only on the in-band failure below. Never beside a choice.
512
528
  * `code` is the numeric HTTP status on the gateways, a slug on OpenAI. */
@@ -550,6 +566,11 @@ export function openRouterCostUsd(usage: {
550
566
  }
551
567
 
552
568
  export function createOpenAIProvider(config: OpenAIConfig): Provider {
569
+ return openaiProvider(config);
570
+ }
571
+
572
+ /** @internal Shared by the plain and hosted entry points. */
573
+ export function openaiProvider(config: OpenAIConfig, codecs?: HostedCodecs): Provider {
553
574
  const baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;
554
575
  const id = config.id ?? "openai";
555
576
  // Keyed on the host, not the id: the host is who sends the bill, and
@@ -570,6 +591,7 @@ export function createOpenAIProvider(config: OpenAIConfig): Provider {
570
591
  opts: StreamOptions = {},
571
592
  ): AsyncIterable<ProviderChunk> {
572
593
  validateMaxAttempts(opts.maxAttempts);
594
+ if (!codecs) refuseHostedTools(id, opts, messages);
573
595
  const effort = opts.effort ?? config.effort;
574
596
  const model = opts.model ?? config.model;
575
597
 
@@ -594,18 +616,25 @@ export function createOpenAIProvider(config: OpenAIConfig): Provider {
594
616
  const serviceTier = opts.serviceTier ?? config.serviceTier;
595
617
  if (serviceTier) request.service_tier = serviceTier;
596
618
  Object.assign(request, effortParams(config.effortDialect ?? dialectFor(id), effort, model));
597
- if (tools.length > 0) {
598
- request.tools = tools.map((tool) => ({
599
- type: "function",
600
- function: {
601
- name: tool.name,
602
- description: tool.description,
603
- parameters: tool.inputSchema,
604
- },
605
- }));
619
+ const openRouter = isOpenRouter(baseUrl);
620
+ const hosted = codecs?.openai.plan(config, baseUrl, id, model, openRouter, opts);
621
+ if (tools.length > 0 || hosted?.tools.length) {
622
+ request.tools = [
623
+ ...tools.map((tool) => ({
624
+ type: "function",
625
+ function: {
626
+ name: tool.name,
627
+ description: tool.description,
628
+ parameters: tool.inputSchema,
629
+ },
630
+ })),
631
+ ...(hosted?.tools ?? []),
632
+ ];
606
633
  // Only beside tools: OpenAI refuses the field on a request without any.
607
- if (opts.parallelToolCalls === false) request.parallel_tool_calls = false;
634
+ if (tools.length > 0 && opts.parallelToolCalls === false)
635
+ request.parallel_tool_calls = false;
608
636
  }
637
+ if (hosted?.searchOptions) request.web_search_options = hosted.searchOptions;
609
638
  if (opts.toolChoice && opts.toolChoice !== "auto") {
610
639
  request.tool_choice =
611
640
  typeof opts.toolChoice === "string"
@@ -620,7 +649,8 @@ export function createOpenAIProvider(config: OpenAIConfig): Provider {
620
649
  // here the only job is to leave the response format off those calls, so
621
650
  // the schema reaches the model the one way nothing can suppress.
622
651
  const promptCarried =
623
- tools.length > 0 && (opts.jsonWithTools ?? config.jsonWithTools) === "prompt";
652
+ (tools.length > 0 || hosted?.active) &&
653
+ (opts.jsonWithTools ?? config.jsonWithTools) === "prompt";
624
654
  const enforced =
625
655
  !promptCarried &&
626
656
  (config.jsonMode ?? (id === "openai" ? "schema" : "object")) === "schema";
@@ -687,6 +717,7 @@ export function createOpenAIProvider(config: OpenAIConfig): Provider {
687
717
  // Each call as its deltas named it, by index. The finish checks them
688
718
  // before it goes out, and they are what says the turn called a tool.
689
719
  const calls = new Map<number, ToolCallIdentity>();
720
+ const hostedStream = codecs?.openai.stream();
690
721
  for await (const data of streamSse({
691
722
  url: apiUrl(baseUrl, config.path ?? defaultPath),
692
723
  headers: {
@@ -738,6 +769,7 @@ export function createOpenAIProvider(config: OpenAIConfig): Provider {
738
769
  chunk.usage.cached_tokens ??
739
770
  0;
740
771
  const reportedCostUsd = reportsCost ? openRouterCostUsd(chunk.usage) : undefined;
772
+ const hostedCalls = codecs?.openai.counts(chunk.usage);
741
773
  yield {
742
774
  type: "usage",
743
775
  usage: {
@@ -750,6 +782,7 @@ export function createOpenAIProvider(config: OpenAIConfig): Provider {
750
782
  ? { reasoningTokens: chunk.usage.completion_tokens_details.reasoning_tokens }
751
783
  : {}),
752
784
  ...(reportedCostUsd !== undefined ? { reportedCostUsd } : {}),
785
+ ...(hostedCalls ? { hostedCalls } : {}),
753
786
  },
754
787
  };
755
788
  }
@@ -765,6 +798,7 @@ export function createOpenAIProvider(config: OpenAIConfig): Provider {
765
798
  out.content = delta.content;
766
799
  has = true;
767
800
  }
801
+ hostedStream?.delta(delta);
768
802
  // `reasoning_content` is DeepSeek's field; `reasoning` is
769
803
  // OpenRouter's normalized one. Whichever arrives is the same thing.
770
804
  const reasoning = delta.reasoning_content ?? delta.reasoning;
@@ -799,6 +833,7 @@ export function createOpenAIProvider(config: OpenAIConfig): Provider {
799
833
 
800
834
  if (choice.finish_reason) {
801
835
  const stated = mapFinishReason(id, choice.finish_reason);
836
+ if (hostedStream) yield* hostedStream.close();
802
837
  const minted = settleToolCalls(id, calls.values());
803
838
  if (minted.length > 0) yield { type: "delta", toolCalls: minted };
804
839
  ended = true;
@@ -812,11 +847,13 @@ export function createOpenAIProvider(config: OpenAIConfig): Provider {
812
847
  // Either proof will do: some gateways send `[DONE]` with no finish, and
813
848
  // some a finish with no `[DONE]`. Neither means the socket closed early.
814
849
  if (!ended) throw streamCut(id);
815
- // A `[DONE]` with no finish stated still owes its calls the same check.
850
+ // A `[DONE]` with no finish stated still owes its calls the same check,
851
+ // and its citations their place.
852
+ if (hostedStream) yield* hostedStream.close();
816
853
  const minted = settleToolCalls(id, calls.values());
817
854
  if (minted.length > 0) yield { type: "delta", toolCalls: minted };
818
855
  },
819
856
  };
820
857
 
821
- return withConfiguredFallbacks(provider, config);
858
+ return configuredFallbacks(provider, config, codecs);
822
859
  }