@rouvanpm/rouva 0.2.9 → 0.2.11

package/README.md

@@ -119,13 +119,13 @@ Models not recognised by the gateway return a `400` immediately:
 
 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).
 
-Intelligent routing applies to `/v1` too — Rouva may substitute a cheaper model within the same provider using your requested model as a cost ceiling. For tool call requests specifically, routing only considers non-reasoning models (reasoning models add unpredictable hidden token costs on tool dispatch). To pin a model exactly, disable Intelligent Routing in your dashboard under **Settings**.
+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.
 
 ## 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.
 
-On the native endpoint (`/api/gateway/messages`), the pinned model is always honored exactly — no substitution. On the `/v1` endpoint with Intelligent Routing enabled, Rouva may route to a cheaper non-reasoning model within the same provider. Disable Intelligent Routing in **Settings** to pin the exact model on `/v1`.
+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.
 
 ```typescript
 const res = await rouva.chat.completions.create({
@@ -167,7 +167,7 @@ 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 but no savings, and 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 or served from the semantic cache.
 
 ## Cost optimisations
 
@@ -190,6 +190,33 @@ const rouva = new Rouva({
 })
 ```
 
+## Agent session tracking
+
+Group all turns of an agent run under a single session ID so the Rouva dashboard can show per-session cost, token usage, and quality.
+
+```typescript
+const rouva = new Rouva({ apiKey: 'rva_...' })
+
+// Start a session — auto-generates an ID and attaches it to every request
+const sessionId = rouva.startSession()
+
+// All turns carry the same session ID automatically
+await rouva.chat.completions.create({ messages: [...], tools: [...] })
+await rouva.chat.completions.create({ messages: [...], tools: [...] })
+await rouva.chat.completions.create({ messages: [...], tools: [...] })
+
+// End the session when the agent run is complete
+rouva.endSession()
+```
+
+You can also read the active session ID at any time:
+
+```typescript
+console.log(rouva.sessionId) // 'rva-sess-abc123' or undefined
+```
+
+Sessions are optional — requests without an active session are tracked individually as before.
+
 ## Response metadata
 
 Parsed non-stream responses may include a `_rouva` field with gateway header metadata when available:

package/dist/index.d.mts

@@ -56,7 +56,7 @@ type RouvaProvider = 'anthropic' | 'openai' | 'gemini' | 'deepseek' | 'mistral'
  * as-is. Until the gateway's registry knows their pricing, such requests are
  * logged with token counts but zero cost.
  */
-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-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.3' | 'grok-4.20-0309-reasoning' | 'grok-4.5' | 'glm-4.7-flash' | 'glm-5.2' | (string & {});
+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' | (string & {});
 /** Anthropic-style text block — the array form of the `system` param */
 interface SystemTextBlock {
     type: 'text';
@@ -168,12 +168,27 @@ interface RouvaResponseMeta {
 declare class Rouva {
     private apiKey;
     private baseURL;
+    private _sessionId;
     readonly chat: {
         completions: {
             create(params: ChatCompletionParams): Promise<ChatCompletion | ReadableStream>;
         };
     };
     constructor(options: RouvaOptions);
+    /**
+     * Start a new agent session. Every subsequent `chat.completions.create()`
+     * call will include `x-rouva-session-id` so all turns are grouped in the
+     * Rouva dashboard. Call `endSession()` when the agent run is complete.
+     * Returns the generated session ID.
+     */
+    startSession(): string;
+    /**
+     * End the current session. Subsequent requests will not carry a session ID
+     * until `startSession()` is called again.
+     */
+    endSession(): void;
+    /** The active session ID, or undefined if no session is in progress. */
+    get sessionId(): string | undefined;
     private _createChatCompletion;
 }
 

package/dist/index.d.ts

@@ -56,7 +56,7 @@ type RouvaProvider = 'anthropic' | 'openai' | 'gemini' | 'deepseek' | 'mistral'
  * as-is. Until the gateway's registry knows their pricing, such requests are
  * logged with token counts but zero cost.
  */
-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-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.3' | 'grok-4.20-0309-reasoning' | 'grok-4.5' | 'glm-4.7-flash' | 'glm-5.2' | (string & {});
+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' | (string & {});
 /** Anthropic-style text block — the array form of the `system` param */
 interface SystemTextBlock {
     type: 'text';
@@ -168,12 +168,27 @@ interface RouvaResponseMeta {
 declare class Rouva {
     private apiKey;
     private baseURL;
+    private _sessionId;
     readonly chat: {
         completions: {
             create(params: ChatCompletionParams): Promise<ChatCompletion | ReadableStream>;
         };
     };
     constructor(options: RouvaOptions);
+    /**
+     * Start a new agent session. Every subsequent `chat.completions.create()`
+     * call will include `x-rouva-session-id` so all turns are grouped in the
+     * Rouva dashboard. Call `endSession()` when the agent run is complete.
+     * Returns the generated session ID.
+     */
+    startSession(): string;
+    /**
+     * End the current session. Subsequent requests will not carry a session ID
+     * until `startSession()` is called again.
+     */
+    endSession(): void;
+    /** The active session ID, or undefined if no session is in progress. */
+    get sessionId(): string | undefined;
     private _createChatCompletion;
 }
 

package/dist/index.js

@@ -383,15 +383,38 @@ var Rouva = class {
       }
     };
   }
+  /**
+   * Start a new agent session. Every subsequent `chat.completions.create()`
+   * call will include `x-rouva-session-id` so all turns are grouped in the
+   * Rouva dashboard. Call `endSession()` when the agent run is complete.
+   * Returns the generated session ID.
+   */
+  startSession() {
+    this._sessionId = `rva-sess-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+    return this._sessionId;
+  }
+  /**
+   * End the current session. Subsequent requests will not carry a session ID
+   * until `startSession()` is called again.
+   */
+  endSession() {
+    this._sessionId = void 0;
+  }
+  /** The active session ID, or undefined if no session is in progress. */
+  get sessionId() {
+    return this._sessionId;
+  }
   async _createChatCompletion(params) {
     const url = `${this.baseURL}/api/gateway/messages`;
     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: {
-        "Content-Type": "application/json",
-        "Authorization": `Bearer ${this.apiKey}`
-      },
+      headers,
       body: JSON.stringify(body)
     });
     if (!res.ok) {

package/dist/index.mjs

@@ -357,15 +357,38 @@ var Rouva = class {
       }
     };
   }
+  /**
+   * Start a new agent session. Every subsequent `chat.completions.create()`
+   * call will include `x-rouva-session-id` so all turns are grouped in the
+   * Rouva dashboard. Call `endSession()` when the agent run is complete.
+   * Returns the generated session ID.
+   */
+  startSession() {
+    this._sessionId = `rva-sess-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+    return this._sessionId;
+  }
+  /**
+   * End the current session. Subsequent requests will not carry a session ID
+   * until `startSession()` is called again.
+   */
+  endSession() {
+    this._sessionId = void 0;
+  }
+  /** The active session ID, or undefined if no session is in progress. */
+  get sessionId() {
+    return this._sessionId;
+  }
   async _createChatCompletion(params) {
     const url = `${this.baseURL}/api/gateway/messages`;
     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: {
-        "Content-Type": "application/json",
-        "Authorization": `Bearer ${this.apiKey}`
-      },
+      headers,
       body: JSON.stringify(body)
     });
     if (!res.ok) {

package/package.json

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