@providerkit/core 0.29.1 → 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 (163) hide show
  1. package/README.md +58 -9
  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 +29 -2
  14. package/dist/errors.js.map +1 -1
  15. package/dist/fallback.d.ts +3 -0
  16. package/dist/fallback.d.ts.map +1 -1
  17. package/dist/fallback.js +9 -5
  18. package/dist/fallback.js.map +1 -1
  19. package/dist/gate.js.map +1 -1
  20. package/dist/hosted/anthropic.d.ts +30 -0
  21. package/dist/hosted/anthropic.d.ts.map +1 -0
  22. package/dist/hosted/anthropic.js +465 -0
  23. package/dist/hosted/anthropic.js.map +1 -0
  24. package/dist/hosted/gemini.d.ts +22 -0
  25. package/dist/hosted/gemini.d.ts.map +1 -0
  26. package/dist/hosted/gemini.js +440 -0
  27. package/dist/hosted/gemini.js.map +1 -0
  28. package/dist/hosted/openai.d.ts +33 -0
  29. package/dist/hosted/openai.d.ts.map +1 -0
  30. package/dist/hosted/openai.js +107 -0
  31. package/dist/hosted/openai.js.map +1 -0
  32. package/dist/hosted/responses.d.ts +28 -0
  33. package/dist/hosted/responses.d.ts.map +1 -0
  34. package/dist/hosted/responses.js +358 -0
  35. package/dist/hosted/responses.js.map +1 -0
  36. package/dist/hosted/shared.d.ts +107 -0
  37. package/dist/hosted/shared.d.ts.map +1 -0
  38. package/dist/hosted/shared.js +264 -0
  39. package/dist/hosted/shared.js.map +1 -0
  40. package/dist/hosted/types.d.ts +191 -0
  41. package/dist/hosted/types.d.ts.map +1 -0
  42. package/dist/hosted/types.js +10 -0
  43. package/dist/hosted/types.js.map +1 -0
  44. package/dist/hosted.d.ts +33 -0
  45. package/dist/hosted.d.ts.map +1 -0
  46. package/dist/hosted.js +61 -0
  47. package/dist/hosted.js.map +1 -0
  48. package/dist/index.d.ts +8 -7
  49. package/dist/index.d.ts.map +1 -1
  50. package/dist/index.js +8 -7
  51. package/dist/index.js.map +1 -1
  52. package/dist/key-pool.d.ts.map +1 -1
  53. package/dist/key-pool.js.map +1 -1
  54. package/dist/presets.d.ts +36 -5
  55. package/dist/presets.d.ts.map +1 -1
  56. package/dist/presets.js +32 -8
  57. package/dist/presets.js.map +1 -1
  58. package/dist/providers/anthropic.d.ts +75 -1
  59. package/dist/providers/anthropic.d.ts.map +1 -1
  60. package/dist/providers/anthropic.js +207 -135
  61. package/dist/providers/anthropic.js.map +1 -1
  62. package/dist/providers/deepgram-transcription.d.ts +24 -0
  63. package/dist/providers/deepgram-transcription.d.ts.map +1 -0
  64. package/dist/providers/deepgram-transcription.js +84 -0
  65. package/dist/providers/deepgram-transcription.js.map +1 -0
  66. package/dist/providers/factory.d.ts +10 -0
  67. package/dist/providers/factory.d.ts.map +1 -1
  68. package/dist/providers/factory.js +31 -23
  69. package/dist/providers/factory.js.map +1 -1
  70. package/dist/providers/gemini.d.ts +123 -1
  71. package/dist/providers/gemini.d.ts.map +1 -1
  72. package/dist/providers/gemini.js +114 -54
  73. package/dist/providers/gemini.js.map +1 -1
  74. package/dist/providers/hosted-codecs.d.ts +10 -0
  75. package/dist/providers/hosted-codecs.d.ts.map +1 -0
  76. package/dist/providers/hosted-codecs.js +8 -0
  77. package/dist/providers/hosted-codecs.js.map +1 -0
  78. package/dist/providers/openai-transcription.d.ts +21 -0
  79. package/dist/providers/openai-transcription.d.ts.map +1 -0
  80. package/dist/providers/openai-transcription.js +144 -0
  81. package/dist/providers/openai-transcription.js.map +1 -0
  82. package/dist/providers/openai.d.ts +69 -0
  83. package/dist/providers/openai.d.ts.map +1 -1
  84. package/dist/providers/openai.js +38 -14
  85. package/dist/providers/openai.js.map +1 -1
  86. package/dist/providers/responses.d.ts +123 -0
  87. package/dist/providers/responses.d.ts.map +1 -1
  88. package/dist/providers/responses.js +57 -22
  89. package/dist/providers/responses.js.map +1 -1
  90. package/dist/providers/speech-factory.js.map +1 -1
  91. package/dist/providers/transcription-factory.d.ts +30 -0
  92. package/dist/providers/transcription-factory.d.ts.map +1 -0
  93. package/dist/providers/transcription-factory.js +38 -0
  94. package/dist/providers/transcription-factory.js.map +1 -0
  95. package/dist/registry.d.ts +3 -0
  96. package/dist/registry.d.ts.map +1 -1
  97. package/dist/registry.js +8 -4
  98. package/dist/registry.js.map +1 -1
  99. package/dist/retry.js.map +1 -1
  100. package/dist/speech-core.d.ts +2 -17
  101. package/dist/speech-core.d.ts.map +1 -1
  102. package/dist/speech-core.js +10 -50
  103. package/dist/speech-core.js.map +1 -1
  104. package/dist/tools.d.ts.map +1 -1
  105. package/dist/tools.js.map +1 -1
  106. package/dist/transcription-core.d.ts +146 -0
  107. package/dist/transcription-core.d.ts.map +1 -0
  108. package/dist/transcription-core.js +193 -0
  109. package/dist/transcription-core.js.map +1 -0
  110. package/dist/transcription.d.ts +7 -0
  111. package/dist/transcription.d.ts.map +1 -0
  112. package/dist/transcription.js +12 -0
  113. package/dist/transcription.js.map +1 -0
  114. package/dist/transport.d.ts +26 -0
  115. package/dist/transport.d.ts.map +1 -1
  116. package/dist/transport.js +57 -2
  117. package/dist/transport.js.map +1 -1
  118. package/dist/turn.d.ts +10 -1
  119. package/dist/turn.d.ts.map +1 -1
  120. package/dist/turn.js +53 -1
  121. package/dist/turn.js.map +1 -1
  122. package/dist/types.d.ts +51 -0
  123. package/dist/types.d.ts.map +1 -1
  124. package/dist/types.js.map +1 -1
  125. package/dist/usage.d.ts +10 -1
  126. package/dist/usage.d.ts.map +1 -1
  127. package/dist/usage.js +40 -2
  128. package/dist/usage.js.map +1 -1
  129. package/dist/watchdog.d.ts +6 -0
  130. package/dist/watchdog.d.ts.map +1 -1
  131. package/dist/watchdog.js +10 -2
  132. package/dist/watchdog.js.map +1 -1
  133. package/package.json +14 -5
  134. package/src/context.ts +21 -5
  135. package/src/errors.ts +35 -2
  136. package/src/fallback.ts +21 -6
  137. package/src/hosted/anthropic.ts +512 -0
  138. package/src/hosted/gemini.ts +510 -0
  139. package/src/hosted/openai.ts +137 -0
  140. package/src/hosted/responses.ts +420 -0
  141. package/src/hosted/shared.ts +341 -0
  142. package/src/hosted/types.ts +214 -0
  143. package/src/hosted.ts +101 -0
  144. package/src/index.ts +64 -7
  145. package/src/presets.ts +54 -8
  146. package/src/providers/anthropic.ts +252 -143
  147. package/src/providers/deepgram-transcription.ts +109 -0
  148. package/src/providers/factory.ts +127 -82
  149. package/src/providers/gemini.ts +184 -60
  150. package/src/providers/hosted-codecs.ts +29 -0
  151. package/src/providers/openai-transcription.ts +177 -0
  152. package/src/providers/openai.ts +52 -15
  153. package/src/providers/responses.ts +93 -24
  154. package/src/providers/transcription-factory.ts +68 -0
  155. package/src/registry.ts +14 -4
  156. package/src/speech-core.ts +9 -47
  157. package/src/transcription-core.ts +345 -0
  158. package/src/transcription.ts +24 -0
  159. package/src/transport.ts +77 -3
  160. package/src/turn.ts +55 -1
  161. package/src/types.ts +62 -1
  162. package/src/usage.ts +32 -2
  163. package/src/watchdog.ts +12 -2
