@animalabs/membrane 0.5.79 → 0.5.81

package/dist/membrane.js

@@ -4,17 +4,104 @@
  * A selective boundary that transforms what passes through.
  */
 import { lastCacheableBlockIndex } from './formatters/native.js';
-import { DEFAULT_RETRY_CONFIG, MembraneError, classifyError, isOverloadedError, } from './types/index.js';
-import { parseToolCalls, formatToolResults, parseAccumulatedIntoBlocks, hasImageInToolResults, formatToolResultsForSplitTurn, } from './utils/tool-parser.js';
+import { sameThinkingText, findSpanningProviderRun, thinkingCarrierKey, stripThinkingForPrefill, } from './utils/thinking-carriers.js';
+import { countWireCacheMarkers, clampCacheMarkers, ownSystemBlocks, MAX_CACHE_BREAKPOINTS, } from './utils/cache-marker-budget.js';
+import { DEFAULT_RETRY_CONFIG, MembraneError, classifyError, isOverloadedError, isTimeoutAbortError, unsupportedError, } from './types/index.js';
+import { parseToolCalls, formatToolResults, parseAccumulatedIntoBlocks, endsWithPartialToolBlock, hasImageInToolResults, formatToolResultsForSplitTurn, } from './utils/tool-parser.js';
 import { AnthropicXmlFormatter } from './formatters/anthropic-xml.js';
-import { normalizeToolPairs, mergeConsecutiveRoles } from './formatters/normalize-tool-pairs.js';
+import { normalizeToolPairs, mergeConsecutiveRoles, PREFIX_REWRITING_NORMALIZE_EVENT_KINDS, } from './formatters/normalize-tool-pairs.js';
 import { YieldingStreamImpl } from './yielding-stream.js';
-import { calculateCost } from './utils/cost.js';
+import { calculateCost, warnUnpricedModel } from './utils/cost.js';
+import { TurnUsageAccumulator, calculateCacheHitRatio, normalizeUsageToCacheExcluded, warnUnconvertibleProviderItem, } from './utils/usage.js';
 import { isAcceptedImageMediaType, strippedImagePlaceholder, shedImagesToFitByteBudget, assertWithinByteBudget, } from './utils/image-media.js';
 import { getDefaultPricing } from './registry/default-pricing.js';
 // ============================================================================
 // Membrane Class
 // ============================================================================
