@animalabs/membrane 0.5.81 → 0.5.83

package/src/cache-wire-receipt.ts

@@ -0,0 +1,125 @@
+import { createHash } from 'node:crypto';
+
+export interface CacheWireMarkerReceipt {
+  ordinal: number;
+  prefixHash: string;
+  estimatedOffset: number;
+}
+
+export interface CacheWireReceipt {
+  requestHash: string;
+  markers: CacheWireMarkerReceipt[];
+}
+
+/** Hash the exact post-format/post-hook provider request and every marked
+ * prefix. Token offsets are estimates; provider usage reconciles them later. */
+export function computeCacheWireReceipt(rawRequest: unknown): CacheWireReceipt {
+  const requestHash = sha(stableStringify(rawRequest));
+  const blocks = flattenWireBlocks(rawRequest);
+  const prefix: unknown[] = [];
+  const markers: CacheWireMarkerReceipt[] = [];
+  let chars = 0;
+  for (const unit of blocks) {
+    prefix.push(unit.identity);
+    chars += unit.estimatedChars;
+    if (unit.marked) {
+      markers.push({
+        ordinal: markers.length,
+        prefixHash: sha(stableStringify(prefix)),
+        estimatedOffset: Math.ceil(chars / 4),
+      });
+    }
+  }
+  return { requestHash, markers };
+}
+
+interface ReceiptUnit {
+  identity: unknown;
+  marked: boolean;
+  estimatedChars: number;
+}
+
+function flattenWireBlocks(rawRequest: unknown): ReceiptUnit[] {
+  if (!rawRequest || typeof rawRequest !== 'object') {
+    return [{ identity: rawRequest, marked: false, estimatedChars: stableStringify(rawRequest).length }];
+  }
+  const request = rawRequest as Record<string, unknown>;
+  const out: ReceiptUnit[] = [];
+  if (Array.isArray(request.tools)) {
+    request.tools.forEach((tool, index) => out.push({
+      identity: { surface: 'tool', index, tool },
+      marked: hasCacheControl(tool),
+      estimatedChars: stableStringify(tool).length,
+    }));
+  } else if (request.tools !== undefined) {
+    out.push({
+      identity: { surface: 'tools', value: request.tools },
+      marked: hasCacheControl(request.tools),
+      estimatedChars: stableStringify(request.tools).length,
+    });
+  }
+  if (request.system !== undefined) {
+    const system = request.system;
+    if (Array.isArray(system)) {
+      system.forEach((block, index) => out.push({
+        identity: { surface: 'system', index, block },
+        marked: hasCacheControl(block),
+        estimatedChars: stableStringify(block).length,
+      }));
+    } else {
+      out.push({
+        identity: { surface: 'system', value: system },
+        marked: hasCacheControl(system),
+        estimatedChars: stableStringify(system).length,
+      });
+    }
+  }
+  if (Array.isArray(request.messages)) {
+    request.messages.forEach((message, messageIndex) => {
+      if (!message || typeof message !== 'object') {
+        out.push({
+          identity: { surface: 'message', messageIndex, value: message },
+          marked: false,
+          estimatedChars: stableStringify(message).length,
+        });
+        return;
+      }
+      const record = message as Record<string, unknown>;
+      const content = (message as Record<string, unknown>).content;
+      if (Array.isArray(content)) {
+        content.forEach((block, blockIndex) => out.push({
+          identity: {
+            surface: 'message-block', messageIndex, blockIndex,
+            role: record.role, block,
+          },
+          marked: hasCacheControl(block),
+          estimatedChars: stableStringify({ role: record.role, content: [block] }).length,
+        }));
+      } else {
+        out.push({
+          identity: { surface: 'message', messageIndex, role: record.role, content },
+          marked: hasCacheControl(message),
+          estimatedChars: stableStringify(message).length,
+        });
+      }
+    });
+  }
+  return out;
+}
+
+function hasCacheControl(value: unknown): boolean {
+  return Boolean(value && typeof value === 'object' && (value as Record<string, unknown>).cache_control);
+}
+
+function stableStringify(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`;
+  if (value && typeof value === 'object') {
+    const record = value as Record<string, unknown>;
+    return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value) ?? 'null';
+}
+
+function sha(value: string): string {
+  return createHash('sha256').update(value).digest('hex');
+}

package/src/formatters/anthropic-xml.ts

@@ -34,7 +34,7 @@ import {
   type ToolDefinitionForPrompt,
 } from '../utils/tool-parser.js';
 import { IncrementalXmlParser } from '../utils/stream-parser.js';
-import { clampCacheMarkers } from '../utils/cache-marker-budget.js';
+import { assertCacheMarkersWithinLimit, clampCacheMarkers } from '../utils/cache-marker-budget.js';
 import { lastCacheableBlockIndex } from './native.js';
 import { isAcceptedImageMediaType, strippedImagePlaceholder } from '../utils/image-media.js';
 
@@ -149,6 +149,7 @@ export class AnthropicXmlFormatter implements PrefillFormatter {
       thinking,
       systemPrompt,
       promptCaching = false,
+      cacheMarkers = 'membrane-system',
       cacheTtl,
       contextPrefix,
       prefillUserMessage,
@@ -233,7 +234,7 @@ export class AnthropicXmlFormatter implements PrefillFormatter {
       systemContent = systemBlocks;
     } else if (systemText) {
       const systemBlock: Record<string, unknown> = { type: 'text', text: systemText };
-      if (promptCaching) {
+      if (promptCaching && cacheMarkers === 'membrane-system') {
         systemBlock.cache_control = cacheControl;
       }
       systemContent = [systemBlock];
@@ -242,7 +243,7 @@ export class AnthropicXmlFormatter implements PrefillFormatter {
     // Add context prefix as first cached assistant message (for simulacrum seeding)
     if (contextPrefix) {
       const prefixBlock: Record<string, unknown> = { type: 'text', text: contextPrefix };
-      if (promptCaching) {
+      if (promptCaching && cacheMarkers === 'membrane-system') {
         prefixBlock.cache_control = cacheControl;
       }
       providerMessages.push({
@@ -425,7 +426,7 @@ export class AnthropicXmlFormatter implements PrefillFormatter {
           type: 'text',
           text: 'The assistant is in CLI simulation mode, and responds to the user\'s CLI commands only with the output of the command.',
         };
-        if (promptCaching) {
+        if (promptCaching && cacheMarkers === 'membrane-system') {
           cliSystemBlock.cache_control = cacheControl;
         }
         systemContent = [cliSystemBlock];
@@ -457,10 +458,10 @@ export class AnthropicXmlFormatter implements PrefillFormatter {
     // limit, which rejects the request outright. Clamping here, once, on the
     // finished artifacts is the only count that can see all five sites; the
     // reported tally is that same recount, so it can never drift from the wire.
-    const budget = clampCacheMarkers(
-      { messages: providerMessages, system: systemContent, tools: nativeTools },
-      'anthropic-xml'
-    );
+    const cacheSurfaces = { messages: providerMessages, system: systemContent, tools: nativeTools };
+    const budget = cacheMarkers === 'cm-owned'
+      ? { total: assertCacheMarkersWithinLimit(cacheSurfaces, 'anthropic-xml') }
+      : clampCacheMarkers(cacheSurfaces, 'anthropic-xml');
 
     return {
       messages: providerMessages,

package/src/formatters/native.ts

@@ -30,6 +30,7 @@ import type {
 } from './types.js';
 import { normalizeToolPairs, mergeConsecutiveRoles } from './normalize-tool-pairs.js';
 import { isAcceptedImageMediaType, strippedImagePlaceholder } from '../utils/image-media.js';
+import { assertCacheMarkersWithinLimit } from '../utils/cache-marker-budget.js';
 
 /** Index of the last content block that can carry cache_control. Anthropic
  *  rejects cache_control on thinking / redacted_thinking blocks, so a cache
@@ -184,6 +185,7 @@ export class NativeFormatter implements PrefillFormatter {
       tools,
       systemPrompt,
       promptCaching = false,
+      cacheMarkers = 'membrane-system',
       cacheTtl,
       hasCacheMarker,
       contextPrefix,
@@ -209,7 +211,7 @@ export class NativeFormatter implements PrefillFormatter {
     // Add context prefix as first assistant message (for simulacrum seeding)
     if (contextPrefix) {
       const prefixBlock: Record<string, unknown> = { type: 'text', text: contextPrefix };
-      if (promptCaching && cacheControl) {
+      if (promptCaching && cacheControl && cacheMarkers === 'membrane-system') {
         prefixBlock.cache_control = cacheControl;
         markedBreakpoints++;
       }
@@ -248,6 +250,13 @@ export class NativeFormatter implements PrefillFormatter {
         includeNames: participantMode === 'multiuser' && !isAssistant,
       });
 
+      if (
+        cacheMarkers === 'cm-owned' &&
+        content.some((block) => Boolean((block as Record<string, unknown>).cache_control))
+      ) {
+        throw new Error('cm-owned cache markers reject imported block-level cache_control');
+      }
+
       if (content.length === 0) {
         continue; // Skip empty messages
       }
@@ -302,7 +311,13 @@ export class NativeFormatter implements PrefillFormatter {
     // Build system content. Cache the system block only as a fallback — when no
     // message breakpoint was marked (see note above; otherwise a message
     // breakpoint already caches tools+system as part of its prefix).
-    const cacheSystem = cacheControl && markedBreakpoints === 0 ? cacheControl : undefined;
+    if (markedBreakpoints > 4) {
+      throw new Error(`cache_control limit exceeded: ${markedBreakpoints} markers (maximum 4)`);
+    }
+    const cacheSystem =
+      cacheMarkers === 'membrane-system' && cacheControl && markedBreakpoints === 0
+        ? cacheControl
+        : undefined;
     let systemContent: unknown;
     if (typeof systemPrompt === 'string') {
       if (cacheSystem) {
@@ -327,6 +342,12 @@ export class NativeFormatter implements PrefillFormatter {
 
     // Native tools
     const nativeTools = tools?.length ? this.convertToNativeTools(tools) : undefined;
+    if (cacheMarkers === 'cm-owned') {
+      assertCacheMarkersWithinLimit(
+        { messages: mergedMessages, system: systemContent, tools: nativeTools },
+        'native'
+      );
+    }
 
     return {
       messages: mergedMessages,

package/src/formatters/types.ts

@@ -68,6 +68,9 @@ export interface BuildOptions {
   /** Enable prompt caching (Anthropic-specific) */
   promptCaching?: boolean;
 
+  /** See NormalizedRequest.cacheMarkers. */
+  cacheMarkers?: 'membrane-system' | 'cm-owned';
+
   /** Cache TTL for Anthropic prompt caching - '5m' (default) or '1h' for extended */
   cacheTtl?: '5m' | '1h';
 

package/src/index.ts

@@ -37,3 +37,9 @@ export type {
   KeepaliveLane,
   KeepaliveSend,
 } from './cache-keepalive.js';
+
+export {
+  computeCacheWireReceipt,
+  type CacheWireReceipt,
+  type CacheWireMarkerReceipt,
+} from './cache-wire-receipt.js';

package/src/membrane.ts

@@ -35,6 +35,7 @@ import {
   stripThinkingForPrefill,
 } from './utils/thinking-carriers.js';
 import {
+  assertCacheMarkersWithinLimit,
   countWireCacheMarkers,
   clampCacheMarkers,
   ownSystemBlocks,
@@ -51,6 +52,7 @@ import {
   unsupportedError,
 } from './types/index.js';
 import type { BuildResult } from './formatters/types.js';
+import { computeCacheWireReceipt } from './cache-wire-receipt.js';
 import {
   parseToolCalls,
   formatToolResults,
@@ -247,7 +249,12 @@ export class Membrane {
 
         // Last exit before the adapter: the only place that sees EVERY
         // contribution (builder, formatter, passthrough, float, hook).
-        clampCacheMarkers(finalRequest, 'complete');
+        if (request.cacheMarkers === 'cm-owned') {
+          assertCacheMarkersWithinLimit(finalRequest, 'complete');
+        } else {
+          clampCacheMarkers(finalRequest, 'complete');
+        }
+        request.onCacheWireReceipt?.(computeCacheWireReceipt(finalRequest));
 
         const rawProviderResponse = await this.adapter.complete(finalRequest, {
           signal: options.signal,
@@ -2153,6 +2160,7 @@ export class Membrane {
       thinking: request.config.thinking,
       systemPrompt: request.system,
       promptCaching: request.promptCaching ?? this.config.defaultPromptCaching ?? true, // Default true for backward compat
+      cacheMarkers: request.cacheMarkers ?? 'membrane-system',
       cacheTtl: request.cacheTtl,
       additionalStopSequences,
       maxParticipantsForStop,
@@ -2266,8 +2274,11 @@ export class Membrane {
     // streaming path — stream(), streamYielding(), both tool loops — funnels
     // through here, so this is the one clamp they all get, and its tally is
     // therefore the only count that describes the wire.
-    const clampOutcome = clampCacheMarkers(finalRequest, 'streamOnce');
-    onWireCacheMarkers?.(clampOutcome.total);
+    const markerCount = normalizedRequest.cacheMarkers === 'cm-owned'
+      ? assertCacheMarkersWithinLimit(finalRequest, 'streamOnce')
+      : clampCacheMarkers(finalRequest, 'streamOnce').total;
+    normalizedRequest.onCacheWireReceipt?.(computeCacheWireReceipt(finalRequest));
+    onWireCacheMarkers?.(markerCount);
 
     // Retries are only safe when the caller can discard the abandoned
     // attempt, so they require BOTH a budget and an onRetrying hook.

package/src/providers/anthropic.ts

@@ -130,6 +130,18 @@ export function thinkingEnabled(request: ProviderRequest): boolean {
 // Adapter Configuration
 // ============================================================================
 
+/**
+ * What the dynamicHeaders callback is told about the request it stamps.
+ * `lane` names the transport shape: 'stream' is the conversational turn loop,
+ * 'complete' the non-streamed lane (compression, side-calls, keepalive
+ * touches). A stamp that describes WHY the agent's turn fired belongs on the
+ * stream lane only — a compression call running in the background is not the
+ * turn, and stamping it with the turn's cause would lie to the ledger.
+ */
+export interface DynamicHeadersContext {
+  lane: 'stream' | 'complete';
+}
+
 export interface AnthropicAdapterConfig {
   /** API key (defaults to ANTHROPIC_API_KEY env var) */
   apiKey?: string | null;
@@ -157,7 +169,7 @@ export interface AnthropicAdapterConfig {
    * never replayed stale — an unstamped touch is honest, a stale stamp lies.
    * null/undefined/'' values are dropped.
    */
-  dynamicHeaders?: () => Record<string, string | number | null | undefined>;
+  dynamicHeaders?: (ctx?: DynamicHeadersContext) => Record<string, string | number | null | undefined>;
   
   /** Default max tokens */
   defaultMaxTokens?: number;
@@ -196,7 +208,7 @@ export class AnthropicAdapter implements ProviderAdapter {
   /** Holds idle agents' cached prefixes warm; undefined when disabled. */
   readonly cacheKeepalive: CacheKeepalive | undefined;
   /** Live per-request header source (see AnthropicAdapterConfig.dynamicHeaders). */
-  private readonly dynamicHeaders?: () => Record<string, string | number | null | undefined>;
+  private readonly dynamicHeaders?: (ctx?: DynamicHeadersContext) => Record<string, string | number | null | undefined>;
 
   constructor(config: AnthropicAdapterConfig = {}) {
     const clientOptions: ClientOptions = {
@@ -250,7 +262,7 @@ export class AnthropicAdapter implements ProviderAdapter {
     try {
       const response = await this.client.messages.create(fullRequest, {
         signal: options?.signal,
-        headers: this.liveHeaders(headers),
+        headers: this.liveHeaders(headers, 'complete'),
       });
 
       return this.parseResponse(response, fullRequest);
@@ -323,7 +335,7 @@ export class AnthropicAdapter implements ProviderAdapter {
     try {
       const stream = await this.client.messages.stream(anthropicRequest, {
         signal: idleAbort.signal,
-        headers: this.liveHeaders(this.betaHeaders(request)),
+        headers: this.liveHeaders(this.betaHeaders(request), 'stream'),
       });
 
       // Accumulate response metadata from SSE events directly, so we can
@@ -573,8 +585,8 @@ export class AnthropicAdapter implements ProviderAdapter {
   /** Base headers + the live dynamicHeaders stamp. Request time only: the
    *  keepalive recorder receives the base headers BEFORE this merge, so
    *  replayed touches never carry a stale telemetry value. */
-  private liveHeaders(base: Record<string, string> | undefined): Record<string, string> | undefined {
-    const dyn = this.dynamicHeaders?.();
+  private liveHeaders(base: Record<string, string> | undefined, lane: DynamicHeadersContext['lane']): Record<string, string> | undefined {
+    const dyn = this.dynamicHeaders?.({ lane });
     if (!dyn) return base;
     const out: Record<string, string> = { ...(base ?? {}) };
     for (const [k, v] of Object.entries(dyn)) {

package/src/providers/index.ts

@@ -7,6 +7,7 @@ export {
   toAnthropicContent,
   fromAnthropicContent,
   type AnthropicAdapterConfig,
+  type DynamicHeadersContext,
 } from './anthropic.js';
 
 export { flattenRootSchemaUnion } from './anthropic-tool-schema.js';

package/src/providers/openai.ts

@@ -112,12 +112,36 @@ export interface OpenAIAdapterConfig {
 // Model Detection Helpers
 // ============================================================================
 
+/**
+ * Major version of a first-party GPT chat model id (`gpt-5` → 5,
+ * `gpt-5.4-mini` → 5, `gpt-6-astra` → 6, `gpt-4o` / `gpt-4.1` → 4). Leading
+ * digits only, no delimiter required, so a digit-plus-letter name (`gpt-4o`,
+ * a future `gpt-6o`) is classified by its generation too. Anything not
+ * `gpt-<digits>` (o-series, chatgpt-*, third-party ids) → undefined.
+ */
+function gptGeneration(model: string): number | undefined {
+  const m = /^gpt-(\d+)/.exec(model);
+  return m ? Number(m[1]) : undefined;
+}
+
+/**
+ * GPT-5 and every later generation share the reasoning-model parameter
+ * surface (max_completion_tokens, default-only temperature/top_p, no stop).
+ * Matched by generation rather than by listing each release so a new one
+ * (gpt-6-astra, 2026-09) does not fall through to the legacy parameters and
+ * 400 at the wire: "Unsupported parameter: 'max_tokens' is not supported with
+ * this model. Use 'max_completion_tokens' instead."
+ */
+function isReasoningGenerationGpt(model: string): boolean {
+  const gen = gptGeneration(model);
+  return gen !== undefined && gen >= 5;
+}
+
 /**
  * Models that require max_completion_tokens instead of max_tokens
+ * (in addition to every GPT-5+ generation model, see isReasoningGenerationGpt)
  */
 const COMPLETION_TOKENS_MODELS = [
-  'gpt-5',
-  'gpt-5-mini',
   'o1',
   'o1-mini',
   'o1-preview',
@@ -130,15 +154,14 @@ const COMPLETION_TOKENS_MODELS = [
  * Check if a model requires max_completion_tokens parameter
  */
 function requiresCompletionTokens(model: string): boolean {
-  return COMPLETION_TOKENS_MODELS.some(prefix => model.startsWith(prefix));
+  return isReasoningGenerationGpt(model) || COMPLETION_TOKENS_MODELS.some(prefix => model.startsWith(prefix));
 }
 
 /**
  * Models that don't support custom temperature (only default 1.0)
  */
 const NO_TEMPERATURE_MODELS = [
-  'gpt-5',       // Base GPT-5 models
-  'gpt-5-mini',
+  // GPT-5+ generations are covered by isReasoningGenerationGpt
   'o1',          // Reasoning models
   'o1-mini',
   'o1-preview',
@@ -151,7 +174,7 @@ const NO_TEMPERATURE_MODELS = [
  * Check if a model doesn't support custom temperature
  */
 function noTemperatureSupport(model: string): boolean {
-  return NO_TEMPERATURE_MODELS.some(prefix => model.startsWith(prefix));
+  return isReasoningGenerationGpt(model) || NO_TEMPERATURE_MODELS.some(prefix => model.startsWith(prefix));
 }
 
 /**
@@ -164,12 +187,7 @@ function noTemperatureSupport(model: string): boolean {
  * included here as they use a different API path entirely.
  */
 const NO_STOP_MODELS = [
-  // GPT-5.x chat models (all variants)
-  'gpt-5',
-  'gpt-5-mini',
-  'gpt-5-nano',
-  'gpt-5.1',
-  'gpt-5.2',
+  // GPT-5+ chat models (all variants) are covered by isReasoningGenerationGpt
   // Reasoning models that still don't support stop
   'o3',          // o3 (full) doesn't support stop, but o3-mini does!
   'o4-mini',
@@ -179,7 +197,7 @@ const NO_STOP_MODELS = [
  * Check if a model doesn't support stop sequences
  */
 function noStopSupport(model: string): boolean {
-  return NO_STOP_MODELS.some(prefix => model.startsWith(prefix));
+  return isReasoningGenerationGpt(model) || NO_STOP_MODELS.some(prefix => model.startsWith(prefix));
 }
 
 // ============================================================================

package/src/registry/default-pricing.ts

@@ -102,6 +102,10 @@ const PRICING_TABLE: Array<{ prefix: string; pricing: ModelPricing }> = [
   // INCLUDES that span (see UsageCacheConvention), which membrane normalizes
   // away before pricing, so cacheReadPerMillion is applied to a disjoint count.
   // --------------------------------------------------------------------------
+  {
+    prefix: 'gpt-6-astra',
+    pricing: { inputPerMillion: 10, outputPerMillion: 50, cacheReadPerMillion: 1.00, currency: 'USD', asOf: '2026-09-06' },
+  },
   {
     prefix: 'gpt-5.6-sol',
     pricing: { inputPerMillion: 4, outputPerMillion: 20, cacheReadPerMillion: 0.40, currency: 'USD', asOf: DEFAULT_PRICING_LAST_VERIFIED },

package/src/types/request.ts

@@ -112,6 +112,9 @@ export type ToolMode =
 // ============================================================================
 
 export interface NormalizedRequest {
+  /** Receives the exact post-format/post-hook cache receipt immediately before
+   * network submission. Observability only; never forwarded to providers. */
+  onCacheWireReceipt?: (receipt: import('../cache-wire-receipt.js').CacheWireReceipt) => void;
   /**
    * Explicitly own the loss of old inline images when the serialized request
    * exceeds the API byte cap: oldest images are replaced with loud
@@ -152,6 +155,10 @@ export interface NormalizedRequest {
    */
   promptCaching?: boolean;
 
+  /** Marker ownership policy. `cm-owned` disables every formatter-generated
+   * system/context-prefix marker; only normalized message breakpoints survive. */
+  cacheMarkers?: 'membrane-system' | 'cm-owned';
+
   /**
    * Cache TTL for Anthropic prompt caching.
    * '5m' (default) = 5 minute TTL

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

@@ -149,6 +149,35 @@ export function countWireCacheMarkers(surfaces: WireCacheSurfaces): number {
   return collectMarkedBlocks(surfaces).length;
 }
 
+/**
+ * Validate a caller-owned marker layout without changing it.
+ *
+ * In `cm-owned` mode the caller has deliberately allocated the complete
+ * breakpoint set. Silently stripping or reordering those markers would make
+ * the cache receipt describe a request that was never sent, so invalid
+ * layouts fail before submission instead of using the legacy repair clamp.
+ */
+export function assertCacheMarkersWithinLimit(
+  surfaces: WireCacheSurfaces,
+  site: string
+): number {
+  const marked = collectMarkedBlocks(surfaces);
+  const invalidThinking = marked.filter(
+    (block) => block.type === 'thinking' || block.type === 'redacted_thinking'
+  ).length;
+  if (invalidThinking > 0) {
+    throw new Error(
+      `${site}: caller-owned cache_control cannot be attached to thinking/redacted_thinking blocks`
+    );
+  }
+  if (marked.length > MAX_CACHE_BREAKPOINTS) {
+    throw new Error(
+      `${site}: cache_control limit exceeded: ${marked.length} markers (maximum ${MAX_CACHE_BREAKPOINTS})`
+    );
+  }
+  return marked.length;
+}
+
 /**
  * Bring a request inside the breakpoint budget, in place, at the last exit
  * before the adapter call. Two repairs, both loud: