@animalabs/membrane 0.5.80 → 0.5.82

package/src/context/types.ts

@@ -66,10 +66,36 @@ export interface ContextConfig {
     preferUserMessages?: boolean;
   };
   
+  /**
+   * Participant name this deployment's assistant speaks as (membrane's own
+   * `assistantParticipant`). Used by the `preferUserMessages` adjustment to
+   * tell an assistant turn from a user turn. When unset, the legacy name
+   * list (`claude`/`assistant`/`bot`/`ai`) is used.
+   */
+  assistantParticipant?: string;
+
   /** Custom token estimator (default: chars / 4) */
   tokenEstimator?: (message: NormalizedMessage) => number;
 }
 
+/**
+ * Thrown by `processContext` when messages do not carry stable identity.
+ *
+ * The module keys continuity detection, marker stability and the
+ * `cachedStartMessageId` fetch anchor off `metadata.sourceId`. Without it
+ * every call sees a brand-new conversation, so rolling and caching are
+ * silently disabled — the module refuses rather than degrade invisibly.
+ */
+export class MembraneContextIdentityError extends Error {
+  constructor(
+    message: string,
+    public readonly messageIndices: readonly number[]
+  ) {
+    super(message);
+    this.name = 'MembraneContextIdentityError';
+  }
+}
+
 // ============================================================================
 // Context State (persisted between calls)
 // ============================================================================
