@animalabs/membrane 0.5.79 → 0.5.81

package/src/registry/default-pricing.ts

@@ -1,66 +1,203 @@
 import type { ModelPricing } from '../types/provider.js';
 
 /**
- * Built-in pricing table for known models.
- * Prices in USD per million tokens. Last updated: 2025-07.
+ * Built-in pricing table for known models, in USD per million tokens.
+ * Used as fallback when no ModelRegistry is configured; registry pricing
+ * (if available) takes precedence.
  *
- * Used as fallback when no ModelRegistry is configured.
- * Registry pricing (if available) takes precedence.
+ * Every row carries its OWN verification date through `ModelPricing.asOf`, out
+ * to `CostBreakdown.pricingAsOf`, so a caller can see how old the number it is
+ * billing against is instead of trusting a prose header. Currently-published
+ * rows were read off the provider's own price page on the date in
+ * {@link DEFAULT_PRICING_LAST_VERIFIED} (the per-section comments name the
+ * page) and carry it. A row for a RETIRED model carries the date its rate was
+ * last published instead — claude-3-5-sonnet is dated 2025-07-01 because it is
+ * no longer listed anywhere to verify against, and stamping it with the sweep
+ * date would claim a check that cannot be performed. The previous header
+ * claimed "Last updated: 2025-07" for the whole table while it carried Claude
+ * 4.6 rows, and three rows were simply wrong by the time they were checked.
+ *
+ * Matching is longest-prefix (see {@link getDefaultPricing}), so a more
+ * specific row always wins over a more general one and rows may be listed in
+ * any order.
  */
