@rouvanpm/rouva 0.2.13 → 0.3.0

package/README.md

@@ -24,7 +24,7 @@ console.log(response.choices[0].message.content)
 
 ## Provider agnostic
 
-Rouva works with all connected providers — Anthropic, OpenAI, Gemini, DeepSeek, Mistral, Moonshot, xAI, and Z.ai. You can request a specific model, force a specific provider, or omit both and let Rouva route to the cheapest capable model automatically.
+Rouva works with all connected providers — Anthropic, OpenAI, Gemini, DeepSeek, Mistral, Moonshot, xAI, Z.ai and Alibaba Qwen. You can request a specific model, force a specific provider, or omit both and let Rouva route to the cheapest capable model automatically.
 
 ```typescript
 // Request a specific model
@@ -89,43 +89,47 @@ const res = await rouva.chat.completions.create({
   model: 'gpt-4o-mini',                    // required when using seed (OpenAI only)
   messages: [{ role: 'user', content: 'Write a haiku about routing.' }],
   system: 'You are a concise assistant.',  // string or Anthropic-style text blocks
-  max_tokens: 1024,                        // default 4096
+  max_tokens: 1024,                        // default 4096 (or max_completion_tokens)
   temperature: 0.7,                        // 0–1
   top_p: 0.9,                              // nucleus sampling, (0, 1]
   stop: ['END'],                           // up to 4 stop sequences
   seed: 42,                                // pins the request to this exact model
+  metadata: { feature: 'search' },         // your labels, stored with the usage record
 })
 ```
 
-- **`temperature`** — sampling temperature between 0 and 1. Reasoning models (the gpt-5 family) only support their default temperature, so the gateway omits it when routing to one.
-- **`max_tokens`** — values below 1024 also steer auto-routing away from reasoning models, which would otherwise spend the whole budget on hidden reasoning tokens.
-- **`top_p`** — nucleus sampling, forwarded to every provider; `top_p: 1` is treated as omitted. OpenAI reasoning models don't support it: auto-routing avoids them when it's set, and pinning one returns a 400.
-- **`stop`** — a string or up to 4 stop sequences, forwarded to every provider (Anthropic receives them as `stop_sequences`).
+- **`temperature`** — sampling temperature between 0 and 1. The gateway omits it for models that only accept their default: OpenAI reasoning models (gpt-5 / gpt-6 families) and the Claude models that reject it (Opus 4.7 and newer, Sonnet 5 and newer, Fable).
+- **`max_tokens`** / **`max_completion_tokens`** — either name works. Values below 1024 also steer auto-routing away from reasoning models, which would otherwise spend the whole budget on hidden reasoning tokens.
+- **`top_p`** — nucleus sampling; `top_p: 1` is treated as omitted. OpenAI reasoning models don't support it: routing avoids them when it's set, and pinning one returns a 400. The gateway omits it for the Claude models that reject it (as for `temperature`).
+- **`stop`** — a string or up to 4 stop sequences (Anthropic receives them as `stop_sequences`). OpenAI and xAI reasoning models (e.g. gpt-5, grok-4.5 / 4.6 / 4.7) reject it: routing avoids them when it's set, and pinning one returns a 400.
+- **`metadata`** — up to 10 string key-value pairs (keys up to 64 characters, values up to 256, no null bytes) stored with the request's usage record; not sent to the provider.
 - **`seed`** — best-effort deterministic sampling. Only OpenAI honors it, so it requires an OpenAI `model` and pins the request to that exact model (no routing, no fallbacks).
 
 Unsupported OpenAI options (`response_format`, `logit_bias`, `n > 1`, the legacy `functions`/`function_call` fields, …) are rejected by the gateway with an explicit 400 rather than silently ignored.
 
 ## Unlisted models
 
-Dated snapshots (`gpt-4o-mini-2024-07-18`) and fine-tunes (`ft:gpt-4o-mini:…`) work when pinned — they are matched to their provider by naming convention and forwarded as-is. Until the gateway's pricing registry knows them, the dashboard records their token counts with zero cost.
-
-Models not recognised by the gateway return a `400` immediately:
+`chat.completions.create()` serves the models the gateway can price — its built-in list (see `RouvaModel` and rouva.io/docs) plus models added to its synced model registry, such as new snapshots. Any other ID returns a `404` immediately:
 
 ```json
-{ "error": "Model \"<id>\" is not supported. See rouva.io/docs for the supported model list." }
+{ "error": "The model `<id>` does not exist or is not supported. See rouva.io/docs for the supported model list." }
 ```
 
+`run()` also accepts an ID whose provider it can infer from the name (e.g. a dated snapshot); without a known price it's logged with no cost, and it's refused for spend-capped keys or runs with `session_budget_usd`.
+
+`'gpt-5.6'` is a deprecated alias for `'gpt-5.6-sol'` — use the full name.
+
 ## OpenAI-compatible endpoint
 
 Using the OpenAI SDK (or LangChain, the Vercel AI SDK, …) instead of this one? The gateway is also served at `POST /v1/chat/completions` — point `baseURL` at `https://app.rouva.io/v1` with your `rva_` key and it behaves exactly like OpenAI: `model` is required, responses are buffered JSON unless `stream: true`, and only OpenAI-format providers are available (use this SDK or the native endpoint for Anthropic models).
 
-Non-tools requests on `/v1` always honor the named model exactly. **Tools requests on `/v1` benefit from within-provider intelligent routing** when Intelligent Routing is enabled in your dashboard — Rouva picks the cheapest capable model within the same provider, using the named `model` as a cost ceiling. The provider never changes (tool schemas are provider-specific), and `response.model` reflects the model that actually served the request. Turn Intelligent Routing off in dashboard Settings → Gateway to always pin the exact model.
+Non-tools requests on `/v1` honor the named model exactly unless the workspace owner has set an account routing override for the task — overrides apply as policy on every endpoint, and on `/v1` one may route to Anthropic (the response is translated back to the OpenAI format). **Tools requests on `/v1` benefit from within-provider intelligent routing** when Intelligent Routing is enabled in your dashboard — Rouva picks the cheapest capable model within the same provider, using the named `model` as a cost ceiling. The provider never changes (tool schemas are provider-specific), and `response.model` reflects the model that actually served the request. Turn Intelligent Routing off in dashboard Settings → Gateway to always pin the exact model.
 
 ## Tool use
 
-Tools are forwarded to your target provider verbatim — define them in the **provider's own format** (OpenAI `{ type: "function", function: {...} }` or Anthropic `{ name, description, input_schema }`) and pin the matching `model`. Tool schemas are provider-specific, so `model` is required and the gateway returns a 400 without it.
+Tools are forwarded to your target provider verbatim — define them in the **provider's own format** (OpenAI `{ type: "function", function: {...} }` or Anthropic `{ name, description, input_schema }`) and pin the matching `model`. Tool schemas are provider-specific, so `model` is required and the gateway returns a 400 without it. Models that don't support tools on Chat Completions (`gpt-6.1-sol`, `gpt-5.6-*`) also return a 400.
 
