@providerkit/core 0.34.0 → 0.35.1

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 (66) hide show
  1. package/README.md +18 -0
  2. package/dist/decisions.js +1 -1
  3. package/dist/decisions.js.map +1 -1
  4. package/dist/errors.d.ts +2 -7
  5. package/dist/errors.d.ts.map +1 -1
  6. package/dist/errors.js +114 -69
  7. package/dist/errors.js.map +1 -1
  8. package/dist/hosted/anthropic.d.ts +4 -2
  9. package/dist/hosted/anthropic.d.ts.map +1 -1
  10. package/dist/hosted/anthropic.js +7 -6
  11. package/dist/hosted/anthropic.js.map +1 -1
  12. package/dist/index.d.ts +3 -2
  13. package/dist/index.d.ts.map +1 -1
  14. package/dist/index.js +3 -2
  15. package/dist/index.js.map +1 -1
  16. package/dist/providers/anthropic.d.ts.map +1 -1
  17. package/dist/providers/anthropic.js +113 -12
  18. package/dist/providers/anthropic.js.map +1 -1
  19. package/dist/providers/gemini.d.ts.map +1 -1
  20. package/dist/providers/gemini.js +5 -4
  21. package/dist/providers/gemini.js.map +1 -1
  22. package/dist/providers/openai.d.ts +3 -34
  23. package/dist/providers/openai.d.ts.map +1 -1
  24. package/dist/providers/openai.js +10 -40
  25. package/dist/providers/openai.js.map +1 -1
  26. package/dist/providers/openrouter-billing.d.ts +27 -0
  27. package/dist/providers/openrouter-billing.d.ts.map +1 -0
  28. package/dist/providers/openrouter-billing.js +37 -0
  29. package/dist/providers/openrouter-billing.js.map +1 -0
  30. package/dist/providers/responses.d.ts +2 -1
  31. package/dist/providers/responses.d.ts.map +1 -1
  32. package/dist/providers/responses.js +26 -13
  33. package/dist/providers/responses.js.map +1 -1
  34. package/dist/rate-limit.d.ts +11 -8
  35. package/dist/rate-limit.d.ts.map +1 -1
  36. package/dist/rate-limit.js +123 -77
  37. package/dist/rate-limit.js.map +1 -1
  38. package/dist/tools.d.ts +2 -0
  39. package/dist/tools.d.ts.map +1 -1
  40. package/dist/tools.js.map +1 -1
  41. package/dist/transport.d.ts +6 -0
  42. package/dist/transport.d.ts.map +1 -1
  43. package/dist/transport.js +12 -9
  44. package/dist/transport.js.map +1 -1
  45. package/dist/watchdog.d.ts.map +1 -1
  46. package/dist/watchdog.js +4 -1
  47. package/dist/watchdog.js.map +1 -1
  48. package/dist/zod.d.ts +17 -0
  49. package/dist/zod.d.ts.map +1 -1
  50. package/dist/zod.js +34 -14
  51. package/dist/zod.js.map +1 -1
  52. package/package.json +1 -1
  53. package/src/decisions.ts +1 -1
  54. package/src/errors.ts +128 -70
  55. package/src/hosted/anthropic.ts +7 -6
  56. package/src/index.ts +9 -2
  57. package/src/providers/anthropic.ts +124 -12
  58. package/src/providers/gemini.ts +5 -4
  59. package/src/providers/openai.ts +29 -63
  60. package/src/providers/openrouter-billing.ts +42 -0
  61. package/src/providers/responses.ts +29 -15
  62. package/src/rate-limit.ts +132 -79
  63. package/src/tools.ts +2 -0
  64. package/src/transport.ts +14 -13
  65. package/src/watchdog.ts +4 -0
  66. package/src/zod.ts +48 -10
@@ -17,7 +17,7 @@ import type { HostedToolType } from "../hosted/types.ts";
17
17
  import { refuseHostedTools, type HostedCodecs } from "./hosted-codecs.ts";
18
18
  import { schemaPrompt, toAnthropicToolSchema } from "../schema.ts";
19
19
  import { parseToolArgs, settleToolCalls, type ToolCallIdentity } from "../tool-args.ts";
20
- import { streamSse, apiUrl, parseFrame, withRedactedErrors, type FetchLike } from "../transport.ts";
20
+ import { openSse, apiUrl, parseFrame, withRedactedErrors, type FetchLike } from "../transport.ts";
21
21
  import { attributionHeaders } from "../attribution.ts";