+export const DEFAULT_PRICING_LAST_VERIFIED = '2026-08-25';
+
 const PRICING_TABLE: Array<{ prefix: string; pricing: ModelPricing }> = [
-  // Anthropic — Claude 4.6
+  // --------------------------------------------------------------------------
+  // Anthropic — https://docs.claude.com/en/docs/about-claude/pricing
+  // Retrieved 2026-08-25. Cache-write column is the 5-minute TTL bucket; the
+  // 1-hour bucket costs more and this table has no field for it.
+  // --------------------------------------------------------------------------
   {
-    prefix: 'claude-opus-4-6',
-    pricing: { inputPerMillion: 15, outputPerMillion: 75, cacheWritePerMillion: 18.75, cacheReadPerMillion: 1.50, currency: 'USD' },
+    prefix: 'claude-fable-5',
+    pricing: { inputPerMillion: 10, outputPerMillion: 50, cacheWritePerMillion: 12.50, cacheReadPerMillion: 1, currency: 'USD', asOf: DEFAULT_PRICING_LAST_VERIFIED },
   },
   {
-    prefix: 'claude-sonnet-4-6',
-    pricing: { inputPerMillion: 3, outputPerMillion: 15, cacheWritePerMillion: 3.75, cacheReadPerMillion: 0.30, currency: 'USD' },
+    prefix: 'claude-opus-5',
+    pricing: { inputPerMillion: 5, outputPerMillion: 25, cacheWritePerMillion: 6.25, cacheReadPerMillion: 0.50, currency: 'USD', asOf: DEFAULT_PRICING_LAST_VERIFIED },
   },
-  // Anthropic — Claude 4.5
   {
-    prefix: 'claude-haiku-4-5',
-    pricing: { inputPerMillion: 0.80, outputPerMillion: 4, cacheWritePerMillion: 1.00, cacheReadPerMillion: 0.08, currency: 'USD' },
+    prefix: 'claude-sonnet-5',
+    pricing: { inputPerMillion: 2, outputPerMillion: 10, cacheWritePerMillion: 2.50, cacheReadPerMillion: 0.20, currency: 'USD', asOf: DEFAULT_PRICING_LAST_VERIFIED },
+  },
+  // Opus 4.5 through 4.8 all price identically to Opus 5.
+  {
+    prefix: 'claude-opus-4-8',
+    pricing: { inputPerMillion: 5, outputPerMillion: 25, cacheWritePerMillion: 6.25, cacheReadPerMillion: 0.50, currency: 'USD', asOf: DEFAULT_PRICING_LAST_VERIFIED },
   },
-  // Anthropic — Claude 4
   {
+    prefix: 'claude-opus-4-7',
+    pricing: { inputPerMillion: 5, outputPerMillion: 25, cacheWritePerMillion: 6.25, cacheReadPerMillion: 0.50, currency: 'USD', asOf: DEFAULT_PRICING_LAST_VERIFIED },
+  },
+  {
+    // Was priced here at 15/75 — the retired Opus 4 rate, 3x the real one.
+    prefix: 'claude-opus-4-6',
+    pricing: { inputPerMillion: 5, outputPerMillion: 25, cacheWritePerMillion: 6.25, cacheReadPerMillion: 0.50, currency: 'USD', asOf: DEFAULT_PRICING_LAST_VERIFIED },
+  },
+  {
+    prefix: 'claude-opus-4-5',
+    pricing: { inputPerMillion: 5, outputPerMillion: 25, cacheWritePerMillion: 6.25, cacheReadPerMillion: 0.50, currency: 'USD', asOf: DEFAULT_PRICING_LAST_VERIFIED },
+  },
+  {
+    // Retired except on Bedrock and Google Cloud; also covers Opus 4.1, which
+    // is priced identically.
     prefix: 'claude-opus-4',
-    pricing: { inputPerMillion: 15, outputPerMillion: 75, cacheWritePerMillion: 18.75, cacheReadPerMillion: 1.50, currency: 'USD' },
+    pricing: { inputPerMillion: 15, outputPerMillion: 75, cacheWritePerMillion: 18.75, cacheReadPerMillion: 1.50, currency: 'USD', asOf: DEFAULT_PRICING_LAST_VERIFIED },
   },
   {
+    prefix: 'claude-sonnet-4-6',
+    pricing: { inputPerMillion: 3, outputPerMillion: 15, cacheWritePerMillion: 3.75, cacheReadPerMillion: 0.30, currency: 'USD', asOf: DEFAULT_PRICING_LAST_VERIFIED },
+  },
+  {
+    prefix: 'claude-sonnet-4-5',
+    pricing: { inputPerMillion: 3, outputPerMillion: 15, cacheWritePerMillion: 3.75, cacheReadPerMillion: 0.30, currency: 'USD', asOf: DEFAULT_PRICING_LAST_VERIFIED },
+  },
+  {
+    // Retired except on Bedrock and Google Cloud.
     prefix: 'claude-sonnet-4',
-    pricing: { inputPerMillion: 3, outputPerMillion: 15, cacheWritePerMillion: 3.75, cacheReadPerMillion: 0.30, currency: 'USD' },
+    pricing: { inputPerMillion: 3, outputPerMillion: 15, cacheWritePerMillion: 3.75, cacheReadPerMillion: 0.30, currency: 'USD', asOf: DEFAULT_PRICING_LAST_VERIFIED },
   },
-  // Anthropic — Claude 3.5
   {
-    prefix: 'claude-3-5-sonnet',
-    pricing: { inputPerMillion: 3, outputPerMillion: 15, cacheWritePerMillion: 3.75, cacheReadPerMillion: 0.30, currency: 'USD' },
+    // Was priced here at 0.80/4 — the retired Haiku 3.5 rate.
+    prefix: 'claude-haiku-4-5',
+    pricing: { inputPerMillion: 1, outputPerMillion: 5, cacheWritePerMillion: 1.25, cacheReadPerMillion: 0.10, currency: 'USD', asOf: DEFAULT_PRICING_LAST_VERIFIED },
   },
   {
+    // Retired except on Bedrock and Google Cloud.
     prefix: 'claude-3-5-haiku',
-    pricing: { inputPerMillion: 0.80, outputPerMillion: 4, cacheWritePerMillion: 1.00, cacheReadPerMillion: 0.08, currency: 'USD' },
+    pricing: { inputPerMillion: 0.80, outputPerMillion: 4, cacheWritePerMillion: 1, cacheReadPerMillion: 0.08, currency: 'USD', asOf: DEFAULT_PRICING_LAST_VERIFIED },
+  },
+  {
+    // Fully retired: no longer listed on the price page as of 2026-08-25, so
+    // this is the last published rate rather than a current one.
+    prefix: 'claude-3-5-sonnet',
+    pricing: { inputPerMillion: 3, outputPerMillion: 15, cacheWritePerMillion: 3.75, cacheReadPerMillion: 0.30, currency: 'USD', asOf: '2025-07-01' },
   },
-  // OpenAI — GPT-4o
+
+  // --------------------------------------------------------------------------
+  // OpenAI — https://platform.openai.com/docs/pricing (standard tier)
+  // Retrieved 2026-08-25. "Cached input" is OpenAI's discounted rate for the
+  // automatically-cached prompt prefix; note that OpenAI's prompt_tokens
+  // INCLUDES that span (see UsageCacheConvention), which membrane normalizes
+  // away before pricing, so cacheReadPerMillion is applied to a disjoint count.
+  // --------------------------------------------------------------------------
   {
-    prefix: 'gpt-4o-2024',
-    pricing: { inputPerMillion: 2.50, outputPerMillion: 10, cacheReadPerMillion: 1.25, currency: 'USD' },
+    prefix: 'gpt-5.6-sol',
+    pricing: { inputPerMillion: 4, outputPerMillion: 20, cacheReadPerMillion: 0.40, currency: 'USD', asOf: DEFAULT_PRICING_LAST_VERIFIED },
   },
   {
-    prefix: 'gpt-4o',
-    pricing: { inputPerMillion: 2.50, outputPerMillion: 10, cacheReadPerMillion: 1.25, currency: 'USD' },
+    prefix: 'gpt-5.6-terra',
+    pricing: { inputPerMillion: 2, outputPerMillion: 12, cacheReadPerMillion: 0.20, currency: 'USD', asOf: DEFAULT_PRICING_LAST_VERIFIED },
+  },
+  {
+    prefix: 'gpt-5.6-luna',
+    pricing: { inputPerMillion: 0.20, outputPerMillion: 1.20, cacheReadPerMillion: 0.02, currency: 'USD', asOf: DEFAULT_PRICING_LAST_VERIFIED },
+  },
+  {
+    // Under 272K context; the long-context tier costs more and this table has
+    // no field for context-dependent rates.
+    prefix: 'gpt-5.5',
+    pricing: { inputPerMillion: 5, outputPerMillion: 30, cacheReadPerMillion: 0.50, currency: 'USD', asOf: DEFAULT_PRICING_LAST_VERIFIED },
+  },
+  {
+    prefix: 'gpt-5.4-mini',
+    pricing: { inputPerMillion: 0.75, outputPerMillion: 4.50, cacheReadPerMillion: 0.075, currency: 'USD', asOf: DEFAULT_PRICING_LAST_VERIFIED },
+  },
+  {
+    prefix: 'gpt-5.4-nano',
+    pricing: { inputPerMillion: 0.20, outputPerMillion: 1.25, cacheReadPerMillion: 0.02, currency: 'USD', asOf: DEFAULT_PRICING_LAST_VERIFIED },
+  },
+  {
+    // Under 272K context.
+    prefix: 'gpt-5.4',
+    pricing: { inputPerMillion: 2.50, outputPerMillion: 15, cacheReadPerMillion: 0.25, currency: 'USD', asOf: DEFAULT_PRICING_LAST_VERIFIED },
+  },
+  {
+    prefix: 'gpt-5.2',
+    pricing: { inputPerMillion: 1.75, outputPerMillion: 14, cacheReadPerMillion: 0.175, currency: 'USD', asOf: DEFAULT_PRICING_LAST_VERIFIED },
+  },
+  {
+    prefix: 'gpt-5.1',
+    pricing: { inputPerMillion: 1.25, outputPerMillion: 10, cacheReadPerMillion: 0.125, currency: 'USD', asOf: DEFAULT_PRICING_LAST_VERIFIED },
+  },
+  {
+    prefix: 'gpt-5-mini',
+    pricing: { inputPerMillion: 0.25, outputPerMillion: 2, cacheReadPerMillion: 0.025, currency: 'USD', asOf: DEFAULT_PRICING_LAST_VERIFIED },
+  },
+  {
+    prefix: 'gpt-5-nano',
+    pricing: { inputPerMillion: 0.05, outputPerMillion: 0.40, cacheReadPerMillion: 0.005, currency: 'USD', asOf: DEFAULT_PRICING_LAST_VERIFIED },
+  },
+  {
+    prefix: 'gpt-5',
+    pricing: { inputPerMillion: 1.25, outputPerMillion: 10, cacheReadPerMillion: 0.125, currency: 'USD', asOf: DEFAULT_PRICING_LAST_VERIFIED },
   },
   {
     prefix: 'gpt-4o-mini',
-    pricing: { inputPerMillion: 0.15, outputPerMillion: 0.60, cacheReadPerMillion: 0.075, currency: 'USD' },
+    pricing: { inputPerMillion: 0.15, outputPerMillion: 0.60, cacheReadPerMillion: 0.075, currency: 'USD', asOf: DEFAULT_PRICING_LAST_VERIFIED },
+  },
+  {
+    // The one gpt-4o snapshot priced differently from plain gpt-4o. Replaces a
+    // `gpt-4o-2024` row that was byte-identical to gpt-4o and so could never
+    // change any answer — while masking this genuine difference.
+    prefix: 'gpt-4o-2024-05-13',
+    pricing: { inputPerMillion: 5, outputPerMillion: 15, currency: 'USD', asOf: DEFAULT_PRICING_LAST_VERIFIED },
+  },
+  {
+    prefix: 'gpt-4o',
+    pricing: { inputPerMillion: 2.50, outputPerMillion: 10, cacheReadPerMillion: 1.25, currency: 'USD', asOf: DEFAULT_PRICING_LAST_VERIFIED },
+  },
+
+  // --------------------------------------------------------------------------
+  // Google — https://ai.google.dev/gemini-api/docs/pricing (paid tier)
+  // Retrieved 2026-08-25. Google's published output price INCLUDES thinking
+  // tokens, which is why the gemini adapter folds thoughtsTokenCount into
+  // outputTokens. Cache rates are the context-caching per-token price and
+  // exclude Google's separate per-hour storage charge, which membrane does not
+  // model. Where a model has a >200k-token tier the smaller-prompt rate is used.
+  // --------------------------------------------------------------------------
+  {
+    prefix: 'gemini-3.5-flash-lite',
+    pricing: { inputPerMillion: 0.30, outputPerMillion: 2.50, cacheReadPerMillion: 0.03, currency: 'USD', asOf: DEFAULT_PRICING_LAST_VERIFIED },
+  },
+  {
+    prefix: 'gemini-3.5-flash',
+    pricing: { inputPerMillion: 1.50, outputPerMillion: 9, cacheReadPerMillion: 0.15, currency: 'USD', asOf: DEFAULT_PRICING_LAST_VERIFIED },
   },
-  // Google — Gemini 2.5
   {
     prefix: 'gemini-2.5-pro',
-    pricing: { inputPerMillion: 1.25, outputPerMillion: 10, currency: 'USD' },
+    pricing: { inputPerMillion: 1.25, outputPerMillion: 10, cacheReadPerMillion: 0.125, currency: 'USD', asOf: DEFAULT_PRICING_LAST_VERIFIED },
+  },
+  {
+    // Was absent, so the gemini-2.5-flash row priced it at 3x input / 6x output.
+    prefix: 'gemini-2.5-flash-lite',
+    pricing: { inputPerMillion: 0.10, outputPerMillion: 0.40, cacheReadPerMillion: 0.01, currency: 'USD', asOf: DEFAULT_PRICING_LAST_VERIFIED },
   },
   {
+    // Was priced here at 0.15/0.60 — text rate; audio input costs more.
     prefix: 'gemini-2.5-flash',
-    pricing: { inputPerMillion: 0.15, outputPerMillion: 0.60, currency: 'USD' },
+    pricing: { inputPerMillion: 0.30, outputPerMillion: 2.50, cacheReadPerMillion: 0.03, currency: 'USD', asOf: DEFAULT_PRICING_LAST_VERIFIED },
   },
 ];
 