package/src/types.ts CHANGED
@@ -6,6 +6,14 @@
6
6
  // the lingua franca forces the other adapters to round-trip through a dialect
7
7
  // that isn't theirs, and every quirk of that dialect then leaks into callers
8
8
  // who never asked for it.
9
+ import type {
10
+ Citation,
11
+ HostedCall,
12
+ HostedCallDelta,
13
+ HostedItems,
14
+ HostedTool,
15
+ HostedToolType,
16
+ } from "./hosted/types.ts";
9
17
  import type { RateLimitReading } from "./rate-limit.ts";
10
18
 
11
19
  /**
@@ -46,7 +54,10 @@ export interface ImagePart {
46
54
  /** A file's media type: anything but an image's, because an image is an
47
55
  * `ImagePart`, which every adapter can send. */
48
56
  export type FileMimeType =
49
- `application/${string}` | `audio/${string}` | `video/${string}` | `text/${string}`;
57
+ | `application/${string}`
58
+ | `audio/${string}`
59
+ | `video/${string}`
60
+ | `text/${string}`;
50
61
 
51
62
  /**
52
63
  * A file the model reads (a PDF, a recording, a video) as base64 bytes,
@@ -119,6 +130,19 @@ export type ChatMessage =
119
130
  */
120
131
  reasoningItems?: ReasoningItems;
