@animalabs/membrane 0.5.76 → 0.5.77

package/src/membrane.ts

@@ -31,6 +31,7 @@ import {
   DEFAULT_RETRY_CONFIG,
   MembraneError,
   classifyError,
+  isOverloadedError,
   isTextContent,
   isAbortedResponse,
 } from './types/index.js';
@@ -80,7 +81,11 @@ export class Membrane {
   ) {
     this.adapter = adapter;
     this.registry = config.registry;
-    this.retryConfig = { ...DEFAULT_RETRY_CONFIG, ...config.retry };
+    this.retryConfig = {
+      ...DEFAULT_RETRY_CONFIG,
+      ...config.retry,
+      overloaded: { ...DEFAULT_RETRY_CONFIG.overloaded, ...config.retry?.overloaded },
+    };
     this.config = config;
     // Use provided formatter or default to AnthropicXmlFormatter
     this.formatter = config.formatter ?? new AnthropicXmlFormatter();
@@ -146,12 +151,23 @@ export class Membrane {
         const errorInfo = classifyError(error);
         errorInfo.rawRequest = rawRequest;
 
-        // Rate limits (429) always retry up to 5 attempts regardless of config.
-        // Other retryable errors only retry when maxRetries > 0.
+        // Rate limits (429) always retry up to 5 attempts regardless of
+        // config, and overloaded (529) always retries on its own longer
+        // schedule — both are transient by definition, and the default
+        // maxRetries of 0 would otherwise turn a capacity blip into a dead
+        // turn. Other retryable errors only retry when maxRetries > 0.
+        // overloaded.maxRetries: 0 disables the dedicated policy entirely;
+        // the 529 then follows the base config like any retryable server
+        // error (exactly the pre-policy behavior), rather than being
+        // silently re-promoted to the long schedule by a positive base limit.
         const isRateLimit = errorInfo.type === 'rate_limit';
+        const isOverloaded =
+          isOverloadedError(errorInfo) && this.retryConfig.overloaded.maxRetries > 0;
         const effectiveMax = isRateLimit
           ? Math.max(this.retryConfig.maxRetries, 5)
-          : this.retryConfig.maxRetries;
+          : isOverloaded
+            ? Math.max(this.retryConfig.maxRetries, this.retryConfig.overloaded.maxRetries)
+            : this.retryConfig.maxRetries;
 
         if (errorInfo.retryable && attempts < effectiveMax) {
           // Check hook for retry decision
@@ -163,7 +179,7 @@ export class Membrane {
           }
 
           // Wait before retry (abort-aware)
-          const delay = this.calculateRetryDelay(attempts);
+          const delay = this.calculateRetryDelay(attempts, isOverloaded);
           await this.sleep(delay, options.signal);
           continue;
         }
@@ -217,11 +233,74 @@ export class Membrane {
 
     // Determine tool mode
     const toolMode = this.resolveToolMode(request);
+    const useNative = toolMode === 'native' && !!request.tools && request.tools.length > 0;
+
+    // Overloaded (529) pre-emission retry. The streaming paths have no retry
+    // loop of their own, so a capacity error used to kill the turn outright —
+    // and 529s most often arrive INSTEAD of a stream, before anything reaches
+    // the caller, where retrying is transparent. Once any callback has
+    // delivered output (tokens, blocks, usage), retrying would replay content
+    // the caller already consumed, so mid-stream errors still throw.
+    let attempts = 0;
+    const retryDelaysMs: number[] = [];
+    while (true) {
+      attempts++;
+      let emitted = false;
+      const mark = <A extends unknown[], R>(fn?: (...args: A) => R) =>
+        fn && ((...args: A): R => { emitted = true; return fn(...args); });
+      const tracked: StreamOptions = {
+        ...options,
+        onChunk: mark(options.onChunk),
+        onContentBlockUpdate: mark(options.onContentBlockUpdate),
+        onToolCalls: mark(options.onToolCalls),
+        onPreToolContent: mark(options.onPreToolContent),
+        onUsage: mark(options.onUsage),
+        onBlock: mark(options.onBlock),
+        onResponse: mark(options.onResponse),
+        // onRequest fires before the send — it is not an emission.
+      };
 
-    if (toolMode === 'native' && request.tools && request.tools.length > 0) {
-      return this.streamWithNativeTools(request, options);
-    } else {
-      return this.streamWithXmlTools(request, options);
+      try {
+        const result = useNative
+          ? await this.streamWithNativeTools(request, tracked)
+          : await this.streamWithXmlTools(request, tracked);
+        // The inner paths report attempts: 1 — they can't see this wrapper.
+        // A call that succeeded after N overloaded retries must not look like
+        // a first-attempt success in durable logs, so patch the real count
+        // (and the waits) into the response telemetry.
+        if (attempts > 1 && 'details' in result) {
+          result.details.timing.attempts = attempts;
+          result.details.timing.retryDelaysMs = retryDelaysMs;
+        }
+        return result;
+      } catch (error) {
+        const errorInfo = classifyError(error);
+        // Same semantics as complete(): maxRetries bounds total attempts,
+        // the overloaded floor applies over the base config, and
+        // overloaded.maxRetries: 0 opts out of stream retries entirely
+        // (streaming had no retry before this policy existed).
+        const overloadedEnabled = this.retryConfig.overloaded.maxRetries > 0;
+        const maxOverloaded = Math.max(
+          this.retryConfig.maxRetries,
+          this.retryConfig.overloaded.maxRetries
+        );
+        if (!emitted && overloadedEnabled && isOverloadedError(errorInfo) && attempts < maxOverloaded) {
+          // Honor the same pre-retry hook contract as complete(): hosts use
+          // onError for circuit-breaking, and its 'abort' decision must work
+          // on the streaming path too.
+          if (this.config.hooks?.onError) {
+            const decision = await this.config.hooks.onError(errorInfo, attempts);
+            if (decision === 'abort') {
+              throw error;
+            }
+          }
+          const delay = this.calculateRetryDelay(attempts, true);
+          retryDelaysMs.push(delay);
+          await this.sleep(delay, options.signal);
+          continue;
+        }
+        throw error;
+      }
     }
   }
 
@@ -330,6 +409,52 @@ export class Membrane {
     // from blocks the model itself opened during generation
     const prefillDepths = parser.getDepths();
 
+    // Resumption spin guards (issue #39). Observed live on Ash 2026-07-26:
+    // each automatic resumption re-sent ~172k input tokens, streamed ~6
+    // output tokens, and stopped on the same (dropped) stop sequence — 43
+    // rounds, ~7M input tokens, zero progress, found only because a human
+    // noticed. Two guards, both scoped to AUTOMATIC false-positive
+    // resumptions — tool rounds are real caller-governed work (maxToolDepth
+    // / the yielding API's uncapped contract) and are never counted here:
+    //   - stall guard: several CONSECUTIVE resumptions that each stream
+    //     almost nothing and stop identically end the turn ('no_progress').
+    //     One short repeated round is low progress, not proof of none — a
+    //     stop sequence inside legitimate tool-argument text can cause a
+    //     couple of short resumptions on the way to completing.
+    //   - round cap: a hard bound on resumptions per turn ('round_limit'),
+    //     the backstop for a spin that keeps technically progressing.
+    const MIN_ROUND_PROGRESS_CHARS = 16;
+    const MAX_CONSECUTIVE_STALLED_RESUMPTIONS = 3;
+    const RESUMPTION_WARN_ROUNDS = 5;
+    const maxResumptionRounds = options.maxResumptionRounds ?? 24;
+    let resumptionRounds = 0;
+    let consecutiveStalledResumptions = 0;
+    let enteredViaResumption = false;
+    let prevRoundStopSequence: string | undefined;
+    const warnLog = this.config.logger ?? console;
+
+    /** Count an automatic resumption; emits the visibility warning at the
+     *  threshold and returns false when the cap says the turn should end. */
+    const registerResumptionRound = (): boolean => {
+      resumptionRounds++;
+      if (resumptionRounds === RESUMPTION_WARN_ROUNDS) {
+        warnLog.warn(
+          `[membrane] automatic resumption at round ${resumptionRounds} ` +
+          `(${totalUsage.inputTokens} input tokens so far this turn) — ` +
+          `a spin shows up here before it shows up on the bill`
+        );
+      }
+      if (resumptionRounds > maxResumptionRounds) {
+        warnLog.warn(
+          `[membrane] automatic resumption cap (${maxResumptionRounds}) reached — ` +
+          `ending turn with stopReason 'round_limit'. ` +
+          `${totalUsage.inputTokens} input tokens spent this turn.`
+        );
+        return false;
+      }
+      return true;
+    };
+
     try {
       // Tool execution loop
       while (toolDepth <= maxToolDepth) {
@@ -338,7 +463,10 @@ export class Membrane {
         let detectedStopSequence: string | null = null;
         let truncatedAccumulated: string | null = null;
 
-        // Track where to start checking for stop sequences (skip already-processed content)
+        // Track where to start checking for stop sequences (skip already-processed content).
+        // Also the round's progress baseline: XML we pushed ourselves at the
+        // end of the previous round (tool results, closing tags) sits below
+        // this index and doesn't count as model progress.
         const checkFromIndex = parser.getAccumulated().length;
 
         // Stream from provider
@@ -465,6 +593,38 @@ export class Membrane {
         // Get accumulated text from parser
         const accumulated = parser.getAccumulated();
 
+        // Stall accounting (issue #39): only rounds ENTERED via automatic
+        // resumption can stall — tool rounds are caller-governed work and a
+        // real tool call is longer than the threshold anyway. A stall is a
+        // resumption that streamed almost nothing and stopped identically to
+        // the previous round; the turn ends only after several IN A ROW
+        // (one short repeated round is low progress, not proof of none —
+        // a stop sequence inside legitimate tool-argument text can cause a
+        // couple of short resumptions on the way to completing).
+        const streamedThisRound = accumulated.length - checkFromIndex;
+        if (
+          enteredViaResumption &&
+          lastStopReason === 'stop_sequence' &&
+          streamedThisRound < MIN_ROUND_PROGRESS_CHARS &&
+          lastStopSequence === prevRoundStopSequence
+        ) {
+          consecutiveStalledResumptions++;
+          if (consecutiveStalledResumptions >= MAX_CONSECUTIVE_STALLED_RESUMPTIONS) {
+            warnLog.warn(
+              `[membrane] ${consecutiveStalledResumptions} consecutive automatic resumptions ` +
+              `made no progress (${streamedThisRound} chars this round, stop ` +
+              `${JSON.stringify(lastStopSequence ?? null)} repeated) — ending turn with ` +
+              `stopReason 'no_progress'. ${totalUsage.inputTokens} input tokens spent this turn.`
+            );
+            lastStopReason = 'no_progress';
+            break;
+          }
+        } else {
+          consecutiveStalledResumptions = 0;
+        }
+        prevRoundStopSequence = lastStopSequence;
+        enteredViaResumption = false;
+
         // Check for tool calls (if handler provided)
         if (onToolCalls && streamResult.stopSequence === '</function_calls>') {
           // Append the closing tag (we truncated before it, or API stopped before it)
@@ -655,7 +815,9 @@ export class Membrane {
               );
             }
 
-            // Reset parser state for new streaming iteration
+            // Reset parser state for new streaming iteration. Tool rounds
+            // are the caller's work — they count against maxToolDepth only,
+            // never against the resumption guards (issue #39 review).
             parser.resetForNewIteration();
             toolDepth++;
             continue;
@@ -692,6 +854,11 @@ export class Membrane {
           if (toolDepth > maxToolDepth) {
             break;
           }
+          if (!registerResumptionRound()) {
+            lastStopReason = 'round_limit';
+            break;
+          }
+          enteredViaResumption = true;
           prefillResult.assistantPrefill = parser.getAccumulated();
           providerRequest = this.buildContinuationRequest(
             request,
@@ -1893,10 +2060,15 @@ export class Membrane {
     return pricing ? calculateCost(usage, pricing) : undefined;
   }
 
-  private calculateRetryDelay(attempt: number): number {
-    const { retryDelayMs, backoffMultiplier, maxRetryDelayMs } = this.retryConfig;
-    const delay = retryDelayMs * Math.pow(backoffMultiplier, attempt - 1);
-    return Math.min(delay, maxRetryDelayMs);
+  private calculateRetryDelay(attempt: number, overloaded = false): number {
+    const { retryDelayMs, backoffMultiplier, maxRetryDelayMs } = overloaded
+      ? this.retryConfig.overloaded
+      : this.retryConfig;
+    const delay = Math.min(retryDelayMs * Math.pow(backoffMultiplier, attempt - 1), maxRetryDelayMs);
+    // Equal jitter on the overloaded schedule only: a capacity storm is
+    // exactly the case where a fleet retrying in sync re-creates the
+    // stampede it's backing off from. [delay/2, delay) keeps the wait long.
+    return overloaded ? Math.floor(delay / 2 + Math.random() * (delay / 2)) : delay;
   }
 
   private attachRawRequest(error: unknown, rawRequest: unknown): Error {
@@ -2033,6 +2205,29 @@ export class Membrane {
         ? Infinity
         : maxToolDepthOpt;
 
+    // Resumption spin guards (issue #39). This is the path the Ash spin ran
+    // on: tool depth here is unlimited BY DESIGN (the caller budgets its own
+    // tool work — that contract stands untouched), and the false-positive
+    // resumption path counted against that same unlimited bound — 43 rounds
+    // × ~172k input tokens of zero progress. Only AUTOMATIC resumptions are
+    // guarded: a stall guard (consecutive no-progress resumptions →
+    // 'no_progress') and a hard resumption cap ('round_limit'). Tool rounds
+    // are never counted. See streamWithXmlTools for the rationale details.
+    const MIN_ROUND_PROGRESS_CHARS = 16;
+    const MAX_CONSECUTIVE_STALLED_RESUMPTIONS = 3;
+    const RESUMPTION_WARN_ROUNDS = 5;
+    const maxResumptionRounds =
+      options.maxResumptionRounds === undefined
+        ? 24
+        : options.maxResumptionRounds === -1
+          ? Infinity
+          : options.maxResumptionRounds;
+    let resumptionRounds = 0;
+    let consecutiveStalledResumptions = 0;
+    let enteredViaResumption = false;
+    let prevRoundStopSequence: string | undefined;
+    const warnLog = this.config.logger ?? console;
+
     // Initialize parser from formatter for format-specific tracking
     const formatter = this.formatter;
     const parser = formatter.createStreamParser();
@@ -2078,6 +2273,28 @@ export class Membrane {
     // from blocks the model itself opened during generation
     const prefillDepths = parser.getDepths();
 
+    /** Count an automatic resumption; emits the visibility warning at the
+     *  threshold and returns false when the cap says the turn should end. */
+    const registerResumptionRound = (): boolean => {
+      resumptionRounds++;
+      if (resumptionRounds === RESUMPTION_WARN_ROUNDS) {
+        warnLog.warn(
+          `[membrane] automatic resumption at round ${resumptionRounds} ` +
+          `(${totalUsage.inputTokens} input tokens so far this turn) — ` +
+          `a spin shows up here before it shows up on the bill`
+        );
+      }
+      if (resumptionRounds > maxResumptionRounds) {
+        warnLog.warn(
+          `[membrane] automatic resumption cap (${maxResumptionRounds}) reached — ` +
+          `ending turn with stopReason 'round_limit'. ` +
+          `${totalUsage.inputTokens} input tokens spent this turn.`
+        );
+        return false;
+      }
+      return true;
+    };
+
     try {
       // Tool execution loop
       while (toolDepth <= maxToolDepth) {
@@ -2206,6 +2423,34 @@ export class Membrane {
           }
         }
 
+        // Stall accounting (issue #39): only rounds ENTERED via automatic
+        // resumption can stall; the turn ends only after several consecutive
+        // stalls. Tool rounds are never counted. Mirrors streamWithXmlTools —
+        // see the detailed rationale there.
+        const streamedThisRound = parser.getAccumulated().length - checkFromIndex;
+        if (
+          enteredViaResumption &&
+          lastStopReason === 'stop_sequence' &&
+          streamedThisRound < MIN_ROUND_PROGRESS_CHARS &&
+          lastStopSequence === prevRoundStopSequence
+        ) {
+          consecutiveStalledResumptions++;
+          if (consecutiveStalledResumptions >= MAX_CONSECUTIVE_STALLED_RESUMPTIONS) {
+            warnLog.warn(
+              `[membrane] ${consecutiveStalledResumptions} consecutive automatic resumptions ` +
+              `made no progress (${streamedThisRound} chars this round, stop ` +
+              `${JSON.stringify(lastStopSequence ?? null)} repeated) — ending turn with ` +
+              `stopReason 'no_progress'. ${totalUsage.inputTokens} input tokens spent this turn.`
+            );
+            lastStopReason = 'no_progress';
+            break;
+          }
+        } else {
+          consecutiveStalledResumptions = 0;
+        }
+        prevRoundStopSequence = lastStopSequence;
+        enteredViaResumption = false;
+
         // Check for tool calls
         if (streamResult.stopSequence === '</function_calls>') {
           const closeTag = '</function_calls>';
@@ -2422,6 +2667,9 @@ export class Membrane {
               );
             }
 
+            // Tool rounds are the caller's work — they count against
+            // maxToolDepth only, never against the resumption guards
+            // (issue #39 review: the uncapped tool-loop contract stands).
             parser.resetForNewIteration();
             toolDepth++;
             continue;
@@ -2453,6 +2701,11 @@ export class Membrane {
           if (toolDepth > maxToolDepth) {
             break;
           }
+          if (!registerResumptionRound()) {
+            lastStopReason = 'round_limit';
+            break;
+          }
+          enteredViaResumption = true;
           prefillResult.assistantPrefill = parser.getAccumulated();
           providerRequest = this.buildContinuationRequest(
             request,

package/src/providers/bedrock.ts

@@ -49,6 +49,16 @@ export interface BedrockAdapterConfig {
 
   /** Anthropic API version header (defaults to 2023-06-01) */
   anthropicVersion?: string;
+
+  /**
+   * Endpoint override (no trailing slash), e.g. an inference gateway leg
+   * like `https://gate.animalabs.ai/bedrock/apse1`. Defaults to
+   * `https://bedrock-runtime.{region}.amazonaws.com`. When pointing at a
+   * gateway, set accessKeyId to the gate token — the gateway reads it from
+   * the SigV4 Credential field, discards the client signature, and re-signs
+   * with real AWS creds that never leave the gateway box.
+   */
+  baseURL?: string;
 }
 
 // ============================================================================
@@ -120,9 +130,25 @@ interface BedrockStreamEvent {
   usage?: {
     input_tokens: number;
     output_tokens: number;
+    cache_creation_input_tokens?: number | null;
+    cache_read_input_tokens?: number | null;
   };
 }
 
+/**
+ * Bedrock accepts `cache_control: { type: 'ephemeral' }` but rejects the
+ * direct-API `ttl` extension ("cache_control.ttl: Extra inputs are not
+ * permitted"). Drop the ttl, keep the marker — the cache still works, at
+ * Bedrock's fixed default TTL.
+ */
+function stripCacheTtl<T extends Record<string, any>>(block: T): T {
+  if (block?.cache_control && typeof block.cache_control === 'object' && 'ttl' in block.cache_control) {
+    const { ttl, ...cacheControl } = block.cache_control;
+    return { ...block, cache_control: cacheControl };
+  }
+  return block;
+}
+
 // ============================================================================
 // AWS Signature V4 Implementation
 // ============================================================================
@@ -252,6 +278,7 @@ export class BedrockAdapter implements ProviderAdapter {
   private region: string;
   private defaultMaxTokens: number;
   private anthropicVersion: string;
+  private baseURL?: string;
 
   constructor(config: BedrockAdapterConfig = {}) {
     this.accessKeyId = config.accessKeyId ?? process.env.AWS_ACCESS_KEY_ID ?? '';
@@ -260,6 +287,7 @@ export class BedrockAdapter implements ProviderAdapter {
     this.region = config.region ?? process.env.AWS_REGION ?? 'us-west-2';
     this.defaultMaxTokens = config.defaultMaxTokens ?? 4096;
     this.anthropicVersion = config.anthropicVersion ?? 'bedrock-2023-05-31';
+    this.baseURL = config.baseURL?.replace(/\/$/, '');
 
     if (!this.accessKeyId || !this.secretAccessKey) {
       throw new Error('AWS credentials required: accessKeyId and secretAccessKey');
@@ -271,6 +299,18 @@ export class BedrockAdapter implements ProviderAdapter {
     return modelId.includes('claude') || modelId.startsWith('anthropic.');
   }
 
+  /**
+   * Cross-region inference-profile prefix for this adapter's region.
+   * Claude 4-era models on Bedrock reject on-demand invocation of the
+   * direct id ("Invocation ... with on-demand throughput isn't supported")
+   * and require the profile form — verified live 2026-07-31.
+   */
+  private inferenceProfilePrefix(): string {
+    if (this.region.startsWith('eu-')) return 'eu.';
+    if (this.region.startsWith('ap-')) return 'apac.';
+    return 'us.';
+  }
+
   /**
    * Convert a standard Claude model ID to Bedrock format if needed
    */
@@ -287,7 +327,13 @@ export class BedrockAdapter implements ProviderAdapter {
       return modelId;
     }
 
-    // Map common Claude model IDs to Bedrock format
+    const profile = this.inferenceProfilePrefix();
+
+    // Map common Claude model IDs to Bedrock format. The 3.x entries keep
+    // their historical direct-id form (those models predate inference
+    // profiles; all are EOL on Bedrock as of 2026-07 anyway, so the exact
+    // shape is moot). 4-era entries use the profile form — the direct id
+    // no longer invokes.
     const modelMap: Record<string, string> = {
       'claude-3-5-sonnet-20241022': 'anthropic.claude-3-5-sonnet-20241022-v2:0',
       'claude-3-5-sonnet-latest': 'anthropic.claude-3-5-sonnet-20241022-v2:0',
@@ -296,13 +342,15 @@ export class BedrockAdapter implements ProviderAdapter {
       'claude-3-opus-20240229': 'anthropic.claude-3-opus-20240229-v1:0',
       'claude-3-sonnet-20240229': 'anthropic.claude-3-sonnet-20240229-v1:0',
       'claude-3-haiku-20240307': 'anthropic.claude-3-haiku-20240307-v1:0',
-      'claude-sonnet-4-20250514': 'anthropic.claude-sonnet-4-20250514-v1:0',
-      'claude-opus-4-20250514': 'anthropic.claude-opus-4-20250514-v1:0',
-      // Haiku 4.5 aliases
-      'claude-haiku-4-5-20251001': 'anthropic.claude-3-5-haiku-20241022-v1:0',
+      'claude-sonnet-4-20250514': `${profile}anthropic.claude-sonnet-4-20250514-v1:0`,
+      'claude-opus-4-20250514': `${profile}anthropic.claude-opus-4-20250514-v1:0`,
+      // Haiku 4.5 previously aliased to 3.5 Haiku (a stand-in from before
+      // Haiku 4.5 reached Bedrock). 3.5 Haiku is EOL on Bedrock now, so the
+      // alias routed every plain-id caller to a guaranteed error.
+      'claude-haiku-4-5-20251001': `${profile}anthropic.claude-haiku-4-5-20251001-v1:0`,
     };
 
-    return modelMap[modelId] ?? `anthropic.${modelId}-v1:0`;
+    return modelMap[modelId] ?? `${profile}anthropic.${modelId}-v1:0`;
   }
 
   async complete(
@@ -347,7 +395,14 @@ export class BedrockAdapter implements ProviderAdapter {
 
   private buildRequest(request: ProviderRequest, bedrockModelId?: string): BedrockMessageRequest {
     // Strip provider-specific fields (e.g., sourceUrl for Gemini) from image blocks
-    // before sending to Bedrock/Anthropic, which rejects extra inputs
+    // before sending to Bedrock/Anthropic, which rejects extra inputs.
+    //
+    // Same treatment for cache_control.ttl: Bedrock's prompt cache runs at the
+    // fixed default (5m) TTL — the ttl field is a direct-API extension and
+    // Bedrock rejects it as an extra input. The marker itself is fine and
+    // caching works without the field, so strip just the ttl and keep the
+    // breakpoint. Transport quirks belong to the transport, not to every
+    // caller that sets cacheTtl. (Connectome issue #35.)
     const sanitizedMessages = (request.messages as any[]).map((msg: any) => {
       if (!Array.isArray(msg.content)) return msg;
       return {
@@ -355,9 +410,9 @@ export class BedrockAdapter implements ProviderAdapter {
         content: msg.content.map((block: any) => {
           if (block.type === 'image' && block.sourceUrl !== undefined) {
             const { sourceUrl, ...rest } = block;
-            return rest;
+            return stripCacheTtl(rest);
           }
-          return block;
+          return stripCacheTtl(block);
         }),
       };
     });
@@ -377,6 +432,10 @@ export class BedrockAdapter implements ProviderAdapter {
       if (needsFlatten && Array.isArray(request.system)) {
         const blocks = request.system as Array<{ type: string; text: string }>;
         params.system = blocks.map(b => b.text).join('\n\n');
+      } else if (Array.isArray(request.system)) {
+        params.system = (request.system as Array<Record<string, any>>).map(
+          b => stripCacheTtl(b)
+        ) as BedrockMessageRequest['system'];
       } else {
         params.system = request.system as BedrockMessageRequest['system'];
       }
@@ -400,7 +459,7 @@ export class BedrockAdapter implements ProviderAdapter {
     }
 
     if (request.tools && request.tools.length > 0) {
-      params.tools = request.tools;
+      params.tools = (request.tools as Array<Record<string, any>>).map(t => stripCacheTtl(t));
     }
 
     // Handle extended thinking
@@ -434,7 +493,7 @@ export class BedrockAdapter implements ProviderAdapter {
     signal?: AbortSignal
   ): Promise<BedrockMessageResponse> {
     const url = new URL(
-      `https://bedrock-runtime.${this.region}.amazonaws.com/model/${encodeURIComponent(modelId)}/invoke`
+      `${this.baseURL ?? `https://bedrock-runtime.${this.region}.amazonaws.com`}/model/${encodeURIComponent(modelId)}/invoke`
     );
 
     const body = JSON.stringify(request);
@@ -477,7 +536,7 @@ export class BedrockAdapter implements ProviderAdapter {
     signal?: AbortSignal
   ): Promise<ProviderResponse> {
     const url = new URL(
-      `https://bedrock-runtime.${this.region}.amazonaws.com/model/${encodeURIComponent(modelId)}/invoke-with-response-stream`
+      `${this.baseURL ?? `https://bedrock-runtime.${this.region}.amazonaws.com`}/model/${encodeURIComponent(modelId)}/invoke-with-response-stream`
     );
 
     const body = JSON.stringify(request);
@@ -516,6 +575,8 @@ export class BedrockAdapter implements ProviderAdapter {
     let finalMessage: BedrockMessageResponse | undefined;
     let inputTokens = 0;
     let outputTokens = 0;
+    let cacheCreationTokens: number | undefined;
+    let cacheReadTokens: number | undefined;
     let stopReason: string = 'end_turn';
     let stopSequence: string | undefined;
     let fullText = '';
@@ -630,7 +691,19 @@ export class BedrockAdapter implements ProviderAdapter {
                 }
 
                 if (eventData.type === 'message_start' && eventData.message) {
-                  inputTokens = eventData.message.usage?.input_tokens ?? 0;
+                  // Cache metrics ride the same usage objects as on the direct
+                  // API. Dropping them (pre-2026-07-31) made caching look
+                  // permanently inert on Bedrock streams: complete() surfaced
+                  // them, stream() zeroed them, and every ledger/pricing
+                  // consumer downstream saw zeros. (Connectome issue #35.)
+                  const startUsage = eventData.message.usage;
+                  inputTokens = startUsage?.input_tokens ?? 0;
+                  if (startUsage?.cache_creation_input_tokens != null) {
+                    cacheCreationTokens = startUsage.cache_creation_input_tokens;
+                  }
+                  if (startUsage?.cache_read_input_tokens != null) {
+                    cacheReadTokens = startUsage.cache_read_input_tokens;
+                  }
                 } else if (eventData.type === 'content_block_start') {
                   currentBlockIndex = eventData.index ?? 0;
                   contentBlocks[currentBlockIndex] = eventData.content_block as { type: string };
@@ -679,6 +752,15 @@ export class BedrockAdapter implements ProviderAdapter {
                 } else if (eventData.type === 'message_delta') {
                   if (eventData.usage) {
                     outputTokens = eventData.usage.output_tokens;
+                    // message_delta carries cumulative cache metrics — use as
+                    // authoritative when present (same contract as the
+                    // Anthropic adapter).
+                    if (eventData.usage.cache_creation_input_tokens != null) {
+                      cacheCreationTokens = eventData.usage.cache_creation_input_tokens;
+                    }
+                    if (eventData.usage.cache_read_input_tokens != null) {
+                      cacheReadTokens = eventData.usage.cache_read_input_tokens;
+                    }
                   }
                   if (eventData.delta?.stop_reason) {
                     stopReason = eventData.delta.stop_reason;
@@ -751,6 +833,8 @@ export class BedrockAdapter implements ProviderAdapter {
       usage: {
         input_tokens: inputTokens,
         output_tokens: outputTokens,
+        ...(cacheCreationTokens != null ? { cache_creation_input_tokens: cacheCreationTokens } : {}),
+        ...(cacheReadTokens != null ? { cache_read_input_tokens: cacheReadTokens } : {}),
       },
     };