22
22
  import { configuredFallbacks, type ProviderFallbackConfig } from "../fallback.ts";
23
23
  import type {
@@ -283,7 +283,8 @@ function partsToAnthropic(content: string | ContentPart[], provider: string): un
283
283
  * tool results are merged into one user turn, which the API requires.
284
284
  */
285
285
  /**
286
- * The system prompt as ONE cached block.
286
+ * The system prompt: one text block per system message, in order, with the
287
+ * cache breakpoint on the last.
287
288
  *
288
289
  * Anthropic's prompt caching is opt-in per block. A plain string system prompt
289
290
  * is never cached, however many times it is re-sent. An agent loop re-sends this
@@ -294,9 +295,116 @@ function partsToAnthropic(content: string | ContentPart[], provider: string): un
294
295
  * Unconditional. Below the model's minimum cacheable length the field is
295
296
  * ignored rather than rejected, and above it the one-time 1.25× write is repaid
296
297
  * by the second turn, which always comes in the loop this package sits under.
298
+ *
299
+ * A block per message, not one joined block, because a decorator over a
300
+ * Provider can only add a system message. A line it puts first then reaches the
301
+ * wire as its own first block, which a gateway that reads the first block finds
302
+ * alone, instead of as the start of a block that holds the whole prompt.
303
+ *
304
+ * A blank message gets no block. Joined, it was a few spaces inside real text;
305
+ * alone, it is a 400 ("system text blocks must contain non-whitespace text",
306
+ * recorded against claude-sonnet-5-5 by PydanticAI, MIT,
307
+ * tests/test_history_properties.py).
308
+ */
309
+ function systemBlocks(messages: readonly string[]): unknown[] | undefined {
310
+ const texts = messages.filter((text) => text.trim() !== "");
311
+ if (texts.length === 0) return undefined;
312
+ return texts.map((text, i) =>
313
+ i === texts.length - 1
314
+ ? { type: "text", text, cache_control: { type: "ephemeral" } }
315
+ : { type: "text", text },
316
+ );
317
+ }
318
+
319
+ /**
320
+ * Whether Anthropic takes a cache marker on this block. A list of the blocks
321
+ * that do, rather than of the ones that don't: a marker on a block that refuses
322
+ * one is a 400 that loses the turn, while a block missing from this list only
323
+ * moves the marker back a block.
324
+ *
325
+ * Thinking blocks of both kinds and empty text cannot carry one; text, images,
326
+ * tool use and tool results can, the last two in user and assistant turns alike
327
+ * (Anthropic, Prompt caching, "What can be cached" and "What cannot be cached",
328
+ * read 2026-11-19). A server tool's result takes one too: the API puts its own
329
+ * breakpoint there before its tool loop's next step (Anthropic, Tool use with
330
+ * prompt caching, read 2026-11-19). Blank text counts as empty: the API refuses
331
+ * a text block of only whitespace outright.
332
+ */
333
+ function takesMarker(block: unknown): block is Record<string, unknown> {
334
+ if (typeof block !== "object" || block === null || !("type" in block)) return false;
335
+ const { type } = block;
336
+ if (type === "text") {
337
+ return "text" in block && typeof block.text === "string" && block.text.trim() !== "";
338
+ }
339
+ return (
340
+ type === "image" ||
341
+ type === "tool_use" ||
342
+ type === "tool_result" ||
343
+ type === "server_tool_use" ||
344
+ (typeof type === "string" && type.endsWith("_tool_result"))
345
+ );
346
+ }
347
+
348
+ /** `message` with a marker on its last block that takes one, or as it was when none does. */
349
+ function markLast(message: AnthropicMessage): AnthropicMessage {
350
+ for (let i = message.content.length - 1; i >= 0; i--) {
351
+ const block = message.content[i];
352
+ if (!takesMarker(block)) continue;
353
+ const content = [...message.content];
354
+ content[i] = { ...block, cache_control: { type: "ephemeral" } };
355
+ return { ...message, content };
356
+ }
357
+ return message;
358
+ }
359
+
360
+ /**
361
+ * The conversation's cache breakpoints. The system marker caches the fixed
362
+ * prefix, tools and system; these cache the conversation, which grows every
363
+ * turn while that prefix stays the same size. Without them every turn billed
364
+ * the whole history again at the full input rate, and only tools and system
365
+ * came from cache.
366
+ *
367
+ * Two of them, on the last block that takes one (see takesMarker):
368
+ * - The newest message. Each request writes its entry there.
369
+ * - The message just before the newest assistant message: where the previous
370
+ * request ended, so this one reads that request's entry exactly. A read looks
371
+ * back at most 20 positions from a breakpoint for an entry an earlier request
372
+ * wrote. On the Claude API a run of tool_use blocks counts as one position, and
373
+ * so does a run of tool_result blocks; the docs state that rule for no other
374
+ * platform. A turn that adds more than 20 would read nothing from the newest
375
+ * marker alone, and bill its whole prefix fresh. An adopter ran on the newest
376
+ * marker alone and named this second one as the upgrade.
377
+ *
378
+ * Only on a request another one will follow: one that declares tools, or one
379
+ * whose messages already hold an assistant turn. A one-shot would pay the 1.25×
380
+ * write for an entry nothing reads. A prefix under the model's minimum (512
381
+ * tokens on the newest models, up to 4,096 on older ones) is neither cached
382
+ * nor billed as a write.
383
+ *
384
+ * Block markers only, never the top-level `cache_control` field that turns on
385
+ * automatic caching: the legacy Bedrock integration (bedrock-runtime) answers
386
+ * that field with a 400, and no Anthropic-shape gateway has been checked.
387
+ *
388
+ * With the system's, three markers at most, under the API's cap of four. They
389
+ * depend only on the messages, and a moved marker is not a changed prefix (the
390
+ * docs' own growing conversation moves it every turn and reads the last
391
+ * turn's entry), so a longer history still sends the shorter one's bytes plus
392
+ * what is new (invariant 14).
393
+ *
394
+ * Documented (Anthropic, Prompt caching, read 2026-11-19:
395
+ * platform.claude.com/docs/en/build-with-claude/prompt-caching); not measured
396
+ * live here.
297
397
  */
298
- function systemBlocks(text: string): unknown[] | undefined {
299
- return text ? [{ type: "text", text, cache_control: { type: "ephemeral" } }] : undefined;
398
+ function markConversation(
399
+ messages: AnthropicMessage[],
400
+ declaresTools: boolean,
401
+ ): AnthropicMessage[] {
402
+ const newestReply = messages.map((message) => message.role).lastIndexOf("assistant");
403
+ if (!declaresTools && newestReply < 0) return messages;
404
+ const previousEnd = newestReply - 1;
405
+ return messages.map((message, i) =>
406
+ i === messages.length - 1 || i === previousEnd ? markLast(message) : message,
407
+ );
300
408
  }
301
409
 
302
410
  /**
@@ -366,10 +474,7 @@ export function anthropicMessages(
366
474
  messages: AnthropicMessage[];
367
475
  } {
368
476
  const wireId = anthropicIds();
369
- const system = messages
370
- .filter((m) => m.role === "system")
371
- .map((m) => m.content)
372
- .join("\n\n");
477
+ const system = messages.flatMap((m) => (m.role === "system" ? [m.content] : []));
373
478
 
374
479
  const toolUse = (call: { id: string; name: string; arguments: string }) => ({
375
480
  type: "tool_use",
@@ -653,9 +758,15 @@ export function anthropicProvider(config: AnthropicConfig, codecs?: HostedCodecs
653
758
  let cached = 0;
654
759
  let written = 0;
655
760
  let output = 0;
656
- const payload = hostedStream?.payload(request, body) ?? request;
761
+ // Marked per pass, because each pass is a request of its own: the one
762
+ // after a pause ends in the paused turn, so that is its newest message.
763
+ const messages = markConversation(
764
+ hostedStream?.messages(body) ?? body,
765
+ request.tools !== undefined,
766
+ );
767
+ const payload = hostedStream?.payload({ ...request, messages }) ?? { ...request, messages };
657
768
 
658
- read: for await (const data of streamSse({
769
+ const stream = await openSse({
659
770
  url: apiUrl(baseUrl, "/v1/messages"),
660
771
  headers,
661
772
  body: payload,
@@ -667,7 +778,8 @@ export function anthropicProvider(config: AnthropicConfig, codecs?: HostedCodecs
667
778
  // The stop reason rides in `message_delta` with the final usage, so a
668
779
  // read that dies after it loses nothing but `message_stop`.
669
780
  finished: () => stopped,
670
- })) {
781
+ });
782
+ read: for await (const data of stream.frames) {
671
783
  const event = parseFrame<AnthropicEvent>(data, id);
672
784
  if (hostedStream) yield* hostedStream.event(event);
673
785
 
@@ -677,7 +789,7 @@ export function anthropicProvider(config: AnthropicConfig, codecs?: HostedCodecs
677
789
  // most of the time, but a prompt found too long mid-stream arrives the
678
790
  // same way, and retrying that one only fails it again more slowly.
679
791
  case "error":
680
- throw streamError(id, event);
792
+ throw streamError(id, event, stream.headers);
681
793
 
682
794
  case "message_start": {
683
795
  const usage = event.message?.usage;
@@ -22,7 +22,7 @@ import type { HostedToolType } from "../hosted/types.ts";
22
22
  import { refuseHostedTools, type HostedCodecs } from "./hosted-codecs.ts";
23
23
  import { schemaPrompt, toAntigravityToolSchema, toGeminiToolSchema } from "../schema.ts";
24
24
  import { parseToolArgs, settleToolCalls } from "../tool-args.ts";
25
- import { streamSse, apiUrl, withRedactedErrors, type FetchLike } from "../transport.ts";
25
+ import { openSse, apiUrl, withRedactedErrors, type FetchLike } from "../transport.ts";
26
26
  import { configuredFallbacks, type ProviderFallbackConfig } from "../fallback.ts";
27
27
  import type {
28
28
  ChatMessage,
@@ -689,7 +689,7 @@ export function geminiProvider(config: GeminiConfig, codecs?: HostedCodecs): Pro
689
689
  for (let baseIdx = 0; baseIdx < bases.length; baseIdx++) {
690
690
  const currentBase = bases[baseIdx]!;
691
691
  try {
692
- for await (const data of streamSse({
692
+ const stream = await openSse({
693
693
  // Without `?alt=sse` the response is one long JSON array that only
694
694
  // parses once complete, which is not a stream.
695
695
  url: apiUrl(currentBase, path),
@@ -704,7 +704,8 @@ export function geminiProvider(config: GeminiConfig, codecs?: HostedCodecs): Pro
704
704
  // the end: a read that dies after it can cost a late usage record, never
705
705
  // the answer.
706
706
  finished: () => finished,
707
- })) {
707
+ });
708
+ for await (const data of stream.frames) {
708
709
  let parsed: GeminiResponse & { response?: GeminiResponse };
709
710
  try {
710
711
  parsed = JSON.parse(data) as GeminiResponse & { response?: GeminiResponse };
@@ -716,7 +717,7 @@ export function geminiProvider(config: GeminiConfig, codecs?: HostedCodecs): Pro
716
717
  // `?alt=sse` commits to 200 the moment the headers go out, so a
717
718
  // throttle or an overload landing after that arrives here as a
718
719
  // google.rpc.Status in the body rather than as a status line.
719
- if (chunk.error) throw streamError(id, chunk);
720
+ if (chunk.error) throw streamError(id, parsed, stream.headers);
720
721
  // A blocked PROMPT has no candidate to finish, so it reads as a cut
721
722
  // stream — retried, into the same block. It is a content failure.
722
723
  const blocked = chunk.promptFeedback?.blockReason;
@@ -4,6 +4,11 @@
4
4
  // OpenRouter, DeepSeek, GLM, Kimi, Groq, Together, vLLM, Ollama and LM Studio.
5
5
  // Their divergences are small and named where they appear.
6
6
  import { repairHistory } from "../context.ts";
7
+ import {
8
+ isOpenRouterBillingHost,
9
+ openRouterCostUsd,
10
+ type OpenRouterBill,
11
+ } from "./openrouter-billing.ts";
7
12
  import {
8
13
  fileRefused,
9
14
  ProviderError,
@@ -13,7 +18,7 @@ import {
13
18
  } from "../errors.ts";
14
19
  import type { HostedToolType } from "../hosted/types.ts";
15
20
  import { refuseHostedTools, type HostedCodecs } from "./hosted-codecs.ts";
16
- import { streamSse, apiUrl, parseFrame, withRedactedErrors, type FetchLike } from "../transport.ts";
21
+ import { openSse, apiUrl, parseFrame, withRedactedErrors, type FetchLike } from "../transport.ts";
17
22
  import { settleToolCalls, type ToolCallIdentity } from "../tool-args.ts";
18
23
  import { attributionHeaders } from "../attribution.ts";
19
24
  import type {
@@ -319,7 +324,9 @@ export function effortParams(
319
324
  case "opencode-go":
320
325
  return goEffortParams(effort, model);
321
326
  case "openai":
322
- return { reasoning_effort: level ?? "none" };
327
+ // The pinned OpenAI host above refuses `none` for gpt-5-mini. Only that measured id
328
+ // gets its floor; an unrequested effort still sends nothing.
329
+ return { reasoning_effort: level ?? (model === "gpt-5-mini" ? "minimal" : "none") };
323
330
  case "off":
324
331
  return {};
325
332
  }
@@ -508,65 +515,26 @@ export interface OpenAIChunk {
508
515
  };
509
516
  finish_reason?: string | null;
510
517
  }[];
511
- usage?: {
512
- prompt_tokens?: number;
513
- completion_tokens?: number;
514
- prompt_tokens_details?: { cached_tokens?: number };
515
- completion_tokens_details?: { reasoning_tokens?: number };
516
- /** DeepSeek's native API reports the cache-hit count here instead of in
517
- * `prompt_tokens_details`, and it is absent from every OpenAI SDK type. */
518
- prompt_cache_hit_tokens?: number;
519
- /** Kimi (Moonshot) puts it at the top level of `usage`. */
520
- cached_tokens?: number;
521
- /** OpenRouter only, from here down: what the call cost, in its credits,
522
- * which are US dollars. */
523
- cost?: unknown;
524
- is_byok?: boolean;
525
- cost_details?: { upstream_inference_cost?: unknown } | null;
526
- /** The server tool calls OpenRouter ran for the turn. */
527
- server_tool_use_details?: { web_search_requests?: number } | null;
528
- } | null;
518
+ usage?:
519
+ | (OpenRouterBill & {
520
+ prompt_tokens?: number;
521
+ completion_tokens?: number;
522
+ prompt_tokens_details?: { cached_tokens?: number };
523
+ completion_tokens_details?: { reasoning_tokens?: number };
524
+ /** DeepSeek's native API reports the cache-hit count here instead of in
525
+ * `prompt_tokens_details`, and it is absent from every OpenAI SDK type. */
526
+ prompt_cache_hit_tokens?: number;
527
+ /** Kimi (Moonshot) puts it at the top level of `usage`. */
528
+ cached_tokens?: number;
529
+ /** The server tool calls OpenRouter ran for the turn. */
530
+ server_tool_use_details?: { web_search_requests?: number } | null;
531
+ })
532
+ | null;
529
533
  /** Present only on the in-band failure below. Never beside a choice.
530
534
  * `code` is the numeric HTTP status on the gateways, a slug on OpenAI. */
531
535
  error?: { message?: string; code?: string | number; type?: string };
532
536
  }
