@zenera/neo 1.1.9 → 1.1.11

package/dist/models/anthropic.d.ts

@@ -1,5 +1,6 @@
 import type Anthropic from '@anthropic-ai/sdk';
 import type { StreamDelta } from '../events.ts';
+import { type ProviderNamed } from '../failure.ts';
 import type { Model, ModelRequest, ModelResponse } from '../model.ts';
 /**
  * Provider-specific knobs.
@@ -9,7 +10,7 @@ import type { Model, ModelRequest, ModelResponse } from '../model.ts';
  * exist. 8192 is the largest value every current Claude model accepts, which
  * makes it the only safe default — raise it per model when you know better.
  */
-export interface AnthropicModelOptions {
+export interface AnthropicModelOptions extends ProviderNamed {
     /** hard cap on output tokens; required by the API, so it always has a value */
     maxTokens?: number;
     /**

package/dist/models/anthropic.js

@@ -1,3 +1,4 @@
+import { callSites, called, reading } from "../failure.js";
 import { zeroUsage, } from "../types.js";
 /** Every current Claude model accepts at least this many output tokens. */
 const DEFAULT_MAX_TOKENS = 8192;
@@ -16,9 +17,11 @@ export class AnthropicModel {
     #client;
     #maxTokens;
     #thinkingBudget;
+    #site;
     constructor(id, client, options = {}) {
         this.id = id;
         this.#client = client;
+        this.#site = callSites(id, options.provider);
         this.#thinkingBudget =
             options.thinkingBudgetTokens && options.thinkingBudgetTokens >= MIN_THINKING_BUDGET
                 ? options.thinkingBudgetTokens
@@ -28,7 +31,7 @@ export class AnthropicModel {
         this.#maxTokens = Math.max(options.maxTokens ?? DEFAULT_MAX_TOKENS, (this.#thinkingBudget ?? 0) + MIN_THINKING_BUDGET);
     }
     async generate(req) {
-        const res = await this.#client.messages.create(this.#params(req), { signal: req.signal });
+        const res = await called(this.#site('llm generation', 'messages.create'), () => this.#client.messages.create(this.#params(req), { signal: req.signal }));
         return {
             ...readBlocks(res.content),
             usage: toUsage(res.usage),
@@ -36,11 +39,15 @@ export class AnthropicModel {
         };
     }
     async stream(req, onDelta) {
-        const stream = this.#client.messages.stream(this.#params(req), { signal: req.signal });
+        const site = this.#site('llm streaming', 'messages.stream');
+        // Reassigned when a broken stream is reopened, so that `finalMessage()`
+        // below is asked of whichever stream actually delivered the answer.
+        let stream = this.#client.messages.stream(this.#params(req), { signal: req.signal });
+        const open = async () => (stream = this.#client.messages.stream(this.#params(req), { signal: req.signal }));
         // Blocks are addressed by index, and a tool call's id and name arrive in
         // its `content_block_start` while the arguments trickle in afterwards.
         const calls = new Map();
-        for await (const event of stream) {
+        for await (const event of reading(site, stream, open)) {
             if (event.type === 'content_block_start') {
                 const block = event.content_block;
                 if (block.type === 'tool_use') {
@@ -79,7 +86,7 @@ export class AnthropicModel {
         // The accumulated message is authoritative: it has the parsed tool
         // inputs and the final usage, so the deltas above are for the UI only
         // and nothing here depends on having reassembled them correctly.
-        const final = await stream.finalMessage();
+        const final = await called(site, () => stream.finalMessage());
         return {
             ...readBlocks(final.content),
             usage: toUsage(final.usage),

package/dist/models/factory.d.ts

@@ -64,6 +64,16 @@ export interface ProviderSpec extends Credentials {
     headers?: Record<string, string>;
     timeoutMs?: number;
     maxRetries?: number;
+    /**
+     * Ceiling on embedding requests in flight against this connection. The
+     * floor and the actual number are discovered from the provider's own
+     * refusals, so this only says how high the discovery may climb — set it
+     * when an account is shared with something else that also needs quota.
+     *
+     * On the provider rather than on a model because a rate limit belongs to
+     * the key: two embedders on one account are one budget, not two.
+     */
+    concurrency?: number;
     /**
      * Pre-built client — bypasses credential resolution entirely. The seam for
      * auth no configuration can express: Vertex service accounts, Bedrock
@@ -182,6 +192,11 @@ export declare class ModelRegistry {
     requirement(ref: ModelRef | EmbeddingRef): ModelRequirement;
     /** `[provider[/api]:]model` → spec. Exposed so a caller can validate a ref. */
     parse(ref: string): ModelSpec;
+    /**
+     * Splits `[provider:]model` into the spec it stands for, so a caller holding
+     * a shorthand can still set the knobs a shorthand has no room for.
+     */
+    parseEmbedding(ref: string): EmbeddingSpec;
     /** A declared kind wins; otherwise a built-in name is its own kind. */
     kindOf(name: string): ProviderKind;
 }

package/dist/models/factory.js

@@ -1,6 +1,7 @@
 import { readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { GeminiEmbedder } from "../embeddings/gemini.js";
+import { DEFAULT_START, RateLimiter } from "../embeddings/limiter.js";
 import { OpenAIEmbedder } from "../embeddings/openai.js";
 import { OpenRouterEmbedder } from "../embeddings/openrouter.js";
 import { AnthropicModel } from "./anthropic.js";
@@ -159,6 +160,7 @@ function expand(value, where) {
 export class ModelRegistry {
     #providers = new Map();
     #clients = new Map();
+    #limiters = new Map();
     #default = 'openai';
     /** Declares (or replaces) a provider. Nothing is contacted until it is used. */
     provider(name, spec = {}) {
@@ -170,6 +172,7 @@ export class ModelRegistry {
         // Re-declaring after a client was handed out would otherwise leave the
         // old credentials in service for the rest of the process.
         this.#clients.delete(name);
+        this.#limiters.delete(name);
         return this;
     }
     /** Names the provider a bare model id belongs to. */
@@ -201,6 +204,27 @@ export class ModelRegistry {
         this.#clients.set(name, built);
         return built;
     }
+    /**
+     * The pacing shared by every embedder on a provider, so that what one of
+     * them learns from a 429 the others do not have to learn again — and so
+     * that two of them cannot each ramp up to the full limit against one key.
+     */
+    #limiter(name) {
+        const existing = this.#limiters.get(name);
+        if (existing) {
+            return existing;
+        }
+        const spec = this.#providers.get(name);
+        const built = new RateLimiter({
+            max: spec?.concurrency,
+            start: spec?.concurrency === undefined
+                ? undefined
+                : Math.min(spec.concurrency, DEFAULT_START),
+            maxRetries: spec?.maxRetries,
+        });
+        this.#limiters.set(name, built);
+        return built;
+    }
     /** Turns a shorthand or a spec into a `Model`. */
     model(ref) {
         const spec = typeof ref === 'string' ? this.parse(ref) : ref;
@@ -213,6 +237,10 @@ export class ModelRegistry {
         // silently ignore them.
         const client = spec.client ??
             (hasCredentials(spec) ? buildClient(name, kind, spec, provider) : this.client(name));
+        // The *resolved* name, not `spec.provider`: a bare ref carries none,
+        // and a failure that cannot say which connection refused it is the
+        // thing this is here to prevent.
+        const options = { ...spec, provider: name };
         // Every protocol but OpenAI's has exactly one API, so naming one is a
         // mistake worth reporting rather than a field to ignore.
         if (defaults.protocol !== 'openai') {
@@ -221,11 +249,11 @@ export class ModelRegistry {
             }
             switch (defaults.protocol) {
                 case 'anthropic':
-                    return new AnthropicModel(spec.model, client, spec);
+                    return new AnthropicModel(spec.model, client, options);
                 case 'gemini':
-                    return new GeminiModel(spec.model, client, spec);
+                    return new GeminiModel(spec.model, client, options);
                 case 'openrouter':
-                    return new OpenRouterModel(spec.model, client, spec);
+                    return new OpenRouterModel(spec.model, client, options);
             }
         }
         const api = spec.api ?? defaults.apis[0];
@@ -234,8 +262,8 @@ export class ModelRegistry {
                 `(supported: ${defaults.apis.join(', ')})`);
         }
         return api === 'responses'
-            ? new OpenAIResponsesModel(spec.model, client, spec)
-            : new OpenAIModel(spec.model, client, spec);
+            ? new OpenAIResponsesModel(spec.model, client, options)
+            : new OpenAIModel(spec.model, client, options);
     }
     /**
      * Turns a shorthand or a spec into an `Embedder`, over the same providers
@@ -243,19 +271,26 @@ export class ModelRegistry {
      * generates and embeds without being mentioned twice.
      */
     embedder(ref) {
-        const spec = typeof ref === 'string' ? this.#parseEmbedding(ref) : ref;
+        const spec = typeof ref === 'string' ? this.parseEmbedding(ref) : ref;
         const name = spec.provider ?? this.#default;
         const provider = this.#spec(name);
         const kind = this.kindOf(name);
         const client = spec.client ??
             (hasCredentials(spec) ? buildClient(name, kind, spec, provider) : this.client(name));
+        // Inline credentials are a different connection, and so a different
+        // budget: they get pacing of their own rather than the provider's.
+        const options = {
+            ...spec,
+            provider: name,
+            limiter: spec.limiter ?? (hasCredentials(spec) ? undefined : this.#limiter(name)),
+        };
         switch (KINDS[kind].protocol) {
             case 'openai':
-                return new OpenAIEmbedder(spec.model, client, spec);
+                return new OpenAIEmbedder(spec.model, client, options);
             case 'gemini':
-                return new GeminiEmbedder(spec.model, client, spec);
+                return new GeminiEmbedder(spec.model, client, options);
             case 'openrouter':
-                return new OpenRouterEmbedder(spec.model, client, spec);
+                return new OpenRouterEmbedder(spec.model, client, options);
             case 'anthropic':
                 // Not an omission to be filled in later: Anthropic publishes no
                 // embeddings API at all, and points at third parties instead.
@@ -318,7 +353,11 @@ export class ModelRegistry {
         }
         return { provider, api, model };
     }
-    #parseEmbedding(ref) {
+    /**
+     * Splits `[provider:]model` into the spec it stands for, so a caller holding
+     * a shorthand can still set the knobs a shorthand has no room for.
+     */
+    parseEmbedding(ref) {
         const { provider, api, model } = this.parse(ref);
         if (api) {
             throw new TypeError(`"${ref}": embeddings have one api, so "${api}" means nothing here`);
@@ -342,6 +381,48 @@ export class ModelRegistry {
         return declared ?? (isProviderKind(name) ? name : 'openai');
     }
 }
+// ---------------------------------------------------------------------------
+// Retries
+// ---------------------------------------------------------------------------
+/**
+ * One backoff policy for every vendor, because a 429 is not a failure of the
+ * run — it is the provider asking to be called again later, and an agent that
+ * gives up on the first one loses the whole trajectory to a wait of a few
+ * seconds. Every SDK here can retry, but none of them agree on what happens
+ * when nothing is configured: the OpenAI and Anthropic clients retry twice,
+ * `@google/genai` does not retry *at all* unless `retryOptions` is present, and
+ * OpenRouter's generated client retries `5XX` only — so a Vertex or OpenRouter
+ * 429 was fatal by default. These constants are what make the four behave the
+ * same; `ProviderSpec.maxRetries` (0 disables) is the per-provider override.
+ *
+ * Retries live at the transport, not around `Model.generate`, so a retried call
+ * is one that never started: no partial stream is replayed, and a `Retry-After`
+ * header is honoured by the SDK that read it.
+ */
+const DEFAULT_MAX_RETRIES = 4;
+/** wait after the first failure; doubles per attempt up to `RETRY_MAX_MS` */
+const RETRY_INITIAL_MS = 1_000;
+const RETRY_MAX_MS = 60_000;
+const RETRY_EXPONENT = 2;
+function retriesOf(opts) {
+    return Math.max(0, opts.maxRetries ?? DEFAULT_MAX_RETRIES);
+}
+/**
+ * The same schedule expressed as a wall-clock budget, which is the only shape
+ * OpenRouter's client accepts. It is the sum of the waits a count of `retries`
+ * would spend, so the two agree on how long a hopeless call may take — not on
+ * exactly how many times it is made, since this budget also has to cover the
+ * requests themselves.
+ */
+function retryWindowMs(retries) {
+    let wait = RETRY_INITIAL_MS;
+    let total = 0;
+    for (let i = 0; i < retries; i++) {
+        total += Math.min(wait, RETRY_MAX_MS);
+        wait *= RETRY_EXPONENT;
+    }
+    return total;
+}
 /**
  * Credential resolution, in one place so a `${VAR}` reference behaves the same
  * whether it came from yaml or from application code. `creds` may be a model
@@ -375,7 +456,7 @@ function buildClient(name, kind, creds, opts) {
         baseURL,
         defaultHeaders: headers,
         timeout: opts.timeoutMs,
-        maxRetries: opts.maxRetries,
+        maxRetries: retriesOf(opts),
         ...(opts.token ? { fetch: bearerFetch(opts.token) } : {}),
     };
     if (defaults.protocol === 'anthropic') {
@@ -408,13 +489,25 @@ function buildOpenRouter(kind, apiKey, baseURL, headers, opts) {
         });
     }
     const { token } = opts;
+    const retries = retriesOf(opts);
     return new OpenRouter({
         apiKey: token ? async () => token() : apiKey,
         serverURL: baseURL,
         timeoutMs: opts.timeoutMs,
         // A count of zero is the one value that has to change shape: this SDK
         // says "do not retry" with a strategy, not with a number.
-        retryConfig: opts.maxRetries === 0 ? { strategy: 'none' } : undefined,
+        retryConfig: retries === 0
+            ? { strategy: 'none' }
+            : {
+                strategy: 'backoff',
+                backoff: {
+                    initialInterval: RETRY_INITIAL_MS,
+                    maxInterval: RETRY_MAX_MS,
+                    exponent: RETRY_EXPONENT,
+                    maxElapsedTime: retryWindowMs(retries),
+                },
+                retryConnectionErrors: true,
+            },
         httpClient,
     });
 }
@@ -438,7 +531,15 @@ function buildOpenRouter(kind, apiKey, baseURL, headers, opts) {
  */
 function buildGenAI(kind, apiKey, baseURL, headers, opts, where) {
     const { GoogleGenAI } = sdk('@google/genai', kind);
-    const httpOptions = { baseUrl: baseURL, headers, timeout: opts.timeoutMs };
+    // `attempts` counts the initial call, so a retry budget of zero is one
+    // attempt. Delays are fractions of a second here, unlike everywhere else.
+    const retryOptions = {
+        attempts: retriesOf(opts) + 1,
+        initialDelay: RETRY_INITIAL_MS / 1000,
+        maxDelay: RETRY_MAX_MS / 1000,
+        expBase: RETRY_EXPONENT,
+    };
+    const httpOptions = { baseUrl: baseURL, headers, timeout: opts.timeoutMs, retryOptions };
     if (kind !== 'vertex') {
         return new GoogleGenAI({ apiKey, httpOptions });
     }

package/dist/models/gemini.d.ts

@@ -1,5 +1,6 @@
 import type { GoogleGenAI } from '@google/genai';
 import type { StreamDelta } from '../events.ts';
+import { type ProviderNamed } from '../failure.ts';
 import type { Model, ModelRequest, ModelResponse } from '../model.ts';
 /** The coarse dial Gemini 3 takes in place of a token budget. */
 export type GeminiThinkingLevel = 'minimal' | 'low' | 'medium' | 'high';
@@ -11,7 +12,7 @@ export type GeminiThinkingLevel = 'minimal' | 'low' | 'medium' | 'high';
  * 3 takes a coarse `thinkingLevel`, and passing the wrong one is an API error
  * rather than something this adapter can paper over.
  */
-export interface GeminiModelOptions {
+export interface GeminiModelOptions extends ProviderNamed {
     /** hard cap on output tokens; the model's own default applies when unset */
     maxTokens?: number;
     /** 2.5-era budget, in tokens: `0` disables thinking, `-1` lets the model decide */

package/dist/models/gemini.js

@@ -1,3 +1,4 @@
+import { callSites, called, reading } from "../failure.js";
 import { zeroUsage, } from "../types.js";
 /**
  * Google's `ThinkingLevel` is a *string* enum, so its members are just their
@@ -40,14 +41,16 @@ export class GeminiModel {
     id;
     #client;
     #options;
+    #site;
     #nextId = 0;
     constructor(id, client, options = {}) {
         this.id = id;
         this.#client = client;
         this.#options = options;
+        this.#site = callSites(id, options.provider);
     }
     async generate(req) {
-        const res = await this.#client.models.generateContent(this.#params(req));
+        const res = await called(this.#site('llm generation', 'models.generateContent'), () => this.#client.models.generateContent(this.#params(req)));
         const read = emptyRead();
         for (const part of candidateParts(res)) {
             this.#readPart(part, read);
@@ -55,10 +58,12 @@ export class GeminiModel {
         return this.#finish(read, res);
     }
     async stream(req, onDelta) {
-        const stream = await this.#client.models.generateContentStream(this.#params(req));
+        const site = this.#site('llm streaming', 'models.generateContentStream');
+        const open = () => this.#client.models.generateContentStream(this.#params(req));
+        const stream = await called(site, open);
         const read = emptyRead();
         let last;
-        for await (const chunk of stream) {
+        for await (const chunk of reading(site, stream, open)) {
             last = chunk;
             for (const part of candidateParts(chunk)) {
                 this.#readPart(part, read, onDelta);

package/dist/models/openai-chat.d.ts

@@ -1,12 +1,13 @@
 import type OpenAI from 'openai';
 import type { StreamDelta } from '../events.ts';
+import { type ProviderNamed } from '../failure.ts';
 import type { Model, ModelRequest, ModelResponse } from '../model.ts';
 /**
  * Provider-specific knobs. Reasoning effort is deliberately *not* part of
  * `ModelRequest`: every provider spells it differently (and most models ignore
  * it), so it belongs to the concrete adapter rather than the `Model` contract.
  */
-export interface OpenAIModelOptions {
+export interface OpenAIModelOptions extends ProviderNamed {
     reasoningEffort?: OpenAI.ReasoningEffort;
 }
 export declare class OpenAIModel implements Model {

package/dist/models/openai-chat.js

@@ -1,5 +1,8 @@
 var _a;
+import { callSites, called, reading } from "../failure.js";
 import { zeroUsage } from "../types.js";
+/** The SDK call these methods make, named as it is named in a failure. */
+const API = 'chat.completions.create';
 // ---------------------------------------------------------------------------
 // OpenAI chat-completions adapter
 // ---------------------------------------------------------------------------
@@ -20,15 +23,15 @@ export class OpenAIModel {
     id;
     #client;
     #reasoningEffort;
+    #site;
     constructor(id, client, options = {}) {
         this.id = id;
         this.#client = client;
         this.#reasoningEffort = options.reasoningEffort;
+        this.#site = callSites(id, options.provider);
     }
     async generate(req) {
-        const res = await this.#client.chat.completions.create(this.#params(req), {
-            signal: req.signal,
-        });
+        const res = await called(this.#site('llm generation', API), () => this.#client.chat.completions.create(this.#params(req), { signal: req.signal }));
         const choice = res.choices[0];
         const message = choice?.message;
         return {
@@ -42,7 +45,9 @@ export class OpenAIModel {
         };
     }
     async stream(req, onDelta) {
-        const stream = await this.#client.chat.completions.create({ ...this.#params(req), stream: true, stream_options: { include_usage: true } }, { signal: req.signal });
+        const site = this.#site('llm streaming', API);
+        const open = () => this.#client.chat.completions.create({ ...this.#params(req), stream: true, stream_options: { include_usage: true } }, { signal: req.signal });
+        const stream = await called(site, open);
         let text = '';
         let thinking = '';
         let usage;
@@ -50,7 +55,7 @@ export class OpenAIModel {
         // Tool calls arrive as deltas keyed by index, with the id and name in the
         // first fragment and arguments trickling in afterwards.
         const calls = new Map();
-        for await (const chunk of stream) {
+        for await (const chunk of reading(site, stream, open)) {
             if (chunk.usage) {
                 usage = toUsage(chunk.usage);
             }

package/dist/models/openai-responses.d.ts

@@ -1,11 +1,12 @@
 import type OpenAI from 'openai';
 import type { StreamDelta } from '../events.ts';
+import { type ProviderNamed } from '../failure.ts';
 import type { Model, ModelRequest, ModelResponse } from '../model.ts';
 /**
  * Provider-specific knobs, mirroring `OpenAIModelOptions` but expressed the way
  * the responses API spells them.
  */
-export interface OpenAIResponsesModelOptions {
+export interface OpenAIResponsesModelOptions extends ProviderNamed {
     reasoningEffort?: OpenAI.ReasoningEffort;
     /** ask the model for a reasoning summary — the only reasoning text this API exposes */
     reasoningSummary?: 'auto' | 'concise' | 'detailed';

package/dist/models/openai-responses.js

@@ -1,5 +1,8 @@
 var _a;
+import { callSites, called, failed, reading, } from "../failure.js";
 import { zeroUsage } from "../types.js";
+/** The SDK call these methods make, named as it is named in a failure. */
+const API = 'responses.create';
 /**
  * Same `Model` contract as `OpenAIModel`, over `/v1/responses` instead of
  * `/v1/chat/completions`. Reasoning models are the reason to prefer it: effort
@@ -11,17 +14,17 @@ export class OpenAIResponsesModel {
     #reasoningEffort;
     #reasoningSummary;
     #store;
+    #site;
     constructor(id, client, options = {}) {
         this.id = id;
         this.#client = client;
         this.#reasoningEffort = options.reasoningEffort;
         this.#reasoningSummary = options.reasoningSummary;
         this.#store = options.store ?? false;
+        this.#site = callSites(id, options.provider);
     }
     async generate(req) {
-        const res = await this.#client.responses.create(this.#params(req), {
-            signal: req.signal,
-        });
+        const res = await called(this.#site('llm generation', API), () => this.#client.responses.create(this.#params(req), { signal: req.signal }));
         const toolCalls = readToolCalls(res.output);
         return {
             text: readText(res.output),
@@ -32,7 +35,11 @@ export class OpenAIResponsesModel {
         };
     }
     async stream(req, onDelta) {
-        const stream = await this.#client.responses.create({ ...this.#params(req), stream: true }, { signal: req.signal });
+        const site = this.#site('llm streaming', API);
+        const open = () => this.#client.responses.create({ ...this.#params(req), stream: true }, {
+            signal: req.signal,
+        });
+        const stream = await called(site, open);
         let text = '';
         let thinking = '';
         let final;
@@ -40,7 +47,7 @@ export class OpenAIResponsesModel {
         // every delta event carries — that is the only stable key while the
         // items are still being assembled.
         const calls = new Map();
-        for await (const event of stream) {
+        for await (const event of reading(site, stream, open)) {
             // Some models/gateways emit `response.reasoning.delta`, which the
             // SDK does not carry in its event union, so it is matched before
             // the typed switch.
@@ -103,9 +110,17 @@ export class OpenAIResponsesModel {
                     }
                     break;
                 }
-                case 'response.completed':
-                case 'response.incomplete':
                 case 'response.failed': {
+                    // The request was accepted, so the refusal arrives as an
+                    // event in a 200 rather than as a status. Returning it as a
+                    // response would make it an empty answer.
+                    const said = event.response.error;
+                    throw failed(site, Object.assign(new Error(said?.message ?? 'the response failed'), {
+                        code: said?.code,
+                    }));
+                }
+                case 'response.completed':
+                case 'response.incomplete': {
                     final = event.response;
                     break;
                 }

package/dist/models/openrouter.d.ts

@@ -1,7 +1,18 @@
 import type { OpenRouter } from '@openrouter/sdk';
 import type { ChatRequestPlugin, ProviderPreferences } from '@openrouter/sdk/models';
 import type { StreamDelta } from '../events.ts';
+import { type ProviderNamed } from '../failure.ts';
 import type { Model, ModelRequest, ModelResponse } from '../model.ts';
+/**
+ * Which failures the SDK's backoff applies to: rate limits, request timeouts,
+ * and the upstream's own errors. Families are written `5XX` in this matcher.
+ *
+ * It has to be passed per call. The generated client resolves `retryCodes` at
+ * the *operation*, defaulting it to `5XX` alone, and no client-wide option
+ * reaches it — so configuring a retry policy and leaving this out gives a
+ * client that backs off diligently on 500s and dies on the first 429.
+ */
+export declare const RETRY_STATUS_CODES: string[];
 /**
  * Effort levels, spelled out rather than imported: the SDK's is an *open* enum
  * (its literals plus any string), which would let a typo through, and naming
@@ -11,7 +22,7 @@ import type { Model, ModelRequest, ModelResponse } from '../model.ts';
  */
 export type OpenRouterEffort = 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | null;
 /** Provider-specific knobs. */
-export interface OpenRouterModelOptions {
+export interface OpenRouterModelOptions extends ProviderNamed {
     reasoningEffort?: OpenRouterEffort;
     /** ask for a reasoning summary from models that expose one */
     reasoningSummary?: 'auto' | 'concise' | 'detailed';

package/dist/models/openrouter.js

@@ -1,5 +1,32 @@
 var _a;
+import { callSites, called, reading } from "../failure.js";
 import { zeroUsage } from "../types.js";
+// ---------------------------------------------------------------------------
+// OpenRouter adapter
+//
+// Not the chat-completions adapter pointed at another base url. OpenRouter's
+// own SDK is a different wire contract in TypeScript terms — camelCase fields
+// remapped to snake_case on the way out, a response union that covers both
+// streaming and not, assistant content that may arrive as an array — so it
+// gets its own adapter rather than a widened `OpenAIModel`.
+//
+// What that buys is the part of OpenRouter the OpenAI client cannot express:
+// provider routing, a model fallback chain, and per-call cost. What it costs
+// is that responses are zod-parsed on the way in, so a provider returning a
+// shape the schema does not know raises `ResponseValidationError` where the
+// OpenAI client would have shrugged. `kind: openai-compatible` against the
+// same base url remains the way back if that ever bites.
+// ---------------------------------------------------------------------------
+/**
+ * Which failures the SDK's backoff applies to: rate limits, request timeouts,
+ * and the upstream's own errors. Families are written `5XX` in this matcher.
+ *
+ * It has to be passed per call. The generated client resolves `retryCodes` at
+ * the *operation*, defaulting it to `5XX` alone, and no client-wide option
+ * reaches it — so configuring a retry policy and leaving this out gives a
+ * client that backs off diligently on 500s and dies on the first 429.
+ */
+export const RETRY_STATUS_CODES = ['408', '429', '5XX'];
 function toStopReason(finish) {
     switch (finish) {
         case 'tool_calls':
@@ -46,13 +73,15 @@ export class OpenRouterModel {
     id;
     #client;
     #options;
+    #site;
     constructor(id, client, options = {}) {
         this.id = id;
         this.#client = client;
         this.#options = options;
+        this.#site = callSites(id, options.provider);
     }
     async generate(req) {
-        const res = await this.#send(req, false);
+        const res = await called(this.#site('llm generation', 'chat.send'), () => this.#send(req, false));
         // Both overloads are declared to return the same union, so the narrowing
         // the `stream` flag implies has to be done here.
         if (Symbol.asyncIterator in res) {
@@ -73,10 +102,15 @@ export class OpenRouterModel {
         };
     }
     async stream(req, onDelta) {
-        const res = await this.#send(req, true);
-        if (!(Symbol.asyncIterator in res)) {
-            throw new Error(`model "${this.id}": asked for a stream, got one completion`);
-        }
+        const site = this.#site('llm streaming', 'chat.send');
+        const open = async () => {
+            const res = await this.#send(req, true);
+            if (!(Symbol.asyncIterator in res)) {
+                throw new Error(`model "${this.id}": asked for a stream, got one completion`);
+            }
+            return res;
+        };
+        const res = await called(site, open);
         let text = '';
         let thinking = '';
         let usage;
@@ -84,7 +118,7 @@ export class OpenRouterModel {
         // Tool calls arrive as deltas keyed by index, with the id and name in the
         // first fragment and arguments trickling in afterwards.
         const calls = new Map();
-        for await (const chunk of res) {
+        for await (const chunk of reading(site, res, open)) {
             // An upstream failure mid-stream arrives as a chunk on a 200, so it
             // has to be raised here or the turn ends early and looks complete.
             if (chunk.error) {
@@ -154,7 +188,7 @@ export class OpenRouterModel {
      * SDK keeps transport concerns out of the body it validates.
      */
     #send(req, stream) {
-        return this.#client.chat.send({ chatRequest: this.#request(req, stream) }, { fetchOptions: { signal: req.signal } });
+        return this.#client.chat.send({ chatRequest: this.#request(req, stream) }, { fetchOptions: { signal: req.signal }, retryCodes: RETRY_STATUS_CODES });
     }
     #request(req, stream) {
         const o = this.#options;