@agentionai/agents 1.6.0 → 1.8.0-beta-0

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