@@ -155,6 +181,18 @@ export interface ContextInfo {
   
   /** Whether hard limit was hit */
   hardLimitHit: boolean;
+
+  /**
+   * Set when the window still exceeds a limit after truncation. The kept
+   * window is floored at one message, so a single oversize message cannot
+   * be truncated away — it is reported here instead of shipping an empty
+   * `messages` array.
+   */
+  residualOverflow?: {
+    unit: 'characters' | 'tokens' | 'messages';
+    limit: number;
+    actual: number;
+  };
   
   /**
    * First message ID of the cached window.

package/src/floating-cache-marker.test.ts

@@ -151,6 +151,30 @@ describe('floating cache marker', () => {
     expect(warn).toHaveBeenCalledTimes(1);
   });
 
+  it('warns again after the rate-limit interval instead of latching for the process lifetime', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const clock = vi.spyOn(Date, 'now');
+    clock.mockReturnValue(1_000_000);
+
+    const messages = turn(3);
+    for (const msg of messages) {
+      if ((msg.content[0] as any).type === 'tool_result') (msg as any).cacheBreakpoint = true;
+    }
+    const membrane = new Membrane({ name: 'anthropic' } as any);
+
+    build(makeRequest(), messages, true, membrane);
+    build(makeRequest(), messages, true, membrane);
+    expect(warn).toHaveBeenCalledTimes(1);
+
+    // A long-lived Membrane must not go permanently quiet about an
+    // over-budget wire: past the interval the condition reports again, and
+    // says how many occurrences it swallowed meanwhile.
+    clock.mockReturnValue(1_000_000 + 61_000);
+    build(makeRequest(), messages, true, membrane);
+    expect(warn).toHaveBeenCalledTimes(2);
+    expect(String(warn.mock.calls[1]![0])).toContain('1 further occurrences suppressed');
+  });
+
   it('floats from the residuum left after the tools/system fallback on markerless requests', () => {
     const pr = build(makeRequest(), turn(2, false), true);
     const m = markers(pr);

package/src/formatters/anthropic-xml.ts

@@ -34,6 +34,8 @@ import {
   type ToolDefinitionForPrompt,
 } from '../utils/tool-parser.js';
 import { IncrementalXmlParser } from '../utils/stream-parser.js';
+import { assertCacheMarkersWithinLimit, clampCacheMarkers } from '../utils/cache-marker-budget.js';
+import { lastCacheableBlockIndex } from './native.js';
 import { isAcceptedImageMediaType, strippedImagePlaceholder } from '../utils/image-media.js';
 
 // ============================================================================
@@ -118,9 +120,13 @@ export class AnthropicXmlFormatter implements PrefillFormatter {
   readonly name = 'anthropic-xml';
   readonly usesPrefill = true;
 
+  /** See PrefillFormatter.configuredToolMode — undefined when the caller left the mode to Membrane. */
+  readonly configuredToolMode: 'xml' | 'native' | undefined;
+
   private config: Required<AnthropicXmlFormatterConfig>;
 
   constructor(config: AnthropicXmlFormatterConfig = {}) {
+    this.configuredToolMode = config.toolMode;
     this.config = {
       toolMode: config.toolMode ?? 'xml',
       toolInjectionMode: config.toolInjectionMode ?? 'conversation',
@@ -143,12 +149,17 @@ export class AnthropicXmlFormatter implements PrefillFormatter {
       thinking,
       systemPrompt,
       promptCaching = false,
+      cacheMarkers = 'membrane-system',
       cacheTtl,
       contextPrefix,
       prefillUserMessage,
       hasCacheMarker,
     } = options;
 
+    // Membrane resolves the mode per request and passes it here; the
+    // constructor-time mode is the fallback for direct callers only.
+    const toolMode = options.toolMode ?? this.config.toolMode;
+
     // Build cache_control object (with optional TTL for extended caching)
     const cacheControl: Record<string, unknown> = { type: 'ephemeral' };
     if (cacheTtl) {
@@ -165,42 +176,66 @@ export class AnthropicXmlFormatter implements PrefillFormatter {
     // message continues the same turn, so it must not get a fresh label.
     let lastWasToolResults = false;
 
-    // Track cache markers applied
-    let cacheMarkersApplied = 0;
 
     // Calculate tool injection point
     const totalMessages = messages.length;
     const toolInjectionIndex = Math.max(0, totalMessages - this.config.toolInjectionPosition);
     let toolsInjected = false;
     const hasToolsForConversation =
-      this.config.toolMode === 'xml' &&
+      toolMode === 'xml' &&
       this.config.toolInjectionMode === 'conversation' &&
       tools &&
       tools.length > 0;
     const toolsText = hasToolsForConversation ? this.formatToolsForInjection(tools!) : '';
 
-    // Build system content
-    let systemText = typeof systemPrompt === 'string' ? systemPrompt : '';
-    if (Array.isArray(systemPrompt)) {
-      systemText = systemPrompt
-        .filter((b): b is ContentBlock & { type: 'text' } => b.type === 'text')
-        .map(b => b.text)
-        .join('\n');
-    }
+    // Build system content. A caller-supplied system ARRAY keeps its block
+    // structure and its per-block cache_control: `request.system` explicitly
+    // accepts caller-marked blocks, and flattening them into one text block
+    // discarded every marker the caller placed (three in, one out) — the
+    // caller's stable prefixes then re-paid full input price forever.
+    const callerSystemBlocks = Array.isArray(systemPrompt)
+      ? systemPrompt
+          .filter((b): b is ContentBlock & { type: 'text' } => b.type === 'text')
+          .map((b) => {
+            const callerMarker = (b as unknown as { cache_control?: unknown }).cache_control;
+            const block: Record<string, unknown> = { type: 'text', text: b.text };
+            if (callerMarker) block.cache_control = callerMarker;
+            return block;
+          })
+      : undefined;
+    const systemBlocks = callerSystemBlocks?.length ? callerSystemBlocks : undefined;
+
+    let systemText = typeof systemPrompt === 'string'
+      ? systemPrompt
+      : (systemBlocks?.map((b) => b.text as string).join('\n') ?? '');
 
     // Inject tools into system if configured
-    if (this.config.toolMode === 'xml' && this.config.toolInjectionMode === 'system' && tools?.length) {
+    if (toolMode === 'xml' && this.config.toolInjectionMode === 'system' && tools?.length) {
       const toolsXml = this.formatToolDefinitionsXml(tools);
       systemText = this.injectToolsIntoSystem(systemText, toolsXml);
+      if (systemBlocks) {
+        // Append to the LAST block only — appending to the join would
+        // collapse the array and take every earlier block's marker with it.
+        const tail = systemBlocks[systemBlocks.length - 1]!;
+        tail.text = this.injectToolsIntoSystem(tail.text as string, toolsXml);
+      }
     }
 
     // Build system content with optional cache control
     let systemContent: unknown;
-    if (systemText) {
+    if (systemBlocks) {
+      // The caller's own markers are authoritative: adding one beside them
+      // spends a slot the caller already allocated.
+      const callerMarkedAny = systemBlocks.some((b) => b.cache_control);
+      if (promptCaching && !callerMarkedAny) {
+        const bpIdx = lastCacheableBlockIndex(systemBlocks);
+        if (bpIdx >= 0) systemBlocks[bpIdx]!.cache_control = cacheControl;
+      }
+      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;
-        cacheMarkersApplied++;
       }
       systemContent = [systemBlock];
     }
@@ -208,9 +243,8 @@ 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;
-        cacheMarkersApplied++;
       }
       providerMessages.push({
         role: 'assistant',
@@ -276,7 +310,6 @@ export class AnthropicXmlFormatter implements PrefillFormatter {
           const content = currentConversation.join(joiner);
           const contentBlock: Record<string, unknown> = { type: 'text', text: content };
           contentBlock.cache_control = cacheControl;
-          cacheMarkersApplied++;
           providerMessages.push({
             role: 'assistant',
             content: [contentBlock],
@@ -344,7 +377,6 @@ export class AnthropicXmlFormatter implements PrefillFormatter {
         const content = currentConversation.join(joiner);
         const contentBlock: Record<string, unknown> = { type: 'text', text: content };
         contentBlock.cache_control = cacheControl;
-        cacheMarkersApplied++;
         providerMessages.push({
           role: 'assistant',
           content: [contentBlock],
@@ -394,9 +426,8 @@ 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;
-          cacheMarkersApplied++;
         }
         systemContent = [cliSystemBlock];
         providerMessages.unshift({
@@ -416,10 +447,22 @@ export class AnthropicXmlFormatter implements PrefillFormatter {
     const stopSequences = this.buildStopSequences(messages, assistantParticipant, options);
 
     // Native tools if configured
-    const nativeTools = this.config.toolMode === 'native' && tools?.length
+    const nativeTools = toolMode === 'native' && tools?.length
       ? this.convertToNativeTools(tools)
       : undefined;
 
+    // Budget. Five sites above attach cache_control (system, contextPrefix,
+    // hasCacheMarker flush, cacheBreakpoint flush, CLI-simulation system) and
+    // multiple cacheBreakpoints are documented input, so a prefill turn with
+    // three marked messages reaches five markers — one over Anthropic's hard
+    // 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 cacheSurfaces = { messages: providerMessages, system: systemContent, tools: nativeTools };
+    const budget = cacheMarkers === 'cm-owned'
+      ? { total: assertCacheMarkersWithinLimit(cacheSurfaces, 'anthropic-xml') }
+      : clampCacheMarkers(cacheSurfaces, 'anthropic-xml');
+
     return {
       messages: providerMessages,
       systemContent,
@@ -428,7 +471,7 @@ export class AnthropicXmlFormatter implements PrefillFormatter {
         : undefined,
       stopSequences,
       nativeTools,
-      cacheMarkersApplied,
+      cacheMarkersApplied: budget.total,
     };
   }
 

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/normalize-tool-pairs.ts

@@ -43,6 +43,55 @@ import type { NormalizeEvent } from './types.js';
  */
 export type ProviderBlock = Record<string, unknown> & { type: string };
 
+/**
+ * Does this repair REWRITE prefix bytes, or only re-shape envelopes?
+ *
+ * The two `true` entries are placeholders that get rewritten again the moment
+ * the real pairing arrives — the synthetic `[pending]` result when its
+ * tool_result lands, the textified orphan when its tool_use does — so a cache
+ * breakpoint placed at or past one caches a prefix that is about to change,
+ * poisoning every subsequent read.
+ *
+ * EVERY kind is listed, and the type is a `Record` over the whole union
+ * precisely so the compiler forces that: a new `NormalizeEvent` kind is a
+ * missing-property error here until someone decides which side it falls on.
+ * The previous shape (`[...] satisfies Array<NormalizeEvent['kind']>`) only
+ * checked that the listed kinds were REAL, and a `satisfies` on an array
+ * accepts any subset — so a new prefix-rewriting repair could be added to the
+ * union, never listed, and silently escape the cache gate below while the
+ * comment claimed a compile error that did not exist.
+ *
+ * NOTE FOR COMPOSE: the `stray_tool_result_textified` kind landing from the
+ * stray-orphan lane belongs here as `true` — it rewrites prefix bytes for the
+ * same reason `orphan_tool_result_textified` does.
+ */
+const NORMALIZE_EVENT_REWRITES_PREFIX: Record<NormalizeEvent['kind'], boolean> = {
+  block_re_roled: false,
+  tool_result_hoisted: false,
+  interloper_deferred: false,
+  synthetic_pending_result: true,
+  orphan_tool_result_textified: true,
+  pending_in_flight: false,
+  cache_suppressed_for_synthetic: false,
+  leading_user_synthesized: false,
+};
+
+function deriveKindsThatRewritePrefix(): ReadonlySet<NormalizeEvent['kind']> {
+  const kinds = Object.entries(NORMALIZE_EVENT_REWRITES_PREFIX)
+    .filter(([, rewritesPrefix]) => rewritesPrefix)
+    .map(([kind]) => kind as NormalizeEvent['kind']);
+  return new Set(kinds);
+}
+
+/**
+ * The repairs that rewrite prefix bytes, derived from the exhaustive
+ * classification above. Consumers gate cache placement on this SET rather
+ * than on a single kind, so a normalizer that grows another prefix-rewriting
+ * repair is covered at every cache site by classifying it once.
+ */
+export const PREFIX_REWRITING_NORMALIZE_EVENT_KINDS: ReadonlySet<NormalizeEvent['kind']> =
+  deriveKindsThatRewritePrefix();
+
 export interface NormalizeOptions {
   /** See `BuildOptions.pendingToolCallIds`. */
   pendingToolCallIds?: ReadonlySet<string>;

package/src/formatters/types.ts

@@ -49,6 +49,16 @@ export interface BuildOptions {
   /** Tool definitions to include */
   tools?: ToolDefinition[];
 
+  /**
+   * The tool mode Membrane RESOLVED for this request (see
+   * `Membrane.resolveToolMode`), which already accounts for `request.toolMode`,
+   * the formatter's own configured mode, and provider/formatter derivation.
+   * A formatter that supports both shapes must build for THIS mode; its
+   * constructor-time mode is only the fallback for direct `buildMessages`
+   * callers that resolve nothing.
+   */
+  toolMode?: 'xml' | 'native';
+
   /** Whether thinking is enabled */
   thinking?: { enabled: boolean; budgetTokens?: number };
 
@@ -58,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';
 
@@ -163,6 +176,18 @@ export interface BuildResult {
   /** Number of cache control markers applied (for Anthropic prompt caching) */
   cacheMarkersApplied?: number;
 
+  /**
+   * Offset into the turn's accumulated assistant text at which the CURRENT
+   * last message of `messages` begins. Zero (or absent) for an ordinary
+   * build: the whole accumulated document is the trailing assistant prefill.
+   *
+   * A split-turn image injection persists its three messages here and moves
+   * this watermark to the image seam, so later continuations replace only
+   * the trailing assistant message and never re-flatten the pre-image text
+   * over the user turn that carries the image.
+   */
+  accumulatedBaseOffset?: number;
+
   /**
    * `false` only when the tool-pair normalizer detected a trailing
    * unmatched tool_use whose id is in `pendingToolCallIds` — i.e. the
@@ -258,6 +283,16 @@ export interface PrefillFormatter {
   /** Whether this formatter uses prefill (vs native pass-through) */
   readonly usesPrefill: boolean;
 
+  /**
+   * The tool mode this formatter instance was EXPLICITLY constructed with, if
+   * any. Read by `Membrane.resolveToolMode` as the fallback under an explicit
+   * `request.toolMode`: a formatter that can build either shape carries its
+   * caller's configured choice here so resolution honors it instead of
+   * re-deriving one from the formatter's name. Left undefined by formatters
+   * that build exactly one shape.
+   */
+  readonly configuredToolMode?: 'xml' | 'native';
+
   // ==========================================================================
   // REQUEST BUILDING
   // ==========================================================================

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';