121
132
  toolCalls?: ToolCall[];
133
+ /**
134
+ * What the vendor's own tools did in this turn (a search, a fetch, a code
135
+ * run), in the order they ran. Never function calls: nothing here is
136
+ * run by the loop or answered with a `tool` message. Display data, with
137
+ * the sensitivity of `content`.
138
+ */
139
+ hostedCalls?: HostedCall[];
140
+ /** The sources the answer cites, with spans into `content`. */
141
+ citations?: Citation[];
142
+ /** The vendor's own record of its hosted tools, replayed only to the
143
+ * provider that made it. Provider-owned like `reasoningItems`: never
144
+ * echo it to a browser. See {@link HostedItems}. */
145
+ hostedItems?: HostedItems;
122
146
  }
123
147
  | {
124
148
  role: "tool";
@@ -189,6 +213,20 @@ export interface TokenUsage {
189
213
  * `costUsd` and `UsageTracker` bill it over any rate.
190
214
  */
191
215
  reportedCostUsd?: number;
216
+ /**
217
+ * The hosted tool calls this turn ran, by type: as the vendor states them
218
+ * (Anthropic, OpenRouter), or as the stream showed them. Absent when none
219
+ * ran. Vendors bill these per call, beside the tokens; `ModelRate.hosted`
220
+ * prices them.
221
+ */
222
+ hostedCalls?: Partial<Record<HostedToolType, number>>;
223
+ /**
224
+ * The prompt of the turn's LAST model pass, cache included, where the
225
+ * vendor states it (Anthropic's `usage.iterations`). A hosted tool loop runs
226
+ * several passes inside one turn and bills their sum, so `inputTokens` can
227
+ * read far larger than the window ever held. Compaction reads this first.
228
+ */
229
+ contextTokens?: number;
192
230
  }
193
231
 
194
232
  export const EMPTY_USAGE: TokenUsage = {
@@ -211,6 +249,13 @@ export interface ProviderChunk {
211
249
  /** Once per turn, where a provider replays its reasoning. See ChatMessage.reasoningItems. */
212
250
  reasoningItems?: ReasoningItems;
213
251
  toolCalls?: ToolCallDelta[];
252
+ /** Hosted call fragments, assembled by `index`. One commits the stream:
253
+ * past it, a retry would rerun and rebill the vendor's tool. */
254
+ hosted?: HostedCallDelta[];
255
+ /** Citations, appended in order. Their spans index the turn's content. */
256
+ citations?: Citation[];
257
+ /** Once per turn, where a provider replays its hosted tools. See ChatMessage.hostedItems. */
258
+ hostedItems?: HostedItems;
214
259
  usage?: TokenUsage;
215
260
  finishReason?: FinishReason;
216
261
  }
@@ -437,6 +482,22 @@ export interface StreamOptions {
437
482
  * Gemini has no such switch. Overrides the provider's own setting.
438
483
  */
439
484
  serviceTier?: ServiceTier;
485
+ /**
486
+ * Tools the model vendor runs inside its own turn: web search, web fetch,
487
+ * code execution, file search, image generation. Each adapter sends them in
488
+ * its dialect, or refuses one it can't send with an `invalid` error before
489
+ * any request, unless the tool is `optional`. `toolChoice: "none"` sends
490
+ * none; a forced choice with any is refused.
491
+ *
492
+ * Import the provider constructor from `@providerkit/core/hosted` first.
493
+ * Plain constructors refuse this option before any request, even with
494
+ * `optional` or `toolChoice: "none"`; they include no hosted codecs.
495
+ *
496
+ * A custom Provider that can't run them must refuse them the same way
497
+ * (`planHostedTools` from `@providerkit/core/hosted` does it): ignored, they
498
+ * become an answer that never searched, with nothing to say so.
499
+ */
500
+ hostedTools?: readonly HostedTool[];
440
501
  }
441
502
 
442
503
  // ponytail: Codex's `ultrafast` tier (gpt-6-astra only) is the next value to add.
package/src/usage.ts CHANGED
@@ -12,9 +12,22 @@
12
12
  // go stale, and where one model id is served by several hosts at different
13
13
  // prices it is the only figure that names the host that answered. When it is
14
14
  // present it wins; the caller's rate prices everything else.
15
+ import { HOSTED_TOOL_TYPES, type HostedToolType } from "./hosted/types.ts";
15
16
  import type { TokenUsage } from "./types.ts";
16
17
  import { EMPTY_USAGE } from "./types.ts";
17
18
 
19
+ type HostedCounts = Partial<Record<HostedToolType, number>>;
20
+
21
+ /** Two count records combined type by type, each clamped at zero. */
22
+ function combineCounts(a: HostedCounts, b: HostedCounts | undefined, sign: 1 | -1): HostedCounts {
23
+ const out: HostedCounts = { ...a };
24
+ for (const type of HOSTED_TOOL_TYPES) {
25
+ const count = b?.[type];
26
+ if (count !== undefined) out[type] = Math.max(0, (out[type] ?? 0) + sign * count);
27
+ }
28
+ return out;
29
+ }
30
+
18
31
  /** USD per million tokens, as every vendor prints its price sheet, so a row
19
32
  * can be checked against one without arithmetic. */
20
33
  export interface ModelRate {
@@ -30,12 +43,17 @@ export interface ModelRate {
30
43
  * (1.25×); the OpenAI-shape auto-cachers bill it at the input rate.
31
44
  * Defaults to `input` when a vendor does not price it separately. */
32
45
  cacheWrite?: number;
46
+ /** USD per hosted tool call (a search, a fetch, a code run), by type, as
47
+ * the vendor's price sheet states it. Billed beside the tokens; a type
48
+ * left out bills nothing. */
49
+ hosted?: Partial<Record<HostedToolType, number>>;
33
50
  }
34
51
 
35
52
  /** Add two usage records. The sum carries no `reportedCostUsd`: a call
36
53
  * priced by its provider plus one priced by a rate is not one bill, and
37
54
  * `costUsd` would price the whole sum at the one figure. Accumulate cost in
38
- * a `UsageTracker`, which prices each call as it arrives. */
55
+ * a `UsageTracker`, which prices each call as it arrives. Nor
56
+ * `contextTokens`: two calls' contexts do not add up to a window. */
39
57
  export function addUsage(a: TokenUsage, b: TokenUsage): TokenUsage {
40
58
  return {
41
59
  inputTokens: a.inputTokens + b.inputTokens,
@@ -45,6 +63,9 @@ export function addUsage(a: TokenUsage, b: TokenUsage): TokenUsage {
45
63
  ...(a.reasoningTokens !== undefined || b.reasoningTokens !== undefined
46
64
  ? { reasoningTokens: (a.reasoningTokens ?? 0) + (b.reasoningTokens ?? 0) }
47
65
  : {}),
66
+ ...(a.hostedCalls || b.hostedCalls
67
+ ? { hostedCalls: combineCounts(a.hostedCalls ?? {}, b.hostedCalls, 1) }
68
+ : {}),
48
69
  };
49
70
  }
50
71
 
@@ -61,6 +82,7 @@ export function subtractUsage(a: TokenUsage, b: TokenUsage): TokenUsage {
61
82
  ...(a.reasoningTokens !== undefined
62
83
  ? { reasoningTokens: Math.max(0, a.reasoningTokens - (b.reasoningTokens ?? 0)) }
63
84
  : {}),
85
+ ...(a.hostedCalls ? { hostedCalls: combineCounts(a.hostedCalls, b.hostedCalls, -1) } : {}),
64
86
  };
65
87
  }
66
88
 
@@ -75,6 +97,9 @@ export function subtractUsage(a: TokenUsage, b: TokenUsage): TokenUsage {
75
97
  * part at the write rate. `cached` is clamped to `input` so an over-reporting
76
98
  * provider can neither drive the miss count negative nor bill for more prompt
77
99
  * than it was sent.
100
+ *
101
+ * Hosted tool calls bill per call at `rate.hosted`. A reported cost already
102
+ * includes them (OpenRouter's search fee is inside its `cost`).
78
103
  */
79
104
  export function costUsd(usage: TokenUsage, rate: ModelRate): number {
80
105
  if (usage.reportedCostUsd !== undefined) return usage.reportedCostUsd;
@@ -85,12 +110,17 @@ export function costUsd(usage: TokenUsage, rate: ModelRate): number {
85
110
  // once at the input rate, again at the write rate: 2.25× on Claude.
86
111
  const miss = Math.max(0, input - cached - written);
87
112
  const writeRate = rate.cacheWrite ?? rate.input;
113
+ let hosted = 0;
114
+ for (const type of HOSTED_TOOL_TYPES) {
115
+ hosted += Math.max(0, usage.hostedCalls?.[type] ?? 0) * (rate.hosted?.[type] ?? 0);
116
+ }
88
117
  return (
89
118
  (miss * rate.input +
90
119
  cached * rate.cacheRead +
91
120
  written * writeRate +
92
121
  Math.max(0, usage.outputTokens) * rate.output) /
93
- 1_000_000
122
+ 1_000_000 +
123
+ hosted
94
124
  );
95
125
  }
96
126
 
package/src/watchdog.ts CHANGED
@@ -208,6 +208,12 @@ export async function* watchChunks<T>(
208
208
  * answers) and backup-eligible (a model that keeps doing it should be walked
209
209
  * away from). Until something streams, the empty frames are held back, so the
210
210
  * retry rule still holds: retry only while nothing was emitted.
211
+ *
212
+ * A hosted call streams the moment it appears, like reasoning, and is not an
213
+ * answer either: a search alone has said nothing. Forwarding it commits the
214
+ * stream, which is the point, because a retry past it would rerun and rebill
215
+ * the vendor's tool and show the reader the same search twice. The one hosted
216
+ * result that IS an answer is a generated image.
211
217
  */
212
218
  export async function* requireContent<T extends ProviderChunk>(
213
219
  provider: string,
@@ -223,9 +229,13 @@ export async function* requireContent<T extends ProviderChunk>(
223
229
  for await (const chunk of chunks) {
224
230
  if (chunk.type === "finish") finish = chunk.finishReason;
225
231
  if (chunk.usage) usage = chunk.usage;
226
- answered ||= Boolean(chunk.content || chunk.toolCalls?.length);
232
+ answered ||= Boolean(
233
+ chunk.content ||
234
+ chunk.toolCalls?.length ||
235
+ chunk.hosted?.some((call) => call.status !== "failed" && call.output?.images?.length),
236
+ );
227
237
  if (!streaming) {
228
- streaming = answered || Boolean(chunk.reasoning);
238
+ streaming = answered || Boolean(chunk.reasoning || chunk.hosted?.length);
229
239
  // Held rather than forwarded: once a chunk is out, the stream is
230
240
  // committed and the retry this guard exists to trigger can no longer
231
241
  // fire. Nothing has arrived worth showing yet, so there is nothing to