@rouvanpm/rouva 0.2.10 → 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/package.json

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