@animalabs/membrane 0.5.80 → 0.5.81

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;
   

package/src/utils/cache-marker-budget.ts

@@ -0,0 +1,208 @@
+/**
+ * One recount of the cache_control markers actually present on a wire
+ * request, plus the clamp that keeps that count legal.
+ *
+ * Anthropic accepts at most 4 cache_control breakpoints per request and
+ * rejects the fifth with a non-retryable 400 ("A maximum of 4 blocks with
+ * cache_control may be provided. Found 5." — measured live 2026-08-25).
+ * Markers arrive from many sites (context strategy breakpoints, block-level
+ * passthrough on imported histories, the tools/system fallback, the floating
+ * tool-loop marker, caller-marked system blocks, and any beforeRequest hook),
+ * and every one of them is invisible to the others' running tallies. The
+ * only trustworthy number is a recount of the constructed artifacts, so this
+ * module owns it and every site calls it.
+ *
+ * A marker can also ride a block NESTED inside another block's content array
+ * (`tool_result.content` is `string | ContentBlock[]`, passed through to the
+ * wire verbatim), so discovery recurses. A belt that cannot see a marker
+ * cannot clamp it, and a top-level-only count would report four while five
+ * shipped — the request rejected outright with the belt's blessing.
+ */
+
+/** Anthropic's hard limit on cache_control breakpoints per request. */
+export const MAX_CACHE_BREAKPOINTS = 4;
+
+/**
+ * How many levels of nested `content` arrays marker discovery descends below
+ * a top-level block.
+ *
+ * A marker can ride a block inside another block's own content array —
+ * `ToolResultContent.content` is typed `string | ContentBlock[]` and every
+ * builder passes it through verbatim, so a caller-built tool_result whose
+ * members carry `cache_control` puts real markers on the wire. The API's own
+ * nesting is one level deep; 4 is headroom for shapes it grows later, and it
+ * is also what makes this walk TOTAL — a caller-built structure that points
+ * back at itself terminates at the cap instead of hanging the request.
+ * Markers below the cap are outside the belt's reach, by construction.
+ */
+export const MAX_NESTED_CONTENT_DEPTH = 4;
+
+/**
+ * Walk one candidate block and everything nested under it, in document order
+ * (a block before its own content), applying `visitBlock` to each object.
+ *
+ * This is the single traversal law: marker discovery and the ownership copy
+ * that protects caller-owned blocks from it both descend exactly here, so
+ * the clamp can never reach a grain that ownership did not copy.
+ */
+function walkBlockTree(
+  candidate: unknown,
+  depth: number,
+  visitBlock: (block: Record<string, unknown>) => void
+): void {
+  if (!candidate || typeof candidate !== 'object') return;
+  const block = candidate as Record<string, unknown>;
+  visitBlock(block);
+  const nested = nestedContentBlocks(block, depth);
+  if (!nested) return;
+  for (const child of nested) walkBlockTree(child, depth + 1, visitBlock);
+}
+
+/**
+ * The one rule for what counts as nested content: an array-valued `content`
+ * on a block, while still above the depth cap. Discovery and the ownership
+ * copy both ask here, so neither can descend where the other does not.
+ */
+function nestedContentBlocks(block: Record<string, unknown>, depth: number): unknown[] | undefined {
+  if (depth >= MAX_NESTED_CONTENT_DEPTH) return undefined;
+  return Array.isArray(block.content) ? block.content : undefined;
+}
+
+export interface WireCacheSurfaces {
+  messages?: unknown;
+  system?: unknown;
+  tools?: unknown;
+}
+
+/**
+ * Every marker-bearing block on the request, in WIRE ORDER (tools, then
+ * system blocks, then message blocks) and, within each, in DOCUMENT order —
+ * a block before anything nested inside its own content. Order is what makes
+ * "deepest" mean anything: a deeper marker caches a longer prefix.
+ *
+ * ONE walk serves both the count and the clamp's strip, so a marker the
+ * counter can see is always a marker the clamp can strip. A collector that
+ * stopped at the top level would count four while five rode to the wire, and
+ * the provider would reject the request the belt just declared legal.
+ */
+function collectMarkedBlocks(surfaces: WireCacheSurfaces): Array<Record<string, unknown>> {
+  const marked: Array<Record<string, unknown>> = [];
+  const collectIfMarked = (candidate: unknown) =>
+    walkBlockTree(candidate, 0, (block) => {
+      if (block.cache_control) marked.push(block);
+    });
+
+  if (Array.isArray(surfaces.tools)) {
+    for (const tool of surfaces.tools) collectIfMarked(tool);
+  }
+  if (Array.isArray(surfaces.system)) {
+    for (const block of surfaces.system) collectIfMarked(block);
+  }
+  if (Array.isArray(surfaces.messages)) {
+    for (const message of surfaces.messages) {
+      const content = (message as { content?: unknown } | null)?.content;
+      if (Array.isArray(content)) {
+        for (const block of content) collectIfMarked(block);
+      } else {
+        collectIfMarked(content);
+      }
+    }
+  }
+  return marked;
+}
+
+/**
+ * Take ownership of a system surface before it can reach the clamp.
+ *
+ * `request.system` accepts caller-marked blocks, and the builders pass that
+ * array through by reference when they add no marker of their own. The clamp
+ * strips markers IN PLACE at the wire boundary — correct for blocks membrane
+ * built, catastrophic for the caller's own array, which a long-lived caller
+ * reuses turn after turn: one over-budget request would silently delete the
+ * caller's breakpoints for the life of that object. Copying the array and its
+ * blocks at build time keeps the clamp's mutations inside the request.
+ *
+ * The copy descends exactly as far as marker discovery does: a shallow
+ * `{...block}` leaves any nested `content` array shared with the caller, and
+ * the clamp now strips markers at that grain, so ownership has to reach it
+ * too or the leak just moves one level down.
+ */
+export function ownSystemBlocks(system: unknown): unknown {
+  if (!Array.isArray(system)) return system;
+  return system.map((block) => copyBlockTree(block, 0));
+}
+
+/**
+ * Shallow-copy a block and, recursively, its nested content blocks, to the
+ * same depth marker discovery walks. Non-objects pass through untouched.
+ */
+function copyBlockTree(candidate: unknown, depth: number): unknown {
+  if (!candidate || typeof candidate !== 'object') return candidate;
+  const copy = { ...(candidate as Record<string, unknown>) };
+  const nested = nestedContentBlocks(copy, depth);
+  if (nested) copy.content = nested.map((child) => copyBlockTree(child, depth + 1));
+  return copy;
+}
+
+/** How many cache_control markers this request would actually put on the wire. */
+export function countWireCacheMarkers(surfaces: WireCacheSurfaces): number {
+  return collectMarkedBlocks(surfaces).length;
+}
+
+/**
+ * Bring a request inside the breakpoint budget, in place, at the last exit
+ * before the adapter call. Two repairs, both loud:
+ *
+ *  1. a marker riding a thinking / redacted_thinking block is stripped — the
+ *     API rejects those outright ("thinking.cache_control: Extra inputs are
+ *     not permitted"), and the three builders' `lastCacheableBlockIndex`
+ *     discipline is only as good as its last caller. This is the runtime
+ *     assertion; a fourth builder can no longer repeat that history.
+ *  2. markers past the limit are dropped SHALLOWEST-FIRST, keeping the 4
+ *     deepest — the deepest marker caches the longest prefix, and every
+ *     shallower prefix it subsumes.
+ *
+ * Dropping loudly beats a 400: the request still ships, cached less than the
+ * caller asked for, with the overspend named.
+ */
+export function clampCacheMarkers(
+  surfaces: WireCacheSurfaces,
+  site: string
+): { total: number; dropped: number; strippedFromThinking: number } {
+  const marked = collectMarkedBlocks(surfaces);
+
+  let strippedFromThinking = 0;
+  const cacheable: Array<Record<string, unknown>> = [];
+  for (const block of marked) {
+    if (block.type === 'thinking' || block.type === 'redacted_thinking') {
+      delete block.cache_control;
+      strippedFromThinking++;
+      continue;
+    }
+    cacheable.push(block);
+  }
+
+  let dropped = 0;
+  if (cacheable.length > MAX_CACHE_BREAKPOINTS) {
+    for (const block of cacheable.slice(0, cacheable.length - MAX_CACHE_BREAKPOINTS)) {
+      delete block.cache_control;
+      dropped++;
+    }
+  }
+
+  if (strippedFromThinking > 0) {
+    console.warn(
+      `[membrane] ${site}: stripped ${strippedFromThinking} cache_control marker(s) from ` +
+      `thinking blocks — the API rejects cache_control on thinking/redacted_thinking.`
+    );
+  }
+  if (dropped > 0) {
+    console.warn(
+      `[membrane] ${site}: ${cacheable.length} cache_control markers exceed the limit of ` +
+      `${MAX_CACHE_BREAKPOINTS} — dropped the ${dropped} shallowest and kept the deepest ` +
+      `${MAX_CACHE_BREAKPOINTS}. The request would otherwise have been rejected outright.`
+    );
+  }
+
+  return { total: cacheable.length - dropped, dropped, strippedFromThinking };
+}

