@animalabs/membrane 0.5.79 → 0.5.81

package/src/providers/anthropic.ts

@@ -20,8 +20,11 @@ import {
   authError,
   serverError,
   abortError,
+  unsupportedError,
 } from '../types/index.js';
 import { flattenRootSchemaUnion } from './anthropic-tool-schema.js';
+import { assertTerminalEventObserved } from './utils.js';
+import { CacheKeepalive, type CacheKeepaliveConfig } from '../cache-keepalive.js';
 
 // ============================================================================
 // Model capability gates
@@ -143,9 +146,30 @@ export interface AnthropicAdapterConfig {
 
   /** Default headers to include with Anthropic requests */
   defaultHeaders?: ClientOptions['defaultHeaders'];
+
+  /**
+   * Live per-request headers, evaluated at request time — for values that
+   * change between calls (e.g. household telemetry stamps such as
+   * `x-gate-debt-chunks`, read by an inference gateway and stripped there
+   * before the vendor ever sees them). Merged over the per-request beta
+   * headers for the OUTGOING request only; cache-keepalive replays
+   * deliberately resend their recorded headers, so a telemetry stamp is
+   * never replayed stale — an unstamped touch is honest, a stale stamp lies.
+   * null/undefined/'' values are dropped.
+   */
+  dynamicHeaders?: () => Record<string, string | number | null | undefined>;
   
   /** Default max tokens */
   defaultMaxTokens?: number;
+
+  /**
+   * Prompt-cache keepalive: hold this agent's cached prefix warm across idle
+   * gaps by replaying the last request with `max_tokens: 0`, which refreshes
+   * the entry's TTL at cache-READ price instead of letting it expire into a
+   * 2x cache write on the next wake. See `../cache-keepalive.ts`.
+   * Pass `{ enabled: false }` to turn off.
+   */
+  cacheKeepalive?: CacheKeepaliveConfig;
 }
 
 // ============================================================================
