@animalabs/membrane 0.5.80 → 0.5.82

package/src/providers/utils.ts

@@ -1,3 +1,180 @@
+import { TimeoutAbortError, authError, networkError, rateLimitError, serverError } from '../types/errors.js';
+
+interface StreamErrorFrameFields {
+  code?: unknown;
+  status?: unknown;
+  type?: unknown;
+  message?: unknown;
+  retry_after?: unknown;
+  retryAfter?: unknown;
+  retry_after_ms?: unknown;
+  retryAfterMs?: unknown;
+  retryDelay?: unknown;
+  retry_delay?: unknown;
+}
+
+const RATE_LIMIT_FRAME_TOKENS = ['rate_limit', 'rate-limit', 'ratelimit', 'too_many_requests', 'resource_exhausted'];
+const OVERLOADED_FRAME_TOKENS = ['overloaded'];
+const SERVER_FRAME_TOKENS = ['server_error', 'internal', 'unavailable'];
+const AUTH_FRAME_TOKENS = [
+  'invalid_api_key',
+  'api_key_invalid',
+  'authentication_error',
+  'unauthenticated',
+  'permission_denied',
+  'permission_error',
+];
+
+function readNumericField(...candidates: unknown[]): number | undefined {
+  for (const candidate of candidates) {
+    if (typeof candidate === 'number' && Number.isFinite(candidate)) return candidate;
+    if (typeof candidate === 'string' && /^\d+$/.test(candidate.trim())) return Number(candidate.trim());
+  }
+  return undefined;
+}
+
+function readDurationSeconds(...candidates: unknown[]): number | undefined {
+  for (const candidate of candidates) {
+    if (typeof candidate === 'number' && Number.isFinite(candidate)) return candidate;
+    if (typeof candidate === 'string') {
+      const duration = candidate.trim().match(/^(\d+(?:\.\d+)?)s?$/);
+      if (duration?.[1]) return Number(duration[1]);
+    }
+  }
+  return undefined;
+}
+
+function readFrameRetryAfterMs(fields: StreamErrorFrameFields): number | undefined {
+  const explicitMilliseconds = readNumericField(fields.retry_after_ms, fields.retryAfterMs);
+  if (explicitMilliseconds !== undefined) return explicitMilliseconds;
+
+  const seconds = readDurationSeconds(fields.retry_after, fields.retryAfter, fields.retryDelay, fields.retry_delay);
+  return seconds === undefined ? undefined : Math.round(seconds * 1000);
+}
+
+/**
+ * The frame's own non-numeric `type`/`status` values — the provider's
+ * structured classification tokens (`rate_limit_error`, `RESOURCE_EXHAUSTED`,
+ * `overloaded_error`), never free prose. Matching a substring against these is
+ * safe in a way that matching the same substring against a human-readable
+ * message is not.
+ */
+function readFrameClassificationTokens(fields: StreamErrorFrameFields): string[] {
+  return [fields.type, fields.status, fields.code]
+    .filter((value): value is string => typeof value === 'string' && value.trim() !== '')
+    .map((value) => value.trim())
+    .filter((token) => !/^\d+$/.test(token));
+}
+
+function frameTokensMatch(tokens: string[], needles: string[]): boolean {
+  return tokens.some((token) => needles.some((needle) => token.toLowerCase().includes(needle)));
+}
+
+/**
+ * Throw when an SSE data frame carries a provider `error` payload.
+ *
+ * Every provider delivers mid-stream failures (upstream 429s, capacity loss,
+ * safety aborts) as a data line with an `error` object inside an HTTP-200
+ * stream. A loop that only looks for `choices`/`candidates` drops that frame,
+ * reaches EOF, and builds a well-formed success out of whatever arrived first:
+ * partial content, the initialised default finish reason, zero usage. Nothing
+ * distinguishes it from the model choosing to stop, so the truncated turn is
+ * persisted as a real one.
+ *
+ * The house ruled this a bug twice before it was hoisted here — once in
+ * openrouter.ts (tests/unit/openrouter-stream-error.test.ts) and once in
+ * openai-responses-api.ts — and both times the fix stayed in the one adapter
+ * that was being touched. This is the single site every SSE adapter calls.
+ *
+ * The frame is CLASSIFIED here rather than downstream. Throwing a bare
+ * `Error(string)` left `code`/`type`/`status` as prose, and each adapter's
+ * `handleError` then re-derived a category by substring-matching that prose —
+ * so a mid-stream 429 arriving as `status: 429` (no literal "429" in the
+ * message) normalized to `unknown, retryable: false` and suppressed the retry
+ * the provider was explicitly asking for. Classified failures reach the caller
+ * intact because every adapter's `handleError` returns a MembraneError
+ * unchanged. Mapping, using the structured fields only:
+ *   - 429, or a rate-limit-shaped token  -> rate_limit (retryable), carrying
+ *     the frame's retry hint when it has one
+ *   - 5xx, or an overloaded/server-shaped token -> server (retryable);
+ *     overloaded-without-a-status takes 529 so it lands on the capacity
+ *     backoff schedule, matching how anthropic.ts recovers the same shape
+ *   - 401/403, or an auth-shaped token   -> auth (non-retryable)
+ *   - anything else -> the previous bare Error, so the adapter's own
+ *     provider-specific fallbacks still get their swing at it
+ * The provider's message text is never dropped, and the raw frame plus the
+ * request ride along on the classified error.
+ *
+ * `errorNoun` names what carried the payload. It defaults to the SSE case, and
+ * exists because the same `{ error: { code, message } }` object also arrives on
+ * a non-streaming 200 body, where calling the failure a stream error would be
+ * false. Classification reads the payload's own fields either way — the
+ * transport was never part of the rule.
+ */
+export function throwOnStreamErrorFrame(
+  parsed: unknown,
+  providerLabel: string,
+  rawRequest?: unknown,
+  errorNoun: string = 'stream error'
+): void {
+  if (typeof parsed !== 'object' || parsed === null) return;
+  const streamError = (parsed as { error?: unknown }).error;
+  if (!streamError) return;
+
+  const fields: StreamErrorFrameFields =
+    typeof streamError === 'object' ? (streamError as StreamErrorFrameFields) : {};
+  const httpStatus = readNumericField(fields.code, fields.status);
+  const tokens = readFrameClassificationTokens(fields);
+  const providerMessage =
+    typeof fields.message === 'string' && fields.message !== ''
+      ? fields.message
+      : JSON.stringify(streamError);
+
+  const description =
+    `${providerLabel} ${errorNoun}` +
+    `${httpStatus !== undefined ? ` (${httpStatus})` : ''}` +
+    `${tokens.length > 0 ? ` [${tokens.join(' ')}]` : ''}: ${providerMessage}`;
+
+  if (httpStatus === 429 || frameTokensMatch(tokens, RATE_LIMIT_FRAME_TOKENS)) {
+    throw rateLimitError(description, readFrameRetryAfterMs(fields), parsed, rawRequest);
+  }
+
+  if (httpStatus === 401 || httpStatus === 403 || frameTokensMatch(tokens, AUTH_FRAME_TOKENS)) {
+    throw authError(description, parsed, rawRequest);
+  }
+
+  const overloadedShaped = frameTokensMatch(tokens, OVERLOADED_FRAME_TOKENS);
+  if ((httpStatus !== undefined && httpStatus >= 500) || overloadedShaped || frameTokensMatch(tokens, SERVER_FRAME_TOKENS)) {
+    throw serverError(description, httpStatus ?? (overloadedShaped ? 529 : undefined), parsed, rawRequest);
+  }
+
+  throw new Error(description);
+}
+
+/**
+ * Throw when a stream reached EOF without ever observing a terminal event.
+ *
+ * The terminal signal (`finish_reason`, `[DONE]`, Anthropic's `message_delta`,
+ * Gemini's `finishReason`) must be an OBSERVATION, not a default. A graceful
+ * upstream close with no terminal frame — proxy/LB idle timeout, early FIN,
+ * a gateway truncating the body — otherwise yields a clean-looking
+ * `end_turn` over partial content plus a fabricated `finish_reason` that never
+ * came off the wire. Abrupt resets already reject the read; graceful ones did
+ * not. Retryable by construction: the request was never answered in full.
+ */
+export function assertTerminalEventObserved(
+  sawTerminalEvent: boolean,
+  providerLabel: string,
+  rawRequest?: unknown
+): void {
+  if (sawTerminalEvent) return;
+  throw networkError(
+    `${providerLabel} stream ended before a terminal event (connection dropped mid-stream)`,
+    undefined,
+    rawRequest
+  );
+}
+
 /**
  * Safely parse a JSON string, returning an empty object on failure.
  * Used for tool call arguments which may be malformed from streaming.
@@ -11,6 +188,52 @@ export function safeParseJson(str: string | undefined): Record<string, unknown>
   }
 }
 
+/**
+ * Marks the abort reason raised by an adapter's own `timeoutMs` deadline, so
+ * the error that comes back out of `fetch` can be told apart from a caller's
+ * cancellation by PROVENANCE rather than by matching its message text.
+ *
+ * `fetch` rejects with the signal's own `reason` object — identity and extra
+ * properties intact, on both the pre-headers and the body-read paths — so the
+ * mark survives the round trip through the platform. When some layer does
+ * replace the error, `isDeadlineAbort` simply reports false and the abort
+ * classifies as it did before: a missing mark degrades to the old answer, it
+ * never invents a timeout.
+ */
+const DEADLINE_ABORT = Symbol.for('membrane.deadlineAbort');
+
+function deadlineAbortReason(): DOMException {
+  const reason = new DOMException('Request timed out', 'AbortError');
+  Object.defineProperty(reason, DEADLINE_ABORT, { value: true, enumerable: false });
+  return reason;
+}
+
+/**
+ * True when this error is the abort raised by an adapter's own deadline.
+ *
+ * A caller's cancellation never carries the mark (the combined controller is
+ * aborted with the caller's own reason), and if both race, whichever fired
+ * first is the reason the platform rejects with — so the mark answers "was
+ * this OUR deadline?" without a separate tie-break.
+ */
+export function isDeadlineAbort(error: unknown): boolean {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    (error as Record<symbol, unknown>)[DEADLINE_ABORT] === true
+  );
+}
+
+/**
+ * The typed error a deadline abort should become: a timeout by classification,
+ * an abort by provenance. Adapters return this from `handleError` instead of a
+ * bare `abortError()`, which used to erase the distinction before Membrane's
+ * caller-signal > timeout > error ladder could read it.
+ */
+export function deadlineTimeoutError(error: unknown, rawRequest?: unknown): TimeoutAbortError {
+  return new TimeoutAbortError('Request timed out', error, rawRequest);
+}
+
 /**
  * Create a combined AbortSignal that fires on either the caller's signal
  * or a timeout (whichever comes first).
@@ -18,8 +241,9 @@ export function safeParseJson(str: string | undefined): Record<string, unknown>
  * The returned `cleanup` function MUST be called in a `finally` block to
  * clear the timeout and remove the event listener, preventing leaks.
  *
- * Timeout aborts with `DOMException('Request timed out', 'AbortError')`
- * so it classifies identically to user-initiated aborts.
+ * Timeout aborts with a marked `DOMException('Request timed out',
+ * 'AbortError')`: abort-shaped like any cancellation, and identifiable as the
+ * deadline's doing via `isDeadlineAbort`.
  */
 export function createCombinedSignal(
   signal?: AbortSignal,
@@ -32,10 +256,7 @@ export function createCombinedSignal(
   let timeoutId: ReturnType<typeof setTimeout> | undefined;
 
   if (timeoutMs) {
-    timeoutId = setTimeout(
-      () => controller.abort(new DOMException('Request timed out', 'AbortError')),
-      timeoutMs
-    );
+    timeoutId = setTimeout(() => controller.abort(deadlineAbortReason()), timeoutMs);
   }
 
   const onAbort = () => controller.abort(signal!.reason);

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/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 */