package/src/utils/cost.ts

@@ -8,6 +8,69 @@ export interface CostableUsage {
   cacheReadTokens?: number;
 }
 
+/** Unpriced models warn once each, not once per call. */
+const warnedUnpricedModels = new Set<string>();
+
+/**
+ * Say once, per model, that membrane has no rates for it — so an omitted
+ * `estimatedCost` reads as "unknown" rather than "free" to a caller who only
+ * ever sees the absence.
+ */
+export function warnUnpricedModel(modelId: string): void {
+  if (warnedUnpricedModels.has(modelId)) return;
+  warnedUnpricedModels.add(modelId);
+  console.warn(
+    `[membrane:cost] no pricing for model "${modelId}" — neither the configured`
+    + ' ModelRegistry nor the built-in table has rates for it, so estimatedCost will be'
+    + ' omitted (this is NOT a cost of zero). Add it to your registry to get cost estimates.'
+  );
+}
+
+/** Test seam: the once-per-model warn latch is process-wide otherwise. */
+export function resetUnpricedModelWarnings(): void {
+  warnedUnpricedModels.clear();
+}
+
+/**
+ * Add two breakdowns that may have been priced at DIFFERENT rates — the
+ * multi-round case, where each round is priced under the model that served it
+ * and the turn total is their sum.
+ *
+ * `pricingAsOf` takes the OLDER of the two: a total is only as fresh as its
+ * stalest input, and a round whose source vouches for NO date is stalest of
+ * all — one unstamped round leaves the sum unstamped. A currency mismatch is
+ * not summable at all (the caller's
+ * registry priced two rounds in different currencies and membrane has no rate
+ * to convert with), so it returns undefined rather than adding dollars to
+ * euros — an absent cost says "membrane does not know", which is true.
+ */
+export function addCostBreakdowns(
+  a: CostBreakdown,
+  b: CostBreakdown,
+): CostBreakdown | undefined {
+  if (a.currency !== b.currency) return undefined;
+
+  const cacheWrite = a.cacheWrite != null || b.cacheWrite != null
+    ? (a.cacheWrite ?? 0) + (b.cacheWrite ?? 0)
+    : undefined;
+  const cacheRead = a.cacheRead != null || b.cacheRead != null
+    ? (a.cacheRead ?? 0) + (b.cacheRead ?? 0)
+    : undefined;
+  const oldestAsOf = a.pricingAsOf && b.pricingAsOf
+    ? (a.pricingAsOf < b.pricingAsOf ? a.pricingAsOf : b.pricingAsOf)
+    : undefined;
+
+  return {
+    input: a.input + b.input,
+    output: a.output + b.output,
+    cacheWrite,
+    cacheRead,
+    total: a.total + b.total,
+    currency: a.currency,
+    ...(oldestAsOf ? { pricingAsOf: oldestAsOf } : {}),
+  };
+}
+
 export function calculateCost(usage: CostableUsage, pricing: ModelPricing): CostBreakdown {
   const input = usage.inputTokens * pricing.inputPerMillion / 1_000_000;
   const output = usage.outputTokens * pricing.outputPerMillion / 1_000_000;
@@ -25,5 +88,6 @@ export function calculateCost(usage: CostableUsage, pricing: ModelPricing): Cost
     cacheRead,
     total: input + output + (cacheWrite ?? 0) + (cacheRead ?? 0),
     currency: pricing.currency,
+    ...(pricing.asOf ? { pricingAsOf: pricing.asOf } : {}),
   };
 }