@@ -154,6 +178,14 @@ export interface AnthropicAdapterConfig {
 
 export class AnthropicAdapter implements ProviderAdapter {
   readonly name = 'anthropic';
+
+  /**
+   * Verified live 2026-08-25 (claude-haiku-4-5, 4,650-token cached system
+   * prompt): call 1 returned input_tokens 8 / cache_creation_input_tokens 4650,
+   * call 2 input_tokens 8 / cache_read_input_tokens 4650. `input_tokens` never
+   * counts the cached span.
+   */
+  readonly usageCacheConvention = 'cache-excluded' as const;
   private client: Anthropic;
   private defaultMaxTokens: number;
   /** Any anthropic-beta value from defaultHeaders (e.g. the oauth beta for
@@ -161,6 +193,10 @@ export class AnthropicAdapter implements ProviderAdapter {
    *  the SDK rather than merging, so when we add a per-request beta we must
    *  re-carry this one alongside it or auth breaks. */
   private defaultBeta: string | undefined;
+  /** 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>;
 
   constructor(config: AnthropicAdapterConfig = {}) {
     const clientOptions: ClientOptions = {
@@ -168,6 +204,7 @@ export class AnthropicAdapter implements ProviderAdapter {
       defaultHeaders: config.defaultHeaders,
     };
     this.defaultBeta = extractBetaHeader(config.defaultHeaders);
+    this.dynamicHeaders = config.dynamicHeaders;
 
     if (config.authToken !== undefined) {
       clientOptions.authToken = config.authToken;
@@ -178,6 +215,19 @@ export class AnthropicAdapter implements ProviderAdapter {
 
     this.client = new Anthropic(clientOptions);
     this.defaultMaxTokens = config.defaultMaxTokens ?? 4096;
+
+    this.cacheKeepalive = config.cacheKeepalive?.enabled === false
+      ? undefined
+      : new CacheKeepalive(
+          // Replay path. Deliberately bypasses buildRequest(): the payload is
+          // the already-built wire request from a real call, and rebuilding it
+          // risks a byte diff that silently converts a 0.1x read into a 2x write.
+          async (wire, headers) => await this.client.messages.create(
+            wire as unknown as Anthropic.MessageCreateParamsNonStreaming,
+            headers ? { headers } : undefined,
+          ),
+          config.cacheKeepalive ?? {},
+        );
   }
 
   supportsModel(modelId: string): boolean {
@@ -192,10 +242,15 @@ export class AnthropicAdapter implements ProviderAdapter {
     const fullRequest = { ...anthropicRequest, stream: false as const };
     options?.onRequest?.(fullRequest);
 
+    const headers = this.betaHeaders(request);
+    this.cacheKeepalive?.record(
+      fullRequest as unknown as Record<string, unknown>, headers, 'complete',
+    );
+
     try {
       const response = await this.client.messages.create(fullRequest, {
         signal: options?.signal,
-        headers: this.betaHeaders(request),
+        headers: this.liveHeaders(headers),
       });
 
       return this.parseResponse(response, fullRequest);
@@ -214,6 +269,14 @@ export class AnthropicAdapter implements ProviderAdapter {
     const fullRequest = { ...anthropicRequest, stream: true };
     options?.onRequest?.(fullRequest);
 
+    // Snapshot the primary lane's prefix so it can be held warm across idle
+    // gaps. `stream: true` is dropped at replay time (transport, not cache key).
+    this.cacheKeepalive?.record(
+      fullRequest as unknown as Record<string, unknown>,
+      this.betaHeaders(request),
+      'stream',
+    );
+
     // Idle timeout: abort if no SSE event arrives within the deadline.
     // The SDK's timeout only covers the initial HTTP response headers;
     // once streaming starts, a silently dropped connection waits forever.
@@ -260,7 +323,7 @@ export class AnthropicAdapter implements ProviderAdapter {
     try {
       const stream = await this.client.messages.stream(anthropicRequest, {
         signal: idleAbort.signal,
-        headers: this.betaHeaders(request),
+        headers: this.liveHeaders(this.betaHeaders(request)),
       });
 
       // Accumulate response metadata from SSE events directly, so we can
@@ -276,6 +339,7 @@ export class AnthropicAdapter implements ProviderAdapter {
       let inferenceGeo: string | undefined;
       let serviceTier: string | undefined;
       let stopReason: string = 'end_turn';
+      let sawTerminalEvent = false;
       let stopSequence: string | undefined;
       let stopDetails: unknown;
 
@@ -291,6 +355,43 @@ export class AnthropicAdapter implements ProviderAdapter {
       // thinking blocks with no thinking_delta at all (signature only).
       const wrapThinkingTags = options?.wrapThinkingTags === true;
       let thinkingTagOpen = false;
+      // Index of a block that has started and not yet been stopped. A stream
+      // can end with one still open: measured live against claude-haiku-4-5
+      // (2026-08-25), a tool call truncated by max_tokens emits
+      // content_block_start + input_json_delta fragments and then goes
+      // straight to message_delta — no content_block_stop at all.
+      let openBlockIndex = -1;
+
+      const finalizeContentBlock = (blockIdx: number, sawBlockStop: boolean): void => {
+        const block = contentBlocks[blockIdx];
+        if (block) {
+          if (block.type === 'text') {
+            block.text = currentBlockContent;
+          } else if (block.type === 'thinking') {
+            block.thinking = currentBlockContent;
+            if (thinkingTagOpen) {
+              callbacks.onChunk('</thinking>\n');
+              thinkingTagOpen = false;
+            }
+          } else if (block.type === 'tool_use') {
+            if (!sawBlockStop) {
+              // Arguments never finished arriving, so `input` is still the
+              // empty object content_block_start carried — a plausible no-arg
+              // call that nothing downstream can distinguish from a real one.
+              block.unparseableInput = currentBlockInputJson;
+            } else if (currentBlockInputJson) {
+              try {
+                block.input = JSON.parse(currentBlockInputJson);
+              } catch {
+                // Same fabrication, reached by a block that did stop: keep the
+                // raw accumulation and mark it so consumers can refuse.
+                block.unparseableInput = currentBlockInputJson;
+              }
+            }
+          }
+        }
+        callbacks.onContentBlock?.(blockIdx, contentBlocks[blockIdx]);
+      };
 
       for await (const event of stream) {
         sawEvent = true;
@@ -316,6 +417,7 @@ export class AnthropicAdapter implements ProviderAdapter {
 
         } else if (event.type === 'content_block_start') {
           currentBlockIndex = event.index;
+          openBlockIndex = event.index;
           currentBlockContent = '';
           currentBlockInputJson = '';
           contentBlocks[currentBlockIndex] = { ...event.content_block };
@@ -349,22 +451,8 @@ export class AnthropicAdapter implements ProviderAdapter {
 
         } else if (event.type === 'content_block_stop') {
           // Finalize block — use event.index for defensive correctness
-          const blockIdx = (event as { index: number }).index;
-          const block = contentBlocks[blockIdx];
-          if (block) {
-            if (block.type === 'text') {
-              block.text = currentBlockContent;
-            } else if (block.type === 'thinking') {
-              block.thinking = currentBlockContent;
-              if (thinkingTagOpen) {
-                callbacks.onChunk('</thinking>\n');
-                thinkingTagOpen = false;
-              }
-            } else if (block.type === 'tool_use' && currentBlockInputJson) {
-              try { block.input = JSON.parse(currentBlockInputJson); } catch { /* partial JSON */ }
-            }
-          }
-          callbacks.onContentBlock?.(blockIdx, contentBlocks[blockIdx]);
+          finalizeContentBlock((event as { index: number }).index, true);
+          openBlockIndex = -1;
 
         } else if (event.type === 'message_delta') {
           // All content blocks are finalized by the time message_delta arrives.
@@ -376,6 +464,7 @@ export class AnthropicAdapter implements ProviderAdapter {
             stop_details?: unknown;
           };
           stopReason = delta.stop_reason ?? 'end_turn';
+          sawTerminalEvent = true;
           stopSequence = delta.stop_sequence ?? undefined;
           // stop_details carries refusal metadata (e.g., category: 'reasoning_extraction')
           stopDetails = delta.stop_details ?? undefined;
@@ -400,9 +489,22 @@ export class AnthropicAdapter implements ProviderAdapter {
       if (idleTimer) clearTimeout(idleTimer);
       options?.signal?.removeEventListener('abort', onExternalAbort);
 
+      // A block still open here never received its content_block_stop: the
+      // turn ended mid-block. Finalize it so the accumulated text is not lost
+      // and a truncated tool call is marked rather than persisted as `{}`.
+      if (openBlockIndex >= 0) {
+        finalizeContentBlock(openBlockIndex, false);
+        openBlockIndex = -1;
+      }
+
       // Force-close the HTTP connection so we don't block on SSE drain
       try { stream.controller.abort(); } catch { /* already closed */ }
 
+      // message_delta is this adapter's terminal event — the loop breaks on
+      // it. Falling out of the for-await without one means the SSE connection
+      // closed mid-turn, and stopReason is still its 'end_turn' initialiser.
+      assertTerminalEventObserved(sawTerminalEvent, 'Anthropic', fullRequest);
+
       return {
         content: contentBlocks,
         stopReason,
@@ -468,6 +570,19 @@ export class AnthropicAdapter implements ProviderAdapter {
    *  the SDK replaces same-key defaults instead of merging, and the API
    *  accepts comma-separated betas. Undefined when nothing to add, so the
    *  defaults apply untouched. */
+  /** 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?.();
+    if (!dyn) return base;
+    const out: Record<string, string> = { ...(base ?? {}) };
+    for (const [k, v] of Object.entries(dyn)) {
+      if (v !== null && v !== undefined && v !== '') out[k] = String(v);
+    }
+    return Object.keys(out).length ? out : undefined;
+  }
+
   private betaHeaders(request: ProviderRequest): Record<string, string> | undefined {
     if (!thinkingEnabled(request) || !needsInterleavedThinkingBeta(request.model)) {
       return undefined;
@@ -634,6 +749,10 @@ export class AnthropicAdapter implements ProviderAdapter {
   }
 
   private handleError(error: unknown, rawRequest?: unknown): MembraneError {
+    // Already-classified failures (e.g. the stream-integrity guards) keep
+    // their type and retryability instead of being re-derived from a string.
+    if (error instanceof MembraneError) return error;
+
     if (error instanceof Anthropic.APIError) {
       // Mid-stream SSE `error` events are rethrown by the SDK as APIError
       // with status === undefined (sdk core/streaming.js), so the HTTP
@@ -664,7 +783,12 @@ export class AnthropicAdapter implements ProviderAdapter {
         return authError(message, error, rawRequest);
       }
 
-      if (message.includes('context') || message.includes('too long')) {
+      // Context-length is a client-side request-shape problem — it only ever
+      // arrives as a 400 (invalid_request_error). Without the status guard, a
+      // transient 5xx whose body happens to contain "context" or "too long"
+      // (e.g. "Internal error: context processing failed") was misclassified
+      // as non-retryable context_length, silently suppressing retries.
+      if (status === 400 && (message.includes('context') || message.includes('too long'))) {
         return contextLengthError(message, error, rawRequest);
       }
 
@@ -837,6 +961,23 @@ export function toAnthropicContent(blocks: ContentBlock[]): Anthropic.ContentBlo
             media_type: block.source.mediaType as 'application/pdf',
             data: block.source.data,
           },
+          // Anthropic's document block carries the filename as `title`; it was
+          // being dropped, so the model lost the one hint about what the PDF is.
+          ...(block.filename ? { title: block.filename } : {}),
+        });
+        break;
+
+      case 'generated_image':
+        // A provider-generated image is a base64 image with a MIME type, which
+        // is exactly Anthropic's image block — carrying it across costs nothing
+        // and lets an image Gemini produced re-enter Anthropic history.
+        result.push({
+          type: 'image',
+          source: {
+            type: 'base64',
+            media_type: block.mimeType as 'image/jpeg' | 'image/png' | 'image/gif' | 'image/webp',
+            data: block.data,
+          },
         });
         break;
         
@@ -876,12 +1017,53 @@ export function toAnthropicContent(blocks: ContentBlock[]): Anthropic.ContentBlo
           data: (block as any).data,
         } as any);
         break;
+
+      default: {
+        // The REQUEST path cannot degrade gracefully: a dropped block reaches
+        // the model as an absence, and it answers about content it was never
+        // shown. `audio` and `video` have no Anthropic Messages representation
+        // at all, and a block type added later would silently join them. Fail
+        // loudly at the boundary instead — the caller can strip or transcode.
+        const unsupportedType = (block as { type?: string }).type ?? 'unknown';
+        throw unsupportedError(
+          `Anthropic has no representation for a "${unsupportedType}" content block, and dropping`
+          + ' it would send the model a message missing content the caller supplied.'
+          + ' Remove or convert the block before sending it on this provider.'
+        );
+      }
     }
   }
 
   return result;
 }
 
+/** Unrecognised response block types warn once each, not once per conversion. */
+const warnedUnconvertibleResponseBlocks = new Set<string>();
+
+/**
+ * The RESPONSE path can degrade gracefully where the request path cannot: the
+ * provider's own block is in hand, so keeping it verbatim on a zero-width
+ * carrier loses nothing recoverable and lets formatters replay it. Warn once
+ * per type so a new provider block type surfaces without flooding the log.
+ */
+function preserveUnconvertibleBlock(block: unknown, sourceLabel: string): ContentBlock {
+  const blockType = (block as { type?: string })?.type ?? 'unknown';
+  if (!warnedUnconvertibleResponseBlocks.has(blockType)) {
+    warnedUnconvertibleResponseBlocks.add(blockType);
+    console.warn(
+      `[membrane:${sourceLabel}] no normalized ContentBlock for provider block type`
+      + ` "${blockType}" — preserving it verbatim as a rawItem carrier so it can be`
+      + ' replayed, but its content is not visible to normalized consumers.'
+    );
+  }
+  return { type: 'text', text: '', rawItem: block } as ContentBlock;
+}
+
+/** Test seam: the once-per-type warn latch is process-wide otherwise. */
+export function resetUnconvertibleBlockWarnings(): void {
+  warnedUnconvertibleResponseBlocks.clear();
+}
+
 /**
  * Convert Anthropic response content to normalized format
  */
@@ -912,11 +1094,14 @@ export function fromAnthropicContent(blocks: Anthropic.ContentBlock[]): ContentB
         break;
         
       default:
-        // Handle redacted_thinking or unknown types
         if ((block as any).type === 'redacted_thinking') {
           // Preserve the encrypted `data` payload — without it the block
           // cannot be round-tripped and prior reasoning is lost.
           result.push({ type: 'redacted_thinking', data: (block as any).data } as any);
+        } else {
+          // server_tool_use, web_search_tool_result, search_result, mcp_tool_use
+          // and anything Anthropic adds later used to fall out here silently.
+          result.push(preserveUnconvertibleBlock(block, 'anthropic'));
         }
         break;
     }

package/src/providers/bedrock.ts

@@ -20,7 +20,7 @@ import {
   serverError,
   abortError,
 } from '../types/index.js';
-import { createCombinedSignal } from './utils.js';
+import { createCombinedSignal, isDeadlineAbort, deadlineTimeoutError, assertTerminalEventObserved } from './utils.js';
 import {
   INTERLEAVED_THINKING_BETA,
   needsInterleavedThinkingBeta,
@@ -273,6 +273,15 @@ async function signRequest(
 export class BedrockAdapter implements ProviderAdapter {
   readonly name = 'bedrock';
 
+  /**
+   * Bedrock serves Anthropic models over the Anthropic Messages payload shape
+   * and this adapter reads Anthropic's own field names
+   * (`cache_read_input_tokens` / `cache_creation_input_tokens`), so it inherits
+   * the convention verified live against api.anthropic.com on 2026-08-25.
+   * Derived from the wire contract, not measured against Bedrock directly.
+   */
+  readonly usageCacheConvention = 'cache-excluded' as const;
+
   private accessKeyId: string;
   private secretAccessKey: string;
   private sessionToken?: string;
@@ -610,6 +619,7 @@ export class BedrockAdapter implements ProviderAdapter {
     let cacheCreationTokens: number | undefined;
     let cacheReadTokens: number | undefined;
     let stopReason: string = 'end_turn';
+    let sawTerminalEvent = false;
     let stopSequence: string | undefined;
     let fullText = '';
 
@@ -782,6 +792,7 @@ export class BedrockAdapter implements ProviderAdapter {
                   }
                   callbacks.onContentBlock?.(blockIdx, contentBlocks[blockIdx]);
                 } else if (eventData.type === 'message_delta') {
+                  sawTerminalEvent = true;
                   if (eventData.usage) {
                     outputTokens = eventData.usage.output_tokens;
                     // message_delta carries cumulative cache metrics — use as
@@ -833,6 +844,11 @@ export class BedrockAdapter implements ProviderAdapter {
       );
     }
 
+    // The empty-response guard above only catches a stream that produced
+    // NOTHING; a stream truncated after any content passed it and was
+    // reported as a clean end_turn. message_delta is the terminal event.
+    assertTerminalEventObserved(sawTerminalEvent, 'Bedrock', { modelId, ...request });
+
     // Build response from accumulated data
     finalMessage = {
       id: 'msg_stream',
@@ -917,6 +933,14 @@ export class BedrockAdapter implements ProviderAdapter {
   }
 
   private handleError(error: unknown, rawRequest?: unknown): MembraneError {
+    // A deadline abort is a timeout and stays one. Collapsing it into a bare
+    // abortError() here is what erased the identity before Membrane's
+    // caller-signal > timeout > error ladder could read it.
+    if (isDeadlineAbort(error)) return deadlineTimeoutError(error, rawRequest);
+    // Already-classified failures (e.g. the stream-integrity guards) keep
+    // their type and retryability instead of being re-derived from a string.
+    if (error instanceof MembraneError) return error;
+
     if (error instanceof BedrockError) {
       const status = error.status;
       const message = error.message;