@agentionai/agents 1.7.0-beta.0 → 1.8.0

package/README.md

@@ -27,6 +27,7 @@ Get an API key from your chosen provider:
 - **OpenAI**: [platform.openai.com](https://platform.openai.com/api-keys)
 - **Gemini**: [aistudio.google.com](https://aistudio.google.com/app/apikey)
 - **Mistral**: [console.mistral.ai](https://console.mistral.ai/)
+- **OpenRouter**: [openrouter.ai/keys](https://openrouter.ai/keys) — one key, dozens of upstream providers
 - **Ollama** / **llama.cpp**: no API key needed — run models locally (see [Agents guide](https://docs.agention.ai/guide/agents))
 
 Set it as an environment variable:
@@ -62,6 +63,7 @@ import { ClaudeAgent } from '@agentionai/agents/claude';     // Requires @anthro
 import { OpenAiAgent } from '@agentionai/agents/openai';     // Requires openai
 import { GeminiAgent } from '@agentionai/agents/gemini';     // Requires @google/generative-ai
 import { MistralAgent } from '@agentionai/agents/mistral';   // Requires @mistralai/mistralai
+import { OpenRouterAgent } from '@agentionai/agents/openrouter'; // Requires @openrouter/sdk
 import { OllamaAgent } from '@agentionai/agents/ollama';     // Requires ollama (local, no API key)
 import { LlamaCppAgent } from '@agentionai/agents/llamacpp'; // Requires openai (local, no API key)
 ```
@@ -75,9 +77,9 @@ import { ClaudeAgent, OpenAiAgent } from '@agentionai/agents';
 
 ## Features
 
-- **Multi-Provider, No Lock-in** - Claude, OpenAI, Gemini, Mistral, plus local models via Ollama and llama.cpp—same interface. Switch models with one line. `listModels()` asks any provider what it currently offers, in one shared shape.
+- **Multi-Provider, No Lock-in** - Claude, OpenAI, Gemini, Mistral, OpenRouter (one key, dozens of upstream providers), plus local models via Ollama and llama.cpp—same interface. Switch models with one line. `listModels()` asks any provider what it currently offers, in one shared shape.
 - **Composable Context Management** - Tool result masking (lossless, free) + rolling summarization (auto-firing) + sub-agent delegation (token isolation by architecture).
-- **Streaming** - `executeStream()` on Claude, OpenAI, and all OpenAI-compatible agents. Yields `{ type: "text" | "reasoning" }` chunks; tool calls handled transparently.
+- **Streaming** - `executeStream()` on Claude, OpenAI, OpenRouter, and all OpenAI-compatible agents. Yields `{ type: "text" | "reasoning" }` chunks; tool calls handled transparently.
 - **Built-In Tools** - Use provider-defined server-side tools (e.g. Anthropic's web search, bash, text editor) alongside your own.
 - **Composable, Not Magical** - Agents are objects. Pipelines are arrays. No hidden state, no surprises.
 - **Multimodal / Vision** - Send images alongside text with a unified `MessageContent[]` API across all providers.

package/dist/agents/Agent.d.ts

@@ -6,6 +6,8 @@ import { GeminiAgent } from "./google/GeminiAgent";
 import { MistralAgent } from "./mistral/MistralAgent";
 import { OllamaAgent } from "./ollama/OllamaAgent";
 import { LlamaCppAgent } from "./llamacpp/LlamaCppAgent";
+import { OpenRouterAgent } from "./openrouter/OpenRouterAgent";
+import type { OpenRouterSpecificConfig } from "./AgentConfig";
 import { ClaudeModel, OpenAIModel, GeminiModel, MistralModel, OllamaModel, LlamaCppModel } from "./model-types";
 type ClaudeAgentConfig = Omit<BaseAgentConfig, "vendor" | "model"> & {
     vendor: "anthropic";
@@ -33,9 +35,14 @@ type LlamaCppAgentConfig = Omit<BaseAgentConfig, "vendor" | "model"> & {
     model?: LlamaCppModel;
     baseURL?: string;
 };
-type AgentConfig = ClaudeAgentConfig | OpenAIAgentConfig | GeminiAgentConfig | MistralAgentConfig | OllamaAgentConfig | LlamaCppAgentConfig;
+type OpenRouterAgentConfig = Omit<BaseAgentConfig, "vendor" | "model"> & OpenRouterSpecificConfig & {
+    vendor: "openrouter";
+    model?: string;
+    baseURL?: string;
+};
+type AgentConfig = ClaudeAgentConfig | OpenAIAgentConfig | GeminiAgentConfig | MistralAgentConfig | OllamaAgentConfig | LlamaCppAgentConfig | OpenRouterAgentConfig;
 export declare class Agent {
-    static create(config: AgentConfig, history?: History): ClaudeAgent | GeminiAgent | MistralAgent | OllamaAgent | LlamaCppAgent | OpenAiAgent<(string & {}) | "gpt-5-pro" | "gpt-5.2-pro" | "gpt-5.4-pro" | "gpt-5.5-pro" | "o1" | "o1-pro" | "o3" | "o3-mini" | "o4-mini" | "gpt-5" | "gpt-5-mini" | "gpt-5-nano" | "gpt-5.1" | "gpt-5.2" | "gpt-5.4" | "gpt-5.4-mini" | "gpt-5.4-nano" | "gpt-5.5" | "gpt-5.6" | "gpt-5.6-sol" | "gpt-5.6-terra" | "gpt-5.6-luna" | "gpt-4.1" | "gpt-4.1-mini" | "gpt-4.1-nano" | "gpt-4o" | "gpt-4o-mini" | "gpt-4o-2024-11-20" | "gpt-4o-2024-08-06" | "gpt-4o-2024-05-13" | "gpt-4o-mini-2024-07-18" | "gpt-4-turbo" | "gpt-4-turbo-2024-04-09" | "gpt-4-turbo-preview" | "gpt-4-0125-preview" | "gpt-4-1106-preview" | "gpt-4" | "gpt-4-0613" | "gpt-3.5-turbo" | "gpt-3.5-turbo-0125" | "gpt-3.5-turbo-1106" | "o1-preview" | "o1-mini">;
+    static create(config: AgentConfig, history?: History): ClaudeAgent | GeminiAgent | MistralAgent | OllamaAgent | LlamaCppAgent | OpenRouterAgent | OpenAiAgent<(string & {}) | "gpt-5-pro" | "gpt-5.2-pro" | "gpt-5.4-pro" | "gpt-5.5-pro" | "o1" | "o1-pro" | "o3" | "o3-mini" | "o4-mini" | "gpt-5" | "gpt-5-mini" | "gpt-5-nano" | "gpt-5.1" | "gpt-5.2" | "gpt-5.4" | "gpt-5.4-mini" | "gpt-5.4-nano" | "gpt-5.5" | "gpt-5.6" | "gpt-5.6-sol" | "gpt-5.6-terra" | "gpt-5.6-luna" | "gpt-4.1" | "gpt-4.1-mini" | "gpt-4.1-nano" | "gpt-4o" | "gpt-4o-mini" | "gpt-4o-2024-11-20" | "gpt-4o-2024-08-06" | "gpt-4o-2024-05-13" | "gpt-4o-mini-2024-07-18" | "gpt-4-turbo" | "gpt-4-turbo-2024-04-09" | "gpt-4-turbo-preview" | "gpt-4-0125-preview" | "gpt-4-1106-preview" | "gpt-4" | "gpt-4-0613" | "gpt-3.5-turbo" | "gpt-3.5-turbo-0125" | "gpt-3.5-turbo-1106" | "o1-preview" | "o1-mini">;
 }
 export {};
 //# sourceMappingURL=Agent.d.ts.map

package/dist/agents/Agent.js

@@ -7,6 +7,7 @@ const GeminiAgent_1 = require("./google/GeminiAgent");
 const MistralAgent_1 = require("./mistral/MistralAgent");
 const OllamaAgent_1 = require("./ollama/OllamaAgent");
 const LlamaCppAgent_1 = require("./llamacpp/LlamaCppAgent");
+const OpenRouterAgent_1 = require("./openrouter/OpenRouterAgent");
 class Agent {
     static create(config, history) {
         if (config.vendor === "anthropic") {
@@ -27,6 +28,9 @@ class Agent {
         else if (config.vendor === "llamacpp") {
             return new LlamaCppAgent_1.LlamaCppAgent(config, history);
         }
+        else if (config.vendor === "openrouter") {
+            return new OpenRouterAgent_1.OpenRouterAgent(config, history);
+        }
         else {
             throw new Error("No vendor defined");
         }

package/dist/agents/AgentConfig.d.ts

@@ -2,8 +2,9 @@ import { Tool } from "../tools/Tool";
 import { BuiltInTool } from "../tools/BuiltInTool";
 import { BaseAgent } from "./BaseAgent";
 import type { ReasoningEffort } from "./model-types";
+import type { OpenRouterProviderPreferences, OpenRouterReasoningConfig, OpenRouterRetryConfig } from "./openrouter/types";
 /** Supported LLM vendors */
-export type AgentVendor = "openai" | "anthropic" | "mistral" | "gemini" | "ollama" | "llamacpp";
+export type AgentVendor = "openai" | "anthropic" | "mistral" | "gemini" | "ollama" | "llamacpp" | "openrouter";
 /**
  * Common configuration shared by all agents
  */
@@ -163,6 +164,76 @@ export interface LlamaCppSpecificConfig {
     /** Base URL of the llama.cpp server's OpenAI-compatible API (default: `http://localhost:8080/v1`) */
     baseURL?: string;
 }
+/** Vendor-specific configuration for Cerebras */
+export interface CerebrasSpecificConfig {
+    /** Cerebras OpenAI-compatible API base URL. */
+    baseURL?: string;
+}
+/**
+ * Vendor-specific configuration for OpenRouter
+ *
+ * @see https://openrouter.ai/docs/api-reference/chat/send-a-chat-completion-request
+ */
+export interface OpenRouterSpecificConfig {
+    /**
+     * Fallback models, tried in order when the primary `model` cannot serve the
+     * request — including when it is rate limited.
+     *
+     * This is the one throttling mitigation that works against a `:free` model's
+     * daily quota, which no amount of client-side backoff will wait out. Put a
+     * paid model last if you want the run to finish regardless.
+     *
+     * @example
+     * ```typescript
+     * model: "deepseek/deepseek-chat-v3:free",
+     * vendorConfig: { openrouter: { models: ["qwen/qwen3-235b-a22b", "openai/gpt-5.6"] } }
+     * ```
+     */
+    models?: string[];
+    /** Where OpenRouter may route the request. */
+    provider?: OpenRouterProviderPreferences;
+    /**
+     * Retry policy for the chat request.
+     *
+     * Overriding the SDK's own default is deliberate. `@openrouter/sdk` retries
+     * only `5XX` on this endpoint, so a 429 fails on the first response even
+     * though its backoff already knows how to honour `Retry-After`; and its
+     * default `maxElapsedTime` is an hour. The agent instead retries
+     * `429`/`408`/`409`/`5XX` with a two-minute ceiling. Pass
+     * `{ strategy: "none" }` to opt out entirely and handle 429s yourself.
+     */
+    retry?: OpenRouterRetryConfig;
+    /**
+     * HTTP status codes the retry policy applies to. Accepts exact codes
+     * (`"429"`) and families (`"5XX"`). Defaults to
+     * `["408", "409", "429", "5XX"]`.
+     */
+    retryCodes?: string[];
+    /** Reasoning configuration for models that support it. */
+    reasoning?: OpenRouterReasoningConfig;
+    /**
+     * OpenRouter plugins to enable — web search, file parsing, context
+     * compression, moderation. Passed through untouched; see
+     * https://openrouter.ai/docs/guides/features/plugins for the shapes.
+     */
+    plugins?: unknown[];
+    /**
+     * Sticky routing key. Requests sharing one are pinned to the same upstream
+     * provider, which is what makes prompt caching hit across a conversation.
+     * Also groups the requests in OpenRouter's observability views.
+     */
+    sessionId?: string;
+    /** Stable per-end-user identifier used for abuse isolation. Never forwarded raw. */
+    user?: string;
+    /** Processing tier; `"fast"` is an accepted alias for `"priority"`. */
+    serviceTier?: string;
+    /** Sent as `HTTP-Referer` — how OpenRouter attributes traffic to your app. */
+    httpReferer?: string;
+    /** Sent as `X-Title` — the app name shown on OpenRouter's leaderboards. */
+    appTitle?: string;
+    /** Disable parallel tool calling (sends `parallel_tool_calls: false`). */
+    disableParallelToolUse?: boolean;
+}
 /**
  * Generic vendor-specific configuration container
  * This allows any vendor to add custom config without modifying base types
@@ -174,6 +245,7 @@ export interface VendorSpecificConfig {
     gemini?: GeminiSpecificConfig;
     ollama?: OllamaSpecificConfig;
     llamacpp?: LlamaCppSpecificConfig;
+    openrouter?: OpenRouterSpecificConfig;
 }
 /**
  * Complete agent configuration with vendor-specific extensions
@@ -217,10 +289,12 @@ export type TypedAgentConfig<V extends AgentVendor> = CommonAgentConfig & {
         ollama?: OllamaSpecificConfig;
     } : V extends "llamacpp" ? {
         llamacpp?: LlamaCppSpecificConfig;
+    } : V extends "openrouter" ? {
+        openrouter?: OpenRouterSpecificConfig;
     } : never;
 };
 /**
  * Helper type to extract vendor-specific config for a given vendor
  */
-export type VendorConfigFor<V extends AgentVendor> = V extends "anthropic" ? ClaudeSpecificConfig : V extends "openai" ? OpenAISpecificConfig : V extends "mistral" ? MistralSpecificConfig : V extends "gemini" ? GeminiSpecificConfig : V extends "ollama" ? OllamaSpecificConfig : V extends "llamacpp" ? LlamaCppSpecificConfig : never;
+export type VendorConfigFor<V extends AgentVendor> = V extends "anthropic" ? ClaudeSpecificConfig : V extends "openai" ? OpenAISpecificConfig : V extends "mistral" ? MistralSpecificConfig : V extends "gemini" ? GeminiSpecificConfig : V extends "ollama" ? OllamaSpecificConfig : V extends "llamacpp" ? LlamaCppSpecificConfig : V extends "openrouter" ? OpenRouterSpecificConfig : never;
 //# sourceMappingURL=AgentConfig.d.ts.map

package/dist/agents/anthropic/ClaudeAgent.js

@@ -217,7 +217,7 @@ class ClaudeAgent extends BaseAgent_1.BaseAgent {
         // Store token usage for metrics tracking
         const usage = this.accumulateUsage(this.parseUsage(response.usage));
         if (response.stop_reason === "max_tokens") {
-            const error = new AgentError_1.MaxTokensExceededError("Response exceeded maximum token limit", this.config.maxTokens || 1024);
+            const error = new AgentError_1.MaxTokensExceededError("Response exceeded maximum token limit", this.config.maxTokens);
             this.emit(AgentEvent_1.AgentEvent.MAX_TOKENS_EXCEEDED, error);
             this.emit(AgentEvent_1.AgentEvent.ERROR, error);
             // Report error to viz
@@ -510,7 +510,7 @@ class ClaudeAgent extends BaseAgent_1.BaseAgent {
         // Checked after accumulateUsage() so the tokens already spent are reported.
         (0, cancellation_1.throwIfAborted)(options?.signal, `Execution of agent ${this.getName()}`);
         if (stopReason === "max_tokens") {
-            const error = new AgentError_1.MaxTokensExceededError("Response exceeded maximum token limit", this.config.maxTokens || 1024);
+            const error = new AgentError_1.MaxTokensExceededError("Response exceeded maximum token limit", this.config.maxTokens);
             this.emit(AgentEvent_1.AgentEvent.MAX_TOKENS_EXCEEDED, error);
             this.emit(AgentEvent_1.AgentEvent.ERROR, error);
             if (this.vizEventId) {

package/dist/agents/errors/AgentError.d.ts

@@ -22,12 +22,44 @@ export declare class ApiError extends AgentError {
     response?: any | undefined;
     constructor(message: string, statusCode?: number | undefined, response?: any | undefined);
 }
+/**
+ * Error thrown when the provider rate limits a request and the agent's retry
+ * policy did not manage to get past it.
+ *
+ * Extends {@link ApiError}, so existing `catch (e) { if (e instanceof ApiError) }`
+ * handling keeps working; the extra fields carry what the provider said about
+ * when to come back.
+ */
+export declare class RateLimitError extends ApiError {
+    retryAfterMs?: number | undefined;
+    limit?: number | undefined;
+    remaining?: number | undefined;
+    resetAt?: Date | undefined;
+    /**
+     * @param message      Error message
+     * @param retryAfterMs How long the provider asked you to wait, in
+     *                     milliseconds, from its `Retry-After` header. Undefined
+     *                     when it sent no hint.
+     * @param limit        Requests permitted in the window (`X-RateLimit-Limit`).
+     * @param remaining    Requests left in the window (`X-RateLimit-Remaining`).
+     * @param resetAt      When the window resets (`X-RateLimit-Reset`).
+     * @param response     The underlying provider error.
+     */
+    constructor(message: string, retryAfterMs?: number | undefined, limit?: number | undefined, remaining?: number | undefined, resetAt?: Date | undefined, response?: unknown);
+}
 /**
  * Error thrown when maximum token limit is exceeded
  */
 export declare class MaxTokensExceededError extends AgentError {
-    tokenLimit: number;
-    constructor(message: string, tokenLimit: number);
+    tokenLimit?: number | undefined;
+    /**
+     * @param message    Error message
+     * @param tokenLimit The configured `maxTokens` that was hit. Undefined when
+     *                   no limit was configured and the model's own output cap
+     *                   is what ended the response — reporting a number the
+     *                   caller never set would just be misleading.
+     */
+    constructor(message: string, tokenLimit?: number | undefined);
 }
 /**
  * Error thrown when maximum retries are exceeded

package/dist/agents/errors/AgentError.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ToolExecutionError = exports.AbortError = exports.MaxRetriesExceededError = exports.MaxTokensExceededError = exports.ApiError = exports.ExecutionError = exports.AgentError = void 0;
+exports.ToolExecutionError = exports.AbortError = exports.MaxRetriesExceededError = exports.MaxTokensExceededError = exports.RateLimitError = exports.ApiError = exports.ExecutionError = exports.AgentError = void 0;
 /**
  * Base error class for all agent-related errors
  */
@@ -37,10 +37,46 @@ class ApiError extends AgentError {
     }
 }
 exports.ApiError = ApiError;
+/**
+ * Error thrown when the provider rate limits a request and the agent's retry
+ * policy did not manage to get past it.
+ *
+ * Extends {@link ApiError}, so existing `catch (e) { if (e instanceof ApiError) }`
+ * handling keeps working; the extra fields carry what the provider said about
+ * when to come back.
+ */
+class RateLimitError extends ApiError {
+    /**
+     * @param message      Error message
+     * @param retryAfterMs How long the provider asked you to wait, in
+     *                     milliseconds, from its `Retry-After` header. Undefined
+     *                     when it sent no hint.
+     * @param limit        Requests permitted in the window (`X-RateLimit-Limit`).
+     * @param remaining    Requests left in the window (`X-RateLimit-Remaining`).
+     * @param resetAt      When the window resets (`X-RateLimit-Reset`).
+     * @param response     The underlying provider error.
+     */
+    constructor(message, retryAfterMs, limit, remaining, resetAt, response) {
+        super(message, 429, response);
+        this.retryAfterMs = retryAfterMs;
+        this.limit = limit;
+        this.remaining = remaining;
+        this.resetAt = resetAt;
+        this.name = "RateLimitError";
+    }
+}
+exports.RateLimitError = RateLimitError;
 /**
  * Error thrown when maximum token limit is exceeded
  */
 class MaxTokensExceededError extends AgentError {
+    /**
+     * @param message    Error message
+     * @param tokenLimit The configured `maxTokens` that was hit. Undefined when
+     *                   no limit was configured and the model's own output cap
+     *                   is what ended the response — reporting a number the
+     *                   caller never set would just be misleading.
+     */
     constructor(message, tokenLimit) {
         super(message);
         this.tokenLimit = tokenLimit;

package/dist/agents/google/GeminiAgent.js

@@ -67,7 +67,12 @@ class GeminiAgent extends BaseAgent_1.BaseAgent {
         const responseSchema = config.responseSchema ?? vendorConfig.responseSchema;
         this.config = {
             model: config.model || "gemini-flash-latest",
-            maxTokens: config.maxTokens || 1024,
+            // No default: `maxOutputTokens` is optional on Gemini, and omitting it
+            // lets the model use its full output budget. A default here silently
+            // truncated every response — and on thinking models it was worse, since
+            // thoughts count against the same budget and a small cap could be spent
+            // entirely on them.
+            maxTokens: config.maxTokens,
             apiKey: config.apiKey,
             temperature: config.temperature,
             topP: config.topP,
@@ -355,7 +360,7 @@ class GeminiAgent extends BaseAgent_1.BaseAgent {
             throw error;
         }
         if (candidate.finishReason === "MAX_TOKENS") {
-            const error = new AgentError_1.MaxTokensExceededError("Response exceeded maximum token limit", this.config.maxTokens || 1024);
+            const error = new AgentError_1.MaxTokensExceededError("Response exceeded maximum token limit", this.config.maxTokens);
             this.emit(AgentEvent_1.AgentEvent.MAX_TOKENS_EXCEEDED, error);
             this.emit(AgentEvent_1.AgentEvent.ERROR, error);
             // Report error to viz

package/dist/agents/mistral/MistralAgent.js

@@ -68,7 +68,10 @@ class MistralAgent extends BaseAgent_1.BaseAgent {
         const rateLimitDelay = config.rateLimitDelay ?? vendorConfig.rateLimitDelay ?? 1500;
         this.config = {
             model: config.model || "mistral-small-latest",
-            maxTokens: config.maxTokens || 1024,
+            // No default: `maxTokens` is optional on Mistral's API, and omitting it
+            // lets the model use its full output budget. A default here silently
+            // truncated every response.
+            maxTokens: config.maxTokens,
             disableParallelToolUse,
             safePrompt,
             randomSeed,
@@ -219,7 +222,7 @@ class MistralAgent extends BaseAgent_1.BaseAgent {
         // Track token usage
         const usage = this.accumulateUsage(this.parseUsage(response.usage));
         if (choice.finishReason === "length") {
-            const error = new AgentError_1.MaxTokensExceededError("Response exceeded maximum token limit", this.config.maxTokens || 1024);
+            const error = new AgentError_1.MaxTokensExceededError("Response exceeded maximum token limit", this.config.maxTokens);
             this.emit(AgentEvent_1.AgentEvent.MAX_TOKENS_EXCEEDED, error);
             this.emit(AgentEvent_1.AgentEvent.ERROR, error);
             // Report error to viz

package/dist/agents/openai/OpenAiAgent.js

@@ -73,7 +73,13 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
         const user = config.user ?? vendorConfig.user;
         this.config = {
             model: config.model || "gpt-4.1-mini",
-            maxTokens: config.maxTokens || 1024,
+            // No default. `max_output_tokens` is optional on the Responses API, and
+            // omitting it lets the model use its full output budget. A default here
+            // silently truncated every response — and on reasoning models it was
+            // worse than a truncation, since reasoning tokens count against the same
+            // budget: a small cap could be spent entirely on thinking, returning
+            // `status: "incomplete"` with no text at all.
+            maxTokens: config.maxTokens,
             disableParallelToolUse,
             disableReasoning,
             reasoningEffort,
@@ -532,7 +538,7 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
                 }
             }
             if (event.type === "response.incomplete") {
-                throw new AgentError_1.MaxTokensExceededError("Response incomplete: max tokens reached", this.config.maxTokens || 1024);
+                throw new AgentError_1.MaxTokensExceededError("Response incomplete: max tokens reached", this.config.maxTokens);
             }
         }
         // The SDK's stream iterator swallows the abort and simply stops yielding.

package/dist/agents/openai-compatible/OpenAICompatibleAgent.js

@@ -172,7 +172,7 @@ class OpenAICompatibleAgent extends BaseAgent_1.BaseAgent {
         const choice = response.choices[0];
         const message = choice.message;
         if (choice.finish_reason === "length") {
-            const error = new AgentError_1.MaxTokensExceededError("Response exceeded maximum token limit", this.config.maxTokens || 1024);
+            const error = new AgentError_1.MaxTokensExceededError("Response exceeded maximum token limit", this.config.maxTokens);
             this.emit(AgentEvent_1.AgentEvent.MAX_TOKENS_EXCEEDED, error);
             this.emit(AgentEvent_1.AgentEvent.ERROR, error);
             if (this.vizEventId) {
@@ -410,7 +410,7 @@ class OpenAICompatibleAgent extends BaseAgent_1.BaseAgent {
         // complete turn — writing partial text to history and emitting DONE.
         (0, cancellation_1.throwIfAborted)(options?.signal, `Execution of agent ${this.getName()}`);
         if (finishReason === "length") {
-            const error = new AgentError_1.MaxTokensExceededError("Response exceeded maximum token limit", this.config.maxTokens || 1024);
+            const error = new AgentError_1.MaxTokensExceededError("Response exceeded maximum token limit", this.config.maxTokens);
             this.emit(AgentEvent_1.AgentEvent.MAX_TOKENS_EXCEEDED, error);
             this.emit(AgentEvent_1.AgentEvent.ERROR, error);
             if (this.vizEventId) {

package/dist/agents/openrouter/OpenRouterAgent.d.ts

@@ -0,0 +1,234 @@
+import { BaseAgent, BaseAgentConfig, ModelInfo, TokenUsage } from "../BaseAgent";
+import { OpenRouterSpecificConfig } from "../AgentConfig";
+import { ExecuteOptions } from "../cancellation";
+import { History, MessageContent } from "../../history/History";
+import type { OpenRouterGenerationInfo } from "./types";
+/**
+ * A single chunk yielded by `executeStream()`.
+ * - `"text"` — visible output token
+ * - `"reasoning"` — internal reasoning token
+ */
+export type StreamChunk = {
+    type: "text" | "reasoning";
+    content: string;
+};
+/**
+ * Build a `beforeRequest` hook that adds custom headers to every request.
+ *
+ * `@openrouter/sdk` has no `defaultHeaders` option like the Anthropic and
+ * OpenAI clients, so headers are injected at the HTTP layer instead. They
+ * overwrite headers the SDK already set, so that `defaultHeaders` means the
+ * same thing on every provider — see `CommonAgentConfig.defaultHeaders`.
+ *
+ * `httpReferer` / `appTitle` are a separate OpenRouter attribution path
+ * (`HTTP-Referer` / `X-Title`). They are not a substitute for tracing or
+ * gateway headers.
+ */
+export declare function defaultHeadersHook(headers: Record<string, string>): (request: Request) => void;
+export type OpenRouterConfig = BaseAgentConfig & OpenRouterSpecificConfig & {
+    model?: string;
+    maxTokens?: number;
+    /** Override the API base URL — for an OpenRouter-compatible gateway. */
+    baseURL?: string;
+    /** Vendor-nested form of the same options, for `AgentConfig` compatibility. */
+    vendorConfig?: {
+        openrouter?: OpenRouterSpecificConfig;
+    };
+};
+/**
+ * A model as OpenRouter's `/models` endpoint reports it.
+ *
+ * Richer than any single upstream provider's listing: OpenRouter publishes
+ * per-token pricing, the context window, and the exact parameter names each
+ * model accepts.
+ */
+export type OpenRouterModelCard = {
+    id: string;
+    canonicalSlug?: string | null;
+    name?: string;
+    created?: number;
+    description?: string;
+    contextLength?: number | null;
+    architecture?: {
+        inputModalities?: string[];
+        outputModalities?: string[];
+        tokenizer?: string;
+        instructType?: string | null;
+    };
+    pricing?: {
+        prompt?: string;
+        completion?: string;
+        request?: string;
+        image?: string;
+        webSearch?: string;
+        internalReasoning?: string;
+    };
+    topProvider?: {
+        contextLength?: number | null;
+        maxCompletionTokens?: number | null;
+        isModerated?: boolean;
+    };
+    /** Parameter names the model accepts, e.g. `"tools"`, `"reasoning"`, `"seed"`. */
+    supportedParameters?: string[] | null;
+    [key: string]: unknown;
+};
+/**
+ * Agent backed by [OpenRouter](https://openrouter.ai) via the official
+ * `@openrouter/sdk`, giving one API key access to models from every provider it
+ * fronts.
+ *
+ * Beyond what an OpenAI-compatible endpoint offers, this agent exposes
+ * OpenRouter's routing controls — `models` fallbacks, `provider` preferences —
+ * reports the credit cost of each run on {@link lastGeneration}, and round-trips
+ * `reasoning_details` so multi-turn tool calls work on reasoning models whose
+ * thinking blocks are signed.
+ *
+ * @requires @openrouter/sdk - Install as a peer dependency:
+ * ```bash
+ * npm install @openrouter/sdk
+ * ```
+ * The SDK is ESM-only, so it is loaded through a dynamic import. On CommonJS
+ * that needs Node 20.19+ or 22.12+, where `require()` of an ES module works.
+ *
+ * @example
+ * ```typescript
+ * const agent = new OpenRouterAgent({
+ *   id: "router",
+ *   name: "Router",
+ *   description: "Answers questions",
+ *   apiKey: process.env.OPENROUTER_API_KEY!,
+ *   model: "anthropic/claude-opus-4-20250514",
+ *   models: ["openai/gpt-5.6"],          // used if the primary is rate limited
+ *   provider: { sort: "throughput" },
+ * });
+ *
+ * const answer = await agent.execute("Explain recursion");
+ * console.log(agent.lastGeneration?.cost, "credits");
+ * ```
+ */
+export declare class OpenRouterAgent extends BaseAgent {
+    protected config: OpenRouterConfig;
+    /**
+     * Cost and routing facts for the most recent `execute()` / `executeStream()`.
+     * Reset at the start of each run, alongside `lastTokenUsage`.
+     */
+    lastGeneration?: OpenRouterGenerationInfo;
+    private clientPromise?;
+    private vizEventId?;
+    private currentToolCallCount;
+    constructor(config: OpenRouterConfig, history?: History);
+    /**
+     * Load `@openrouter/sdk` and construct the client, once per agent.
+     *
+     * The specifier goes through a variable so TypeScript does not resolve it at
+     * build time, which keeps the dependency genuinely optional — the same
+     * approach `MCPClient` uses. The promise is memoized including its rejection,
+     * so a missing package reports the install hint on every call rather than
+     * retrying the import.
+     */
+    private getClient;
+    private createClient;
+    protected getToolDefinitions(): Array<Record<string, unknown>>;
+    protected process(_input: string): Promise<string>;
+    /**
+     * List the models OpenRouter offers, following pagination to the end.
+     *
+     * Fills `contextLength`, `maxOutputTokens` and `capabilities` from
+     * OpenRouter's own metadata: `supported_parameters` says whether a model takes
+     * `tools` and `reasoning`, and `architecture.input_modalities` whether it
+     * accepts images. Per-token pricing is on `raw.pricing`.
+     */
+    listModels(): Promise<ModelInfo<OpenRouterModelCard>[]>;
+    execute(input: string | MessageContent[], options?: ExecuteOptions): Promise<string>;
+    /**
+     * Stream a response as an async generator of {@link StreamChunk} objects.
+     *
+     * Tool calls are executed transparently — the generator keeps streaming after
+     * each tool-call round trip.
+     */
+    executeStream(input: string | MessageContent[], options?: ExecuteOptions): AsyncGenerator<StreamChunk>;
+    /** Shared setup for `execute()` and `executeStream()`. */
+    private beginRun;
+    /**
+     * Map whatever a run threw onto this library's error types, emit it, and close
+     * any open visualization event. Returns the error for the caller to throw.
+     */
+    private failRun;
+    /**
+     * Turn an `@openrouter/sdk` error into an {@link AgentError}.
+     *
+     * The SDK throws one class per status code, all extending `OpenRouterError`
+     * with `statusCode`, `headers` and `body`. Rather than importing those classes
+     * — which would make the optional peer dependency mandatory — this reads the
+     * shape structurally.
+     */
+    private mapProviderError;
+    /**
+     * Build a {@link RateLimitError} from a 429, lifting OpenRouter's rate-limit
+     * headers onto it. They are only present on OpenRouter's own platform limits —
+     * a 429 passed through from an upstream provider carries neither, which is why
+     * every field is optional.
+     */
+    private rateLimitError;
+    private closeViz;
+    /**
+     * Wrap a `ChatRequest` in the envelope `@openrouter/sdk` `chat.send()` expects.
+     * Passing the body bare fails Speakeasy validation (`Input validation failed`).
+     */
+    private sendRequest;
+    /** The `ChatRequest` body, identical for the streaming and buffered paths. */
+    private buildRequest;
+    /**
+     * Per-request options: the cancellation signal plus the retry policy.
+     *
+     * `retryCodes` has to be passed on every call — the SDK reads it only from the
+     * call options, never from the client's, so setting it once at construction
+     * would silently do nothing.
+     */
+    private requestOptions;
+    private callProvider;
+    protected handleResponse(response: any, options?: ExecuteOptions): Promise<string>;
+    private streamTurn;
+    private handleToolCalls;
+    /**
+     * Fold one API call's cost and routing facts into {@link lastGeneration}.
+     * Cost is summed — a tool loop bills once per hop — while the id and model
+     * describe the most recent call.
+     */
+    private recordGeneration;
+    protected parseUsage(response: unknown): TokenUsage;
+    private parseUsageObject;
+    private completeViz;
+}
+/**
+ * Milliseconds to wait from a `Retry-After` header.
+ *
+ * RFC 9110 allows two forms — delay-seconds (`120`) and an HTTP-date
+ * (`Wed, 21 Oct 2026 07:28:00 GMT`). OpenRouter sends the first; the second is
+ * accepted because it is legal and cheap to support. A date already in the past
+ * yields `0` rather than a negative wait.
+ *
+ * @returns The delay in milliseconds, or `undefined` when the header is absent
+ *          or unparseable.
+ */
+export declare function parseRetryAfter(raw: string | null | undefined): number | undefined;
+/**
+ * The instant an `X-RateLimit-Reset` header points at.
+ *
+ * OpenRouter documents that the header exists but not what is in it, and the
+ * three encodings in common use across APIs are indistinguishable by type — so
+ * they are told apart by magnitude, taking "the answer is somewhere near now" as
+ * the tiebreaker:
+ *
+ * - below `10^9` — a duration in seconds from now (a literal epoch would be
+ *   before 2001, which no live API means)
+ * - below `10^11` — Unix **seconds** (`10^11` seconds is the year 5138, so
+ *   anything under it is a plausible timestamp and anything over it is not)
+ * - otherwise — Unix **milliseconds**
+ *
+ * Returns `undefined` for a missing or non-finite value, so callers see "not
+ * reported" rather than a date in 1970. Prefer
+ * {@link RateLimitError.retryAfterMs} when both are present: it is unambiguous.
+ */
+export declare function parseResetAt(value: number | undefined): Date | undefined;
+//# sourceMappingURL=OpenRouterAgent.d.ts.map