@rouvanpm/rouva 0.3.1 → 0.4.0

package/README.md

@@ -80,13 +80,13 @@ while (true) {
 
 Streaming responses are normalized to OpenAI-style SSE chunks, even when Rouva routes the request to Anthropic.
 
-`stream` is a client-side toggle: `stream: true` returns the raw `ReadableStream`, omitting it (or `stream: false`) returns a buffered `ChatCompletion`. It is never sent to the gateway.
+`stream` is a client-side toggle: `stream: true` returns the raw `ReadableStream` (with the routing metadata on `_rouva` — see [Response metadata](#response-metadata)), omitting it (or `stream: false`) returns a buffered `ChatCompletion`. It is never sent to the gateway.
 
 ## Request parameters
 
 ```typescript
 const res = await rouva.chat.completions.create({
-  model: 'gpt-4o-mini',                    // required when using seed (OpenAI only)
+  model: 'gpt-6-luna',                     // 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 (or max_completion_tokens)
@@ -104,8 +104,9 @@ const res = await rouva.chat.completions.create({
 - **`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).
+- **`response_format`** — JSON mode or a JSON schema; see [Structured output](#structured-output).
 
-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.
+Unsupported OpenAI options (`logit_bias`, `logprobs`, `reasoning_effort`, `n > 1`, the legacy `functions`/`function_call` fields, …) are rejected by the gateway with an explicit 400 rather than silently ignored.
 
 ## Unlisted models
 
@@ -313,20 +314,67 @@ Sessions are optional — requests without an active session are tracked individ
 
 ## Response metadata
 
-Parsed non-stream responses may include a `_rouva` field with gateway header metadata when available:
+Every response says what Rouva decided, in `_rouva` — on a buffered completion, and on the stream `stream: true` returns (the headers arrive before the first chunk):
 
 ```typescript
 const res = await rouva.chat.completions.create({ messages })
 
 console.log(res._rouva)
 // {
-//   model_used: 'gpt-4o-mini',
+//   request_id: '7c0e…',          // your request log's id for it
+//   model_used: 'gpt-6-luna',
 //   provider_used: 'openai',
+//   requested_model: 'gpt-6-sol', // only when Rouva served a different model
 //   task_type: 'summarize',
-//   dedup: true             // only when served from the duplicate-request cache
+//   route_reason: 'intelligent',  // override | allowlist | fallback | no_key_fallback | direct | escalation | dedup
+//   dedup: true                   // only when served from the duplicate-request cache
 // }
 ```
 
+### Cost, savings and quality score — `rouva.requests.get(id)`
+
+A request's cost is known only once its last chunk has arrived, and its quality score once the judge has run, so read them back by `request_id`:
+
+```typescript
+import type { RouvaStream } from '@rouvanpm/rouva'
+
+const stream = await rouva.chat.completions.create({ messages, stream: true }) as RouvaStream
+// ...consume the stream...
+
+const id = stream._rouva?.request_id // absent on a duplicate-cache replay (cost 0)
+if (id) {
+  const req = await rouva.requests.get(id)
+  console.log(req.status)        // 'pending' | 'incomplete' | 'settled' | 'scored'
+  console.log(req.cost_usd)      // e.g. 0.000412
+  console.log(req.saved_usd)     // vs the model you named (negative when the route cost more)
+  console.log(req.quality_score) // 0–1, once scored
+  console.log(req.dashboard_url) // opens it in your request log
+}
+```
+
+`pending` means it hasn't settled yet — retry after a moment. `incomplete` means it settled from partial usage (a stream cut short), so the provider may have billed more; `settled` and `scored` costs are final. A key reads only its own requests. A duplicate-cache replay has no `request_id` (nothing new was recorded or charged).
+
+## Structured output
+
+`response_format` asks for JSON: `{ type: 'json_object' }` (JSON mode — your prompt must mention "json") or `{ type: 'json_schema', json_schema: { name, schema, strict } }` (the answer follows your schema). Rouva only routes to models that serve the format; see [the docs](https://rouva.io/docs#structured-output) for which models do.
+
+```typescript
+import type { ChatCompletion } from '@rouvanpm/rouva'
+
+const res = await rouva.chat.completions.create({
+  messages: [{ role: 'user', content: 'Extract the city: "Flying to Paris on Monday."' }],
+  response_format: {
+    type: 'json_schema',
+    json_schema: {
+      name: 'city',
+      strict: true,
+      schema: { type: 'object', properties: { city: { type: 'string' } }, required: ['city'], additionalProperties: false },
+    },
+  },
+}) as ChatCompletion
+const { city } = JSON.parse(res.choices[0].message.content!)
+```
+
 ## Errors
 
 Any non-2xx response throws a `RouvaError` (a subclass of `Error`, so existing `catch` blocks keep working):
@@ -338,14 +386,15 @@ 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.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
+    console.log(e.requestId)   // when the request was recorded — rouva.requests.get(e.requestId)
   }
 }
 ```
 
-`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`). Every Rouva refusal is marked, so a `429` without `refusal` came from the provider, not from Rouva. Every call also takes `{ signal }` as a second argument to abort it.
+`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`), for spend-capped keys a model with no known price (`unpriced`) or input or a model whose cost can't be bounded (`unbounded`), or — a `504` — the request ran out of its time budget before the provider was called (`deadline`; nothing was sent, so it's safe to retry, and `retryAfter` is set). Every Rouva refusal is marked, so a `429` or `504` without `refusal` came from the provider, not from Rouva — with one exception: `rouva.run()` returns an unmarked `504` "Run deadline exceeded before completion" when the run runs out of time, because earlier turns were already billed and their tool handlers ran; check what completed before retrying it. Every call also takes `{ signal }` as a second argument to abort it.
 
 ## Getting your API key
 

package/dist/index.d.mts

@@ -64,7 +64,7 @@ type RouvaProvider = 'anthropic' | 'openai' | 'gemini' | 'deepseek' | 'mistral'
  *
  * `'gpt-5.6'` is a deprecated alias the gateway maps to `'gpt-5.6-sol'`.
  */
-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' | 'qwen3.8-flash' | 'qwen3.7-plus' | 'qwen-max' | 'qwen-plus' | 'qwen-flash' | (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-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' | 'deepseek-flash-think' | 'deepseek-v4-pro' | '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' | 'qwen3.8-flash' | 'qwen3.7-plus' | 'qwen-max' | 'qwen-plus' | 'qwen-flash' | (string & {});
 /** Anthropic-style text block — the array form of the `system` param */
 interface SystemTextBlock {
     type: 'text';
@@ -132,6 +132,17 @@ interface ChatCompletionParams {
      * no cheaper-model substitution, no cross-provider fallbacks.
      */
     seed?: number;
+    /**
+     * Ask for JSON output (gateway support since 2026-10-20). `json_object` is
+     * JSON mode: the prompt (a message or `system`) must contain the word
+     * "json", or the gateway returns a 400. `json_schema` is Structured Outputs:
+     * the answer follows your schema. Routing only picks a model that serves the
+     * format; Claude models serve `json_schema` only (every object needs
+     * `additionalProperties: false`), and not when the conversation ends with an
+     * assistant message. `{ type: 'text' }` or `null` is the default (no-op).
+     * `rouva.run()` doesn't accept it. See https://rouva.io/docs#structured-output
+     */
+    response_format?: ResponseFormat | null;
     /**
      * Stream the response. Client-side only — controls whether `create()`
      * returns a ReadableStream or a buffered ChatCompletion; never sent to
@@ -154,6 +165,22 @@ interface ChatCompletionParams {
      */
     tool_choice?: string | Record<string, unknown>;
 }
+/** `response_format` values the gateway accepts. */
+type ResponseFormat = {
+    type: 'text';
+} | {
+    type: 'json_object';
+} | {
+    type: 'json_schema';
+    json_schema: {
+        /** 1–64 letters, digits, underscores or dashes. */
+        name: string;
+        /** A JSON Schema object. */
+        schema: Record<string, unknown>;
+        strict?: boolean;
+        description?: string;
+    };
+};
 /** Assistant message in a completed response; `tool_calls` present when the model requested tools */
 interface ResponseMessage {
     role: 'assistant';
@@ -180,13 +207,42 @@ interface ChatCompletion {
     /** Rouva metadata — cost, savings, routing decision */
     _rouva?: RouvaResponseMeta;
 }
+/**
+ * Why Rouva sent a request to the model it did (header `X-Rouva-Route-Reason`):
+ * `intelligent` (Intelligent Routing chose it), `override` (an account routing
+ * override), `allowlist` (a workspace member's allowed-model list),
+ * `fallback` (a retry after a provider error), `escalation` (`run()` stepped
+ * up a model), `no_key_fallback` (the named provider has no key, so a
+ * connected one stood in), `direct` (the model you named, as named), or
+ * `dedup` (a replay of an identical request — no new call was made).
+ */
+type RouvaRouteReason = 'intelligent' | 'override' | 'allowlist' | 'fallback' | 'escalation' | 'no_key_fallback' | 'direct' | 'dedup' | (string & {});
 interface RouvaResponseMeta {
-    /** Actual model used when exposed by the gateway */
+    /**
+     * The request's id in your Rouva request log (`X-Rouva-Request-Id`). Pass it
+     * to `rouva.requests.get(id)` for the request's cost, savings and quality
+     * score. Absent on a duplicate-cache replay (no new request was recorded).
+     */
+    request_id?: string;
+    /** The model that served the request — after a fallback, the fallback model. */
     model_used?: string;
-    /** Actual provider used when exposed by the gateway */
+    /** That model's provider, e.g. `openai`, `anthropic`. */
     provider_used?: string;
-    /** Task type classified by Rouva when exposed by the gateway */
+    /** The model you named, when Rouva served a different one. */
+    requested_model?: string;
+    /** Task type classified by Rouva, e.g. `code`; absent when not classified. */
     task_type?: string;
+    /** Why this model was chosen. */
+    route_reason?: RouvaRouteReason;
+    /**
+     * What the request cost in USD, when the gateway sent it in a header: only
+     * on non-streaming responses once the cost is final, and as 0 on a
+     * duplicate-cache replay (`dedup: true`). The SDK streams, so otherwise read
+     * cost with `rouva.requests.get(request_id)`.
+     */
+    cost_usd?: number;
+    /** Saved against the model you named (or the priciest candidate), in USD; negative when the route cost more. Same availability as `cost_usd`. */
+    saved_usd?: number;
     /**
      * True when the gateway answered from its duplicate-request cache (an
      * identical request within the last 60 seconds) instead of calling the
@@ -199,6 +255,48 @@ interface RouvaResponseMeta {
      */
     cache?: string;
 }
+/**
+ * The stream `chat.completions.create({ stream: true })` returns: OpenAI-shaped
+ * SSE bytes, plus the routing metadata from the response headers (known
+ * before the first chunk).
+ */
+type RouvaStream = ReadableStream<Uint8Array> & {
+    _rouva?: RouvaResponseMeta;
+};
+/**
+ * A request's settlement state: `pending` (not settled yet — in flight, or it
+ * never reached the provider), `incomplete` (settled from partial usage, e.g. a
+ * stream cut short — the provider may have billed more), `settled` (tokens and
+ * cost are final), `scored` (final, and a quality score is recorded).
+ */
+type RouvaRequestStatus = 'pending' | 'incomplete' | 'settled' | 'scored' | (string & {});
+/** One request from your request log — `rouva.requests.get(id)`. */
+interface RouvaRequest {
+    id: string;
+    /** ISO timestamp. */
+    created_at: string;
+    status: RouvaRequestStatus;
+    provider: string;
+    model: string;
+    requested_model: string | null;
+    task_type: string | null;
+    route_reason: RouvaRouteReason | null;
+    /** 0 while pending. */
+    input_tokens: number;
+    output_tokens: number;
+    /** USD; 0 while pending. Final once `status` is `settled` or `scored`. */
+    cost_usd: number;
+    /** USD saved against the model you named (or the priciest candidate); negative when the route cost more. */
+    saved_usd: number;
+    /** 0–1, or null until a score is recorded (or when none is). */
+    quality_score: number | null;
+    /** Whether the judge scored it, or why not (then `quality_score` is the heuristic checks'). */
+    judge_status: string | null;
+    finish_reason: string | null;
+    session_id: string | null;
+    /** Opens this request in the dashboard's request log. */
+    dashboard_url: string;
+}
 interface RunParams {
     /**
      * Conversation history to seed the agent loop with.
@@ -301,9 +399,30 @@ declare class Rouva {
     private _sessionId;
     readonly chat: {
         completions: {
-            create(params: ChatCompletionParams, options?: RequestOptions): Promise<ChatCompletion | ReadableStream>;
+            create(params: ChatCompletionParams, options?: RequestOptions): Promise<ChatCompletion | RouvaStream>;
         };
     };
+    readonly requests: {
+        /**
+         * Read one request from your request log (`GET /api/gateway/requests/{id}`)
+         * by the id a response carried (`_rouva.request_id`, header
+         * `X-Rouva-Request-Id`): its model, routing reason, tokens, cost, savings and
+         * quality score. A key reads only its own requests (another's id is a 404).
+         *
+         * A stream's cost is recorded just after its last chunk, and the quality
+         * score once the judge has run (a few seconds), so check `status`:
+         * `pending` → not settled yet, retry shortly; `incomplete` → settled from
+         * partial usage; `settled` → cost final; `scored` → cost final and scored.
+         * Throws `RouvaError` on a non-2xx response (a 503 carries `retryAfter`).
+         *
+         * @example
+         * const stream = await rouva.chat.completions.create({ messages, stream: true }) as RouvaStream
+         * // ...consume the stream...
+         * const req = await rouva.requests.get(stream._rouva!.request_id!)
+         * console.log(req.status, req.cost_usd, req.saved_usd)
+         */
+        get(id: string, options?: RequestOptions): Promise<RouvaRequest>;
+    };
     constructor(options: RouvaOptions);
     /**
      * Start a new agent session. Every subsequent `chat.completions.create()`
@@ -347,7 +466,9 @@ declare class Rouva {
      * console.log(result.session_id)   // dashboard session ID
      */
     run(params: RunParams, options?: RequestOptions): Promise<RunResult>;
+    private _getRequest;
     private _post;
+    private _fetch;
     private _createChatCompletion;
 }
 
@@ -364,18 +485,30 @@ declare class RouvaError extends Error {
      * 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).
-     * Every Rouva cap, rate-limit and pricing refusal carries it, so a 429
-     * without `refusal` came from the provider, not from Rouva.
+     * `"unbounded"` (a capped key can't send input, or use a model, whose cost
+     * can't be bounded), `"deadline"` (a 504: the request ran out of its time
+     * budget before the provider was called — nothing was sent, so it's safe to
+     * retry; `retryAfter` is set). Every Rouva cap, rate-limit, pricing and time
+     * refusal carries it, so a 429 or 504 without `refusal` came from the
+     * provider — except `rouva.run()`'s "Run deadline exceeded" 504, which is
+     * Rouva's but deliberately unmarked: earlier turns were billed and their
+     * tool handlers ran, so it must not be retried blindly.
      */
     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 request's id in your Rouva request log (`X-Rouva-Request-Id`), when
+     * the error came after the request was recorded — e.g. a provider error.
+     * Look it up with `rouva.requests.get(requestId)`. Absent on errors Rouva
+     * returns before recording the request (validation 400s, auth).
+     */
+    readonly requestId?: 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);
+    constructor(kind: 'Gateway' | 'Run' | 'Request', 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 };
+export { type AssistantToolCallMessage, type ChatCompletion, type ChatCompletionChoice, type ChatCompletionParams, type ChatCompletionUsage, type ChatMessage, type ContentBlockMessage, type FunctionToolCall, type Message, type RequestOptions, type ResponseFormat, type ResponseMessage, Rouva, RouvaError, type RouvaModel, type RouvaOptions, type RouvaProvider, type RouvaRequest, type RouvaRequestStatus, type RouvaResponseMeta, type RouvaRouteReason, type RouvaStream, type RunParams, type RunResult, type SystemTextBlock, type ToolResultMessage };

package/dist/index.d.ts

@@ -64,7 +64,7 @@ type RouvaProvider = 'anthropic' | 'openai' | 'gemini' | 'deepseek' | 'mistral'
  *
  * `'gpt-5.6'` is a deprecated alias the gateway maps to `'gpt-5.6-sol'`.
  */
-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' | 'qwen3.8-flash' | 'qwen3.7-plus' | 'qwen-max' | 'qwen-plus' | 'qwen-flash' | (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-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' | 'deepseek-flash-think' | 'deepseek-v4-pro' | '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' | 'qwen3.8-flash' | 'qwen3.7-plus' | 'qwen-max' | 'qwen-plus' | 'qwen-flash' | (string & {});
 /** Anthropic-style text block — the array form of the `system` param */
 interface SystemTextBlock {
     type: 'text';
@@ -132,6 +132,17 @@ interface ChatCompletionParams {
      * no cheaper-model substitution, no cross-provider fallbacks.
      */
     seed?: number;
+    /**
+     * Ask for JSON output (gateway support since 2026-10-20). `json_object` is
+     * JSON mode: the prompt (a message or `system`) must contain the word
+     * "json", or the gateway returns a 400. `json_schema` is Structured Outputs:
+     * the answer follows your schema. Routing only picks a model that serves the
+     * format; Claude models serve `json_schema` only (every object needs
+     * `additionalProperties: false`), and not when the conversation ends with an
+     * assistant message. `{ type: 'text' }` or `null` is the default (no-op).
+     * `rouva.run()` doesn't accept it. See https://rouva.io/docs#structured-output
+     */
+    response_format?: ResponseFormat | null;
     /**
      * Stream the response. Client-side only — controls whether `create()`
      * returns a ReadableStream or a buffered ChatCompletion; never sent to
@@ -154,6 +165,22 @@ interface ChatCompletionParams {
      */
     tool_choice?: string | Record<string, unknown>;
 }
+/** `response_format` values the gateway accepts. */
+type ResponseFormat = {
+    type: 'text';
+} | {
+    type: 'json_object';
+} | {
+    type: 'json_schema';
+    json_schema: {
+        /** 1–64 letters, digits, underscores or dashes. */
+        name: string;
+        /** A JSON Schema object. */
+        schema: Record<string, unknown>;
+        strict?: boolean;
+        description?: string;
+    };
+};
 /** Assistant message in a completed response; `tool_calls` present when the model requested tools */
 interface ResponseMessage {
     role: 'assistant';
@@ -180,13 +207,42 @@ interface ChatCompletion {
     /** Rouva metadata — cost, savings, routing decision */
     _rouva?: RouvaResponseMeta;
 }
+/**
+ * Why Rouva sent a request to the model it did (header `X-Rouva-Route-Reason`):
+ * `intelligent` (Intelligent Routing chose it), `override` (an account routing
+ * override), `allowlist` (a workspace member's allowed-model list),
+ * `fallback` (a retry after a provider error), `escalation` (`run()` stepped
+ * up a model), `no_key_fallback` (the named provider has no key, so a
+ * connected one stood in), `direct` (the model you named, as named), or
+ * `dedup` (a replay of an identical request — no new call was made).
+ */
+type RouvaRouteReason = 'intelligent' | 'override' | 'allowlist' | 'fallback' | 'escalation' | 'no_key_fallback' | 'direct' | 'dedup' | (string & {});
 interface RouvaResponseMeta {
-    /** Actual model used when exposed by the gateway */
+    /**
+     * The request's id in your Rouva request log (`X-Rouva-Request-Id`). Pass it
+     * to `rouva.requests.get(id)` for the request's cost, savings and quality
+     * score. Absent on a duplicate-cache replay (no new request was recorded).
+     */
+    request_id?: string;
+    /** The model that served the request — after a fallback, the fallback model. */
     model_used?: string;
-    /** Actual provider used when exposed by the gateway */
+    /** That model's provider, e.g. `openai`, `anthropic`. */
     provider_used?: string;
-    /** Task type classified by Rouva when exposed by the gateway */
+    /** The model you named, when Rouva served a different one. */
+    requested_model?: string;
+    /** Task type classified by Rouva, e.g. `code`; absent when not classified. */
     task_type?: string;
+    /** Why this model was chosen. */
+    route_reason?: RouvaRouteReason;
+    /**
+     * What the request cost in USD, when the gateway sent it in a header: only
+     * on non-streaming responses once the cost is final, and as 0 on a
+     * duplicate-cache replay (`dedup: true`). The SDK streams, so otherwise read
+     * cost with `rouva.requests.get(request_id)`.
+     */
+    cost_usd?: number;
+    /** Saved against the model you named (or the priciest candidate), in USD; negative when the route cost more. Same availability as `cost_usd`. */
+    saved_usd?: number;
     /**
      * True when the gateway answered from its duplicate-request cache (an
      * identical request within the last 60 seconds) instead of calling the
@@ -199,6 +255,48 @@ interface RouvaResponseMeta {
      */
     cache?: string;
 }
+/**
+ * The stream `chat.completions.create({ stream: true })` returns: OpenAI-shaped
+ * SSE bytes, plus the routing metadata from the response headers (known
+ * before the first chunk).
+ */
+type RouvaStream = ReadableStream<Uint8Array> & {
+    _rouva?: RouvaResponseMeta;
+};
+/**
+ * A request's settlement state: `pending` (not settled yet — in flight, or it
+ * never reached the provider), `incomplete` (settled from partial usage, e.g. a
+ * stream cut short — the provider may have billed more), `settled` (tokens and
+ * cost are final), `scored` (final, and a quality score is recorded).
+ */
+type RouvaRequestStatus = 'pending' | 'incomplete' | 'settled' | 'scored' | (string & {});
+/** One request from your request log — `rouva.requests.get(id)`. */
+interface RouvaRequest {
+    id: string;
+    /** ISO timestamp. */
+    created_at: string;
+    status: RouvaRequestStatus;
+    provider: string;
+    model: string;
+    requested_model: string | null;
+    task_type: string | null;
+    route_reason: RouvaRouteReason | null;
+    /** 0 while pending. */
+    input_tokens: number;
+    output_tokens: number;
+    /** USD; 0 while pending. Final once `status` is `settled` or `scored`. */
+    cost_usd: number;
+    /** USD saved against the model you named (or the priciest candidate); negative when the route cost more. */
+    saved_usd: number;
+    /** 0–1, or null until a score is recorded (or when none is). */
+    quality_score: number | null;
+    /** Whether the judge scored it, or why not (then `quality_score` is the heuristic checks'). */
+    judge_status: string | null;
+    finish_reason: string | null;
+    session_id: string | null;
+    /** Opens this request in the dashboard's request log. */
+    dashboard_url: string;
+}
 interface RunParams {
     /**
      * Conversation history to seed the agent loop with.
@@ -301,9 +399,30 @@ declare class Rouva {
     private _sessionId;
     readonly chat: {
         completions: {
-            create(params: ChatCompletionParams, options?: RequestOptions): Promise<ChatCompletion | ReadableStream>;
+            create(params: ChatCompletionParams, options?: RequestOptions): Promise<ChatCompletion | RouvaStream>;
         };
     };
+    readonly requests: {
+        /**
+         * Read one request from your request log (`GET /api/gateway/requests/{id}`)
+         * by the id a response carried (`_rouva.request_id`, header
+         * `X-Rouva-Request-Id`): its model, routing reason, tokens, cost, savings and
+         * quality score. A key reads only its own requests (another's id is a 404).
+         *
+         * A stream's cost is recorded just after its last chunk, and the quality
+         * score once the judge has run (a few seconds), so check `status`:
+         * `pending` → not settled yet, retry shortly; `incomplete` → settled from
+         * partial usage; `settled` → cost final; `scored` → cost final and scored.
+         * Throws `RouvaError` on a non-2xx response (a 503 carries `retryAfter`).
+         *
+         * @example
+         * const stream = await rouva.chat.completions.create({ messages, stream: true }) as RouvaStream
+         * // ...consume the stream...
+         * const req = await rouva.requests.get(stream._rouva!.request_id!)
+         * console.log(req.status, req.cost_usd, req.saved_usd)
+         */
+        get(id: string, options?: RequestOptions): Promise<RouvaRequest>;
+    };
     constructor(options: RouvaOptions);
     /**
      * Start a new agent session. Every subsequent `chat.completions.create()`
@@ -347,7 +466,9 @@ declare class Rouva {
      * console.log(result.session_id)   // dashboard session ID
      */
     run(params: RunParams, options?: RequestOptions): Promise<RunResult>;
+    private _getRequest;
     private _post;
+    private _fetch;
     private _createChatCompletion;
 }
 
@@ -364,18 +485,30 @@ declare class RouvaError extends Error {
      * 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).
-     * Every Rouva cap, rate-limit and pricing refusal carries it, so a 429
-     * without `refusal` came from the provider, not from Rouva.
+     * `"unbounded"` (a capped key can't send input, or use a model, whose cost
+     * can't be bounded), `"deadline"` (a 504: the request ran out of its time
+     * budget before the provider was called — nothing was sent, so it's safe to
+     * retry; `retryAfter` is set). Every Rouva cap, rate-limit, pricing and time
+     * refusal carries it, so a 429 or 504 without `refusal` came from the
+     * provider — except `rouva.run()`'s "Run deadline exceeded" 504, which is
+     * Rouva's but deliberately unmarked: earlier turns were billed and their
+     * tool handlers ran, so it must not be retried blindly.
      */
     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 request's id in your Rouva request log (`X-Rouva-Request-Id`), when
+     * the error came after the request was recorded — e.g. a provider error.
+     * Look it up with `rouva.requests.get(requestId)`. Absent on errors Rouva
+     * returns before recording the request (validation 400s, auth).
+     */
+    readonly requestId?: 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);
+    constructor(kind: 'Gateway' | 'Run' | 'Request', 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 };
+export { type AssistantToolCallMessage, type ChatCompletion, type ChatCompletionChoice, type ChatCompletionParams, type ChatCompletionUsage, type ChatMessage, type ContentBlockMessage, type FunctionToolCall, type Message, type RequestOptions, type ResponseFormat, type ResponseMessage, Rouva, RouvaError, type RouvaModel, type RouvaOptions, type RouvaProvider, type RouvaRequest, type RouvaRequestStatus, type RouvaResponseMeta, type RouvaRouteReason, type RouvaStream, type RunParams, type RunResult, type SystemTextBlock, type ToolResultMessage };

package/dist/index.js

@@ -357,17 +357,30 @@ async function readChatCompletionFromSse(stream, metadata) {
 }
 function getRouvaMetadata(headers) {
   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,
-    ...dedup ? { dedup } : {}
+  const usd = (name) => {
+    const raw = read(name);
+    const n = raw === void 0 ? NaN : Number(raw);
+    return Number.isFinite(n) ? n : void 0;
+  };
+  const meta = {
+    // X-Rouva-Row-Id is the same id under its older name.
+    request_id: read("x-rouva-request-id") ?? read("x-rouva-row-id"),
+    model_used: read("x-rouva-model"),
+    provider_used: read("x-rouva-provider"),
+    requested_model: read("x-rouva-requested-model"),
+    // X-Rouva-Task is the older name, still sent alongside.
+    task_type: read("x-rouva-task-type") ?? read("x-rouva-task"),
+    route_reason: read("x-rouva-route-reason"),
+    cost_usd: usd("x-rouva-cost-usd"),
+    saved_usd: usd("x-rouva-saved-usd"),
+    // Duplicate-request cache hit (an identical request within 60s, not charged).
+    // (The old x-rouva-cache header went away with the semantic cache.)
+    dedup: headers.get("x-rouva-dedup") === "1" ? true : void 0
   };
+  for (const key of Object.keys(meta)) {
+    if (meta[key] === void 0) delete meta[key];
+  }
+  return Object.keys(meta).length > 0 ? meta : void 0;
 }
 
 // src/errors.ts
@@ -379,6 +392,7 @@ var RouvaError = class extends Error {
     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;
+    this.requestId = headers.get("x-rouva-request-id") || headers.get("x-rouva-row-id") || void 0;
     let parsed = rawBody;
     try {
       parsed = JSON.parse(rawBody);
@@ -412,6 +426,9 @@ var Rouva = class {
         create: (params, options2) => this._createChatCompletion(params, options2)
       }
     };
+    this.requests = {
+      get: (id, options2) => this._getRequest(id, options2)
+    };
   }
   /**
    * Start a new agent session. Every subsequent `chat.completions.create()`
@@ -466,16 +483,25 @@ var Rouva = class {
     if (!res.ok) throw await toRouvaError("Run", res);
     return res.json();
   }
-  // One request path for every endpoint: auth, JSON body, optional abort signal.
+  async _getRequest(id, options) {
+    if (typeof id !== "string" || !id) throw new Error("[Rouva] request id is required");
+    const res = await this._fetch("GET", `/api/gateway/requests/${encodeURIComponent(id)}`, void 0, {}, options);
+    if (!res.ok) throw await toRouvaError("Request", res);
+    return res.json();
+  }
   _post(path, body, extraHeaders, options) {
+    return this._fetch("POST", path, body, extraHeaders, options);
+  }
+  // One request path for every endpoint: auth, JSON body, optional abort signal.
+  _fetch(method, path, body, extraHeaders, options) {
     return fetch(`${this.baseURL}${path}`, {
-      method: "POST",
+      method,
       headers: {
-        "Content-Type": "application/json",
+        ...method === "POST" ? { "Content-Type": "application/json" } : {},
         "Authorization": `Bearer ${this.apiKey}`,
         ...extraHeaders
       },
-      body: JSON.stringify(body),
+      ...method === "POST" ? { body: JSON.stringify(body) } : {},
       ...options?.signal ? { signal: options.signal } : {}
     });
   }
@@ -486,8 +512,12 @@ var Rouva = class {
     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;
-    return readChatCompletionFromSse(normalizedStream, getRouvaMetadata(res.headers));
+    const metadata = getRouvaMetadata(res.headers);
+    if (params.stream) {
+      if (metadata) normalizedStream._rouva = metadata;
+      return normalizedStream;
+    }
+    return readChatCompletionFromSse(normalizedStream, metadata);
   }
 };
 // Annotate the CommonJS export names for ESM import in node:

package/dist/index.mjs

@@ -330,17 +330,30 @@ async function readChatCompletionFromSse(stream, metadata) {
 }
 function getRouvaMetadata(headers) {
   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,
-    ...dedup ? { dedup } : {}
+  const usd = (name) => {
+    const raw = read(name);
+    const n = raw === void 0 ? NaN : Number(raw);
+    return Number.isFinite(n) ? n : void 0;
+  };
+  const meta = {
+    // X-Rouva-Row-Id is the same id under its older name.
+    request_id: read("x-rouva-request-id") ?? read("x-rouva-row-id"),
+    model_used: read("x-rouva-model"),
+    provider_used: read("x-rouva-provider"),
+    requested_model: read("x-rouva-requested-model"),
+    // X-Rouva-Task is the older name, still sent alongside.
+    task_type: read("x-rouva-task-type") ?? read("x-rouva-task"),
+    route_reason: read("x-rouva-route-reason"),
+    cost_usd: usd("x-rouva-cost-usd"),
+    saved_usd: usd("x-rouva-saved-usd"),
+    // Duplicate-request cache hit (an identical request within 60s, not charged).
+    // (The old x-rouva-cache header went away with the semantic cache.)
+    dedup: headers.get("x-rouva-dedup") === "1" ? true : void 0
   };
+  for (const key of Object.keys(meta)) {
+    if (meta[key] === void 0) delete meta[key];
+  }
+  return Object.keys(meta).length > 0 ? meta : void 0;
 }
 
 // src/errors.ts
@@ -352,6 +365,7 @@ var RouvaError = class extends Error {
     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;
+    this.requestId = headers.get("x-rouva-request-id") || headers.get("x-rouva-row-id") || void 0;
     let parsed = rawBody;
     try {
       parsed = JSON.parse(rawBody);
@@ -385,6 +399,9 @@ var Rouva = class {
         create: (params, options2) => this._createChatCompletion(params, options2)
       }
     };
+    this.requests = {
+      get: (id, options2) => this._getRequest(id, options2)
+    };
   }
   /**
    * Start a new agent session. Every subsequent `chat.completions.create()`
@@ -439,16 +456,25 @@ var Rouva = class {
     if (!res.ok) throw await toRouvaError("Run", res);
     return res.json();
   }
-  // One request path for every endpoint: auth, JSON body, optional abort signal.
+  async _getRequest(id, options) {
+    if (typeof id !== "string" || !id) throw new Error("[Rouva] request id is required");
+    const res = await this._fetch("GET", `/api/gateway/requests/${encodeURIComponent(id)}`, void 0, {}, options);
+    if (!res.ok) throw await toRouvaError("Request", res);
+    return res.json();
+  }
   _post(path, body, extraHeaders, options) {
+    return this._fetch("POST", path, body, extraHeaders, options);
+  }
+  // One request path for every endpoint: auth, JSON body, optional abort signal.
+  _fetch(method, path, body, extraHeaders, options) {
     return fetch(`${this.baseURL}${path}`, {
-      method: "POST",
+      method,
       headers: {
-        "Content-Type": "application/json",
+        ...method === "POST" ? { "Content-Type": "application/json" } : {},
         "Authorization": `Bearer ${this.apiKey}`,
         ...extraHeaders
       },
-      body: JSON.stringify(body),
+      ...method === "POST" ? { body: JSON.stringify(body) } : {},
       ...options?.signal ? { signal: options.signal } : {}
     });
   }
@@ -459,8 +485,12 @@ var Rouva = class {
     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;
-    return readChatCompletionFromSse(normalizedStream, getRouvaMetadata(res.headers));
+    const metadata = getRouvaMetadata(res.headers);
+    if (params.stream) {
+      if (metadata) normalizedStream._rouva = metadata;
+      return normalizedStream;
+    }
+    return readChatCompletionFromSse(normalizedStream, metadata);
   }
 };
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rouvanpm/rouva",
-  "version": "0.3.1",
+  "version": "0.4.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",