package/src/types/config.ts

@@ -180,6 +180,12 @@ export interface MembraneConfig {
    */
   defaultPromptCaching?: boolean;
 
+  /**
+   * Default for request.floatingCacheMarker when the request doesn't set it.
+   * Default: true. See NormalizedRequest.floatingCacheMarker.
+   */
+  defaultFloatingCacheMarker?: boolean;
+
   /**
    * Prefill formatter for message serialization and response parsing.
    * Controls how messages are formatted for the API and how responses are parsed.

package/src/types/content.ts

@@ -121,6 +121,20 @@ export interface ToolUseContent {
    * block. Absent on native-tools blocks and on legacy stored blocks.
    */
   rawXml?: string;
+  /**
+   * Raw accumulated argument text that FAILED to parse as JSON, kept verbatim.
+   *
+   * Present only when the provider's streamed `input_json_delta` fragments did
+   * not assemble into valid JSON — a call truncated mid-arguments (max_tokens)
+   * is the usual cause. `input` then holds whatever the provider's
+   * content_block_start carried, which for Anthropic is `{}`: a wire-valid
+   * tool call with empty arguments, indistinguishable from a genuine no-arg
+   * call once it is written to durable history. Presence of this field means
+   * `input` is NOT the model's arguments, so a consumer can refuse the block
+   * (or attempt its own repair) instead of trusting a plausible `{}`.
+   */
+  unparseableInput?: string;
+
   /** See {@link TextContent.rawItem}. */
   rawItem?: unknown;
 }