533
537
 
534
- /** A price off the wire, or undefined when it is not one. A negative or a
535
- * string falls back to the caller's rate rather than billing a nonsense
536
- * number. 0 is a real price: the one a free model charges. */
537
- function price(value: unknown): number | undefined {
538
- return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
539
- }
540
-
541
- /**
542
- * What an OpenRouter call cost, in USD, or undefined when it did not say.
543
- *
544
- * Nothing has to ask for it. OpenRouter's usage-accounting docs (read
545
- * 2026-09-26) say every response now carries the full usage record, cost
546
- * included, on the last frame of a stream, and that `usage: { include: true }`
547
- * is deprecated and does nothing. Measured the same day: a streamed call and a
548
- * plain one, neither sending the flag, both came back with `usage.cost`, the
549
- * stream on its last frame. So the request does not send it.
550
- *
551
- * With the caller's own provider key (BYOK), `cost` is only OpenRouter's fee.
552
- * The inference is billed to the caller's provider account and arrives as
553
- * `cost_details.upstream_inference_cost`, so the call cost the two together.
554
- * Without that second figure there is no whole bill to report, and the
555
- * caller's rate prices the call instead.
556
- *
557
- * Exported for the other OpenRouter wire that bills the same way: Jev's.
558
- */
559
- export function openRouterCostUsd(usage: {
560
- cost?: unknown;
561
- is_byok?: boolean;
562
- cost_details?: { upstream_inference_cost?: unknown } | null;
563
- }): number | undefined {
564
- const cost = price(usage.cost);
565
- if (cost === undefined || usage.is_byok !== true) return cost;
566
- const upstream = price(usage.cost_details?.upstream_inference_cost);
567
- return upstream === undefined ? undefined : cost + upstream;
568
- }
569
-
570
538
  export function createOpenAIProvider(config: OpenAIConfig): Provider {
571
539
  return openaiProvider(config);
572
540
  }