+/**
+ * Block-lifecycle tracking shared by the two native-tools streaming paths
+ * (`streamWithNativeTools` and `runNativeToolsYielding`).
+ *
+ * Providers signal blocks through `onContentBlock(index, block)`, but not all
+ * of them the same way: the Anthropic and Bedrock adapters fire it twice per
+ * index (content_block_start with an empty block, content_block_stop with the
+ * finalised one), while the OpenAI Responses adapter fires it ONCE per block,
+ * already finalised, after the stream has ended. Treating "second sighting"
+ * as the only completion signal therefore left single-callback adapters with
+ * `block_start` events that never completed (#63 review). The tracker keeps
+ * the paired semantics and adds `flush()`, which the caller runs once the
+ * provider stream has returned: every started block that never saw a second
+ * callback is completed from the last block payload seen for it.
+ */
+class NativeBlockTracker {
+    emit;
+    currentType = 'text';
+    blockIndex = 0;
+    started = new Map();
+    completed = new Set();
+    lastSeen = new Map();
+    constructor(emit) {
+        this.emit = emit;
+    }
+    static mapApiBlockType(apiType) {
+        if (apiType === 'thinking' || apiType === 'redacted_thinking' || apiType === 'reasoning')
+            return 'thinking';
+        if (apiType === 'tool_use' || apiType === 'function_call' || apiType === 'tool_call')
+            return 'tool_call';
+        return 'text';
+    }
+    /** Provider block callback: first sighting of an index starts it, a second completes it. */
+    onProviderBlock(index, block) {
+        this.lastSeen.set(index, block);
+        if (!this.started.has(index)) {
+            const mbType = NativeBlockTracker.mapApiBlockType(block?.type);
+            this.started.set(index, mbType);
+            this.currentType = mbType;
+            this.blockIndex = index;
+            this.emit?.({ event: 'block_start', index, block: { type: mbType } });
+            return;
+        }
+        this.complete(index, block);
+    }
+    /**
+     * Complete every started block that never received its second callback.
+     * Run after the provider stream has returned; idempotent, and a no-op for
+     * paired-callback adapters.
+     */
+    flush() {
+        for (const index of this.started.keys()) {
+            if (!this.completed.has(index))
+                this.complete(index, this.lastSeen.get(index));
+        }
+    }
+    /** Discard tracking state (refusal retry rolled the attempt back). */
+    reset() {
+        this.currentType = 'text';
+        this.blockIndex = 0;
+        this.started.clear();
+        this.completed.clear();
+        this.lastSeen.clear();
+    }
+    complete(index, block) {
+        if (this.completed.has(index))
+            return;
+        this.completed.add(index);
+        const mbType = this.started.get(index)
+            ?? NativeBlockTracker.mapApiBlockType(block?.type);
+        const apiBlock = block;
+        const mb = { type: mbType };
+        if (mbType === 'text')
+            mb.content = apiBlock?.text;
+        else if (mbType === 'thinking')
+            mb.content = apiBlock?.thinking;
+        else if (mbType === 'tool_call') {
+            mb.toolId = apiBlock?.id;
+            mb.toolName = apiBlock?.name;
+            mb.input = apiBlock?.input;
+        }
+        this.emit?.({ event: 'block_complete', index, block: mb });
+    }
+}
 export class Membrane {
     adapter;
     registry;
@@ -47,17 +134,27 @@ export class Membrane {
         // refusal is a successful HTTP call with an unwanted verdict, and letting
         // it consume error retries would couple two unrelated budgets.
         let refusalRetriesUsed = 0;
+        // Spend on attempts we threw away. A refused attempt is a completed,
+        // billed HTTP call; reporting only the surviving attempt's usage
+        // under-reports the turn by one full call per retry.
+        let discardedUsage;
+        // One selection for the whole call: mode resolution and the build must
+        // name the same formatter instance (see resolveActiveFormatter).
+        const activeFormatter = this.resolveActiveFormatter(options.formatter);
         while (true) {
             attempts++;
             try {
-                const { providerRequest, prefillResult } = this.transformRequest(request, options.formatter);
+                const { providerRequest, prefillResult } = this.transformRequest(request, activeFormatter);
                 // Route through the single canonical hook helper so any future
                 // change to hook semantics (logging, retry interaction, error
                 // handling) applies to both complete() and the streaming paths.
                 // Cast back to the local provider-request shape: the hook returns
                 // `unknown` deliberately, and we acknowledge the cast at the boundary.
                 const finalRequest = (await this.applyBeforeRequestHook(request, providerRequest));
-                const providerResponse = await this.adapter.complete(finalRequest, {
+                // Last exit before the adapter: the only place that sees EVERY
+                // contribution (builder, formatter, passthrough, float, hook).
+                clampCacheMarkers(finalRequest, 'complete');
+                const rawProviderResponse = await this.adapter.complete(finalRequest, {
                     signal: options.signal,
                     timeoutMs: options.timeoutMs,
                     onRequest: (req) => {
@@ -65,6 +162,11 @@ export class Membrane {
                         options.onRequest?.(req);
                     },
                 });
+                // Restate usage in the one convention before any ratio or price sees it.
+                const providerResponse = {
+                    ...rawProviderResponse,
+                    usage: normalizeUsageToCacheExcluded(rawProviderResponse.usage, this.adapter.name, this.adapter.usageCacheConvention),
+                };
                 // Call onResponse callback with raw response from API
                 options.onResponse?.(providerResponse.raw);
                 const response = this.transformResponse(providerResponse, request, prefillResult, startTime, attempts, rawRequest);
@@ -76,8 +178,16 @@ export class Membrane {
                 if (response.stopReason === 'refusal' &&
                     refusalRetriesUsed < Math.max(0, options.refusalRetries ?? 0)) {
                     refusalRetriesUsed++;
+                    discardedUsage = this.mergeDiscardedAttempts(discardedUsage, this.discardedAttemptFrom(response.usage));
                     continue;
                 }
+                // Report what the discarded attempts cost. Set BEFORE afterResponse
+                // so a hook that logs spend sees the whole turn, not just the
+                // attempt that stands.
+                if (discardedUsage) {
+                    response.details.usage.discardedAttempts =
+                        this.pricedDiscardedAttempts(discardedUsage, request.config.model);
+                }
                 // Call afterResponse hook
                 if (this.config.hooks?.afterResponse) {
                     return await this.config.hooks.afterResponse(response, providerResponse.raw);
@@ -111,9 +221,17 @@ export class Membrane {
                             throw new MembraneError(errorInfo);
                         }
                     }
-                    // Wait before retry (abort-aware)
+                    // Wait before retry (abort-aware). An abort landing inside the
+                    // sleep must fail like every other failure of this method — a
+                    // MembraneError — rather than escaping the loop as a raw
+                    // DOMException whose shape no caller of complete() expects.
                     const delay = this.calculateRetryDelay(attempts, isOverloaded);
-                    await this.sleep(delay, options.signal);
+                    try {
+                        await this.sleep(delay, options.signal);
+                    }
+                    catch (sleepError) {
+                        throw this.attachRawRequest(sleepError, rawRequest);
+                    }
                     continue;
                 }
                 throw new MembraneError(errorInfo);
@@ -142,6 +260,18 @@ export class Membrane {
         // If streaming is explicitly disabled on the request, fall back to complete()
         // and synthesize the streaming callbacks from the full response
         if (request.streaming === false) {
+            // complete() has no tool loop, and neither branch of this fallback can
+            // build one: honouring onToolCalls here would mean re-implementing the
+            // whole XML/native continuation machinery. Silently dropping it turned
+            // a working agent into one that narrates tool calls it never makes —
+            // the raw <function_calls> XML lands in the returned text and the turn
+            // ends. Refuse where the option is passed, before spending a call.
+            if (options.onToolCalls) {
+                throw unsupportedError('stream() cannot execute tools with streaming: false — the non-streaming ' +
+                    'fallback routes to complete(), which has no tool loop, so onToolCalls ' +
+                    'would never run. Leave streaming enabled (or drive the loop yourself ' +
+                    'with complete() per round).');
+            }
             const response = await this.complete(request, options);
             // Synthesize onChunk callbacks so callers that depend on them still work
             if (options.onChunk && 'content' in response) {
@@ -158,8 +288,9 @@ export class Membrane {
             }
             return response;
         }
-        // Determine tool mode
-        const toolMode = this.resolveToolMode(request);
+        // Determine tool mode against the formatter that will build the request
+        const activeFormatter = this.resolveActiveFormatter(options.formatter);
+        const toolMode = this.resolveToolMode(request, activeFormatter);
         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 —
@@ -186,14 +317,16 @@ export class Membrane {
             };
             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.
+                    ? await this.streamWithNativeTools(request, tracked, activeFormatter)
+                    : await this.streamWithXmlTools(request, tracked, activeFormatter);
+                // The inner paths count their own provider calls but cannot see this
+                // wrapper's discarded attempts. Each failed attempt here died before
+                // emitting anything (that is the precondition for retrying), so it
+                // cost at least the one call it failed on — ADD those to the inner
+                // count rather than overwriting it, or a turn that retried twice and
+                // then ran three tool rounds would report 2 calls instead of 5.
                 if (attempts > 1 && 'details' in result) {
-                    result.details.timing.attempts = attempts;
+                    result.details.timing.attempts += attempts - 1;
                     result.details.timing.retryDelaysMs = retryDelaysMs;
                 }
                 return result;
@@ -218,7 +351,21 @@ export class Membrane {
                     }
                     const delay = this.calculateRetryDelay(attempts, true);
                     retryDelaysMs.push(delay);
-                    await this.sleep(delay, options.signal);
+                    // An abort during the backoff window is still a cancellation of
+                    // this stream, and stream() documents cancellation as an
+                    // AbortedResponse. Letting the sleep's rejection escape made that
+                    // contract depend on which millisecond the abort landed in.
+                    // Nothing has been emitted on this path (that is the precondition
+                    // for retrying at all), so there is no partial content to report.
+                    try {
+                        await this.sleep(delay, options.signal);
+                    }
+                    catch (sleepError) {
+                        if (this.isAbortError(sleepError)) {
+                            return this.buildAbortedResponse('', { inputTokens: 0, outputTokens: 0 }, [], [], this.abortReason(sleepError, options.signal));
+                        }
+                        throw sleepError;
+                    }
                     continue;
                 }
                 throw error;
@@ -226,17 +373,62 @@ export class Membrane {
         }
     }
     /**
-     * Determine the effective tool mode
+     * Select the ACTIVE formatter for a request: the one instance that resolves
+     * its tool mode, builds its provider request, and parses its stream.
+     *
+     * A per-request override (`CompleteOptions.formatter` /
+     * `StreamOptions.formatter`) wins over the instance formatter, with ONE
+     * transport exception: the Responses adapter's input is a provider-native
+     * item array, and a generic override (for example Context Manager's
+     * NativeFormatter) produces Anthropic-style `{ role, content: [{ type:
+     * 'text' }] }` envelopes the Responses API rejects before inference — so a
+     * configured Responses formatter stays authoritative there.
+     *
+     * The exception is why this selection is a method rather than a `??` at each
+     * call site: while it lived inside transformRequest alone, the BUILD honored
+     * it and every other formatter reader resolved against a different instance,
+     * which is the split resolveToolMode exists to prevent, one layer down.
+     * Every entry point selects once, here, and threads the result.
      */
-    resolveToolMode(request) {
+    resolveActiveFormatter(requestFormatter) {
+        if (this.adapter.name === 'openai-responses-api' && this.formatter.name === 'openai-responses') {
+            return this.formatter;
+        }
+        return requestFormatter ?? this.formatter;
+    }
+    /**
+     * Determine the effective tool mode.
+     *
+     * THE single source of truth for the mode: both complete() (via
+     * transformRequest → BuildOptions.toolMode) and the streaming paths (via
+     * their native-vs-XML path choice) resolve here, so a given request resolves
+     * to the same mode whichever entry point it arrives through.
+     *
+     * Precedence, strongest first:
+     *   1. an explicit non-'auto' `request.toolMode`
+     *   2. the mode the BUILDING formatter was explicitly constructed with
+     *      (`AnthropicXmlFormatter({ toolMode: 'native' })`) — a caller's stated
+     *      choice, not a derivation
+     *   3. formatter/provider derivation
+     *
+     * `formatter` is the formatter that will actually build the request — the
+     * instance `resolveActiveFormatter` selected for this call — because
+     * resolving against one formatter while building with another is exactly the
+     * split this method exists to prevent.
+     */
+    resolveToolMode(request, formatter = this.formatter) {
         // Explicit mode takes precedence
         if (request.toolMode && request.toolMode !== 'auto') {
             return request.toolMode;
         }
+        // A formatter constructed with an explicit mode states its caller's choice
+        if (formatter.configuredToolMode) {
+            return formatter.configuredToolMode;
+        }
         // Auto mode: choose based on formatter
         // NativeFormatter → native tools via API
         // AnthropicXmlFormatter (default) → XML tools in prefill
-        if (this.formatter.name === 'native' || this.formatter.name === 'openai-responses') {
+        if (formatter.name === 'native' || formatter.name === 'openai-responses') {
             return 'native';
         }
         // Also handle known native-tool providers regardless of formatter
@@ -253,16 +445,25 @@ export class Membrane {
      * - False-positive stop sequence detection (e.g., "\nUser:" inside tool results)
      * - Structured block events for UI
      */
-    async streamWithXmlTools(request, options) {
+    async streamWithXmlTools(request, options, activeFormatter = this.resolveActiveFormatter(options.formatter)) {
         const startTime = Date.now();
-        const { onChunk, onContentBlockUpdate, onToolCalls, onPreToolContent, onUsage, onBlock, onRequest, onResponse, maxToolDepth = 10, signal, formatter: requestFormatter, } = options;
-        // Use per-request formatter if provided, otherwise use instance formatter
-        const formatter = requestFormatter ?? this.formatter;
+        const { onChunk, onContentBlockUpdate, onToolCalls, onPreToolContent, onUsage, onBlock, onRequest, onResponse, maxToolDepth = 10, signal, timeoutMs, idleTimeoutMs, } = options;
+        // The formatter stream() selected: the same instance that resolved the
+        // mode and will build the request, so the parser can never be reading a
+        // different format than the one on the wire.
+        const formatter = activeFormatter;
         // Initialize parser from formatter for format-specific tracking
         const parser = formatter.createStreamParser();
         let toolDepth = 0;
-        let totalUsage = { inputTokens: 0, outputTokens: 0 };
-        const pricing = this.resolvePricing(request.config.model);
+        // Each round is priced under the model that served THAT round and the
+        // costs are summed: a routed turn can change models mid-turn, and pricing
+        // the whole accumulated usage at the latest rate re-bills every earlier
+        // round at a price it was never charged.
+        const turnUsage = new TurnUsageAccumulator(request.config.model, (servedModel) => this.resolvePricing(request.config.model, servedModel));
+        // Honest turn telemetry: provider calls actually made (including refusal
+        // re-issues inside streamOnce) and continuation rounds.
+        let providerCalls = 0;
+        let rounds = 0;
         const contentBlocks = [];
         let lastStopReason = 'end_turn';
         let lastStopSequence;
@@ -337,13 +538,13 @@ export class Membrane {
             resumptionRounds++;
             if (resumptionRounds === RESUMPTION_WARN_ROUNDS) {
                 warnLog.warn(`[membrane] automatic resumption at round ${resumptionRounds} ` +
-                    `(${totalUsage.inputTokens} input tokens so far this turn) — ` +
+                    `(${turnUsage.total.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.`);
+                    `${turnUsage.total.inputTokens} input tokens spent this turn.`);
                 return false;
             }
             return true;
@@ -407,6 +608,8 @@ export class Membrane {
                         : undefined,
                 }, {
                     signal,
+                    timeoutMs,
+                    idleTimeoutMs,
                     normalizedRequest: request,
                     // The tag-based parser tracks thinking via <thinking> tags — ask the
                     // provider to wrap native thinking deltas so they don't stream as
@@ -417,6 +620,8 @@ export class Membrane {
                         onRequest?.(req);
                     },
                 });
+                rounds++;
+                providerCalls += streamResult.providerCalls;
                 // If we detected stop sequence manually, fix up the parser and result
                 if (detectedStopSequence && truncatedAccumulated !== null) {
                     parser.reset();
@@ -446,18 +651,11 @@ export class Membrane {
                 onResponse?.(rawResponse);
                 lastStopReason = this.mapStopReason(streamResult.stopReason);
                 lastStopSequence = streamResult.stopSequence ?? undefined;
-                // Accumulate usage (including cache metrics)
-                totalUsage.inputTokens += streamResult.usage.inputTokens;
-                totalUsage.outputTokens += streamResult.usage.outputTokens;
-                if (streamResult.usage.cacheCreationTokens) {
-                    totalUsage.cacheCreationTokens = (totalUsage.cacheCreationTokens ?? 0) + streamResult.usage.cacheCreationTokens;
-                }
-                if (streamResult.usage.cacheReadTokens) {
-                    totalUsage.cacheReadTokens = (totalUsage.cacheReadTokens ?? 0) + streamResult.usage.cacheReadTokens;
-                }
-                if (pricing)
-                    totalUsage.estimatedCost = calculateCost(totalUsage, pricing);
-                onUsage?.(totalUsage);
+                // Accumulate usage (including cache metrics), priced at this round's
+                // model. NOT inlined into the optional call — `onUsage?.(addRound())`
+                // skips evaluating its argument entirely when no callback is set.
+                const usageSoFar = turnUsage.addRound(streamResult.model, streamResult.usage);
+                onUsage?.(usageSoFar);
                 // Flush the parser to complete any in-progress streaming block
                 const flushResult = parser.flush();
                 for (const emission of flushResult.emissions) {
@@ -485,7 +683,7 @@ export class Membrane {
                         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.`);
+                            `stopReason 'no_progress'. ${turnUsage.total.inputTokens} input tokens spent this turn.`);
                         lastStopReason = 'no_progress';
                         break;
                     }
@@ -718,14 +916,14 @@ export class Membrane {
             // The full accumulated text is still available in raw.response
             const fullAccumulated = parser.getAccumulated();
             const newContent = fullAccumulated.slice(initialPrefillLength);
-            const response = this.buildFinalResponse(newContent, contentBlocks, lastStopReason, totalUsage, request, prefillResult, startTime, 1, // attempts
-            rawRequest, rawResponse, executedToolCalls, executedToolResults, initialBlockType, lastStopSequence);
+            const response = this.buildFinalResponse(newContent, contentBlocks, lastStopReason, turnUsage, request, prefillResult, startTime, providerCalls, rawRequest, rawResponse, executedToolCalls, executedToolResults, initialBlockType, lastStopSequence);
             // Append non-text content blocks (e.g., generated_image) that the XML parser can't handle
             if (extraContentBlocks.length > 0) {
                 response.content.push(...extraContentBlocks);
             }
             // Merge provider thinking signatures into parser-derived thinking blocks
             this.mergeProviderThinkingBlocks(response.content, providerThinkingBlocks);
+            response.details.timing.rounds = rounds;
             return response;
         }
         catch (error) {
@@ -734,7 +932,7 @@ export class Membrane {
                 // Only use NEW content (after initial prefill) for partial content
                 const fullAccumulated = parser.getAccumulated();
                 const newContent = fullAccumulated.slice(initialPrefillLength);
-                return this.buildAbortedResponse(newContent, totalUsage, executedToolCalls, executedToolResults, 'user', initialBlockType);
+                return this.buildAbortedResponse(newContent, turnUsage.total, executedToolCalls, executedToolResults, this.abortReason(error, signal), initialBlockType);
             }
             // Re-throw with rawRequest attached for logging
             throw this.attachRawRequest(error, rawRequest);
@@ -743,12 +941,17 @@ export class Membrane {
     /**
      * Stream with native API tool execution
      */
-    async streamWithNativeTools(request, options) {
+    async streamWithNativeTools(request, options, activeFormatter = this.resolveActiveFormatter(options.formatter)) {
         const startTime = Date.now();
-        const { onChunk, onContentBlockUpdate, onToolCalls, onPreToolContent, onUsage, onRequest, onResponse, maxToolDepth = 10, signal, } = options;
+        const { onChunk, onContentBlockUpdate, onBlock, onToolCalls, onPreToolContent, onUsage, onRequest, onResponse, maxToolDepth = 10, signal, timeoutMs, idleTimeoutMs, } = options;
         let toolDepth = 0;
-        let totalUsage = { inputTokens: 0, outputTokens: 0 };
-        const pricing = this.resolvePricing(request.config.model);
+        // See streamWithXmlTools: one accumulator per turn, pricing each round
+        // under the model that served it.
+        const turnUsage = new TurnUsageAccumulator(request.config.model, (servedModel) => this.resolvePricing(request.config.model, servedModel));
+        // Honest turn telemetry: provider calls actually made (including refusal
+        // re-issues inside streamOnce) and continuation rounds.
+        let providerCalls = 0;
+        let rounds = 0;
         let lastStopReason = 'end_turn';
         let lastStopSequence;
         let rawRequest;
@@ -761,55 +964,69 @@ export class Membrane {
         // Build messages array that we'll update with tool results
         let messages = [...request.messages];
         let allContentBlocks = [];
+        let markersInLastRequest = 0;
         try {
             // Tool execution loop
             while (toolDepth <= maxToolDepth) {
                 // Build provider request with native tools
-                const providerRequest = this.buildNativeToolRequest(request, messages);
+                const providerRequest = this.buildNativeToolRequest(request, messages, toolDepth > 0, activeFormatter);
                 // Stream from provider
                 let textAccumulated = '';
-                let blockIndex = 0;
+                // Tag every token chunk with the membrane block it belongs to and
+                // surface the block lifecycle through onBlock — the same shape
+                // runNativeToolsYielding uses (#19). Before this, meta.type was
+                // hardcoded to 'text' on every chunk and onBlock was never invoked
+                // from this path (#20).
+                const tracker = new NativeBlockTracker(onBlock ? (event) => onBlock(event) : undefined);
                 const streamResult = await this.streamOnce(providerRequest, {
                     onChunk: (chunk) => {
                         textAccumulated += chunk;
                         allTextAccumulated += chunk;
-                        // For native mode, emit text chunks with basic metadata
-                        // TODO: Use native API content_block events for richer metadata
                         const meta = {
-                            type: 'text',
-                            visible: true,
-                            blockIndex,
+                            type: tracker.currentType,
+                            visible: tracker.currentType === 'text',
+                            blockIndex: tracker.blockIndex,
                         };
                         onChunk?.(chunk, meta);
                     },
-                    onContentBlock: onContentBlockUpdate
-                        ? (index, block) => onContentBlockUpdate(index, block)
-                        : undefined,
+                    onContentBlock: (index, block) => {
+                        tracker.onProviderBlock(index, block);
+                        // Deprecated pass-through, kept for callers still on it.
+                        onContentBlockUpdate?.(index, block);
+                    },
                 }, {
                     signal,
+                    timeoutMs,
+                    idleTimeoutMs,
                     normalizedRequest: request,
                     onRequest: (req) => {
                         rawRequest = req;
                         onRequest?.(req);
                     },
+                    // Telemetry reports what this request actually SHIPPED with —
+                    // builder breakpoints, stale passthrough, fallback, float, plus
+                    // whatever the beforeRequest hook and the wire clamp did after
+                    // the build. Both native paths used to hardcode 0, and counting
+                    // at build time reported a number no request ever had.
+                    onWireCacheMarkers: (markerCount) => {
+                        markersInLastRequest = markerCount;
+                    },
                 });
+                // Single-callback adapters (OpenAI Responses) report each finalised
+                // block once, after the stream: complete whatever never saw a stop.
+                tracker.flush();
+                rounds++;
+                providerCalls += streamResult.providerCalls;
                 rawResponse = streamResult.raw;
                 // Call onResponse callback with raw response from API
                 onResponse?.(rawResponse);
                 lastStopReason = this.mapStopReason(streamResult.stopReason);
                 lastStopSequence = streamResult.stopSequence ?? undefined;
-                // Accumulate usage (including cache metrics)
-                totalUsage.inputTokens += streamResult.usage.inputTokens;
-                totalUsage.outputTokens += streamResult.usage.outputTokens;
-                if (streamResult.usage.cacheCreationTokens) {
-                    totalUsage.cacheCreationTokens = (totalUsage.cacheCreationTokens ?? 0) + streamResult.usage.cacheCreationTokens;
-                }
-                if (streamResult.usage.cacheReadTokens) {
-                    totalUsage.cacheReadTokens = (totalUsage.cacheReadTokens ?? 0) + streamResult.usage.cacheReadTokens;
-                }
-                if (pricing)
-                    totalUsage.estimatedCost = calculateCost(totalUsage, pricing);
-                onUsage?.(totalUsage);
+                // Accumulate usage (including cache metrics), priced at this round's
+                // model. NOT inlined into the optional call — `onUsage?.(addRound())`
+                // skips evaluating its argument entirely when no callback is set.
+                const usageSoFar = turnUsage.addRound(streamResult.model, streamResult.usage);
+                onUsage?.(usageSoFar);
                 // Parse content blocks from response
                 const responseBlocks = this.parseProviderContent(streamResult.content);
                 allContentBlocks.push(...responseBlocks);
@@ -879,6 +1096,7 @@ export class Membrane {
                 break;
             }
             const durationMs = Date.now() - startTime;
+            const totalUsage = turnUsage.total;
             return {
                 content: allContentBlocks,
                 rawAssistantText: allTextAccumulated,
@@ -895,15 +1113,17 @@ export class Membrane {
                     usage: { ...totalUsage },
                     timing: {
                         totalDurationMs: durationMs,
-                        attempts: 1,
+                        attempts: providerCalls,
+                        rounds,
                     },
                     model: {
                         requested: request.config.model,
-                        actual: request.config.model,
+                        actual: turnUsage.lastServedModel || request.config.model,
                         provider: this.adapter.name,
+                        perRound: turnUsage.perRound,
                     },
                     cache: {
-                        markersInRequest: 0,
+                        markersInRequest: markersInLastRequest,
                         tokensCreated: totalUsage.cacheCreationTokens ?? 0,
                         tokensRead: totalUsage.cacheReadTokens ?? 0,
                         hitRatio: this.calculateCacheHitRatio(totalUsage),
@@ -918,22 +1138,60 @@ export class Membrane {
         catch (error) {
             // Check if this is an abort error
             if (this.isAbortError(error)) {
-                return this.buildAbortedResponse(allTextAccumulated, totalUsage, executedToolCalls, executedToolResults, 'user');
+                return this.buildAbortedResponse(allTextAccumulated, turnUsage.total, executedToolCalls, executedToolResults, this.abortReason(error, signal));
             }
             // Re-throw with rawRequest attached for logging
             throw this.attachRawRequest(error, rawRequest);
         }
     }
     /**
-     * Build a provider request with native tool support
+     * Rate-limit state for the float's budget warning. See the
+     * floating-cache-marker block in buildNativeToolRequest.
+     *
+     * A once-per-instance latch made the ONLY observable of an over-budget wire
+     * go quiet for the life of the process: a long-lived Membrane warns for the
+     * first agent that trips it and never again, so the condition looks like it
+     * healed. Warn on the first occurrence, then at most once per interval,
+     * carrying the count of what was suppressed in between.
      */
-    buildNativeToolRequest(request, messages) {
+    floatBudgetWarnState = { lastWarnedAtMs: 0, suppressedSinceWarn: 0 };
+    static FLOAT_BUDGET_WARN_INTERVAL_MS = 60_000;
+    warnFloatBudgetExhausted(wireMarkers) {
+        const now = Date.now();
+        const state = this.floatBudgetWarnState;
+        const elapsed = now - state.lastWarnedAtMs;
+        if (state.lastWarnedAtMs !== 0 && elapsed < Membrane.FLOAT_BUDGET_WARN_INTERVAL_MS) {
+            state.suppressedSinceWarn++;
+            return;
+        }
+        const suppressed = state.suppressedSinceWarn;
+        state.lastWarnedAtMs = now;
+        state.suppressedSinceWarn = 0;
+        console.warn(`[membrane] floating cache marker withheld: upstream markers already ` +
+            `occupy all ${MAX_CACHE_BREAKPOINTS} cache_control slots (${wireMarkers} on the wire). ` +
+            `Tool-round suffixes will not cache incrementally.` +
+            (suppressed > 0 ? ` (${suppressed} further occurrences suppressed since the last warning.)` : ''));
+    }
+    /**
+     * Build a provider request with native tool support.
+     *
+     * `toolLoopRebuild` is true when this build is a tool-loop continuation
+     * (toolDepth > 0) rather than the turn's first request — the only case
+     * where the floating cache marker applies.
+     *
+     * `activeFormatter` is the formatter the caller selected for the request
+     * (see resolveActiveFormatter). Reading `this.formatter` here instead made
+     * the native loop build through the instance formatter while the mode had
+     * been resolved against a per-request override — the two disagreeing about
+     * which formatter is active.
+     */
+    buildNativeToolRequest(request, messages, toolLoopRebuild = false, activeFormatter = this.formatter) {
         // Provider-native formatters own their complete input-item shape. The
         // legacy implementation below is intentionally Anthropic-specific; using
         // it for Responses would normalize away item IDs, encrypted reasoning,
         // assistant phases, and compaction items.
-        if (this.formatter.name === 'openai-responses') {
-            return this.transformRequest({ ...request, messages }, this.formatter).providerRequest;
+        if (activeFormatter.name === 'openai-responses') {
+            return this.transformRequest({ ...request, messages }, activeFormatter).providerRequest;
         }
         // Convert messages to provider format
         const providerMessages = [];
@@ -944,10 +1202,13 @@ export class Membrane {
         // Anthropic allows at most 4 cache_control breakpoints per request. The
         // message breakpoints are the valuable ones (they cache the longest prefixes,
         // and every one already includes tools+system at the front of the request).
-        // So tools/system get a breakpoint only as a FALLBACK — when no message
-        // breakpoint was marked — otherwise they're redundant and would push the
-        // total past 4, which the API hard-rejects (the agent goes unresponsive).
-        let messageBreakpoints = 0;
+        // So tools/system get a breakpoint only as a FALLBACK — when no marker
+        // exists anywhere on the wire — otherwise they're redundant and would push
+        // the total past 4, which the API hard-rejects (the agent goes
+        // unresponsive). The fallback gate reads a RECOUNT of the built artifacts
+        // (see below), never a running tally: a running tally cannot see a
+        // caller-marked system block, and double-counts a message breakpoint that
+        // lands on a block already carrying stale cache_control.
         for (const msg of messages) {
             const isAssistant = msg.participant === assistantName;
             const role = isAssistant ? 'assistant' : 'user';
@@ -968,14 +1229,13 @@ export class Membrane {
                     }
                     const textBlock = { type: 'text', text };
                     if (block.cache_control) {
-                        textBlock.cache_control = block.cache_control;
                         // A block-level passthrough occupies one of the 4 breakpoint slots
-                        // exactly like a marked message — count it, so the tools/system
-                        // fallback below doesn't stack more on top. (Imported/seeded
-                        // conversations can carry stale request-time cache_control on
-                        // stored blocks — first seen wedging Sill 2026-07-25: 3 cm markers
-                        // + 2 stale Arc-export blocks = 5 → hard 400 on every inference.)
-                        messageBreakpoints++;
+                        // exactly like a marked message; the recount below sees it.
+                        // (Imported/seeded conversations carry stale request-time
+                        // cache_control on stored blocks — first seen wedging Sill
+                        // 2026-07-25: 3 cm markers + 2 stale Arc-export blocks = 5 → hard
+                        // 400 on every inference.)
+                        textBlock.cache_control = block.cache_control;
                     }
                     content.push(textBlock);
                 }
@@ -1052,7 +1312,6 @@ export class Membrane {
                 const bpIdx = lastCacheableBlockIndex(content);
                 if (bpIdx >= 0) {
                     content[bpIdx].cache_control = cacheControl;
-                    messageBreakpoints++;
                 }
             }
             providerMessages.push({ role, content });
@@ -1076,8 +1335,36 @@ export class Membrane {
         // tool_results to `messages`. Any unmatched tool_use that reaches
         // this splice is upstream stranding (the bug class this fix exists
         // to catch) — `[pending]` is exactly the right synthesis.
-        const normalized = normalizeToolPairs(providerMessages);
+        // A synthesized [pending] tool_result's bytes are rewritten when the
+        // real result lands — the floating-marker block below must not cache
+        // past one. `synthetic_pending_result` (not the downstream
+        // cache_suppressed_for_synthetic, which only fires when a marker was
+        // actually stripped) is the root condition.
+        // Every repair that REWRITES prefix bytes stands the float down, not just
+        // the synthetic [pending] result: a textified orphan tool_result is
+        // rewritten the same way when its real pairing arrives, so caching at or
+        // past one poisons the prefix identically. The kinds live in one exported
+        // set so a normalizer that grows a new prefix-rewriting repair cannot
+        // silently escape this guard.
+        let prefixRewritten = false;
+        const normalized = normalizeToolPairs(providerMessages, {
+            onEvent: (e) => {
+                if (PREFIX_REWRITING_NORMALIZE_EVENT_KINDS.has(e.kind))
+                    prefixRewritten = true;
+            },
+        });
         const mergedMessages = mergeConsecutiveRoles(normalized.messages);
+        // ONE recount of the constructed wire artifacts, taken BEFORE the
+        // tools/system fallback decision so the fallback and the float share a
+        // single truth. Counted post-normalize, so phase-5.5 cache suppression is
+        // already reflected. `request.system` is the caller's own system content:
+        // it explicitly accepts pre-marked blocks, and those are real wire markers
+        // that no running tally ever saw (three of them plus both fallbacks = 5 on
+        // the wire = a 400 on every inference of that config).
+        const upstreamWireMarkers = countWireCacheMarkers({
+            messages: mergedMessages,
+            system: request.system,
+        });
         // Convert tools to provider format.
         // Native tool names must match ^[a-zA-Z0-9_-]{1,128}$ — sanitize colons
         // from the module:tool namespace convention. Reversed in parseProviderContent.
@@ -1089,7 +1376,7 @@ export class Membrane {
             };
             // Cache the tool list (last tool) only as a fallback — a marked message
             // breakpoint already caches the tools as part of its prefix.
-            if (cacheControl && messageBreakpoints === 0 && request.tools && idx === request.tools.length - 1) {
+            if (cacheControl && upstreamWireMarkers === 0 && request.tools && idx === request.tools.length - 1) {
                 t.cache_control = cacheControl;
             }
             return t;
@@ -1097,14 +1384,75 @@ export class Membrane {
         // Wrap system prompt with cache_control only as a fallback (no message
         // breakpoint marked); otherwise a message breakpoint already caches
         // tools+system as part of its prefix.
-        let system = request.system;
-        if (cacheControl && messageBreakpoints === 0 && typeof system === 'string' && system.length > 0) {
+        let system = ownSystemBlocks(request.system);
+        if (cacheControl && upstreamWireMarkers === 0 && typeof system === 'string' && system.length > 0) {
             system = [{ type: 'text', text: system, cache_control: cacheControl }];
         }
-        else if (cacheControl && messageBreakpoints === 0 && Array.isArray(system) && system.length > 0) {
+        else if (cacheControl && upstreamWireMarkers === 0 && Array.isArray(system) && system.length > 0) {
             const blocks = system;
             system = blocks.map((block, idx) => idx === blocks.length - 1 ? { ...block, cache_control: cacheControl } : block);
         }
+        // ------------------------------------------------------------------
+        // Floating cache marker: incremental prompt caching inside the native
+        // tool loop. Message breakpoints are placed by the context strategy at
+        // compile time — once per turn — but this builder re-runs on every
+        // tool round with that round's messages appended, so the deepest
+        // upstream marker stays glued to the turn-start snapshot and each
+        // rebuild re-pays the entire appended suffix at full input price
+        // (qa-ops incident, 2026-08-20: two subagents re-sent a suffix growing
+        // to ~118k tokens ~30 times each — ~5.3M uncached tokens in 18 min —
+        // with their one marker sitting on message 2 of 61).
+        //
+        // The tool loop only ever appends, so a marker riding the newest
+        // message yields the intended incremental pattern: each round writes
+        // its delta and cache-reads everything before it.
+        //
+        // Authority contract: the float spends only the RESIDUAL breakpoint
+        // budget (Anthropic allows 4 cache_control including tools/system).
+        // Upstream markers are never displaced or stripped — if they fill all
+        // 4 slots the float is withheld (with a warning) and behavior is
+        // exactly pre-float. With 2+ slots free, the previous round's
+        // endpoint is marked too: a wide parallel-tool round can append more
+        // blocks than the provider's ~20-block backward search covers, which
+        // would orphan the previous round's cache entry behind an unmarked
+        // boundary.
+        //
+        // Skipped when the normalizer synthesized a [pending] tool_result:
+        // those bytes are rewritten when the real result lands, and caching
+        // past them poisons the prefix — the same rationale as the
+        // normalizer's phase 5.5 cache suppression.
+        // ------------------------------------------------------------------
+        const floatingEnabled = request.floatingCacheMarker ?? this.config.defaultFloatingCacheMarker ?? true;
+        if (toolLoopRebuild && floatingEnabled && cacheControl && !prefixRewritten) {
+            // Same recount as the fallback gate, re-taken POST-fallback so the
+            // fallback's own spend is inside the residuum.
+            const wireMarkers = countWireCacheMarkers({ messages: mergedMessages, system, tools });
+            let residuum = MAX_CACHE_BREAKPOINTS - wireMarkers;
+            if (residuum <= 0) {
+                this.warnFloatBudgetExhausted(wireMarkers);
+            }
+            else {
+                // Newest message first; then the previous round's endpoint (two
+                // wire messages back: [..., prevResults, assistant, results]).
+                const targets = [mergedMessages.length - 1, mergedMessages.length - 3];
+                for (const mi of targets) {
+                    if (residuum <= 0 || mi < 0)
+                        continue;
+                    const content = mergedMessages[mi]?.content;
+                    if (!Array.isArray(content) || content.length === 0)
+                        continue;
+                    const bpIdx = lastCacheableBlockIndex(content);
+                    if (bpIdx < 0)
+                        continue;
+                    // Already a breakpoint here (e.g. the strategy's own end marker
+                    // on the turn's first rebuild) — nothing to add.
+                    if (content[bpIdx].cache_control)
+                        continue;
+                    content[bpIdx].cache_control = cacheControl;
+                    residuum--;
+                }
+            }
+        }
         // Build thinking config for native extended thinking (budget clamped to max_tokens)
         // Fable/Mythos models: thinking is always on and unconfigurable; sampling params are removed.
         // Sending thinking config or temperature returns a 400 — omit both entirely.
@@ -1152,6 +1500,9 @@ export class Membrane {
                         id: item.id,
                         name: unsanitizeToolName(item.name),
                         input: item.input,
+                        // Arguments that never parsed: carry the marker through so a
+                        // consumer can refuse the block instead of trusting `input`.
+                        ...(item.unparseableInput !== undefined ? { unparseableInput: item.unparseableInput } : {}),
                         ...(item.rawItem ? { rawItem: item.rawItem } : {}),
                     });
                 }
@@ -1174,14 +1525,24 @@ export class Membrane {
                         mimeType: item.mimeType,
                     });
                 }
-                else if (item.rawItem) {
+                else if (item.rawItem || item.type) {
                     // Opaque Responses items such as encrypted compaction or custom
                     // tool records have no normalized ContentBlock equivalent. Retain a
                     // zero-width carrier so Chronicle and the Responses formatter can
                     // replay the raw item without surfacing synthetic prompt text.
                     // Anthropic-bound conversion paths filter these out (empty text
                     // blocks are a 400 there); the Responses formatter replays rawItem.
-                    blocks.push({ type: 'text', text: '', rawItem: item.rawItem });
+                    //
+                    // An item with a `type` this switch does not know (server_tool_use,
+                    // web_search_tool_result, search_result, mcp_tool_use, or whatever a
+                    // provider adds next) used to fall out of this chain and vanish. It
+                    // gets the same carrier treatment, holding the item itself, plus a
+                    // one-time warning so the gap surfaces instead of being inferred
+                    // later from missing content.
+                    const carriedRawItem = item.rawItem ?? item;
+                    if (!item.rawItem)
+                        warnUnconvertibleProviderItem(item.type);
+                    blocks.push({ type: 'text', text: '', rawItem: carriedRawItem });
                 }
             }
             return blocks;
@@ -1215,10 +1576,32 @@ export class Membrane {
     }
     /**
      * Merge provider thinking signatures into parser-derived thinking blocks
-     * (matched in stream order), and prepend any leftover provider blocks —
-     * signature-only thinking (display:'omitted') never appears in the text
-     * stream, so the parser produces no block for it. redacted_thinking
-     * blocks are always prepended verbatim.
+     * and prepend any leftover provider blocks — signature-only thinking
+     * (display:'omitted') never appears in the text stream, so the parser
+     * produces no block for it. redacted_thinking blocks are always prepended
+     * verbatim.
+     *
+     * Pairing is by CONTENT IDENTITY, never by index. The two lists are
+     * differently shaped whenever the provider emits a block the parser cannot
+     * see (signature-only), the parser emits a block the provider never
+     * produced (the XML path's literal `Claude: <thinking>` prefill turns
+     * VISIBLE text into a thinking block), or one provider block spans several
+     * (auto-continuation: capture runs per round while the parser sees the
+     * CONCATENATED accumulation). Index-zipping crosses the lists in all three
+     * shapes and stamps a signature onto content that never produced it —
+     * which round-trips into the consumer's stored history and fails Anthropic
+     * signature validation on the next turn.
+     *
+     * The three rules, in order:
+     *   1. identity — a provider block pairs with the parsed block whose
+     *      thinking text is the same; empty-thinking (signature-only) blocks
+     *      are never text-match candidates and are prepend-only.
+     *   2. span — a parsed block that reconstructs as the concatenation of a
+     *      RUN of consecutive unpaired provider blocks is REPLACED in place by
+     *      those originals, so the spanning block never wears a fragment's
+     *      signature and no reasoning is sent twice.
+     *   3. leftover — everything still unpaired is prepended, de-duplicated
+     *      against what `content` already carries (and against itself).
      *
      * Mutates `content` in place. Shared by the XML stream paths
      * (streamWithXmlTools and runXmlToolsYielding).
@@ -1226,20 +1609,70 @@ export class Membrane {
     mergeProviderThinkingBlocks(content, providerThinkingBlocks) {
         if (providerThinkingBlocks.length === 0)
             return;
-        const parsedThinking = content.filter((b) => b.type === 'thinking');
         const providerThinking = providerThinkingBlocks.filter((b) => b.type === 'thinking');
         const redacted = providerThinkingBlocks.filter((b) => b.type === 'redacted_thinking');
-        const matched = Math.min(providerThinking.length, parsedThinking.length);
-        for (let i = 0; i < matched; i++) {
-            const sig = providerThinking[i].signature;
-            if (sig) {
-                parsedThinking[i].signature = sig;
-            }
+        const pairedProviderBlocks = new Set();
+        const claimedParsedIndices = new Set();
+        const parsedThinkingIndices = () => content.reduce((acc, block, index) => {
+            if (block.type === 'thinking')
+                acc.push(index);
+            return acc;
+        }, []);
+        for (let p = 0; p < providerThinking.length; p++) {
+            const providerText = providerThinking[p].thinking ?? '';
+            if (providerText === '')
+                continue;
+            const match = parsedThinkingIndices().find((index) => !claimedParsedIndices.has(index) &&
+                sameThinkingText(content[index].thinking ?? '', providerText));
+            if (match === undefined)
+                continue;
+            const signature = providerThinking[p].signature;
+            if (signature)
+                content[match].signature = signature;
+            claimedParsedIndices.add(match);
+            pairedProviderBlocks.add(p);
+        }
+        for (const parsedIndex of parsedThinkingIndices().reverse()) {
+            if (claimedParsedIndices.has(parsedIndex))
+                continue;
+            const parsedText = content[parsedIndex].thinking ?? '';
+            if (parsedText === '')
+                continue;
+            const run = findSpanningProviderRun(providerThinking, pairedProviderBlocks, parsedText);
+            if (!run)
+                continue;
+            content.splice(parsedIndex, 1, ...run.map((p) => {
+                pairedProviderBlocks.add(p);
+                const block = providerThinking[p];
+                return {
+                    type: 'thinking',
+                    thinking: block.thinking ?? '',
+                    ...(block.signature ? { signature: block.signature } : {}),
+                };
+            }));
+            claimedParsedIndices.add(parsedIndex);
+        }
+        const seen = new Set(content.map((block) => thinkingCarrierKey(block)));
+        const leftover = [];
+        for (let p = 0; p < providerThinking.length; p++) {
+            if (pairedProviderBlocks.has(p))
+                continue;
+            const block = providerThinking[p];
+            const key = thinkingCarrierKey(block);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            leftover.push(block);
         }
-        const leftover = providerThinking.slice(matched);
-        if (leftover.length > 0 || redacted.length > 0) {
-            content.unshift(...leftover, ...redacted);
+        for (const block of redacted) {
+            const key = thinkingCarrierKey(block);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            leftover.push(block);
         }
+        if (leftover.length > 0)
+            content.unshift(...leftover);
     }
     // ==========================================================================
     // Internal Methods
@@ -1315,19 +1748,15 @@ export class Membrane {
         return { type: 'enabled', budget_tokens: budget, ...(display ? { display } : {}) };
     }
     /**
-     * Transform a normalized request into provider format using the formatter
+     * Transform a normalized request into provider format using the formatter.
+     *
+     * `activeFormatter` is the instance the caller already selected via
+     * resolveActiveFormatter — including that selection's Responses-transport
+     * authority rule, which used to live inline here. It is a parameter and not
+     * a re-derivation so that the formatter which BUILDS is the same one that
+     * resolved the tool mode and drives the loop.
      */
-    transformRequest(request, formatter) {
-        // The Responses adapter's input is a provider-native item array. A generic
-        // per-request formatter (for example Context Manager's NativeFormatter)
-        // produces Anthropic-style `{ role, content: [{ type: 'text' }] }`
-        // envelopes, which the Responses API rejects before inference. Keep the
-        // configured Responses formatter authoritative at this transport boundary;
-        // per-request formatter overrides remain available for adapters whose wire
-        // format supports them.
-        const activeFormatter = this.adapter.name === 'openai-responses-api' && this.formatter.name === 'openai-responses'
-            ? this.formatter
-            : formatter ?? this.formatter;
+    transformRequest(request, activeFormatter = this.formatter) {
         // Extract user-provided stop sequences
         const additionalStopSequences = Array.isArray(request.stopSequences)
             ? request.stopSequences
@@ -1341,6 +1770,10 @@ export class Membrane {
             participantMode: 'multiuser',
             assistantParticipant: request.assistantParticipant ?? this.config.assistantParticipant ?? 'Claude',
             tools: request.tools,
+            // One resolution for every entry point: complete() used to build from the
+            // formatter's constructor-time mode alone, so request.toolMode was a
+            // second, disconnected source of truth on this path.
+            toolMode: this.resolveToolMode(request, activeFormatter),
             thinking: request.config.thinking,
             systemPrompt: request.system,
             promptCaching: request.promptCaching ?? this.config.defaultPromptCaching ?? true, // Default true for backward compat
@@ -1364,7 +1797,9 @@ export class Membrane {
         const providerRequest = {
             ...this.getBaseProviderParams(request.config),
             messages: buildResult.messages,
-            system: buildResult.systemContent,
+            // Owned, not aliased: the wire clamp strips markers in place, and a
+            // formatter may pass the caller's own system array straight through.
+            system: ownSystemBlocks(buildResult.systemContent),
             stopSequences: buildResult.stopSequences,
             tools: buildResult.nativeTools,
             extra: {
@@ -1377,8 +1812,8 @@ export class Membrane {
         // literal `<thinking>` text prefix instead of the API feature — drop the
         // API param when the built request actually ends in an assistant prefill.
         // Chat-style builds (no prefill) keep it.
-        if (buildResult.assistantPrefill && providerRequest.thinking) {
-            delete providerRequest.thinking;
+        if (buildResult.assistantPrefill) {
+            stripThinkingForPrefill(providerRequest);
         }
         return { providerRequest, prefillResult: buildResult };
     }
@@ -1388,17 +1823,42 @@ export class Membrane {
         // compatibility won't catch the excess field (checked only on object
         // literals, not on variables). Leaving it in would silently leak the
         // normalized form into every adapter's options.
-        const { normalizedRequest, refusalRetries, onRetrying, ...adapterOptions } = options;
+        const { normalizedRequest, refusalRetries, onRetrying, onWireCacheMarkers, ...adapterOptions } = options;
         const finalRequest = (await this.applyBeforeRequestHook(normalizedRequest, request));
+        // Last exit before the adapter: the only place that sees EVERY
+        // contribution (builder, formatter, passthrough, float, hook). Every
+        // 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);
         // Retries are only safe when the caller can discard the abandoned
         // attempt, so they require BOTH a budget and an onRetrying hook.
         const maxAttempts = onRetrying ? Math.max(0, refusalRetries ?? 0) : 0;
         let retried = 0;
+        // Every re-issued attempt was a completed, billed provider call. The
+        // caller's usage accumulator only ever sees the surviving result, so the
+        // abandoned spend rides back out on the result itself.
+        let discardedUsage;
+        let providerCalls = 0;
         while (true) {
-            const result = await this.adapter.stream(finalRequest, callbacks, adapterOptions);
-            if (result.stopReason !== 'refusal' || retried >= maxAttempts)
-                return result;
+            providerCalls++;
+            const rawResult = await this.adapter.stream(finalRequest, callbacks, adapterOptions);
+            // Restate usage in the one convention before any accumulator, ratio or
+            // price sees it — this is the only door streamed usage enters through.
+            const result = {
+                ...rawResult,
+                usage: normalizeUsageToCacheExcluded(rawResult.usage, this.adapter.name, this.adapter.usageCacheConvention),
+            };
+            if (result.stopReason !== 'refusal' || retried >= maxAttempts) {
+                return {
+                    ...result,
+                    providerCalls,
+                    ...(discardedUsage ? { discardedUsage } : {}),
+                };
+            }
             retried++;
+            discardedUsage = this.mergeDiscardedAttempts(discardedUsage, this.discardedAttemptFrom(result.usage));
             const category = result.raw
                 ?.response?.stop_details?.category;
             onRetrying({ attempt: retried, maxAttempts, category });
@@ -1407,6 +1867,12 @@ export class Membrane {
     buildContinuationRequest(originalRequest, prefillResult, accumulated) {
         // Anthropic quirk: assistant content cannot end with trailing whitespace
         const trimmedAccumulated = accumulated.trimEnd();
+        // Everything before the watermark already rides EARLIER messages (a
+        // persisted split turn), so only the suffix belongs in the trailing
+        // assistant prefill — replacing it with the whole document would
+        // duplicate the pre-seam text and flatten the image user-turn away.
+        const baseOffset = prefillResult.accumulatedBaseOffset ?? 0;
+        const trailingContent = accumulated.slice(baseOffset).trimEnd();
         // Build continuation messages: keep all messages up to last assistant,
         // then replace/add the accumulated content
         const messages = [...prefillResult.messages];
@@ -1414,32 +1880,32 @@ export class Membrane {
         let foundAssistant = false;
         for (let i = messages.length - 1; i >= 0; i--) {
             if (messages[i]?.role === 'assistant') {
-                messages[i] = { role: 'assistant', content: trimmedAccumulated };
+                messages[i] = { role: 'assistant', content: trailingContent };
                 foundAssistant = true;
                 break;
             }
         }
         if (!foundAssistant) {
-            messages.push({ role: 'assistant', content: trimmedAccumulated });
+            messages.push({ role: 'assistant', content: trailingContent });
         }
-        return {
+        return stripThinkingForPrefill({
             ...this.getBaseProviderParams(originalRequest.config),
             // Continuations always end in an assistant prefill — the API rejects
             // extended thinking combined with prefill, so never send the param here
             thinking: undefined,
             messages,
-            system: prefillResult.systemContent
-                ? (Array.isArray(prefillResult.systemContent) && prefillResult.systemContent.length > 0
-                    ? prefillResult.systemContent
-                    : prefillResult.systemContent)
-                : undefined,
+            system: ownSystemBlocks(prefillResult.systemContent) ?? undefined,
             stopSequences: prefillResult.stopSequences,
             extra: {
                 ...originalRequest.providerParams,
+                // Same contract transformRequest sends: adapters that reason about
+                // the normalized shape (or fall back to serializing it) must not see
+                // a continuation as a request with no normalized form at all.
+                normalizedMessages: originalRequest.messages,
                 // Pre-serialized prompt for completions adapters — skip re-serialization
                 prompt: trimmedAccumulated,
             },
-        };
+        });
     }
     /**
      * Build continuation request with split-turn image injection.
@@ -1461,6 +1927,11 @@ export class Membrane {
     buildContinuationRequestWithImages(originalRequest, prefillResult, accumulated, images, afterImageXml) {
         // Anthropic quirk: assistant content cannot end with trailing whitespace
         const trimmedAccumulated = accumulated.trimEnd();
+        // The split replaces only the CURRENT trailing assistant message, which
+        // covers the accumulated text from the previous seam onward (0 on the
+        // first split, the previous image seam on a later one).
+        const baseOffset = prefillResult.accumulatedBaseOffset ?? 0;
+        const trailingContent = accumulated.slice(baseOffset).trimEnd();
         // Build messages: copy all, then replace only the last assistant with split-turn
         const messages = prefillResult.messages.map(msg => ({ ...msg }));
         // Find last assistant — replace in-place via splice to preserve history
@@ -1474,7 +1945,7 @@ export class Membrane {
         // Anthropic quirk: assistant content cannot end with trailing whitespace
         const trimmedAfterXml = afterImageXml.trimEnd();
         const splitTurnMessages = [
-            { role: 'assistant', content: trimmedAccumulated },
+            { role: 'assistant', content: trailingContent },
             { role: 'user', content: images },
             { role: 'assistant', content: trimmedAfterXml },
         ];
@@ -1484,20 +1955,39 @@ export class Membrane {
         else {
             messages.push(...splitTurnMessages);
         }
-        return {
+        // PERSIST the split. Later rounds rebuild from prefillResult.messages;
+        // without this the image user-turn exists on exactly one request and the
+        // next continuation flattens the accumulated document back over it —
+        // leaving <function_results> XML asserting a screenshot the model can no
+        // longer see. Reassign (never mutate in place): the previous array is
+        // still referenced by the request already on the wire. The watermark
+        // moves to the seam — the point in `accumulated` where afterImageXml is
+        // about to be appended — so the next builder replaces only the closing
+        // assistant turn.
+        prefillResult.messages = messages;
+        prefillResult.accumulatedBaseOffset = accumulated.length;
+        return stripThinkingForPrefill({
             ...this.getBaseProviderParams(originalRequest.config),
             // Continuations always end in an assistant prefill — the API rejects
             // extended thinking combined with prefill, so never send the param here
             thinking: undefined,
             messages,
-            system: prefillResult.systemContent
-                ? (Array.isArray(prefillResult.systemContent) && prefillResult.systemContent.length > 0
-                    ? prefillResult.systemContent
-                    : prefillResult.systemContent)
-                : undefined,
+            system: ownSystemBlocks(prefillResult.systemContent) ?? undefined,
             stopSequences: prefillResult.stopSequences,
-            extra: originalRequest.providerParams,
-        };
+            // Copied, not aliased: the guard below deletes the smuggled thinking
+            // config, and mutating the caller's own providerParams object would
+            // silently disable thinking on their NEXT (non-prefill) request.
+            extra: {
+                ...originalRequest.providerParams,
+                // Same contract as transformRequest and the plain continuation
+                // builder. Without these a completions-style adapter fell through to
+                // serializing PROVIDER-shaped messages as if they were normalized
+                // ones, re-adding participant stop sequences the continuation
+                // deliberately suppresses.
+                normalizedMessages: originalRequest.messages,
+                prompt: trimmedAccumulated,
+            },
+        });
     }
     transformResponse(providerResponse, request, prefillResult, startTime, attempts, rawRequest) {
         // Extract text from response
@@ -1565,6 +2055,7 @@ export class Membrane {
         }
         // Parse XML tool calls from text if no native tool_use blocks were found
         // This handles prefill mode where tools are XML in the text
+        let emptyToolBlocks = 0;
         if (toolCalls.length === 0 && rawAssistantText.includes('<function_calls>')) {
             const parsed = parseToolCalls(rawAssistantText);
             if (parsed?.calls.length) {
@@ -1572,12 +2063,25 @@ export class Membrane {
                     toolCalls.push(tc);
                 }
             }
+            else if (parsed) {
+                emptyToolBlocks = 1;
+            }
         }
+        const unclosedToolBlock = endsWithPartialToolBlock(rawAssistantText);
         const stopReason = this.mapStopReason(providerResponse.stopReason);
+        this.reportToolParseDiagnostics({ unclosedToolBlock, emptyToolBlocks }, stopReason);
         const durationMs = Date.now() - startTime;
+        // `NormalizedResponse.usage` is typed DetailedUsage and the streaming paths
+        // already return the whole thing; complete() used to narrow it to
+        // input/output here, so a caller reading `response.usage.cacheReadTokens`
+        // saw undefined on one path and a number on the other.
         const usage = {
             inputTokens: providerResponse.usage.inputTokens,
             outputTokens: providerResponse.usage.outputTokens,
+            cacheCreationTokens: providerResponse.usage.cacheCreationTokens,
+            cacheReadTokens: providerResponse.usage.cacheReadTokens,
+            thinkingTokens: providerResponse.usage.thinkingTokens,
+            estimatedCost: this.estimateCost(providerResponse.usage, request.config.model, providerResponse.model),
         };
         return {
             content,
@@ -1591,14 +2095,9 @@ export class Membrane {
                     reason: stopReason,
                     triggeredSequence: providerResponse.stopSequence,
                     wasTruncated: stopReason === 'max_tokens',
+                    unclosedToolBlock,
                 },
-                usage: {
-                    inputTokens: providerResponse.usage.inputTokens,
-                    outputTokens: providerResponse.usage.outputTokens,
-                    cacheCreationTokens: providerResponse.usage.cacheCreationTokens,
-                    cacheReadTokens: providerResponse.usage.cacheReadTokens,
-                    estimatedCost: this.estimateCost(providerResponse.usage, request.config.model),
-                },
+                usage,
                 timing: {
                     totalDurationMs: durationMs,
                     attempts,
@@ -1621,12 +2120,47 @@ export class Membrane {
             },
         };
     }
-    buildFinalResponse(accumulated, contentBlocks, stopReason, usage, request, prefillResult, startTime, attempts, rawRequest, rawResponse, executedToolCalls = [], executedToolResults = [], startInsideBlock = null, triggeredSequence) {
+    /**
+     * The turn is over, and the two guards that detect a half-written tool block
+     * finally have a call site. Both shapes are defects a consumer must not
+     * persist blind: an unclosed block splices onto the NEXT round's closing tag
+     * (the loop does not resume on a length stop, so max_tokens leaves exactly
+     * this), and a block that parsed to nothing means the model believes it
+     * called a tool that never ran.
+     */
+    reportToolParseDiagnostics(diagnostics, stopReason) {
+        const warnLog = this.config.logger ?? console;
+        if (diagnostics.unclosedToolBlock) {
+            warnLog.warn(`[membrane] turn ended (${stopReason}) with an unclosed tool block in the ` +
+                `assistant text — the loop does not resume on a length stop. Persisting this ` +
+                `turn verbatim lets the next round's closing tag splice onto the stale ` +
+                `opener; see details.stop.unclosedToolBlock.`);
+        }
+        if (diagnostics.emptyToolBlocks > 0) {
+            warnLog.warn(`[membrane] ${diagnostics.emptyToolBlocks} function_calls block(s) parsed to ` +
+                `zero tool calls — always a defect, never a normal ending. The call was ` +
+                `returned as assistant text and nothing executed.`);
+        }
+        if (diagnostics.splicedToolBlocks) {
+            warnLog.warn(`[membrane] ${diagnostics.splicedToolBlocks} tool block(s) spanned a second ` +
+                `<function_calls> opener and were re-anchored to the innermost one — an ` +
+                `earlier truncated block is present in this conversation's assistant text.`);
+        }
+        if (diagnostics.unclosedInvokeHeads) {
+            warnLog.warn(`[membrane] ${diagnostics.unclosedInvokeHeads} <invoke> head(s) were left ` +
+                `unclosed and swallowed the invoke that followed — nothing was dispatched ` +
+                `under an unclosed head's name, and the call it absorbed was re-anchored ` +
+                `and ran with its own parameters.`);
+        }
+    }
+    buildFinalResponse(accumulated, contentBlocks, stopReason, turnUsage, request, prefillResult, startTime, attempts, rawRequest, rawResponse, executedToolCalls = [], executedToolResults = [], startInsideBlock = null, triggeredSequence) {
+        const usage = turnUsage.total;
         // Parse accumulated text into structured content blocks
         // This extracts thinking, tool_use, tool_result, and text blocks
         let finalContent;
         let toolCalls;
         let toolResults;
+        let unclosedToolBlock = false;
         if (contentBlocks.length > 0) {
             // Native mode - content blocks already structured
             finalContent = contentBlocks;
@@ -1642,6 +2176,8 @@ export class Membrane {
             finalContent = parsed.blocks;
             toolCalls = parsed.toolCalls.length > 0 ? parsed.toolCalls : executedToolCalls;
             toolResults = parsed.toolResults.length > 0 ? parsed.toolResults : executedToolResults;
+            unclosedToolBlock = parsed.unclosedToolBlock;
+            this.reportToolParseDiagnostics(parsed, stopReason);
         }
         const durationMs = Date.now() - startTime;
         return {
@@ -1656,19 +2192,21 @@ export class Membrane {
                     reason: stopReason,
                     triggeredSequence,
                     wasTruncated: stopReason === 'max_tokens',
+                    unclosedToolBlock,
                 },
-                usage: {
-                    ...usage,
-                    estimatedCost: usage.estimatedCost ?? this.estimateCost(usage, request.config.model),
-                },
+                // Priced per round by the accumulator and summed — NOT re-derived here
+                // from the turn totals, which would re-bill every round at the last
+                // model's rate.
+                usage,
                 timing: {
                     totalDurationMs: durationMs,
                     attempts,
                 },
                 model: {
                     requested: request.config.model,
-                    actual: request.config.model, // TODO: get from response
+                    actual: turnUsage.lastServedModel || request.config.model,
                     provider: this.adapter.name,
+                    perRound: turnUsage.perRound,
                 },
                 cache: {
                     markersInRequest: prefillResult.cacheMarkersApplied ?? 0,
@@ -1683,6 +2221,45 @@ export class Membrane {
             },
         };
     }
+    /**
+     * Fold one discarded (billed but abandoned) attempt's usage into a carry.
+     * Returns a NEW object so a caller's earlier snapshot is never mutated.
+     */
+    mergeDiscardedAttempts(carry, add) {
+        if (!add)
+            return carry;
+        const next = carry
+            ? { ...carry }
+            : { attempts: 0, inputTokens: 0, outputTokens: 0 };
+        next.attempts += add.attempts;
+        next.inputTokens += add.inputTokens;
+        next.outputTokens += add.outputTokens;
+        if (add.cacheCreationTokens) {
+            next.cacheCreationTokens = (next.cacheCreationTokens ?? 0) + add.cacheCreationTokens;
+        }
+        if (add.cacheReadTokens) {
+            next.cacheReadTokens = (next.cacheReadTokens ?? 0) + add.cacheReadTokens;
+        }
+        return next;
+    }
+    /** One provider call's usage as a single-attempt discard record. */
+    discardedAttemptFrom(usage) {
+        const detailed = (usage ?? { inputTokens: 0, outputTokens: 0 });
+        return {
+            attempts: 1,
+            inputTokens: detailed.inputTokens ?? 0,
+            outputTokens: detailed.outputTokens ?? 0,
+            ...(detailed.cacheCreationTokens ? { cacheCreationTokens: detailed.cacheCreationTokens } : {}),
+            ...(detailed.cacheReadTokens ? { cacheReadTokens: detailed.cacheReadTokens } : {}),
+        };
+    }
+    /** Price the discarded spend so a caller can read it without re-deriving. */
+    pricedDiscardedAttempts(discarded, model) {
+        if (!discarded)
+            return undefined;
+        const estimatedCost = this.estimateCost(discarded, model);
+        return estimatedCost ? { ...discarded, estimatedCost } : discarded;
+    }
     mapStopReason(providerReason) {
         switch (providerReason) {
             case 'end_turn':
@@ -1703,19 +2280,50 @@ export class Membrane {
         }
     }
     calculateCacheHitRatio(usage) {
-        const cacheRead = usage.cacheReadTokens ?? 0;
-        const total = usage.inputTokens ?? 0;
-        if (total === 0)
-            return 0;
-        return cacheRead / total;
+        return calculateCacheHitRatio(usage);
     }
-    resolvePricing(model) {
-        return this.registry?.getPricing(model) ?? getDefaultPricing(model);
+    /**
+     * Pricing is resolved on TWO axes, and SOURCE outranks SPECIFICITY:
+     *
+     *   registry[served] → registry[requested] → builtin[served] → builtin[requested]
+     *
+     * Specificity — preferring the model that ACTUALLY served over the id that
+     * was requested — is real: an alias or an auto-routed request otherwise
+     * prices against a string the provider already replaced, and a live
+     * 2026-08-25 call asking for `gpt-4o-mini` was served by
+     * `gpt-4o-mini-2024-07-18`. But it only breaks ties WITHIN one source.
+     * A configured `ModelRegistry` is the caller stating their own rates —
+     * account-specific, negotiated, authoritative; the built-in table is
+     * membrane's shipped guess at public list prices. Merging the two per-model
+     * (`registry[served] ?? builtin[served]`, return on the first hit) let the
+     * guess for a snapshot outrank the caller's own entry for the alias they
+     * asked for, so a caller who prices their alias and lets the provider pick
+     * the snapshot was billed at membrane's number instead of theirs.
+     *
+     * Both fallbacks stay: the served model may be absent from a source, and the
+     * provider may name none at all.
+     */
+    resolvePricing(requestedModel, actualModel) {
+        const servedModel = actualModel && actualModel !== requestedModel ? actualModel : undefined;
+        const fromRegistry = (modelId) => modelId === undefined ? undefined : this.registry?.getPricing(modelId);
+        const fromBuiltin = (modelId) => modelId === undefined ? undefined : getDefaultPricing(modelId);
+        return fromRegistry(servedModel)
+            ?? fromRegistry(requestedModel)
+            ?? fromBuiltin(servedModel)
+            ?? fromBuiltin(requestedModel);
     }
     /** Resolve pricing + calculate cost in one call (for one-shot use outside loops). */
-    estimateCost(usage, model) {
-        const pricing = this.resolvePricing(model);
-        return pricing ? calculateCost(usage, pricing) : undefined;
+    estimateCost(usage, requestedModel, actualModel) {
+        const pricing = this.resolvePricing(requestedModel, actualModel);
+        if (!pricing) {
+            // An absent cost and a zero cost are different claims. Returning
+            // undefined says "membrane does not know what this costs"; saying it out
+            // loud once per model keeps that from reading as "free" to a caller that
+            // only ever sees the omission.
+            warnUnpricedModel(actualModel || requestedModel);
+            return undefined;
+        }
+        return calculateCost(usage, pricing);
     }
     calculateRetryDelay(attempt, overloaded = false) {
         const { retryDelayMs, backoffMultiplier, maxRetryDelayMs } = overloaded
@@ -1749,6 +2357,11 @@ export class Membrane {
      * Check if an error is an abort error
      */
     isAbortError(error) {
+        // An adapter's own deadline: a timeout by classification, still an abort
+        // by provenance, so the streaming paths hand back the partial content
+        // they collected instead of throwing.
+        if (isTimeoutAbortError(error))
+            return true;
         if (error instanceof Error) {
             // Standard AbortError
             if (error.name === 'AbortError')
@@ -1763,6 +2376,21 @@ export class Membrane {
         }
         return false;
     }
+    /**
+     * Why a caught abort happened. The caller's own signal is authoritative:
+     * if it fired, the cancellation is theirs whatever the error text says.
+     * Otherwise an adapter-side deadline classifies as a timeout — the adapters
+     * mark the abort createCombinedSignal's timeoutMs raises and map it to a
+     * TimeoutAbortError, so the identity survives their error handling — and
+     * anything else that reached the abort catch is a failure, not a person.
+     */
+    abortReason(error, signal) {
+        if (signal?.aborted)
+            return 'user';
+        if (classifyError(error).type === 'timeout')
+            return 'timeout';
+        return 'error';
+    }
     /**
      * Build an AbortedResponse from current execution state
      */
@@ -1812,7 +2440,12 @@ export class Membrane {
      * ```
      */
     streamYielding(request, options = {}) {
-        const toolMode = this.resolveToolMode(request);
+        // YieldingStreamOptions carries no per-request formatter override, so the
+        // selection here can only land on the instance formatter — it goes through
+        // resolveActiveFormatter anyway so this path reads the same single source
+        // as complete() and stream() if an override is ever added.
+        const activeFormatter = this.resolveActiveFormatter();
+        const toolMode = this.resolveToolMode(request, activeFormatter);
         // refusalRetries is implemented on the native path only. The XML path
         // accumulates into a streaming parser carrying prefill context and
         // resumption depths; rolling that back mid-turn is a separate problem,
@@ -1824,14 +2457,14 @@ export class Membrane {
         }
         // Create the yielding stream with the appropriate inference runner
         const runInference = toolMode === 'native'
-            ? (stream) => this.runNativeToolsYielding(request, options, stream)
-            : (stream) => this.runXmlToolsYielding(request, options, stream);
+            ? (stream) => this.runNativeToolsYielding(request, options, stream, activeFormatter)
+            : (stream) => this.runXmlToolsYielding(request, options, stream, activeFormatter);
         return new YieldingStreamImpl(options, runInference);
     }
     /**
      * Run XML-based tool execution with yielding stream.
      */
-    async runXmlToolsYielding(request, options, stream) {
+    async runXmlToolsYielding(request, options, stream, activeFormatter = this.resolveActiveFormatter()) {
         const startTime = Date.now();
         const { maxToolDepth: maxToolDepthOpt, emitTokens = true, emitBlocks = true, emitUsage = true, } = options;
         // Yielding paths default to unlimited (the caller — typically an agent
@@ -1863,14 +2496,20 @@ export class Membrane {
         let enteredViaResumption = false;
         let prevRoundStopSequence;
         const warnLog = this.config.logger ?? console;
-        // Initialize parser from formatter for format-specific tracking
-        const formatter = this.formatter;
+        // Initialize parser from the formatter streamYielding selected, so the
+        // parser and the build below read the same format.
+        const formatter = activeFormatter;
         const parser = formatter.createStreamParser();
         let toolDepth = 0;
+        // Honest turn telemetry: provider calls actually made (including refusal
+        // re-issues inside streamOnce) and continuation rounds.
+        let providerCalls = 0;
+        let rounds = 0;
         // Once-per-stream latch for the injectedMessages-unsupported warning.
         let warnedInjectionUnsupported = false;
-        let totalUsage = { inputTokens: 0, outputTokens: 0 };
-        const pricing = this.resolvePricing(request.config.model);
+        // See streamWithXmlTools: one accumulator per turn, pricing each round
+        // under the model that served it.
+        const turnUsage = new TurnUsageAccumulator(request.config.model, (servedModel) => this.resolvePricing(request.config.model, servedModel));
         const contentBlocks = [];
         let lastStopReason = 'end_turn';
         let lastStopSequence;
@@ -1912,13 +2551,13 @@ export class Membrane {
             resumptionRounds++;
             if (resumptionRounds === RESUMPTION_WARN_ROUNDS) {
                 warnLog.warn(`[membrane] automatic resumption at round ${resumptionRounds} ` +
-                    `(${totalUsage.inputTokens} input tokens so far this turn) — ` +
+                    `(${turnUsage.total.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.`);
+                    `${turnUsage.total.inputTokens} input tokens spent this turn.`);
                 return false;
             }
             return true;
@@ -2001,6 +2640,8 @@ export class Membrane {
                     wrapThinkingTags: true,
                     onRequest: (req) => { rawRequest = req; },
                 });
+                rounds++;
+                providerCalls += streamResult.providerCalls;
                 // If we detected stop sequence manually, fix up the parser and result
                 if (detectedStopSequence && truncatedAccumulated !== null) {
                     parser.reset();
@@ -2015,19 +2656,10 @@ export class Membrane {
                 rawResponse = streamResult.raw;
                 lastStopReason = this.mapStopReason(streamResult.stopReason);
                 lastStopSequence = streamResult.stopSequence ?? undefined;
-                // Accumulate usage (including cache metrics)
-                totalUsage.inputTokens += streamResult.usage.inputTokens;
-                totalUsage.outputTokens += streamResult.usage.outputTokens;
-                if (streamResult.usage.cacheCreationTokens) {
-                    totalUsage.cacheCreationTokens = (totalUsage.cacheCreationTokens ?? 0) + streamResult.usage.cacheCreationTokens;
-                }
-                if (streamResult.usage.cacheReadTokens) {
-                    totalUsage.cacheReadTokens = (totalUsage.cacheReadTokens ?? 0) + streamResult.usage.cacheReadTokens;
-                }
-                if (pricing)
-                    totalUsage.estimatedCost = calculateCost(totalUsage, pricing);
+                // Accumulate usage (including cache metrics), priced at this round's model
+                const usageSoFar = turnUsage.addRound(streamResult.model, streamResult.usage);
                 if (emitUsage) {
-                    stream.emit({ type: 'usage', usage: { ...totalUsage } });
+                    stream.emit({ type: 'usage', usage: usageSoFar });
                 }
                 // Flush the parser
                 const flushResult = parser.flush();
@@ -2050,7 +2682,7 @@ export class Membrane {
                         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.`);
+                            `stopReason 'no_progress'. ${turnUsage.total.inputTokens} input tokens spent this turn.`);
                         lastStopReason = 'no_progress';
                         break;
                     }
@@ -2298,9 +2930,10 @@ export class Membrane {
             // Build final response
             const fullAccumulated = parser.getAccumulated();
             const newContent = fullAccumulated.slice(initialPrefillLength);
-            const response = this.buildFinalResponse(newContent, contentBlocks, lastStopReason, totalUsage, request, prefillResult, startTime, 1, rawRequest, rawResponse, executedToolCalls, executedToolResults, initialBlockType, lastStopSequence);
+            const response = this.buildFinalResponse(newContent, contentBlocks, lastStopReason, turnUsage, request, prefillResult, startTime, providerCalls, rawRequest, rawResponse, executedToolCalls, executedToolResults, initialBlockType, lastStopSequence);
             // Merge provider thinking signatures into parser-derived thinking blocks
             this.mergeProviderThinkingBlocks(response.content, providerThinkingBlocks);
+            response.details.timing.rounds = rounds;
             stream.emit({ type: 'complete', response });
         }
         catch (error) {
@@ -2309,7 +2942,7 @@ export class Membrane {
                 const newContent = fullAccumulated.slice(initialPrefillLength);
                 stream.emit({
                     type: 'aborted',
-                    reason: 'user',
+                    reason: this.abortReason(error, stream.signal),
                     partialContent: parseAccumulatedIntoBlocks(newContent).blocks,
                     rawAssistantText: newContent,
                     toolCalls: executedToolCalls,
@@ -2324,7 +2957,7 @@ export class Membrane {
     /**
      * Run native tool execution with yielding stream.
      */
-    async runNativeToolsYielding(request, options, stream) {
+    async runNativeToolsYielding(request, options, stream, activeFormatter = this.resolveActiveFormatter()) {
         const startTime = Date.now();
         const { maxToolDepth: maxToolDepthOpt, emitTokens = true, emitBlocks = true, emitUsage = true, } = options;
         // Yielding paths default to unlimited (the caller — typically an agent
@@ -2336,8 +2969,13 @@ export class Membrane {
             ? Infinity
             : maxToolDepthOpt;
         let toolDepth = 0;
-        let totalUsage = { inputTokens: 0, outputTokens: 0 };
-        const pricing = this.resolvePricing(request.config.model);
+        // See streamWithXmlTools: one accumulator per turn, pricing each round
+        // under the model that served it.
+        const turnUsage = new TurnUsageAccumulator(request.config.model, (servedModel) => this.resolvePricing(request.config.model, servedModel));
+        // Honest turn telemetry: provider calls actually made (including refusal
+        // re-issues inside streamOnce) and continuation rounds.
+        let providerCalls = 0;
+        let rounds = 0;
         let lastStopReason = 'end_turn';
         let lastStopSequence;
         let rawRequest;
@@ -2345,8 +2983,11 @@ export class Membrane {
         let allTextAccumulated = '';
         const executedToolCalls = [];
         const executedToolResults = [];
+        // Spend on refusal attempts this turn threw away (see streamOnce).
+        let discardedUsage;
         let messages = [...request.messages];
         let allContentBlocks = [];
+        let markersInLastRequest = 0;
         try {
             // Tool execution loop
             while (toolDepth <= maxToolDepth) {
@@ -2362,26 +3003,17 @@ export class Membrane {
                     return;
                 }
                 // Build provider request with native tools
-                const providerRequest = this.buildNativeToolRequest(request, messages);
+                const providerRequest = this.buildNativeToolRequest(request, messages, toolDepth > 0, activeFormatter);
                 // Stream from provider
                 let textAccumulated = '';
-                let blockIndex = 0;
                 // Where this attempt starts inside the tool-loop-spanning buffer, so
                 // a refusal retry can roll back exactly this attempt's contribution.
                 const allTextBefore = allTextAccumulated.length;
-                // Track block-type from the provider's content_block_start signal so
+                // Track block-type from the provider's content_block signals so
                 // every token chunk is tagged with the membrane block it belongs to.
                 // Without this, thinking_delta chunks get mislabelled as 'text' and
                 // downstream consumers (TUIs, WebUIs) can't render them distinctly.
-                let currentBlockType = 'text';
-                const seenBlockIndices = new Set();
-                const mapApiBlockType = (apiType) => {
-                    if (apiType === 'thinking')
-                        return 'thinking';
-                    if (apiType === 'tool_use')
-                        return 'tool_call';
-                    return 'text';
-                };
+                const tracker = new NativeBlockTracker(emitBlocks ? (event) => stream.emit({ type: 'block', event }) : undefined);
                 const streamResult = await this.streamOnce(providerRequest, {
                     onChunk: (chunk) => {
                         if (stream.isCancelled)
@@ -2390,9 +3022,9 @@ export class Membrane {
                         allTextAccumulated += chunk;
                         if (emitTokens) {
                             const meta = {
-                                type: currentBlockType,
-                                visible: currentBlockType === 'text',
-                                blockIndex,
+                                type: tracker.currentType,
+                                visible: tracker.currentType === 'text',
+                                blockIndex: tracker.blockIndex,
                             };
                             stream.emit({ type: 'tokens', content: chunk, meta });
                         }
@@ -2400,41 +3032,7 @@ export class Membrane {
                     onContentBlock: (index, block) => {
                         if (stream.isCancelled)
                             return;
-                        const apiType = block?.type;
-                        const mbType = mapApiBlockType(apiType);
-                        const isStart = !seenBlockIndices.has(index);
-                        if (isStart) {
-                            seenBlockIndices.add(index);
-                            currentBlockType = mbType;
-                            blockIndex = index;
-                            if (emitBlocks) {
-                                stream.emit({
-                                    type: 'block',
-                                    event: { event: 'block_start', index, block: { type: mbType } },
-                                });
-                            }
-                        }
-                        else if (emitBlocks) {
-                            // Second call for the same index = content_block_stop. The
-                            // provider has filled the block with final content; surface
-                            // a block_complete with the relevant fields for consumers
-                            // that want full block payloads (e.g. context-manager).
-                            const apiBlock = block;
-                            const mb = { type: mbType };
-                            if (mbType === 'text')
-                                mb.content = apiBlock?.text;
-                            else if (mbType === 'thinking')
-                                mb.content = apiBlock?.thinking;
-                            else if (mbType === 'tool_call') {
-                                mb.toolId = apiBlock?.id;
-                                mb.toolName = apiBlock?.name;
-                                mb.input = apiBlock?.input;
-                            }
-                            stream.emit({
-                                type: 'block',
-                                event: { event: 'block_complete', index, block: mb },
-                            });
-                        }
+                        tracker.onProviderBlock(index, block);
                     },
                 }, {
                     signal: stream.signal,
@@ -2442,6 +3040,14 @@ export class Membrane {
                     idleTimeoutMs: options.idleTimeoutMs,
                     normalizedRequest: request,
                     onRequest: (req) => { rawRequest = req; },
+                    // Telemetry reports what this request actually SHIPPED with —
+                    // builder breakpoints, stale passthrough, fallback, float, plus
+                    // whatever the beforeRequest hook and the wire clamp did after
+                    // the build. Both native paths used to hardcode 0, and counting
+                    // at build time reported a number no request ever had.
+                    onWireCacheMarkers: (markerCount) => {
+                        markersInLastRequest = markerCount;
+                    },
                     refusalRetries: options.refusalRetries,
                     // Discard the refused attempt: roll the accumulators back to
                     // where this attempt began and tell the consumer to drop what it
@@ -2450,9 +3056,7 @@ export class Membrane {
                     onRetrying: (info) => {
                         allTextAccumulated = allTextAccumulated.slice(0, allTextBefore);
                         textAccumulated = '';
-                        blockIndex = 0;
-                        currentBlockType = 'text';
-                        seenBlockIndices.clear();
+                        tracker.reset();
                         stream.emit({
                             type: 'retrying',
                             attempt: info.attempt,
@@ -2462,22 +3066,21 @@ export class Membrane {
                         });
                     },
                 });
+                // Single-callback adapters (OpenAI Responses) report each finalised
+                // block once, after the stream: complete whatever never saw a stop.
+                tracker.flush();
+                rounds++;
+                providerCalls += streamResult.providerCalls;
                 rawResponse = streamResult.raw;
                 lastStopReason = this.mapStopReason(streamResult.stopReason);
                 lastStopSequence = streamResult.stopSequence ?? undefined;
-                // Accumulate usage (including cache metrics)
-                totalUsage.inputTokens += streamResult.usage.inputTokens;
-                totalUsage.outputTokens += streamResult.usage.outputTokens;
-                if (streamResult.usage.cacheCreationTokens) {
-                    totalUsage.cacheCreationTokens = (totalUsage.cacheCreationTokens ?? 0) + streamResult.usage.cacheCreationTokens;
-                }
-                if (streamResult.usage.cacheReadTokens) {
-                    totalUsage.cacheReadTokens = (totalUsage.cacheReadTokens ?? 0) + streamResult.usage.cacheReadTokens;
-                }
-                if (pricing)
-                    totalUsage.estimatedCost = calculateCost(totalUsage, pricing);
+                // Attempts this round re-issued past a refusal are billed calls whose
+                // output was discarded — carry their spend to the final response.
+                discardedUsage = this.mergeDiscardedAttempts(discardedUsage, streamResult.discardedUsage);
+                // Accumulate usage (including cache metrics), priced at this round's model
+                const usageSoFar = turnUsage.addRound(streamResult.model, streamResult.usage);
                 if (emitUsage) {
-                    stream.emit({ type: 'usage', usage: { ...totalUsage } });
+                    stream.emit({ type: 'usage', usage: usageSoFar });
                 }
                 // Parse content blocks from response
                 const responseBlocks = this.parseProviderContent(streamResult.content);
@@ -2563,6 +3166,7 @@ export class Membrane {
                 break;
             }
             const durationMs = Date.now() - startTime;
+            const totalUsage = turnUsage.total;
             const response = {
                 content: allContentBlocks,
                 rawAssistantText: allTextAccumulated,
@@ -2576,18 +3180,25 @@ export class Membrane {
                         triggeredSequence: lastStopSequence,
                         wasTruncated: lastStopReason === 'max_tokens',
                     },
-                    usage: { ...totalUsage },
+                    usage: {
+                        ...totalUsage,
+                        ...(discardedUsage
+                            ? { discardedAttempts: this.pricedDiscardedAttempts(discardedUsage, request.config.model) }
+                            : {}),
+                    },
                     timing: {
                         totalDurationMs: durationMs,
-                        attempts: 1,
+                        attempts: providerCalls,
+                        rounds,
                     },
                     model: {
                         requested: request.config.model,
-                        actual: request.config.model,
+                        actual: turnUsage.lastServedModel || request.config.model,
                         provider: this.adapter.name,
+                        perRound: turnUsage.perRound,
                     },
                     cache: {
-                        markersInRequest: 0,
+                        markersInRequest: markersInLastRequest,
                         tokensCreated: totalUsage.cacheCreationTokens ?? 0,
                         tokensRead: totalUsage.cacheReadTokens ?? 0,
                         hitRatio: this.calculateCacheHitRatio(totalUsage),
@@ -2604,7 +3215,7 @@ export class Membrane {
             if (this.isAbortError(error)) {
                 stream.emit({
                     type: 'aborted',
-                    reason: 'user',
+                    reason: this.abortReason(error, stream.signal),
                     rawAssistantText: allTextAccumulated,
                     toolCalls: executedToolCalls,
                     toolResults: executedToolResults,