package/src/utils/thinking-carriers.ts

@@ -0,0 +1,125 @@
+/**
+ * Helpers for pairing provider-native thinking carriers (which hold the
+ * signatures) with parser-derived thinking blocks (which hold the text).
+ * See Membrane.mergeProviderThinkingBlocks for the pairing rules.
+ */
+import type { ContentBlock } from '../types/index.js';
+
+/**
+ * Identity for thinking text, insensitive to exactly two artifacts that ride
+ * the parser's view of the same reasoning — and to nothing else:
+ *
+ *  - stream scaffolding: the XML path prefills `Claude: <thinking>` and asks
+ *    the adapter to wrap native thinking deltas, so a parsed block can carry
+ *    a literal `<thinking>` / `</thinking>` tag the provider block never had.
+ *  - OUTER boundary whitespace: the continuation path trims the accumulation
+ *    at each round boundary (`buildContinuationRequest` trimEnds before
+ *    re-prefilling), so a fragment and the parsed text can differ by leading
+ *    or trailing whitespace.
+ *
+ * INTERNAL whitespace is payload and is compared verbatim. Erasing it (the
+ * first implementation stripped every `\s`) makes distinct signed payloads
+ * collide on nothing but where their spaces fall, and the caller then stamps
+ * one payload's signature onto the other's text — a carrier that fails
+ * Anthropic signature validation when the consumer ships its history back.
+ *
+ * Comparison only — stored text is never rewritten. Empty text is never
+ * identical to anything: signature-only carriers are prepend-only.
+ */
+export function sameThinkingText(left: string, right: string): boolean {
+  if (left === right) return left !== '';
+  if (left === '' || right === '') return false;
+  const normalized = (text: string) => text.replace(/<\/?(antml:)?thinking>/g, '').trim();
+  const normalizedLeft = normalized(left);
+  if (normalizedLeft === '') return false;
+  return normalizedLeft === normalized(right);
+}
+
+/**
+ * Find a RUN of consecutive still-unpaired provider blocks whose concatenated
+ * thinking reconstructs `parsedText` (an auto-continuation split across a
+ * max_tokens boundary). Returns the provider indices in order, or undefined
+ * when no run of two or more reconstructs it.
+ *
+ * Two joins are tried, because the round boundary itself is the one place a
+ * fragment's whitespace can legitimately vanish: `buildContinuationRequest`
+ * trimEnds the accumulation before re-prefilling, so the resumed text may
+ * pick up exactly where the trim left off. Modelling that single
+ * transformation keeps internal whitespace comparable everywhere else —
+ * `sameThinkingText` treats it as payload.
+ */
+export function findSpanningProviderRun(
+  providerThinking: Array<{ thinking?: string; signature?: string }>,
+  pairedProviderBlocks: ReadonlySet<number>,
+  parsedText: string
+): number[] | undefined {
+  for (let start = 0; start < providerThinking.length; start++) {
+    if (pairedProviderBlocks.has(start)) continue;
+    const firstFragment = providerThinking[start]!.thinking ?? '';
+    let verbatimJoin = firstFragment;
+    let trimmedJoin = firstFragment;
+    const run = [start];
+    for (let next = start + 1; next < providerThinking.length; next++) {
+      if (pairedProviderBlocks.has(next)) break;
+      const fragment = providerThinking[next]!.thinking ?? '';
+      verbatimJoin += fragment;
+      trimmedJoin = trimmedJoin.trimEnd() + fragment;
+      run.push(next);
+      if (sameThinkingText(verbatimJoin, parsedText) || sameThinkingText(trimmedJoin, parsedText)) {
+        return [...run];
+      }
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Drop the extended-thinking config from a prefill-shaped provider request —
+ * from BOTH channels the `thinkingEnabled` resolver reads.
+ *
+ * Whether the API rejects thinking beside an assistant prefill is MODEL
+ * DEPENDENT, not a universal law. Measured live 2026-08-25 against the
+ * Anthropic Messages API: `claude-haiku-4-5-20251001` accepts an assistant
+ * prefill together with `thinking: {type: 'enabled'}` (HTTP 200, and the
+ * response carries no thinking block), while `claude-sonnet-4-6` refuses
+ * assistant prefill outright — HTTP 400, "This model does not support
+ * assistant message prefill."
+ *
+ * So the strip is the prefill path's DESIGN wherever prefill works: the XML
+ * formatter uses the thinking config to emit a literal `<thinking>` text
+ * prefix rather than the API feature, and sending both pays for API thinking
+ * the prefill format does not consume. On models that reject the combination
+ * it is additionally the 400 guard it always was. Either way both channels
+ * must agree, and the guard that only deleted the top-level field left
+ * `extra.thinking` (spread from `providerParams`) riding the adapter's
+ * `Object.assign(params, rest)` onto the wire — reproducing both the 400 and
+ * the interleaved-thinking beta header, since the resolver correctly saw the
+ * smuggled config. Mutates and returns the request; callers must own `extra`
+ * (never alias the caller's `providerParams`).
+ */
+export function stripThinkingForPrefill<T extends { thinking?: unknown; extra?: unknown }>(
+  providerRequest: T
+): T {
+  delete providerRequest.thinking;
+  const extra = providerRequest.extra;
+  if (extra && typeof extra === 'object') {
+    delete (extra as Record<string, unknown>).thinking;
+  }
+  return providerRequest;
+}
+
+/**
+ * De-duplication key for a thinking / redacted_thinking carrier: two carriers
+ * are the same carrier when their payload and signature match. Any other block
+ * type gets a unique key so it can never collide.
+ */
+export function thinkingCarrierKey(block: ContentBlock): string {
+  if (block.type === 'thinking') {
+    const { thinking, signature } = block as { thinking?: string; signature?: string };
+    return `thinking\u0000${thinking ?? ''}\u0000${signature ?? ''}`;
+  }
+  if (block.type === 'redacted_thinking') {
+    return `redacted\u0000${(block as unknown as { data?: string }).data ?? ''}`;
+  }
+  return `other\u0000${JSON.stringify(block)}`;
+}