@@ -575,10 +543,7 @@ export function createOpenAIProvider(config: OpenAIConfig): Provider {
575
543
  export function openaiProvider(config: OpenAIConfig, codecs?: HostedCodecs): Provider {
576
544
  const baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;
577
545
  const id = config.id ?? "openai";
578
- // Keyed on the host, not the id: the host is who sends the bill, and
579
- // `usage.cost` is its field in its unit. Another gateway that sends a
580
- // `cost` has not said what it means.
581
- const reportsCost = isOpenRouter(baseUrl);
546
+ const reportsCost = isOpenRouterBillingHost(baseUrl);
582
547
  const instanceSessionId = config.sessionHeader
583
548
  ? (config.instanceSessionId ?? crypto.randomUUID())
584
549
  : undefined;
@@ -720,7 +685,7 @@ export function openaiProvider(config: OpenAIConfig, codecs?: HostedCodecs): Pro
720
685
  // before it goes out, and they are what says the turn called a tool.
721
686
  const calls = new Map<number, ToolCallIdentity>();
722
687
  const hostedStream = codecs?.openai.stream();
723
- for await (const data of streamSse({
688
+ const stream = await openSse({
724
689
  url: apiUrl(baseUrl, config.path ?? defaultPath),
725
690
  headers: {
726
691
  ...(config.apiKey ? { authorization: `Bearer ${config.apiKey}` } : {}),
@@ -746,7 +711,8 @@ export function openaiProvider(config: OpenAIConfig, codecs?: HostedCodecs): Pro
746
711
  // to `[DONE]` (invariant 5). But a read that dies in between costs only
747
712
  // the usage frame: the answer is whole once its finish is stated.
748
713
  finished: () => ended,
749
- })) {
714
+ });
715
+ for await (const data of stream.frames) {
750
716
  const chunk = parseFrame<OpenAIChunk>(data, id);
751
717
 
752
718
  // A failure the backend reports after its headers went out. The
@@ -755,7 +721,7 @@ export function openaiProvider(config: OpenAIConfig, codecs?: HostedCodecs): Pro
755
721
  // line, and a frame carrying `error` carries no choices: unread, it
756
722
  // falls through both branches below and the turn ends as a successful
757
723
  // zero-token completion nobody retries.
758
- if (chunk.error) throw streamError(id, chunk);
724
+ if (chunk.error) throw streamError(id, chunk, stream.headers);
759
725
 
760
726
  // A usage-only frame carries no choices — this shape sends it last.
761
727
  if (chunk.usage) {
@@ -0,0 +1,42 @@
1
+ export interface OpenRouterBill {
2
+ cost?: unknown;
3
+ is_byok?: boolean;
4
+ cost_details?: { upstream_inference_cost?: unknown } | null;
5
+ }
6
+
7
+ /** Other gateways may speak the same wire format without billing in US dollars. */
8
+ export function isOpenRouterBillingHost(baseUrl: string): boolean {
9
+ try {
10
+ return /(?:^|\.)openrouter\.ai\.?$/.test(new URL(baseUrl).hostname);
11
+ } catch {
12
+ return false;
13
+ }
14
+ }
15
+
16
+ /** A negative or a string falls back to the caller's rate. Zero is a real bill. */
17
+ function price(value: unknown): number | undefined {
18
+ return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
19
+ }
20
+
21
+ /**
22
+ * What an OpenRouter call cost, in USD, or undefined when it did not say.
23
+ *
24
+ * Nothing has to ask for it. OpenRouter's usage-accounting docs (read
25
+ * 2026-09-26) say every response now carries the full usage record, cost
26
+ * included, on the last frame of a stream, and that `usage: { include: true }`
27
+ * is deprecated and does nothing. Measured the same day: a streamed call and a
28
+ * plain one, neither sending the flag, both came back with `usage.cost`, the
29
+ * stream on its last frame. So the request does not send it.
30
+ *
31
+ * With the caller's own provider key (BYOK), `cost` is only OpenRouter's fee.
32
+ * The inference is billed to the caller's provider account and arrives as
33
+ * `cost_details.upstream_inference_cost`, so the call cost the two together.
34
+ * Without that second figure there is no whole bill to report, and the
35
+ * caller's rate prices the call instead.
36
+ */
37
+ export function openRouterCostUsd(usage: OpenRouterBill): number | undefined {
38
+ const cost = price(usage.cost);
39
+ if (cost === undefined || usage.is_byok !== true) return cost;
40
+ const upstream = price(usage.cost_details?.upstream_inference_cost);
41
+ return upstream === undefined ? undefined : price(cost + upstream);
42
+ }
@@ -25,7 +25,7 @@ import {
25
25
  } from "../errors.ts";
26
26
  import type { HostedToolType } from "../hosted/types.ts";
27
27
  import { refuseHostedTools, type HostedCodecs } from "./hosted-codecs.ts";
28
- import { streamSse, apiUrl, parseFrame, withRedactedErrors, type FetchLike } from "../transport.ts";
28
+ import { openSse, apiUrl, parseFrame, withRedactedErrors, type FetchLike } from "../transport.ts";
29
29
  import { parseRateLimitReset } from "../rate-limit.ts";
30
30
  import { settleToolCalls } from "../tool-args.ts";
31
31
  import type {
@@ -44,6 +44,11 @@ import { toDataUri } from "../types.ts";
44
44
  import { isStrictSchema, withoutPatterns } from "../schema.ts";
45
45
  import { configuredFallbacks, type ProviderFallbackConfig } from "../fallback.ts";
46
46
  import { gateImages, type ImageLimits } from "../image.ts";
47
+ import {
48
+ isOpenRouterBillingHost,
49
+ openRouterCostUsd,
50
+ type OpenRouterBill,
51
+ } from "./openrouter-billing.ts";
47
52
 
48
53
  export interface ResponsesConfig extends ProviderFallbackConfig {
49
54
  apiKey: string;
@@ -285,7 +290,7 @@ export function toResponsesInput(
285
290
 
286
291
  // ── stream events ─────────────────────────────────────────────────────────
287
292
 
288
- interface ResponsesUsage {
293
+ interface ResponsesUsage extends OpenRouterBill {
289
294
  input_tokens?: number;
290
295
  input_tokens_details?: { cached_tokens?: number };
291
296
  output_tokens?: number;
@@ -418,8 +423,10 @@ function codexHeaders(limits: CodexRateLimits): Headers {
418
423
  * them per call and states no count of its own. */
419
424
  function usageChunk(
420
425
  usage: ResponsesUsage,
426
+ reportsCost: boolean,
421
427
  hostedCalls?: Partial<Record<HostedToolType, number>>,
422
428
  ): ProviderChunk {
429
+ const reportedCostUsd = reportsCost ? openRouterCostUsd(usage) : undefined;
423
430
  return {
424
431
  type: "usage",
425
432
  usage: {
@@ -432,6 +439,7 @@ function usageChunk(
432
439
  ...(usage.output_tokens_details?.reasoning_tokens !== undefined
433
440
  ? { reasoningTokens: usage.output_tokens_details.reasoning_tokens }
434
441
  : {}),
442
+ ...(reportedCostUsd !== undefined ? { reportedCostUsd } : {}),
435
443
  ...(hostedCalls ? { hostedCalls } : {}),
436
444
  },
437
445
  };
@@ -463,6 +471,7 @@ export function createResponsesProvider(config: ResponsesConfig): Provider {
463
471
  /** @internal Shared by the plain and hosted entry points. */
464
472
  export function responsesProvider(config: ResponsesConfig, codecs?: HostedCodecs): Provider {
465
473
  const baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;
474
+ const reportsCost = isOpenRouterBillingHost(baseUrl);
466
475
  const id = config.id ?? "openai-responses";
467
476
  const instanceSessionId = config.sessionHeader
468
477
  ? (config.instanceSessionId ?? crypto.randomUUID())
@@ -637,7 +646,10 @@ export function responsesProvider(config: ResponsesConfig, codecs?: HostedCodecs
637
646
  ? [{ type: "delta", reasoningItems: { provider: id, items: reasoningItems } }]
638
647
  : [];
639
648
  const hostedStream = codecs?.responses.stream(hosted?.hosted ?? []);
640
- for await (const data of streamSse({
649
+ function* reportUsage(usage?: ResponsesUsage): Generator<ProviderChunk> {
650
+ if (usage) yield usageChunk(usage, reportsCost, hostedStream?.counts());
651
+ }
652
+ const stream = await openSse({
641
653
  url: apiUrl(baseUrl, config.path ?? DEFAULT_PATH),
642
654
  headers: {
643
655
  authorization: `Bearer ${config.apiKey}`,
@@ -652,7 +664,8 @@ export function responsesProvider(config: ResponsesConfig, codecs?: HostedCodecs
652
664
  ...(config.fetchImpl ? { fetchImpl: config.fetchImpl } : {}),
653
665
  ...(opts.onActivity ? { onActivity: opts.onActivity } : {}),
654
666
  ...(opts.onRateLimit ? { onRateLimit: opts.onRateLimit } : {}),
655
- })) {
667
+ });
668
+ for await (const data of stream.frames) {
656
669
  const event = parseFrame<ResponsesEvent>(data, id);
657
670
  if (event.type?.endsWith(".delta") || event.type === "response.output_item.added") {
658
671
  produced = true;
@@ -806,7 +819,7 @@ export function responsesProvider(config: ResponsesConfig, codecs?: HostedCodecs
806
819
  // error failed, and one that states `incomplete` was cut. Read as
807
820
  // a clean stop, either is a broken turn reported as a finished one.
808
821
  if (response?.status === "failed" || response?.error) {
809
- throw streamError(id, response.error ? response : { message: "response failed" });
822
+ throw streamError(id, event, stream.headers);
810
823
  }
811
824
  // Any other status (`cancelled`, `queued`, one added later) says
812
825
  // nothing about the answer being whole. Read as a clean stop, it
@@ -823,12 +836,19 @@ export function responsesProvider(config: ResponsesConfig, codecs?: HostedCodecs
823
836
  } else {
824
837
  // Checked on a whole turn only: a cut one may have lost a call's
825
838
  // name to the cut, and nobody runs a cut turn's calls.
826
- const minted = settleToolCalls(id, calls);
839
+ let minted;
840
+ try {
841
+ minted = settleToolCalls(id, calls);
842
+ } catch (error) {
843
+ // Opening the call already emitted a delta. Its bill is due even if no tool can run.
844
+ yield* reportUsage(response?.usage);
845
+ throw error;
846
+ }
827
847
  if (minted.length > 0) yield { type: "delta", toolCalls: minted };
828
848
  }
829
849
  if (hostedStream) yield* hostedStream.close();
830
850
  yield* reasoningChunk();
831
- if (response?.usage) yield usageChunk(response.usage, hostedStream?.counts());
851
+ yield* reportUsage(response?.usage);
832
852
  yield { type: "finish", finishReason };
833
853
  return;
834
854
  }
@@ -843,8 +863,7 @@ export function responsesProvider(config: ResponsesConfig, codecs?: HostedCodecs
843
863
  const finishReason = incompleteFinish(id, event.response?.incomplete_details?.reason);
844
864
  if (hostedStream) yield* hostedStream.close();
845
865
  yield* reasoningChunk();
846
- const usage = event.response?.usage;
847
- if (usage) yield usageChunk(usage, hostedStream?.counts());
866
+ yield* reportUsage(event.response?.usage);
848
867
  yield { type: "finish", finishReason };
849
868
  return;
850
869
  }
@@ -853,18 +872,13 @@ export function responsesProvider(config: ResponsesConfig, codecs?: HostedCodecs
853
872
  // out: a terminal `response.failed`, or a bare error frame from a
854
873
  // gateway in front of it.
855
874
  case "response.failed":
856
- throw streamError(
857
- id,
858
- event.response?.error ? event.response : { message: "response failed" },
859
- );
860
-
861
875
  case "error":
862
876
  case "response.error":
863
877
  // The status and the window clocks ride beside `error`. Without
864
878
  // them a spent Codex window reads as an unnamed in-stream failure:
865
879
  // floored to overload, then retried and walked across every backup
866
880
  // on the same account wall.
867
- throw streamError(id, event);
881
+ throw streamError(id, event, stream.headers);
868
882
  }
869
883
  }
870
884