OpenRouter Multi-Model LLM

Description

OpenRouter Multi-Model LLM gives Dots one direct provider adapter across OpenRouter's changing upstream model catalog. It implements buffered completion, token streaming, message history, tool definitions and tool calls, sticky session routing, per-call model selection, usage reporting, and the shared LLMProvider contract over a reusable OpenAI-compatible HTTP core.

The adapter lazily fetches and caches GET /models, resolves friendly or shortened model IDs to catalog entries, and derives capabilities and pricing from the live catalog. Catalog failure does not fail a completion: the adapter falls back to its configured default, marks pricing unknown, and reports the catalog problem through a safe injected sink. A direct model-list request remains honest and propagates the failure.

User Story

A user selects an available model from the live provider catalog and starts a Chat turn with vault tools enabled. The adapter streams the response, returns any tool calls to the harness, and supplies final model and usage data for persistence. If the catalog refresh fails mid-session, the turn can still run on the default model while the UI avoids presenting stale pricing as fact.

Extension Surface

Pluggable is the first true rung because packages/llm-providers/src/types.ts defines the common provider contract and packages/llm-providers/src/openrouter.ts is a swappable implementation. The HTTP core in packages/llm-providers/src/openai-compatible-http.ts is parameterized for compatible gateways, while runtime provider registration lives in the package registry.

Capabilities & Limits

• Completes or streams multi-turn requests with tools, model overrides, sticky sessions, budgets, cancellation, and deadlines.
• Fetches a dynamic model catalog and performs exact, suffix, and separator-folded model resolution.
• Uses known catalog pricing when available and returns pricingKnown: false instead of inventing a rate.
• Limits: a cold or failed catalog can leave pricing unknown and uses the configured default for completion resolution.
• Limits: upstream availability, retention, and model-specific policies vary by routed provider and are not normalized by this adapter.

Implementation Map

• packages/llm-providers/src/openrouter.ts
• packages/llm-providers/src/openrouter-http.ts
• GET /models
• packages/llm-providers/src/openai-compatible-http.ts
• packages/llm-providers/src/types.ts
• packages/llm-providers/src/provider-registry.ts

Related Features

- Complements Runtime LLM Provider Registry. - Can be wrapped by Vault-Aware Agent Tool Loop to execute returned workspace tool calls. - Complements LLM and Embedding Spend Caps through reported usage and model pricing.