package/src/types/errors.ts

@@ -215,6 +215,34 @@ export function abortError(message: string = 'Request was aborted', rawRequest?:
   });
 }
 
+/**
+ * A request cancelled by the adapter's OWN deadline (`timeoutMs`), as opposed
+ * to a caller's signal or a stray abort.
+ *
+ * It is both facts at once, and callers need both: a timeout by `type` (so
+ * `classifyError` and the abort-reason ladder report `'timeout'`), and an
+ * abort by provenance (so the streaming paths still hand back an
+ * `AbortedResponse` with whatever partial content arrived, rather than
+ * throwing). Non-retryable: the deadline that fired belongs to this call, and
+ * retrying inside it would only spend the caller's budget again.
+ */
+export class TimeoutAbortError extends MembraneError {
+  constructor(message: string = 'Request timed out', raw?: unknown, rawRequest?: unknown) {
+    super({
+      type: 'timeout',
+      message,
+      retryable: false,
+      rawError: raw,
+      rawRequest,
+    });
+    this.name = 'TimeoutAbortError';
+  }
+}
+
+export function isTimeoutAbortError(error: unknown): error is TimeoutAbortError {
+  return error instanceof TimeoutAbortError;
+}
+
 export function safetyError(message: string, raw?: unknown, rawRequest?: unknown): MembraneError {
   return new MembraneError({
     type: 'safety',

package/src/types/index.ts

@@ -73,7 +73,10 @@ export type {
 export type {
   StopReason,
   BasicUsage,
+  CallUsage,
   DetailedUsage,
+  TurnRoundUsage,
+  DiscardedAttemptsUsage,
   CostBreakdown,
   StopInfo,
   ModelInfo,
@@ -101,6 +104,7 @@ export type {
   ProviderRequestOptions,
   ProviderResponse,
   StreamCallbacks,
+  UsageCacheConvention,
 } from './provider.js';
 
 // Streaming
@@ -162,6 +166,8 @@ export {
   networkError,
   timeoutError,
   abortError,
+  TimeoutAbortError,
+  isTimeoutAbortError,
   safetyError,
   unsupportedError,
   classifyError,

package/src/types/provider.ts

@@ -82,6 +82,21 @@ export interface ProviderCapabilities {
 // Model Pricing
 // ============================================================================
 
+/**
+ * Whether a provider's prompt-token count INCLUDES the span served from cache.
+ *
+ * Measured live 2026-08-25 — Anthropic (`cache-excluded`): a 4,650-token cached
+ * system prompt returned `input_tokens: 8` with `cache_read_input_tokens: 4650`.
+ * OpenAI (`cache-inclusive`): `prompt_tokens` stayed at 1732 across a cache hit
+ * that reported `cached_tokens: 1664`, so cached is a SUBSET of the prompt.
+ *
+ * `unknown` is a real epistemic state, not a default to lean on: it means no
+ * one has established this adapter's convention, and membrane will pass the
+ * counts through unchanged and warn the first time a cache read makes the
+ * ambiguity bite.
+ */
+export type UsageCacheConvention = 'cache-excluded' | 'cache-inclusive' | 'unknown';
+
 export interface ModelPricing {
   /** Cost per million input tokens */
   inputPerMillion: number;
@@ -97,6 +112,14 @@ export interface ModelPricing {
   
   /** Currency code */
   currency: string;
+
+  /**
+   * ISO date these rates were last checked against the provider's published
+   * price page, surfaced to callers as {@link CostBreakdown.pricingAsOf}. A
+   * pricing source that cannot vouch for a date leaves it unset — better an
+   * absent freshness signal than a fabricated one.
+   */
+  asOf?: string;
 }
 
 // ============================================================================
@@ -169,6 +192,21 @@ export interface ProviderAdapter {
   /** Provider name */
   readonly name: string;
   
+  /**
+   * Which convention this adapter's `usage.inputTokens` carries. Membrane
+   * normalizes every response onto `cache-excluded` before any ratio or cost is
+   * computed, and it can only do that if the adapter says what it is reporting.
+   *
+   * OPTIONAL, defaulting to `'unknown'`: an adapter that declares nothing is in
+   * exactly the state `'unknown'` names, and treating it that way — pass the
+   * counts through untouched, warn once when a cache read makes the ambiguity
+   * bite — is the honest reading of silence. Requiring it would also stop every
+   * external custom adapter compiling for a fact membrane can already say it
+   * does not know. Declare it: `'unknown'` is a real epistemic state, not a
+   * resting place.
+   */
+  usageCacheConvention?: UsageCacheConvention;
+
   /** Check if this adapter handles a model */
   supportsModel(modelId: string): boolean;
   
@@ -272,6 +310,23 @@ export interface ProviderResponse {
     outputTokens: number;
     cacheCreationTokens?: number;
     cacheReadTokens?: number;
+
+    /**
+     * Thinking/reasoning tokens reported separately from the visible-output
+     * count and already folded INTO `outputTokens`.
+     * See {@link DetailedUsage.thinkingTokens}.
+     */
+    thinkingTokens?: number;
+
+    /**
+     * Overrides {@link ProviderAdapter.usageCacheConvention} for THIS response.
+     * Needed where one adapter fronts several upstream conventions: OpenRouter
+     * reads `cache_read_input_tokens` (Anthropic, cache-excluded) OR
+     * `prompt_tokens_details.cached_tokens` (OpenAI, cache-inclusive) depending
+     * on which provider it routed to, so the convention is a per-response fact
+     * there rather than a per-adapter one.
+     */
+    cacheConvention?: UsageCacheConvention;
   };
   
   /** Model that actually ran */

package/src/types/request.ts

@@ -159,6 +159,20 @@ export interface NormalizedRequest {
    */
   cacheTtl?: '5m' | '1h';
 
+  /**
+   * Float a trailing cache_control marker onto the newest message when the
+   * native tool loop rebuilds the request between tool-execution rounds, so
+   * the growing tool-round suffix caches incrementally (each round writes
+   * only its delta and cache-reads everything before it). Placed only from
+   * the request's *residual* breakpoint budget — the marker is withheld when
+   * upstream markers already occupy all 4 Anthropic cache_control slots —
+   * so upstream breakpoints are never displaced or stripped.
+   * Defaults to true (when promptCaching is enabled). Set false for context
+   * strategies whose request prefix churns between rounds, where a trailing
+   * marker would be pure cache-write cost.
+   */
+  floatingCacheMarker?: boolean;
+
   /**
    * Context prefix for simulacrum seeding.
    * Injected as first assistant message (before conversation history).

package/src/types/response.ts

@@ -30,20 +30,77 @@ export interface BasicUsage {
   outputTokens: number;
 }
 
-export interface DetailedUsage extends BasicUsage {
+/**
+ * What ONE priced unit of work cost — a turn, or the discarded attempts summed
+ * together. Held apart from `DetailedUsage` so the discarded-spend record can
+ * carry every token field without also inheriting `discardedAttempts`, which
+ * would let the type describe discarded spend nested inside discarded spend:
+ * a shape nothing produces and nothing could read sensibly.
+ */
+export interface CallUsage extends BasicUsage {
   /** Tokens used for cache creation */
   cacheCreationTokens?: number;
-  
+
   /** Tokens read from cache */
   cacheReadTokens?: number;
-  
-  /** Tokens used for thinking/reasoning */
+
+  /**
+   * Thinking/reasoning tokens the provider reported separately from its
+   * visible-output count, already INCLUDED in `outputTokens` (they are billed
+   * at the output rate). Surfaced so a caller can attribute spend to thinking;
+   * summing it with `outputTokens` would double-count. Gemini's
+   * `thoughtsTokenCount` is the current source.
+   */
   thinkingTokens?: number;
-  
+
   /** Estimated cost breakdown */
   estimatedCost?: CostBreakdown;
 }
 
+export interface DetailedUsage extends CallUsage {
+  /**
+   * Spend on provider calls whose output was thrown away — today, refusal
+   * retries. Those attempts were completed, billed HTTP calls; the response
+   * describes only the attempt that STANDS, so without this the real cost of
+   * a turn is invisible. Absent when nothing was discarded.
+   *
+   * Reported on `details.usage` only: the top-level `usage` stays the
+   * surviving attempt's, so existing consumers keep their meaning.
+   */
+  discardedAttempts?: DiscardedAttemptsUsage;
+}
+
+export interface DiscardedAttemptsUsage extends CallUsage {
+  /** How many billed-but-abandoned provider calls are summed here. */
+  attempts: number;
+}
+
+type Assert<TCondition extends true> = TCondition;
+
+/**
+ * Erased at build; checked by `tsc --noEmit`, which covers src/ and not the
+ * test suite — so this is where a type-level guarantee can actually fail the
+ * build. Re-widening the discarded record to `DetailedUsage` reintroduces
+ * discarded-spend-inside-discarded-spend and turns this line red.
+ */
+type DiscardedSpendDoesNotNest = Assert<
+  'discardedAttempts' extends keyof DiscardedAttemptsUsage ? false : true
+>;
+
+/**
+ * One provider round of a turn: the model that served it and what that round
+ * alone used and cost. `usage.estimatedCost` here is priced at THIS round's
+ * model, which is why the rounds can be summed into a turn total that a
+ * multi-model turn's bill actually matches.
+ */
+export interface TurnRoundUsage {
+  /** Model the provider named as having served this round; the requested id when it named none. */
+  model: string;
+
+  /** This round's own tokens and its own cost. */
+  usage: DetailedUsage;
+}
+
 export interface CostBreakdown {
   input: number;
   output: number;
@@ -51,6 +108,13 @@ export interface CostBreakdown {
   cacheRead?: number;
   total: number;
   currency: string;
+
+  /**
+   * ISO date the rates behind this breakdown were last verified against the
+   * provider's published prices, when the pricing source records one. Unset
+   * means the source vouches for no date, NOT that the numbers are current.
+   */
+  pricingAsOf?: string;
 }
 
 // ============================================================================
@@ -65,6 +129,16 @@ export interface StopInfo {
   
   /** Whether output was truncated */
   wasTruncated: boolean;
+
+  /**
+   * XML tool mode: the turn ended with a tool block still open — a
+   * `<function_calls>` opener with no closer, or text cut mid-tag. The loop
+   * does not resume on a length stop, so this is the shape a max_tokens
+   * truncation leaves behind. A consumer persisting the turn must not write it
+   * back bare: on the next round the stale opener would be read as part of that
+   * round's block.
+   */
+  unclosedToolBlock?: boolean;
 }
 
 // ============================================================================
@@ -75,11 +149,26 @@ export interface ModelInfo {
   /** Model ID that was requested */
   requested: string;
   
-  /** Model ID that actually ran (may differ due to routing/fallback) */
+  /** Model ID that actually ran (may differ due to routing/fallback). On a
+   *  multi-round turn this is the model that served the LAST round; see
+   *  {@link perRound} for the whole roster. */
   actual: string;
   
   /** Provider that served the request */
   provider: string;
+
+  /**
+   * Every provider round of this turn in order, each naming the model that
+   * served it and what that round alone used and cost — the audit trail behind
+   * `usage.estimatedCost`, which is their sum. A routed turn can change models
+   * mid-turn (OpenRouter re-picks a provider per call), so `actual` alone
+   * cannot say what was billed at which rate.
+   *
+   * Set on the streaming/tool-loop paths, which are the ones that sum. Unset
+   * on `complete()`, which makes exactly one call: `actual` is the whole story
+   * there.
+   */
+  perRound?: TurnRoundUsage[];
 }
 
 // ============================================================================
@@ -96,9 +185,21 @@ export interface TimingInfo {
   /** Tokens per second (streaming only) */
   tokensPerSecond?: number;
   
-  /** Number of retry attempts */
+  /**
+   * Provider calls this turn actually cost: retries plus, on the streaming
+   * paths, every continuation round and refusal re-issue. A stitched
+   * multi-call turn used to report 1 here, indistinguishable in durable
+   * logs from a single-shot one.
+   */
   attempts: number;
-  
+
+  /**
+   * Continuation rounds that made up the turn — tool rounds and automatic
+   * resumptions. 1 for a single-round turn; lower than `attempts` whenever a
+   * round was re-issued. Streaming paths only.
+   */
+  rounds?: number;
+
   /** Delay between retries */
   retryDelaysMs?: number[];
 }

package/src/types/streaming.ts

@@ -194,9 +194,15 @@ export interface StreamOptions {
   /** Abort signal for cancellation */
   signal?: AbortSignal;
   
-  /** Request timeout */
+  /** Request timeout (per provider call, not per turn) */
   timeoutMs?: number;
-  
+
+  /**
+   * Abort a call whose stream goes silent for this many ms. Parity with
+   * YieldingStreamOptions.idleTimeoutMs; the adapter owns the default.
+   */
+  idleTimeoutMs?: number;
+
   /** Request ID for correlation */
   requestId?: string;