-When using the `/v1` endpoint (OpenAI SDK, LangChain, Vercel AI SDK, …) with Intelligent Routing enabled, tools requests are routed to the cheapest capable model within the same provider — see [OpenAI-compatible endpoint](#openai-compatible-endpoint) for details. On the native SDK endpoint (`/api/gateway/messages`), the named model is always honored exactly.
+A tools request only ever moves to another model of the **same provider**: an account routing override for the task (when it targets the same provider), or — on the `/v1` endpoint with Intelligent Routing enabled — the cheapest capable model within that provider, using the named `model` as a cost ceiling (see [OpenAI-compatible endpoint](#openai-compatible-endpoint)). Otherwise the named model is honored exactly.
 
 ```typescript
 const res = await rouva.chat.completions.create({
@@ -167,19 +171,19 @@ Responses are normalized to the OpenAI shape regardless of provider: Anthropic `
 
 **Don't branch on `finish_reason` to detect tool calls** — check for the presence of `message.tool_calls` instead. `finish_reason` follows each provider's own semantics, and OpenAI notably returns `"stop"` (not `"tool_calls"`) when `tool_choice` forces a specific function. The SDK passes OpenAI's values through unchanged so behavior matches calling OpenAI directly.
 
-Tools requests record usage and cost. Savings are recorded when within-provider routing substitutes a cheaper model on `/v1`. Tools responses are not quality-scored or served from the semantic cache.
+Tools requests record usage and cost. Savings are recorded when within-provider routing substitutes a cheaper model on `/v1`. Tools responses are not quality-scored, and streaming tools requests are never served from the duplicate-request cache.
 
 ## Cost optimisations
 
 Rouva applies several cost-saving layers automatically on every non-tools request — no configuration required.
 
-**Semantic cache (A)** — repeated or semantically similar prompts are served from cache without hitting the upstream provider. Cache hits record zero cost and appear in your dashboard with a `semantic_cache_hit` flag.
+**Duplicate-request cache** — an identical request repeated within 60 seconds (typically a client retry) gets the earlier response instead of a second provider call, and isn't charged. Such responses carry `_rouva.dedup: true`.
 
-**Prompt caching (B)** — Anthropic requests automatically include cache-control headers on large system prompts and conversation prefixes, reducing input token costs on repeated turns.
+**Prompt caching** — Anthropic requests automatically include cache-control markers on large system prompts, tool definitions and conversation prefixes, reducing input token costs on repeated turns.
 
-**Conversation summarisation (C2)** — long Anthropic conversations are summarised by a cheap model before forwarding, compressing the context window and reducing input tokens. The summarisation cost is included in the request's spend snapshot. Only runs when the conversation exceeds ~2,000 tokens of non-system content and the request is not a tools request.
+**Conversation summarisation** — long Anthropic conversations are summarised by a cheap model before forwarding, compressing the context window and reducing input tokens. The summarisation cost is included in the request's spend snapshot. Only runs when the conversation exceeds ~2,000 tokens of non-system content and the request is not a tools request.
 
-All three are skipped for tools requests, which are forwarded verbatim.
+Tools requests are forwarded verbatim: no summarisation or whitespace trimming.
 
 ## Options
 
@@ -226,16 +230,16 @@ console.log(result.session_cost_usd)  // total USD spent
 ### How it works
 
 1. The gateway sends your `messages` to the model (non-streaming)
-2. When the model returns tool calls, all handlers are dispatched **in parallel** via POST — the request body is the tool's JSON input, the response body is used as the tool result
+2. When the model returns tool calls, all handlers are dispatched **in parallel** via POST — the request body is `{ "name": "<tool>", "arguments": { …the model's input… } }`, and the response body is used as the tool result
 3. Results are appended and the loop continues
-4. The loop exits when `finish_reason` is `"stop"` / `"end_turn"`, `max_turns` is reached, or `session_budget_usd` is exceeded
+4. The loop exits when the model stops (`finish_reason: "stop"`, for every provider), `max_turns` is reached (`"max_turns"`), or `session_budget_usd` is reached (`"session_budget_exceeded"`). If the last turn's output is truncated, the run returns with `error` set and the truncation reason (e.g. `"length"`)
 
-Every turn is logged as a usage snapshot in the Rouva dashboard under the shared `session_id`, giving you a full session replay with per-turn cost, model used, tool calls, and quality score.
+Every turn is logged as a usage snapshot in the Rouva dashboard under the shared `session_id`, giving you a full session replay with per-turn cost, model used and tool calls. (Tool-loop turns aren't quality-scored.)
 
 ### Handler URL requirements
 
 - Must be a public HTTPS URL (private/local addresses are rejected)
-- The gateway sends a `POST` with `Content-Type: application/json` and the tool's input object as the body
+- The gateway sends a `POST` with `Content-Type: application/json` and the body `{ "name": "<tool>", "arguments": { … } }`
 - The response body (text or JSON) is returned to the model as the tool result
 
 ### Parameters
@@ -256,16 +260,21 @@ Every turn is logged as a usage snapshot in the Rouva dashboard under the shared
 
 ```typescript
 interface RunResult {
-  content: string | null        // final model response text
-  turns: number                 // turns executed
-  tool_calls_made: number       // total tool calls dispatched
-  session_id: string            // groups all turns in the dashboard
-  finish_reason: string | null  // "stop", "end_turn", "max_turns", "budget_exceeded", "length"
-  cost_usd: number              // cost of the last turn
-  session_cost_usd: number      // cumulative cost across all turns
+  content: string | null            // final model response text
+  turns: number                     // turns executed
+  tool_calls_made: number           // total tool calls dispatched
+  session_id: string                // groups all turns in the dashboard
+  finish_reason: string | null      // "stop", "max_turns", "session_budget_exceeded", or a truncation reason ("length", …)
+  session_cost_usd: number          // cumulative cost across all turns
+  session_cost_incomplete?: boolean // a turn reported no usage — cost is a lower bound
+  routed_model?: string             // when Intelligent Routing chose a different model
+  requested_model?: string
+  error?: string                    // why a run that still returned 200 stopped early
 }
 ```
 
+A non-2xx response throws a `RouvaError` (see [Errors](#errors)). Once the loop has started, its `body` also carries the partial `turns`, `session_id` and `session_cost_usd`; errors before the first turn (validation, no provider key, allowlist) carry only `error`. A run can take several minutes — pass `{ signal }` as the second argument to cancel it.
+
 ### When to use `run()` vs `chat.completions.create()`
 
 | | `rouva.run()` | `chat.completions.create()` |
@@ -313,10 +322,31 @@ console.log(res._rouva)
 // {
 //   model_used: 'gpt-4o-mini',
 //   provider_used: 'openai',
-//   task_type: 'summarize'
+//   task_type: 'summarize',
+//   dedup: true             // only when served from the duplicate-request cache
 // }
 ```
 
+## Errors
+
+Any non-2xx response throws a `RouvaError` (a subclass of `Error`, so existing `catch` blocks keep working):
+
+```typescript
+import { Rouva, RouvaError } from '@rouvanpm/rouva'
+
+try {
+  await rouva.chat.completions.create({ messages })
+} catch (e) {
+  if (e instanceof RouvaError && e.status === 429) {
+    console.log(e.refusal)     // 'key_cap' | 'member_cap' | 'rate' — Rouva refused before calling the provider
+    console.log(e.retryAfter)  // seconds, from Retry-After
+    console.log(e.error)       // the gateway's message
+  }
+}
+```
+
+`refusal` (header `X-Rouva-Refusal`) names why Rouva itself refused the request before contacting the provider, when the gateway marks it: a monthly spend cap would be exceeded (`key_cap`, `member_cap`), the rate limit (`rate`), or — for spend-capped keys — a model with no known price (`unpriced`) or input whose cost can't be bounded (`unbounded`). Not every refusal is marked yet: a `429` with `retryAfter` but no `refusal` can still be a Rouva cap or rate-limit refusal — read `error`. Every call also takes `{ signal }` as a second argument to abort it.
+
 ## Getting your API key
 
 1. Sign in to [app.rouva.io](https://app.rouva.io)

package/dist/index.d.mts

@@ -1,3 +1,8 @@
+/** Per-call options. */
+interface RequestOptions {
+    /** Abort the request (e.g. a long `run()` the user navigated away from). */
+    signal?: AbortSignal;
+}
 interface RouvaOptions {
     /** Your Rouva gateway API key (rva_...) */
     apiKey: string;
@@ -47,16 +52,19 @@ interface ContentBlockMessage {
 type ChatMessage = Message | AssistantToolCallMessage | ToolResultMessage | ContentBlockMessage;
 type RouvaProvider = 'anthropic' | 'openai' | 'gemini' | 'deepseek' | 'mistral' | 'moonshot' | 'xai' | 'zai' | 'alibaba' | (string & {});
 /**
- * Supported models across all providers.
+ * Supported models across all providers (the gateway's list as of SDK 0.3.0).
  * Omit `model` entirely to let Rouva route to the cheapest capable model automatically.
  *
- * IDs not listed here also work when pinned — dated snapshots
- * (`gpt-4o-mini-2024-07-18`), fine-tunes (`ft:gpt-4o-mini:…`), and new
- * releases are matched to their provider by naming convention and forwarded
- * as-is. Until the gateway's registry knows their pricing, such requests are
- * logged with token counts but zero cost.
+ * Other IDs are accepted by the type for forward compatibility. On
+ * `chat.completions.create()` the gateway only serves models it can price
+ * (its built-in list plus its synced model registry); any other ID returns a
+ * 404. `run()` also accepts IDs whose provider it can infer from the name,
+ * logging them without a cost unless the key is spend-capped or the run has a
+ * `session_budget_usd` (then an unpriced model is refused).
+ *
+ * `'gpt-5.6'` is a deprecated alias the gateway maps to `'gpt-5.6-sol'`.
  */
-type RouvaModel = 'claude-opus-4-6' | 'claude-opus-4-7' | 'claude-opus-4-8' | 'claude-sonnet-4-6' | 'claude-sonnet-5' | 'claude-haiku-4-5-20251001' | 'claude-fable-5' | 'gpt-5-nano' | 'gpt-5-mini' | 'gpt-5.4-mini' | 'gpt-5' | 'gpt-5.6' | 'gpt-4.1-nano' | 'gpt-4.1-mini' | 'gpt-4.1' | 'gpt-4o' | 'gpt-4o-mini' | 'gemini-3.7-flash' | 'gemini-3.6-flash' | 'gemini-2.5-flash' | 'gemini-2.5-pro' | 'deepseek-v4-flash' | 'deepseek-v4-flash-think' | 'deepseek-v4-pro' | 'mistral-small-latest' | 'mistral-large-latest' | 'kimi-k2.6' | 'kimi-k3' | 'grok-4.6' | 'grok-4.5' | 'grok-4.3' | 'grok-4.20-0309-reasoning' | 'glm-4.7-flash' | 'glm-5.2' | 'qwen-turbo' | 'qwen-plus' | 'qwen-max' | 'qwen3-30b-a3b' | 'qwen3-32b' | 'qwen3-235b-a22b' | (string & {});
+type RouvaModel = 'claude-fable-5-1' | 'claude-fable-5' | 'claude-opus-5-5' | 'claude-opus-5' | 'claude-opus-4-8' | 'claude-opus-4-7' | 'claude-opus-4-6' | 'claude-sonnet-5-5' | 'claude-sonnet-5' | 'claude-sonnet-4-6' | 'claude-haiku-4-5-20251001' | 'gpt-6.1-sol' | 'gpt-6-sol' | 'gpt-6-luna' | 'gpt-5.6-sol' | 'gpt-5.6-terra' | 'gpt-5.6-luna' | 'gpt-5.6' | 'gpt-5' | 'gpt-5.4-mini' | 'gpt-5-mini' | 'gpt-5-nano' | 'gpt-4.1' | 'gpt-4.1-mini' | 'gpt-4.1-nano' | 'gpt-4o' | 'gpt-4o-mini' | 'gemini-3.8-flash' | 'gemini-3.7-flash' | 'gemini-3.6-flash' | 'gemini-3.5-flash-lite' | 'gemini-2.5-pro' | 'gemini-2.5-flash' | 'deepseek-flash-4-1' | 'deepseek-v4-pro' | 'deepseek-v4-flash' | 'deepseek-v4-flash-think' | 'mistral-large-latest' | 'mistral-small-latest' | 'kimi-k3' | 'kimi-k2.6' | 'grok-4.7' | 'grok-4.6' | 'grok-4.5' | 'grok-4.3' | 'grok-4.20-0309-reasoning' | 'glm-5.3' | 'glm-5.2' | 'glm-4.7-flash' | 'qwen3.8-omni-flash' | 'qwen-max' | 'qwen-plus' | 'qwen-turbo' | 'qwen3-235b-a22b' | 'qwen3-32b' | 'qwen3-30b-a3b' | (string & {});
 /** Anthropic-style text block — the array form of the `system` param */
 interface SystemTextBlock {
     type: 'text';
@@ -72,8 +80,13 @@ interface ChatCompletionParams {
      */
     system?: string | SystemTextBlock[];
     /**
-     * Target model — omit to let Rouva route intelligently to the cheapest capable model.
-     * Supports models from any connected provider (Anthropic, OpenAI).
+     * Target model — omit to let Rouva route intelligently to the cheapest
+     * capable model. With Intelligent Routing on, a named model is a price
+     * ceiling for Rouva's own choices: it may substitute a cheaper capable model,
+     * never a pricier one (retries after a provider error included). Two
+     * exceptions: an account routing override set by the workspace owner applies
+     * as policy, even if pricier; and with `provider` also set, the exact model
+     * is used (no substitution).
      */
     model?: RouvaModel;
     /**
@@ -83,23 +96,34 @@ interface ChatCompletionParams {
     provider?: RouvaProvider;
     /** Maximum tokens to generate */
     max_tokens?: number;
+    /** OpenAI's newer name for `max_tokens`; the gateway accepts either. */
+    max_completion_tokens?: number;
+    /**
+     * Your own labels for the request, stored with its usage record and not
+     * sent to the provider: up to 10 string key-value pairs, keys up to 64
+     * characters, values up to 256 characters, no null bytes.
+     */
+    metadata?: Record<string, string>;
     /**
      * Sampling temperature 0–1.
-     * Note: reasoning models (gpt-5 family) only support their default
-     * temperature, so the gateway omits it for those.
+     * The gateway omits it for models that only accept their default: OpenAI
+     * reasoning models (gpt-5 / gpt-6 families) and the Claude models that reject
+     * it (Opus 4.7 and newer, Sonnet 5 and newer, Fable).
      */
     temperature?: number;
     /**
-     * Nucleus sampling — greater than 0 and at most 1, forwarded to every
-     * provider. `top_p: 1` (the no-op default) is treated as omitted. OpenAI
-     * reasoning models (gpt-5 family, o-series) don't support it: auto-routing
-     * avoids them when top_p is set, and pinning one returns a 400.
+     * Nucleus sampling — greater than 0 and at most 1. `top_p: 1` (the no-op
+     * default) is treated as omitted. OpenAI reasoning models (gpt-5 / gpt-6
+     * families, o-series) don't support it: routing avoids them when top_p is
+     * set, and pinning one returns a 400. The gateway omits it for the Claude
+     * models that reject it (Opus 4.7 and newer, Sonnet 5 and newer, Fable).
      */
     top_p?: number;
     /**
-     * Up to 4 stop sequences — a string or array of non-empty strings,
-     * forwarded to every provider (Anthropic receives them as
-     * `stop_sequences`).
+     * Up to 4 stop sequences — a string or array of non-empty strings
+     * (Anthropic receives them as `stop_sequences`). OpenAI and xAI reasoning
+     * models (e.g. gpt-5, grok-4.5 / 4.6 / 4.7) reject `stop`: routing avoids
+     * them when it is set, and pinning one returns a 400.
      */
     stop?: string | string[];
     /**
@@ -117,9 +141,11 @@ interface ChatCompletionParams {
     /**
      * Tool definitions in your target provider's own format, forwarded to the
      * provider verbatim (OpenAI `{ type: "function", function: {...} }` or
-     * Anthropic `{ name, description, input_schema }`). Requires `model` —
-     * tool schemas are provider-specific, so tools requests are never
-     * re-routed by the gateway.
+     * Anthropic `{ name, description, input_schema }`). Requires `model`.
+     * Tool schemas are provider-specific, so a tools request only ever moves to
+     * another model of the SAME provider (a routing override, or cheaper-model
+     * routing on /v1). Models that don't support tools on Chat Completions
+     * (gpt-6.1-sol, gpt-5.6-*) return a 400.
      */
     tools?: Array<Record<string, unknown>>;
     /**
@@ -161,7 +187,16 @@ interface RouvaResponseMeta {
     provider_used?: string;
     /** Task type classified by Rouva when exposed by the gateway */
     task_type?: string;
-    /** Semantic cache status when exposed by the gateway */
+    /**
+     * True when the gateway answered from its duplicate-request cache (an
+     * identical request within the last 60 seconds) instead of calling the
+     * provider — that request wasn't charged. Header: `X-Rouva-Dedup`.
+     */
+    dedup?: boolean;
+    /**
+     * @deprecated The semantic cache was removed from the gateway (2026-10-08),
+     * so this is never set. Use `dedup`.
+     */
     cache?: string;
 }
 interface RunParams {
@@ -186,9 +221,9 @@ interface RunParams {
     tools: Array<Record<string, unknown>>;
     /**
      * Map of tool name → handler URL. When the model calls a tool, the gateway
-     * POSTs the tool input as JSON to the corresponding URL and feeds the
-     * response body back as the tool result. All handlers must be public HTTPS
-     * endpoints.
+     * POSTs `{ "name": <tool name>, "arguments": <the model's input object> }`
+     * as JSON to the corresponding URL and feeds the response body back as the
+     * tool result. All handlers must be public HTTPS endpoints.
      *
      * @example
      * { search: 'https://api.example.com/search', calculator: 'https://api.example.com/calc' }
@@ -199,10 +234,9 @@ interface RunParams {
      * the loop begins — the session stays on that provider for all turns. When
      * the session history is fully translatable, routing may cross the
      * Anthropic ↔ OpenAI-compatible boundary; the canonical layer handles tool
-     * schema translation automatically. Omit to let Rouva select the cheapest
-     * capable model automatically.
+     * schema translation automatically. Required by /run.
      */
-    model?: RouvaModel;
+    model: RouvaModel;
     /**
      * Force a specific provider when paired with `model`.
      */
@@ -222,8 +256,9 @@ interface RunParams {
      */
     temperature?: number;
     /**
-     * Hard cap on total session spend in USD. The loop exits cleanly when the
-     * cumulative cost of all turns reaches this threshold.
+     * Hard cap on total session spend in USD. The loop exits cleanly (with
+     * `finish_reason: "session_budget_exceeded"`) when the cumulative cost of
+     * all turns reaches this threshold.
      */
     session_budget_usd?: number;
 }
@@ -237,15 +272,27 @@ interface RunResult {
     /** Session ID — all turns are grouped under this ID in the Rouva dashboard. */
     session_id: string;
     /**
-     * Why the loop exited: `"stop"` (model finished), `"max_turns"` (turn limit
-     * reached), `"budget_exceeded"` (session_budget_usd hit), or a provider
-     * finish reason such as `"end_turn"` or `"length"`.
+     * Why the loop exited: `"stop"` (the model finished — reported as "stop" for
+     * every provider), `"max_turns"` (turn limit reached),
+     * `"session_budget_exceeded"` (session_budget_usd hit), or a truncation
+     * reason such as `"length"` / `"max_tokens"` (then `error` explains it).
      */
     finish_reason: string | null;
-    /** USD cost of the final turn. */
-    cost_usd: number;
     /** Cumulative USD cost of all turns in the session. */
     session_cost_usd: number;
+    /**
+     * True when a turn reported no usage, so `session_cost_usd` is a lower
+     * bound rather than the full cost.
+     */
+    session_cost_incomplete?: boolean;
+    /** Set when Intelligent Routing chose a different model than requested. */
+    routed_model?: string;
+    requested_model?: string;
+    /**
+     * Explanation when the run stopped early but still returned 200 — e.g.
+     * output truncated on the last turn (raise `max_tokens`).
+     */
+    error?: string;
 }
 
 declare class Rouva {
@@ -254,7 +301,7 @@ declare class Rouva {
     private _sessionId;
     readonly chat: {
         completions: {
-            create(params: ChatCompletionParams): Promise<ChatCompletion | ReadableStream>;
+            create(params: ChatCompletionParams, options?: RequestOptions): Promise<ChatCompletion | ReadableStream>;
         };
     };
     constructor(options: RouvaOptions);
@@ -273,9 +320,15 @@ declare class Rouva {
     /** The active session ID, or undefined if no session is in progress. */
     get sessionId(): string | undefined;
     /**
-     * Run a server-side agentic loop. The gateway calls the model, dispatches
-     * tool calls in parallel to your handler URLs, and loops until the model
-     * stops or limits are reached — no streaming, no client-side loop required.
+     * Run a server-side agentic loop (`POST /api/gateway/run`). The gateway
+     * calls the model, POSTs each tool call to its handler URL as
+     * `{ name, arguments }` (in parallel), feeds the response bodies back as tool
+     * results, and loops until the model stops or a limit is reached — no
+     * streaming, no client-side loop required. Throws `RouvaError` on a non-2xx
+     * response; once the loop has started, its `body` also carries the partial
+     * `turns`, `session_id` and `session_cost_usd` (errors before the first turn
+     * — validation, no key, allowlist — carry only `error`). Pass
+     * `{ signal }` to cancel; a run can take several minutes.
      *
      * Every turn is logged as a usage snapshot grouped by `session_id` in the
      * Rouva dashboard, giving you a full session replay with per-turn cost,
@@ -293,8 +346,36 @@ declare class Rouva {
      * console.log(result.turns)        // how many turns it took
      * console.log(result.session_id)   // dashboard session ID
      */
-    run(params: RunParams): Promise<RunResult>;
+    run(params: RunParams, options?: RequestOptions): Promise<RunResult>;
+    private _post;
     private _createChatCompletion;
 }
 
-export { type AssistantToolCallMessage, type ChatCompletion, type ChatCompletionChoice, type ChatCompletionParams, type ChatCompletionUsage, type ChatMessage, type ContentBlockMessage, type FunctionToolCall, type Message, type ResponseMessage, Rouva, type RouvaOptions, type RouvaProvider, type RouvaResponseMeta, type RunParams, type RunResult, type SystemTextBlock, type ToolResultMessage };
+/**
+ * Thrown for any non-2xx gateway response. Extends Error and keeps the
+ * message format of earlier versions (`[Rouva] Gateway error 429: …`), so
+ * existing `catch` blocks keep working; the fields make refusals actionable.
+ */
+declare class RouvaError extends Error {
+    /** HTTP status from the gateway. */
+    readonly status: number;
+    /**
+     * Why Rouva itself refused the request before contacting the provider, when
+     * the gateway marks it (header `X-Rouva-Refusal`): `"key_cap"` /
+     * `"member_cap"` (a monthly spend cap would be exceeded), `"rate"` (rate
+     * limit), `"unpriced"` (a capped key can't use a model with no known price),
+     * `"unbounded"` (a capped key can't send input whose cost can't be bounded).
+     * Not every refusal carries it yet — a 429 with `retryAfter` and no
+     * `refusal` can still be a Rouva cap or rate refusal; read `error`.
+     */
+    readonly refusal?: string;
+    /** Seconds to wait before retrying, from `Retry-After`, when present. */
+    readonly retryAfter?: number;
+    /** The gateway's error message (`error` field), when the body is JSON. */
+    readonly error?: string;
+    /** The parsed JSON body, or the raw text when it isn't JSON. */
+    readonly body: unknown;
+    constructor(kind: 'Gateway' | 'Run', status: number, headers: Headers, rawBody: string);
+}
+
+export { type AssistantToolCallMessage, type ChatCompletion, type ChatCompletionChoice, type ChatCompletionParams, type ChatCompletionUsage, type ChatMessage, type ContentBlockMessage, type FunctionToolCall, type Message, type RequestOptions, type ResponseMessage, Rouva, RouvaError, type RouvaModel, type RouvaOptions, type RouvaProvider, type RouvaResponseMeta, type RunParams, type RunResult, type SystemTextBlock, type ToolResultMessage };

package/dist/index.d.ts

@@ -1,3 +1,8 @@
+/** Per-call options. */
+interface RequestOptions {
+    /** Abort the request (e.g. a long `run()` the user navigated away from). */
+    signal?: AbortSignal;
+}
 interface RouvaOptions {
     /** Your Rouva gateway API key (rva_...) */
     apiKey: string;
@@ -47,16 +52,19 @@ interface ContentBlockMessage {
 type ChatMessage = Message | AssistantToolCallMessage | ToolResultMessage | ContentBlockMessage;
 type RouvaProvider = 'anthropic' | 'openai' | 'gemini' | 'deepseek' | 'mistral' | 'moonshot' | 'xai' | 'zai' | 'alibaba' | (string & {});
 /**
- * Supported models across all providers.
+ * Supported models across all providers (the gateway's list as of SDK 0.3.0).
  * Omit `model` entirely to let Rouva route to the cheapest capable model automatically.
  *
- * IDs not listed here also work when pinned — dated snapshots
- * (`gpt-4o-mini-2024-07-18`), fine-tunes (`ft:gpt-4o-mini:…`), and new
- * releases are matched to their provider by naming convention and forwarded
- * as-is. Until the gateway's registry knows their pricing, such requests are
- * logged with token counts but zero cost.
+ * Other IDs are accepted by the type for forward compatibility. On
+ * `chat.completions.create()` the gateway only serves models it can price
+ * (its built-in list plus its synced model registry); any other ID returns a
+ * 404. `run()` also accepts IDs whose provider it can infer from the name,
+ * logging them without a cost unless the key is spend-capped or the run has a
+ * `session_budget_usd` (then an unpriced model is refused).
+ *
+ * `'gpt-5.6'` is a deprecated alias the gateway maps to `'gpt-5.6-sol'`.
  */
-type RouvaModel = 'claude-opus-4-6' | 'claude-opus-4-7' | 'claude-opus-4-8' | 'claude-sonnet-4-6' | 'claude-sonnet-5' | 'claude-haiku-4-5-20251001' | 'claude-fable-5' | 'gpt-5-nano' | 'gpt-5-mini' | 'gpt-5.4-mini' | 'gpt-5' | 'gpt-5.6' | 'gpt-4.1-nano' | 'gpt-4.1-mini' | 'gpt-4.1' | 'gpt-4o' | 'gpt-4o-mini' | 'gemini-3.7-flash' | 'gemini-3.6-flash' | 'gemini-2.5-flash' | 'gemini-2.5-pro' | 'deepseek-v4-flash' | 'deepseek-v4-flash-think' | 'deepseek-v4-pro' | 'mistral-small-latest' | 'mistral-large-latest' | 'kimi-k2.6' | 'kimi-k3' | 'grok-4.6' | 'grok-4.5' | 'grok-4.3' | 'grok-4.20-0309-reasoning' | 'glm-4.7-flash' | 'glm-5.2' | 'qwen-turbo' | 'qwen-plus' | 'qwen-max' | 'qwen3-30b-a3b' | 'qwen3-32b' | 'qwen3-235b-a22b' | (string & {});
+type RouvaModel = 'claude-fable-5-1' | 'claude-fable-5' | 'claude-opus-5-5' | 'claude-opus-5' | 'claude-opus-4-8' | 'claude-opus-4-7' | 'claude-opus-4-6' | 'claude-sonnet-5-5' | 'claude-sonnet-5' | 'claude-sonnet-4-6' | 'claude-haiku-4-5-20251001' | 'gpt-6.1-sol' | 'gpt-6-sol' | 'gpt-6-luna' | 'gpt-5.6-sol' | 'gpt-5.6-terra' | 'gpt-5.6-luna' | 'gpt-5.6' | 'gpt-5' | 'gpt-5.4-mini' | 'gpt-5-mini' | 'gpt-5-nano' | 'gpt-4.1' | 'gpt-4.1-mini' | 'gpt-4.1-nano' | 'gpt-4o' | 'gpt-4o-mini' | 'gemini-3.8-flash' | 'gemini-3.7-flash' | 'gemini-3.6-flash' | 'gemini-3.5-flash-lite' | 'gemini-2.5-pro' | 'gemini-2.5-flash' | 'deepseek-flash-4-1' | 'deepseek-v4-pro' | 'deepseek-v4-flash' | 'deepseek-v4-flash-think' | 'mistral-large-latest' | 'mistral-small-latest' | 'kimi-k3' | 'kimi-k2.6' | 'grok-4.7' | 'grok-4.6' | 'grok-4.5' | 'grok-4.3' | 'grok-4.20-0309-reasoning' | 'glm-5.3' | 'glm-5.2' | 'glm-4.7-flash' | 'qwen3.8-omni-flash' | 'qwen-max' | 'qwen-plus' | 'qwen-turbo' | 'qwen3-235b-a22b' | 'qwen3-32b' | 'qwen3-30b-a3b' | (string & {});
 /** Anthropic-style text block — the array form of the `system` param */
 interface SystemTextBlock {
     type: 'text';
@@ -72,8 +80,13 @@ interface ChatCompletionParams {
      */
     system?: string | SystemTextBlock[];
     /**
-     * Target model — omit to let Rouva route intelligently to the cheapest capable model.
-     * Supports models from any connected provider (Anthropic, OpenAI).
+     * Target model — omit to let Rouva route intelligently to the cheapest
+     * capable model. With Intelligent Routing on, a named model is a price
+     * ceiling for Rouva's own choices: it may substitute a cheaper capable model,
+     * never a pricier one (retries after a provider error included). Two
+     * exceptions: an account routing override set by the workspace owner applies
+     * as policy, even if pricier; and with `provider` also set, the exact model
+     * is used (no substitution).
      */
     model?: RouvaModel;
     /**
@@ -83,23 +96,34 @@ interface ChatCompletionParams {
     provider?: RouvaProvider;
     /** Maximum tokens to generate */
     max_tokens?: number;
+    /** OpenAI's newer name for `max_tokens`; the gateway accepts either. */
+    max_completion_tokens?: number;
+    /**
+     * Your own labels for the request, stored with its usage record and not
+     * sent to the provider: up to 10 string key-value pairs, keys up to 64
+     * characters, values up to 256 characters, no null bytes.
+     */
+    metadata?: Record<string, string>;
     /**
      * Sampling temperature 0–1.
-     * Note: reasoning models (gpt-5 family) only support their default
-     * temperature, so the gateway omits it for those.
+     * The gateway omits it for models that only accept their default: OpenAI
+     * reasoning models (gpt-5 / gpt-6 families) and the Claude models that reject
+     * it (Opus 4.7 and newer, Sonnet 5 and newer, Fable).
      */
     temperature?: number;
     /**
-     * Nucleus sampling — greater than 0 and at most 1, forwarded to every
-     * provider. `top_p: 1` (the no-op default) is treated as omitted. OpenAI
-     * reasoning models (gpt-5 family, o-series) don't support it: auto-routing
-     * avoids them when top_p is set, and pinning one returns a 400.
+     * Nucleus sampling — greater than 0 and at most 1. `top_p: 1` (the no-op
+     * default) is treated as omitted. OpenAI reasoning models (gpt-5 / gpt-6
+     * families, o-series) don't support it: routing avoids them when top_p is
+     * set, and pinning one returns a 400. The gateway omits it for the Claude
+     * models that reject it (Opus 4.7 and newer, Sonnet 5 and newer, Fable).
      */
     top_p?: number;
     /**
-     * Up to 4 stop sequences — a string or array of non-empty strings,
-     * forwarded to every provider (Anthropic receives them as
-     * `stop_sequences`).
+     * Up to 4 stop sequences — a string or array of non-empty strings
+     * (Anthropic receives them as `stop_sequences`). OpenAI and xAI reasoning
+     * models (e.g. gpt-5, grok-4.5 / 4.6 / 4.7) reject `stop`: routing avoids
+     * them when it is set, and pinning one returns a 400.
      */
     stop?: string | string[];
     /**
@@ -117,9 +141,11 @@ interface ChatCompletionParams {
     /**
      * Tool definitions in your target provider's own format, forwarded to the
      * provider verbatim (OpenAI `{ type: "function", function: {...} }` or
-     * Anthropic `{ name, description, input_schema }`). Requires `model` —
-     * tool schemas are provider-specific, so tools requests are never
-     * re-routed by the gateway.
+     * Anthropic `{ name, description, input_schema }`). Requires `model`.
+     * Tool schemas are provider-specific, so a tools request only ever moves to
+     * another model of the SAME provider (a routing override, or cheaper-model
+     * routing on /v1). Models that don't support tools on Chat Completions
+     * (gpt-6.1-sol, gpt-5.6-*) return a 400.
      */
     tools?: Array<Record<string, unknown>>;
     /**
@@ -161,7 +187,16 @@ interface RouvaResponseMeta {
     provider_used?: string;
     /** Task type classified by Rouva when exposed by the gateway */
     task_type?: string;
-    /** Semantic cache status when exposed by the gateway */
+    /**
+     * True when the gateway answered from its duplicate-request cache (an
+     * identical request within the last 60 seconds) instead of calling the
+     * provider — that request wasn't charged. Header: `X-Rouva-Dedup`.
+     */
+    dedup?: boolean;
+    /**
+     * @deprecated The semantic cache was removed from the gateway (2026-10-08),
+     * so this is never set. Use `dedup`.
+     */
     cache?: string;
 }
 interface RunParams {
@@ -186,9 +221,9 @@ interface RunParams {
     tools: Array<Record<string, unknown>>;
     /**
      * Map of tool name → handler URL. When the model calls a tool, the gateway
-     * POSTs the tool input as JSON to the corresponding URL and feeds the
-     * response body back as the tool result. All handlers must be public HTTPS
-     * endpoints.
+     * POSTs `{ "name": <tool name>, "arguments": <the model's input object> }`
+     * as JSON to the corresponding URL and feeds the response body back as the
+     * tool result. All handlers must be public HTTPS endpoints.
      *
      * @example
      * { search: 'https://api.example.com/search', calculator: 'https://api.example.com/calc' }
@@ -199,10 +234,9 @@ interface RunParams {
      * the loop begins — the session stays on that provider for all turns. When
      * the session history is fully translatable, routing may cross the
      * Anthropic ↔ OpenAI-compatible boundary; the canonical layer handles tool
-     * schema translation automatically. Omit to let Rouva select the cheapest
-     * capable model automatically.
+     * schema translation automatically. Required by /run.
      */
-    model?: RouvaModel;
+    model: RouvaModel;
     /**
      * Force a specific provider when paired with `model`.
      */
@@ -222,8 +256,9 @@ interface RunParams {
      */
     temperature?: number;
     /**
-     * Hard cap on total session spend in USD. The loop exits cleanly when the
-     * cumulative cost of all turns reaches this threshold.
+     * Hard cap on total session spend in USD. The loop exits cleanly (with
+     * `finish_reason: "session_budget_exceeded"`) when the cumulative cost of
+     * all turns reaches this threshold.
      */
     session_budget_usd?: number;
 }
@@ -237,15 +272,27 @@ interface RunResult {
     /** Session ID — all turns are grouped under this ID in the Rouva dashboard. */
     session_id: string;
     /**
-     * Why the loop exited: `"stop"` (model finished), `"max_turns"` (turn limit
-     * reached), `"budget_exceeded"` (session_budget_usd hit), or a provider
-     * finish reason such as `"end_turn"` or `"length"`.
+     * Why the loop exited: `"stop"` (the model finished — reported as "stop" for
+     * every provider), `"max_turns"` (turn limit reached),
+     * `"session_budget_exceeded"` (session_budget_usd hit), or a truncation
+     * reason such as `"length"` / `"max_tokens"` (then `error` explains it).
      */
     finish_reason: string | null;
-    /** USD cost of the final turn. */
-    cost_usd: number;
     /** Cumulative USD cost of all turns in the session. */
     session_cost_usd: number;
+    /**
+     * True when a turn reported no usage, so `session_cost_usd` is a lower
+     * bound rather than the full cost.
+     */
+    session_cost_incomplete?: boolean;
+    /** Set when Intelligent Routing chose a different model than requested. */
+    routed_model?: string;
+    requested_model?: string;
+    /**
+     * Explanation when the run stopped early but still returned 200 — e.g.
+     * output truncated on the last turn (raise `max_tokens`).
+     */
+    error?: string;
 }
 
 declare class Rouva {
@@ -254,7 +301,7 @@ declare class Rouva {
     private _sessionId;
     readonly chat: {
         completions: {
-            create(params: ChatCompletionParams): Promise<ChatCompletion | ReadableStream>;
+            create(params: ChatCompletionParams, options?: RequestOptions): Promise<ChatCompletion | ReadableStream>;
         };
     };
     constructor(options: RouvaOptions);
@@ -273,9 +320,15 @@ declare class Rouva {
     /** The active session ID, or undefined if no session is in progress. */
     get sessionId(): string | undefined;
     /**
-     * Run a server-side agentic loop. The gateway calls the model, dispatches
-     * tool calls in parallel to your handler URLs, and loops until the model
-     * stops or limits are reached — no streaming, no client-side loop required.
+     * Run a server-side agentic loop (`POST /api/gateway/run`). The gateway
+     * calls the model, POSTs each tool call to its handler URL as
+     * `{ name, arguments }` (in parallel), feeds the response bodies back as tool
+     * results, and loops until the model stops or a limit is reached — no
+     * streaming, no client-side loop required. Throws `RouvaError` on a non-2xx
+     * response; once the loop has started, its `body` also carries the partial
+     * `turns`, `session_id` and `session_cost_usd` (errors before the first turn
+     * — validation, no key, allowlist — carry only `error`). Pass
+     * `{ signal }` to cancel; a run can take several minutes.
      *
      * Every turn is logged as a usage snapshot grouped by `session_id` in the
      * Rouva dashboard, giving you a full session replay with per-turn cost,
@@ -293,8 +346,36 @@ declare class Rouva {
      * console.log(result.turns)        // how many turns it took
      * console.log(result.session_id)   // dashboard session ID
      */
-    run(params: RunParams): Promise<RunResult>;
+    run(params: RunParams, options?: RequestOptions): Promise<RunResult>;
+    private _post;
     private _createChatCompletion;
 }
 
-export { type AssistantToolCallMessage, type ChatCompletion, type ChatCompletionChoice, type ChatCompletionParams, type ChatCompletionUsage, type ChatMessage, type ContentBlockMessage, type FunctionToolCall, type Message, type ResponseMessage, Rouva, type RouvaOptions, type RouvaProvider, type RouvaResponseMeta, type RunParams, type RunResult, type SystemTextBlock, type ToolResultMessage };
+/**
+ * Thrown for any non-2xx gateway response. Extends Error and keeps the
+ * message format of earlier versions (`[Rouva] Gateway error 429: …`), so
+ * existing `catch` blocks keep working; the fields make refusals actionable.
+ */
+declare class RouvaError extends Error {
+    /** HTTP status from the gateway. */
+    readonly status: number;
+    /**
+     * Why Rouva itself refused the request before contacting the provider, when
+     * the gateway marks it (header `X-Rouva-Refusal`): `"key_cap"` /
+     * `"member_cap"` (a monthly spend cap would be exceeded), `"rate"` (rate
+     * limit), `"unpriced"` (a capped key can't use a model with no known price),
+     * `"unbounded"` (a capped key can't send input whose cost can't be bounded).
+     * Not every refusal carries it yet — a 429 with `retryAfter` and no
+     * `refusal` can still be a Rouva cap or rate refusal; read `error`.
+     */
+    readonly refusal?: string;
+    /** Seconds to wait before retrying, from `Retry-After`, when present. */
+    readonly retryAfter?: number;
+    /** The gateway's error message (`error` field), when the body is JSON. */
+    readonly error?: string;
+    /** The parsed JSON body, or the raw text when it isn't JSON. */
+    readonly body: unknown;
+    constructor(kind: 'Gateway' | 'Run', status: number, headers: Headers, rawBody: string);
+}
+
+export { type AssistantToolCallMessage, type ChatCompletion, type ChatCompletionChoice, type ChatCompletionParams, type ChatCompletionUsage, type ChatMessage, type ContentBlockMessage, type FunctionToolCall, type Message, type RequestOptions, type ResponseMessage, Rouva, RouvaError, type RouvaModel, type RouvaOptions, type RouvaProvider, type RouvaResponseMeta, type RunParams, type RunResult, type SystemTextBlock, type ToolResultMessage };

package/dist/index.js

@@ -20,7 +20,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  Rouva: () => Rouva
+  Rouva: () => Rouva,
+  RouvaError: () => RouvaError
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -246,8 +247,9 @@ function normalizeGatewayStream(stream) {
             }
           }
         }
-      } finally {
         controller.close();
+      } catch (err) {
+        controller.error(err);
       }
     }
   });
@@ -354,19 +356,47 @@ async function readChatCompletionFromSse(stream, metadata) {
   return response;
 }
 function getRouvaMetadata(headers) {
-  const modelUsed = headers.get("x-rouva-model") ?? void 0;
-  const providerUsed = headers.get("x-rouva-provider") ?? void 0;
-  const taskType = headers.get("x-rouva-task") ?? void 0;
-  const cache = headers.get("x-rouva-cache") ?? void 0;
-  if (!modelUsed && !providerUsed && !taskType && !cache) return void 0;
+  const read = (name) => headers.get(name) || void 0;
+  const modelUsed = read("x-rouva-model");
+  const providerUsed = read("x-rouva-provider");
+  const taskType = read("x-rouva-task");
+  const dedup = headers.get("x-rouva-dedup") === "1" ? true : void 0;
+  if (!modelUsed && !providerUsed && !taskType && !dedup) return void 0;
   return {
     model_used: modelUsed,
     provider_used: providerUsed,
     task_type: taskType,
-    cache
+    ...dedup ? { dedup } : {}
   };
 }
 
+// src/errors.ts
+var RouvaError = class extends Error {
+  constructor(kind, status, headers, rawBody) {
+    super(`[Rouva] ${kind} error ${status}: ${rawBody}`);
+    this.name = "RouvaError";
+    this.status = status;
+    this.refusal = headers.get("x-rouva-refusal") ?? void 0;
+    const retry = Number(headers.get("retry-after"));
+    this.retryAfter = headers.get("retry-after") !== null && Number.isFinite(retry) ? retry : void 0;
+    let parsed = rawBody;
+    try {
+      parsed = JSON.parse(rawBody);
+    } catch {
+    }
+    this.body = parsed;
+    const e = parsed?.error;
+    this.error = typeof e === "string" ? e : void 0;
+  }
+};
+async function toRouvaError(kind, res) {
+  const raw = await res.text().catch((err) => {
+    if (err?.name === "AbortError") throw err;
+    return res.statusText;
+  });
+  return new RouvaError(kind, res.status, res.headers, raw);
+}
+
 // src/client.ts
 var DEFAULT_BASE_URL = "https://app.rouva.io";
 var Rouva = class {
@@ -379,7 +409,7 @@ var Rouva = class {
     this.baseURL = (options.baseURL ?? DEFAULT_BASE_URL).replace(/\/$/, "");
     this.chat = {
       completions: {
-        create: (params) => this._createChatCompletion(params)
+        create: (params, options2) => this._createChatCompletion(params, options2)
       }
     };
   }
@@ -405,9 +435,15 @@ var Rouva = class {
     return this._sessionId;
   }
   /**
-   * Run a server-side agentic loop. The gateway calls the model, dispatches
-   * tool calls in parallel to your handler URLs, and loops until the model
-   * stops or limits are reached — no streaming, no client-side loop required.
+   * Run a server-side agentic loop (`POST /api/gateway/run`). The gateway
+   * calls the model, POSTs each tool call to its handler URL as
+   * `{ name, arguments }` (in parallel), feeds the response bodies back as tool
+   * results, and loops until the model stops or a limit is reached — no
+   * streaming, no client-side loop required. Throws `RouvaError` on a non-2xx
+   * response; once the loop has started, its `body` also carries the partial
+   * `turns`, `session_id` and `session_cost_usd` (errors before the first turn
+   * — validation, no key, allowlist — carry only `error`). Pass
+   * `{ signal }` to cancel; a run can take several minutes.
    *
    * Every turn is logged as a usage snapshot grouped by `session_id` in the
    * Rouva dashboard, giving you a full session replay with per-turn cost,
@@ -425,39 +461,29 @@ var Rouva = class {
    * console.log(result.turns)        // how many turns it took
    * console.log(result.session_id)   // dashboard session ID
    */
-  async run(params) {
-    const url = `${this.baseURL}/api/gateway/run`;
-    const res = await fetch(url, {
+  async run(params, options) {
+    const res = await this._post("/api/gateway/run", params, {}, options);
+    if (!res.ok) throw await toRouvaError("Run", res);
+    return res.json();
+  }
+  // One request path for every endpoint: auth, JSON body, optional abort signal.
+  _post(path, body, extraHeaders, options) {
+    return fetch(`${this.baseURL}${path}`, {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
-        "Authorization": `Bearer ${this.apiKey}`
+        "Authorization": `Bearer ${this.apiKey}`,
+        ...extraHeaders
       },
-      body: JSON.stringify(params)
+      body: JSON.stringify(body),
+      ...options?.signal ? { signal: options.signal } : {}
     });
-    if (!res.ok) {
-      const body = await res.text().catch(() => res.statusText);
-      throw new Error(`[Rouva] Run error ${res.status}: ${body}`);
-    }
-    return res.json();
   }
-  async _createChatCompletion(params) {
-    const url = `${this.baseURL}/api/gateway/messages`;
+  async _createChatCompletion(params, options) {
     const { stream: _stream, ...body } = params;
-    const headers = {
-      "Content-Type": "application/json",
-      "Authorization": `Bearer ${this.apiKey}`
-    };
-    if (this._sessionId) headers["x-rouva-session-id"] = this._sessionId;
-    const res = await fetch(url, {
-      method: "POST",
-      headers,
-      body: JSON.stringify(body)
-    });
-    if (!res.ok) {
-      const body2 = await res.text().catch(() => res.statusText);
-      throw new Error(`[Rouva] Gateway error ${res.status}: ${body2}`);
-    }
+    const sessionHeader = this._sessionId ? { "x-rouva-session-id": this._sessionId } : {};
+    const res = await this._post("/api/gateway/messages", body, sessionHeader, options);
+    if (!res.ok) throw await toRouvaError("Gateway", res);
     if (!res.body) throw new Error("[Rouva] No response body from gateway");
     const normalizedStream = normalizeGatewayStream(res.body);
     if (params.stream) return normalizedStream;
@@ -466,5 +492,6 @@ var Rouva = class {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  Rouva
+  Rouva,
+  RouvaError
 });

package/dist/index.mjs

@@ -220,8 +220,9 @@ function normalizeGatewayStream(stream) {
             }
           }
         }
-      } finally {
         controller.close();
+      } catch (err) {
+        controller.error(err);
       }
     }
   });
@@ -328,19 +329,47 @@ async function readChatCompletionFromSse(stream, metadata) {
   return response;
 }
 function getRouvaMetadata(headers) {
-  const modelUsed = headers.get("x-rouva-model") ?? void 0;
-  const providerUsed = headers.get("x-rouva-provider") ?? void 0;
-  const taskType = headers.get("x-rouva-task") ?? void 0;
-  const cache = headers.get("x-rouva-cache") ?? void 0;
-  if (!modelUsed && !providerUsed && !taskType && !cache) return void 0;
+  const read = (name) => headers.get(name) || void 0;
+  const modelUsed = read("x-rouva-model");
+  const providerUsed = read("x-rouva-provider");
+  const taskType = read("x-rouva-task");
+  const dedup = headers.get("x-rouva-dedup") === "1" ? true : void 0;
+  if (!modelUsed && !providerUsed && !taskType && !dedup) return void 0;
   return {
     model_used: modelUsed,
     provider_used: providerUsed,
     task_type: taskType,
-    cache
+    ...dedup ? { dedup } : {}
   };
 }
 
+// src/errors.ts
+var RouvaError = class extends Error {
+  constructor(kind, status, headers, rawBody) {
+    super(`[Rouva] ${kind} error ${status}: ${rawBody}`);
+    this.name = "RouvaError";
+    this.status = status;
+    this.refusal = headers.get("x-rouva-refusal") ?? void 0;
+    const retry = Number(headers.get("retry-after"));
+    this.retryAfter = headers.get("retry-after") !== null && Number.isFinite(retry) ? retry : void 0;
+    let parsed = rawBody;
+    try {
+      parsed = JSON.parse(rawBody);
+    } catch {
+    }
+    this.body = parsed;
+    const e = parsed?.error;
+    this.error = typeof e === "string" ? e : void 0;
+  }
+};
+async function toRouvaError(kind, res) {
+  const raw = await res.text().catch((err) => {
+    if (err?.name === "AbortError") throw err;
+    return res.statusText;
+  });
+  return new RouvaError(kind, res.status, res.headers, raw);
+}
+
 // src/client.ts
 var DEFAULT_BASE_URL = "https://app.rouva.io";
 var Rouva = class {
@@ -353,7 +382,7 @@ var Rouva = class {
     this.baseURL = (options.baseURL ?? DEFAULT_BASE_URL).replace(/\/$/, "");
     this.chat = {
       completions: {
-        create: (params) => this._createChatCompletion(params)
+        create: (params, options2) => this._createChatCompletion(params, options2)
       }
     };
   }
@@ -379,9 +408,15 @@ var Rouva = class {
     return this._sessionId;
   }
   /**
-   * Run a server-side agentic loop. The gateway calls the model, dispatches
-   * tool calls in parallel to your handler URLs, and loops until the model
-   * stops or limits are reached — no streaming, no client-side loop required.
+   * Run a server-side agentic loop (`POST /api/gateway/run`). The gateway
+   * calls the model, POSTs each tool call to its handler URL as
+   * `{ name, arguments }` (in parallel), feeds the response bodies back as tool
+   * results, and loops until the model stops or a limit is reached — no
+   * streaming, no client-side loop required. Throws `RouvaError` on a non-2xx
+   * response; once the loop has started, its `body` also carries the partial
+   * `turns`, `session_id` and `session_cost_usd` (errors before the first turn
+   * — validation, no key, allowlist — carry only `error`). Pass
+   * `{ signal }` to cancel; a run can take several minutes.
    *
    * Every turn is logged as a usage snapshot grouped by `session_id` in the
    * Rouva dashboard, giving you a full session replay with per-turn cost,
@@ -399,39 +434,29 @@ var Rouva = class {
    * console.log(result.turns)        // how many turns it took
    * console.log(result.session_id)   // dashboard session ID
    */
-  async run(params) {
-    const url = `${this.baseURL}/api/gateway/run`;
-    const res = await fetch(url, {
+  async run(params, options) {
+    const res = await this._post("/api/gateway/run", params, {}, options);
+    if (!res.ok) throw await toRouvaError("Run", res);
+    return res.json();
+  }
+  // One request path for every endpoint: auth, JSON body, optional abort signal.
+  _post(path, body, extraHeaders, options) {
+    return fetch(`${this.baseURL}${path}`, {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
-        "Authorization": `Bearer ${this.apiKey}`
+        "Authorization": `Bearer ${this.apiKey}`,
+        ...extraHeaders
       },
-      body: JSON.stringify(params)
+      body: JSON.stringify(body),
+      ...options?.signal ? { signal: options.signal } : {}
     });
-    if (!res.ok) {
-      const body = await res.text().catch(() => res.statusText);
-      throw new Error(`[Rouva] Run error ${res.status}: ${body}`);
-    }
-    return res.json();
   }
-  async _createChatCompletion(params) {
-    const url = `${this.baseURL}/api/gateway/messages`;
+  async _createChatCompletion(params, options) {
     const { stream: _stream, ...body } = params;
-    const headers = {
-      "Content-Type": "application/json",
-      "Authorization": `Bearer ${this.apiKey}`
-    };
-    if (this._sessionId) headers["x-rouva-session-id"] = this._sessionId;
-    const res = await fetch(url, {
-      method: "POST",
-      headers,
-      body: JSON.stringify(body)
-    });
-    if (!res.ok) {
-      const body2 = await res.text().catch(() => res.statusText);
-      throw new Error(`[Rouva] Gateway error ${res.status}: ${body2}`);
-    }
+    const sessionHeader = this._sessionId ? { "x-rouva-session-id": this._sessionId } : {};
+    const res = await this._post("/api/gateway/messages", body, sessionHeader, options);
+    if (!res.ok) throw await toRouvaError("Gateway", res);
     if (!res.body) throw new Error("[Rouva] No response body from gateway");
     const normalizedStream = normalizeGatewayStream(res.body);
     if (params.stream) return normalizedStream;
@@ -439,5 +464,6 @@ var Rouva = class {
   }
 };
 export {
-  Rouva
+  Rouva,
+  RouvaError
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rouvanpm/rouva",
-  "version": "0.2.13",
+  "version": "0.3.0",
   "description": "Official Node.js SDK for Rouva — managed AI gateway with intelligent routing and spend tracking",
   "main": "dist/index.js",
   "module": "dist/index.mjs",