@animalabs/membrane 0.5.52 → 0.5.53

package/dist/formatters/normalize-tool-pairs.js

@@ -0,0 +1,498 @@
+/**
+ * Tool-Pair Normalizer
+ *
+ * Anthropic's API enforces structural rules on tool cycles that any of
+ * Membrane's upstreams can accidentally violate:
+ *
+ *   - `tool_use` blocks must live in assistant-role messages.
+ *   - `tool_result` blocks must live in user-role messages.
+ *   - Every `tool_use` must be matched by its `tool_result` in the very
+ *     next user-role message.
+ *   - `thinking` blocks must live in assistant turns.
+ *
+ * When these are violated, the API returns 400 (e.g. `tool_use blocks can
+ * only be in assistant messages`). This module is the wire-boundary safety
+ * net: every formatter funnels through `normalizeToolPairs` before its
+ * output is shipped, so producer-side bugs cannot leak the same 400 family
+ * (compression-bug 5/6/7/8/9, agent-framework #37, 2026-05-22 miner stall).
+ *
+ * Algorithm overview (six phases): reclassify blocks by required role,
+ * reflow into role-correct envelopes, hoist matching tool_results across
+ * the assistant→user boundary, evict interlopers wedged between use and
+ * result, synthesize `[pending]` results for trailing orphans (or signal
+ * not-ready when the id is in the caller-supplied pending set), validate.
+ */
+export class MembraneNormalizerError extends Error {
+    input;
+    output;
+    constructor(message, input, output) {
+        super(message);
+        this.input = input;
+        this.output = output;
+        this.name = 'MembraneNormalizerError';
+    }
+}
+// ============================================================================
+// Implementation
+// ============================================================================
+/**
+ * Normalize a sequence of provider messages so the output is API-valid
+ * with respect to Anthropic's tool-cycle structural rules.
+ *
+ * This function does NOT merge consecutive same-role envelopes — that
+ * remains the caller's responsibility (NativeFormatter.mergeConsecutiveRoles)
+ * so existing cache-control / breakpoint logic continues to work.
+ */
+export function normalizeToolPairs(input, options = {}) {
+    const pending = options.pendingToolCallIds ?? new Set();
+    const onEvent = options.onEvent ?? noop;
+    // ---------------------------------------------------------------------
+    // Phase 1 + 2: reclassify blocks by required role and reflow envelopes
+    // ---------------------------------------------------------------------
+    let envelopes = rebuildEnvelopes(input, onEvent);
+    // ---------------------------------------------------------------------
+    // Phase 3: pair tool_use → tool_result across assistant→user boundary
+    // ---------------------------------------------------------------------
+    envelopes = hoistMatchingResults(envelopes, onEvent);
+    // ---------------------------------------------------------------------
+    // Phase 4: evict interlopers wedged between a tool_use and its result
+    // ---------------------------------------------------------------------
+    envelopes = evictInterlopers(envelopes, onEvent);
+    // ---------------------------------------------------------------------
+    // Phase 5: resolve orphans
+    // ---------------------------------------------------------------------
+    const orphanRes = resolveOrphans(envelopes, pending, onEvent);
+    envelopes = orphanRes.envelopes;
+    const ready = orphanRes.ready;
+    // ---------------------------------------------------------------------
+    // Phase 5.5: suppress cache_control on/after any envelope containing
+    // a synthetic block, so cache keys don't get invalidated when the
+    // real result arrives in a later round.
+    // ---------------------------------------------------------------------
+    if (orphanRes.firstSyntheticEnvelope !== null) {
+        suppressCacheControlFrom(envelopes, orphanRes.firstSyntheticEnvelope, onEvent);
+    }
+    // ---------------------------------------------------------------------
+    // Phase 6: drop empty envelopes (can arise from phase 4 dropping or
+    // phase 3 hoisting), repair first-message-must-be-user, validate. We
+    // deliberately do NOT merge consecutive same-role envelopes here —
+    // that's the formatter's job.
+    // ---------------------------------------------------------------------
+    envelopes = envelopes.filter((e) => e.content.length > 0);
+    // First-message-must-be-user repair: only repair the case where the
+    // original input's first message WAS user, but re-roling moved blocks
+    // to a leading assistant envelope (e.g. misplaced thinking block).
+    // If the producer genuinely shipped an assistant-first conversation,
+    // that's a real bug and validate() will throw.
+    const originalFirstRole = input.length > 0 ? input[0].role : 'user';
+    if (envelopes.length > 0 &&
+        envelopes[0].role === 'assistant' &&
+        originalFirstRole === 'user') {
+        envelopes.unshift({ role: 'user', content: [{ type: 'text', text: '[continuing]' }] });
+    }
+    // Validate. When `ready === false` we intentionally have unmatched
+    // tool_uses — but ONLY the ones in `pending` are allowed to remain
+    // unsynthesized. Any other gap is a bug in phase 5 and must throw.
+    validate(envelopes, input, pending);
+    return { messages: envelopes.map(toProviderMessage), ready };
+}
+/**
+ * Role-strict block types. Extending Anthropic's tool surface
+ * (e.g. `server_tool_use`, `web_search_tool_result`, `computer_use`)
+ * means adding entries here. Unknown block types whose `type` starts
+ * with `tool_` or `thinking` fall through to 'inherit' and trigger a
+ * one-shot console warning so the next addition doesn't sail silently
+ * through the safety net.
+ */
+function requiredRoleOf(block) {
+    switch (block.type) {
+        case 'tool_use':
+        case 'thinking':
+        case 'redacted_thinking':
+            return 'assistant';
+        case 'tool_result':
+            return 'user';
+        default:
+            if (block.type.startsWith('tool_') || block.type.startsWith('thinking')) {
+                warnUnknownStrictType(block.type);
+            }
+            return 'inherit';
+    }
+}
+const _warnedTypes = new Set();
+function warnUnknownStrictType(blockType) {
+    if (_warnedTypes.has(blockType))
+        return;
+    _warnedTypes.add(blockType);
+    // eslint-disable-next-line no-console
+    console.warn(`[membrane:normalize-tool-pairs] Unknown strict-role block type '${blockType}' — ` +
+        `falling through as 'inherit'. If this type has role placement rules at the API, ` +
+        `add it to requiredRoleOf in normalize-tool-pairs.ts.`);
+}
+function rebuildEnvelopes(input, onEvent) {
+    const out = [];
+    let current = null;
+    for (const msg of input) {
+        if (!Array.isArray(msg.content)) {
+            // Defensive: provider message with non-array content (e.g. a plain
+            // string). Treat it as a single text block under the message's
+            // declared role.
+            const role = msg.role;
+            if (current === null || current.role !== role) {
+                if (current)
+                    out.push(current);
+                current = { role, content: [] };
+            }
+            current.content.push({ type: 'text', text: String(msg.content ?? '') });
+            continue;
+        }
+        for (const block of msg.content) {
+            const req = requiredRoleOf(block);
+            const targetRole = req === 'inherit' ? msg.role : req;
+            if (req !== 'inherit' && req !== msg.role) {
+                onEvent({
+                    kind: 'block_re_roled',
+                    blockType: block.type,
+                    from: msg.role,
+                    to: req,
+                });
+            }
+            if (current === null || current.role !== targetRole) {
+                if (current)
+                    out.push(current);
+                current = { role: targetRole, content: [] };
+            }
+            current.content.push(block);
+        }
+    }
+    if (current)
+        out.push(current);
+    return out;
+}
+function hoistMatchingResults(envelopes, onEvent) {
+    // For every assistant envelope, ensure its tool_use ids have matching
+    // tool_results in the immediately-following user envelope. If a
+    // matching tool_result lives further downstream, hoist it forward.
+    for (let i = 0; i < envelopes.length; i++) {
+        const env = envelopes[i];
+        if (env.role !== 'assistant')
+            continue;
+        const useIds = collectToolUseIds(env);
+        if (useIds.length === 0)
+            continue;
+        // Ensure there is a user envelope at i+1. If not, insert an empty one.
+        let nextIdx = i + 1;
+        if (nextIdx >= envelopes.length || envelopes[nextIdx].role !== 'user') {
+            envelopes.splice(nextIdx, 0, { role: 'user', content: [] });
+        }
+        const nextEnv = envelopes[nextIdx];
+        const presentIds = new Set(nextEnv.content
+            .filter((b) => b.type === 'tool_result')
+            .map(getToolUseId)
+            .filter((id) => typeof id === 'string'));
+        for (const useId of useIds) {
+            if (presentIds.has(useId))
+                continue;
+            // Search downstream envelopes for this id; hoist the first match.
+            const found = removeFirstMatchingResult(envelopes, nextIdx + 1, useId);
+            if (found) {
+                // Place the hoisted result at the front of nextEnv to keep
+                // tool_results adjacent to (and before) any interloping content
+                // already present.
+                nextEnv.content.unshift(found.block);
+                presentIds.add(useId);
+                onEvent({
+                    kind: 'tool_result_hoisted',
+                    toolUseId: useId,
+                    fromEnvelope: found.fromEnvelope,
+                    toEnvelope: nextIdx,
+                });
+            }
+            // If not found downstream, leave it — phase 5 will synthesize.
+        }
+    }
+    return envelopes;
+}
+function evictInterlopers(envelopes, onEvent) {
+    // For every assistant envelope ending with a tool_use, the
+    // immediately-following user envelope's tool_results should appear
+    // BEFORE any interloping text/image/etc. — otherwise the agent's
+    // forward timeline reads "tool called, then [unrelated event], then
+    // tool result." Phase 3 already places hoisted results at the front,
+    // but locally-present results may sit after text in the same envelope
+    // (e.g. user sent a chat message and the tool_result is appended
+    // afterward by the producer). We always defer interlopers — never
+    // drop — so that a mid-cycle user event isn't lost to the agent's
+    // long-term memory after the chunk gets summarized. A summarizer LLM
+    // can tolerate slight temporal reordering; it cannot reconstruct a
+    // message that was discarded.
+    for (let i = 0; i < envelopes.length; i++) {
+        const env = envelopes[i];
+        if (env.role !== 'assistant')
+            continue;
+        const useIds = new Set(collectToolUseIds(env));
+        if (useIds.size === 0)
+            continue;
+        const next = envelopes[i + 1];
+        if (!next || next.role !== 'user')
+            continue;
+        const matching = [];
+        const interlopers = [];
+        const rest = [];
+        let seenMatching = false;
+        for (const block of next.content) {
+            const isResult = block.type === 'tool_result';
+            const resultId = isResult ? getToolUseId(block) : undefined;
+            const isMatching = isResult && typeof resultId === 'string' && useIds.has(resultId);
+            if (isMatching) {
+                matching.push(block);
+                seenMatching = true;
+            }
+            else if (!seenMatching && !isResult) {
+                // Block precedes the first matching tool_result. Treat as
+                // interloper only if it would sit between the assistant's
+                // tool_use and its result.
+                interlopers.push(block);
+            }
+            else {
+                rest.push(block);
+            }
+        }
+        if (interlopers.length === 0)
+            continue;
+        for (const block of interlopers) {
+            onEvent({
+                kind: 'interloper_deferred',
+                blockType: block.type,
+                fromEnvelope: i + 1,
+            });
+        }
+        next.content = [...matching, ...interlopers, ...rest];
+    }
+    return envelopes;
+}
+function resolveOrphans(envelopes, pending, onEvent) {
+    let ready = true;
+    let firstSyntheticEnvelope = null;
+    // First pass: textify any tool_result whose tool_use never appeared
+    // anywhere in the message list (orphan result).
+    const allUseIds = new Set();
+    for (const env of envelopes) {
+        for (const block of env.content) {
+            if (block.type === 'tool_use') {
+                const id = block.id;
+                if (typeof id === 'string')
+                    allUseIds.add(id);
+            }
+        }
+    }
+    for (const env of envelopes) {
+        if (env.role !== 'user')
+            continue;
+        env.content = env.content.map((block) => {
+            if (block.type !== 'tool_result')
+                return block;
+            const id = getToolUseId(block);
+            if (typeof id !== 'string' || !allUseIds.has(id)) {
+                const inner = block.content;
+                const innerText = typeof inner === 'string' ? inner : '';
+                onEvent({ kind: 'orphan_tool_result_textified', toolUseId: id ?? '<missing>' });
+                return {
+                    type: 'text',
+                    text: `[orphan tool_result for ${id ?? '<missing>'}]: ${innerText}`,
+                };
+            }
+            return block;
+        });
+    }
+    // Second pass: for each assistant envelope, every tool_use must have
+    // a matching tool_result in the immediately-following user envelope.
+    // If pending, signal not-ready. Else, synthesize.
+    for (let i = 0; i < envelopes.length; i++) {
+        const env = envelopes[i];
+        if (env.role !== 'assistant')
+            continue;
+        const useIds = collectToolUseIds(env);
+        if (useIds.length === 0)
+            continue;
+        let nextIdx = i + 1;
+        if (nextIdx >= envelopes.length || envelopes[nextIdx].role !== 'user') {
+            envelopes.splice(nextIdx, 0, { role: 'user', content: [] });
+        }
+        const nextEnv = envelopes[nextIdx];
+        // 'trailing' iff after the next user envelope there are no further
+        // envelopes AND the next envelope is empty (so it exists only to
+        // receive our synthetic). This must be computed *after* the splice
+        // because phase 3 may have already inserted an empty user envelope
+        // earlier in the pipeline.
+        const isTrailing = nextIdx + 1 >= envelopes.length && nextEnv.content.length === 0;
+        const presentIds = new Set(nextEnv.content
+            .filter((b) => b.type === 'tool_result')
+            .map(getToolUseId)
+            .filter((id) => typeof id === 'string'));
+        for (const useId of useIds) {
+            if (presentIds.has(useId))
+                continue;
+            if (pending.has(useId)) {
+                ready = false;
+                onEvent({ kind: 'pending_in_flight', toolUseId: useId });
+                continue;
+            }
+            const synth = syntheticToolResult(useId);
+            // Place at the front so it's adjacent to the tool_use.
+            nextEnv.content.unshift(synth);
+            presentIds.add(useId);
+            if (firstSyntheticEnvelope === null)
+                firstSyntheticEnvelope = nextIdx;
+            onEvent({
+                kind: 'synthetic_pending_result',
+                toolUseId: useId,
+                reason: isTrailing ? 'trailing' : 'mid_stream',
+            });
+        }
+    }
+    return { envelopes, ready, firstSyntheticEnvelope };
+}
+function suppressCacheControlFrom(envelopes, startIndex, onEvent) {
+    // Strip cache_control from blocks at-or-after startIndex. We must NOT
+    // mutate the caller's input blocks (envelopes share references with
+    // the input via rebuildEnvelopes), so clone-on-write: replace any
+    // block carrying cache_control with a shallow copy that omits it.
+    // The envelope's content array is replaced wholesale via .map; this
+    // is the only place in the normalizer that creates new block objects
+    // out of existing ones (synthetics aside).
+    let suppressed = false;
+    for (let i = startIndex; i < envelopes.length; i++) {
+        const env = envelopes[i];
+        env.content = env.content.map((block) => {
+            if (!('cache_control' in block))
+                return block;
+            suppressed = true;
+            const { cache_control: _drop, ...rest } = block;
+            return rest;
+        });
+    }
+    if (suppressed) {
+        onEvent({ kind: 'cache_suppressed_for_synthetic', envelopeIndex: startIndex });
+    }
+}
+function validate(envelopes, input, pending) {
+    // Empty input → empty output is fine.
+    if (envelopes.length === 0)
+        return;
+    // First message must be user (Anthropic requirement). We try to
+    // repair this in the caller; if it still isn't user here, fail.
+    if (envelopes[0].role !== 'user') {
+        throw new MembraneNormalizerError(`First message must have role 'user', got '${envelopes[0].role}'. ` +
+            `Repair (prepending '[continuing]') did not engage — internal bug.`, input.map(cloneMsg), envelopes.map(toProviderMessage));
+    }
+    // Every tool_use in an assistant envelope must have a matching
+    // tool_result in the immediately-following user envelope — except
+    // tool_uses whose id is in `pending` (the in-flight set the caller
+    // declared off-limits for synthesis). A gap on any other id is a
+    // phase-5 bug and must throw.
+    for (let i = 0; i < envelopes.length; i++) {
+        const env = envelopes[i];
+        if (env.role !== 'assistant')
+            continue;
+        const useIds = collectToolUseIds(env);
+        if (useIds.length === 0)
+            continue;
+        const next = envelopes[i + 1];
+        const presentIds = new Set(next?.role === 'user'
+            ? next.content
+                .filter((b) => b.type === 'tool_result')
+                .map(getToolUseId)
+                .filter((id) => typeof id === 'string')
+            : []);
+        for (const useId of useIds) {
+            if (presentIds.has(useId))
+                continue;
+            if (pending.has(useId))
+                continue; // legitimately in-flight
+            throw new MembraneNormalizerError(`tool_use id='${useId}' in envelope ${i} has no matching tool_result in envelope ${i + 1}, ` +
+                `and the id is not in pendingToolCallIds. This indicates a bug in the normalizer itself — ` +
+                `phase 5 should have synthesized a result for any non-pending unmatched id.`, input.map(cloneMsg), envelopes.map(toProviderMessage));
+        }
+    }
+}
+// ============================================================================
+// Helpers
+// ============================================================================
+/**
+ * Read a tool_result's id, tolerating either Anthropic's canonical
+ * `tool_use_id` (snake_case) or the camelCase `toolUseId` some
+ * Membrane producers ship. Only used for *reading*; synthetic
+ * tool_results MUST be written in the canonical snake_case form
+ * (see {@link syntheticToolResult}) — the dual-form read is defensive
+ * against producers, not a license to mix.
+ */
+function getToolUseId(block) {
+    const b = block;
+    if (typeof b.tool_use_id === 'string')
+        return b.tool_use_id;
+    if (typeof b.toolUseId === 'string')
+        return b.toolUseId;
+    return undefined;
+}
+function collectToolUseIds(env) {
+    const ids = [];
+    for (const block of env.content) {
+        if (block.type === 'tool_use') {
+            const id = block.id;
+            if (typeof id === 'string')
+                ids.push(id);
+        }
+    }
+    return ids;
+}
+function removeFirstMatchingResult(envelopes, fromIdx, useId) {
+    for (let i = fromIdx; i < envelopes.length; i++) {
+        const env = envelopes[i];
+        if (env.role !== 'user')
+            continue;
+        for (let j = 0; j < env.content.length; j++) {
+            const block = env.content[j];
+            if (block.type !== 'tool_result')
+                continue;
+            if (getToolUseId(block) === useId) {
+                // Mutates the envelope's content array in place. Caller
+                // (phase 3) is expected to handle the possibly-empty source
+                // envelope; phase 6's filter sweeps any envelope left empty.
+                env.content.splice(j, 1);
+                return { block, fromEnvelope: i };
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Synthetic tool_result for an unmatched tool_use. Writes
+ * `tool_use_id` in Anthropic's canonical snake_case form — do NOT
+ * change to camelCase without auditing every consumer of the
+ * downstream message. The "[pending]" content is intentionally
+ * tombstone-shaped (is_error: false) — most synthesis triggers are
+ * normal-flow gaps (cancellations, stream restarts), not failures
+ * worth alarming the agent about.
+ */
+function syntheticToolResult(toolUseId) {
+    return {
+        type: 'tool_result',
+        tool_use_id: toolUseId,
+        content: '[pending]',
+        is_error: false,
+    };
+}
+function toProviderMessage(env) {
+    return { role: env.role, content: env.content };
+}
+function cloneMsg(msg) {
+    return {
+        role: msg.role,
+        content: Array.isArray(msg.content) ? [...msg.content] : msg.content,
+    };
+}
+function noop() {
+    /* intentionally empty */
+}
+//# sourceMappingURL=normalize-tool-pairs.js.map

package/dist/formatters/normalize-tool-pairs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize-tool-pairs.js","sourceRoot":"","sources":["../../src/formatters/normalize-tool-pairs.ts"],"names":[],"mappings":"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"}

package/dist/formatters/types.d.ts

@@ -51,7 +51,54 @@ export interface BuildOptions {
      * This enables per-message cache boundaries in the conversation.
      */
     hasCacheMarker?: (message: NormalizedMessage, index: number) => boolean;
+    /**
+     * IDs of tool_use blocks the caller knows are currently in-flight
+     * (e.g. a yielding stream that has emitted the tool_use but is still
+     * waiting on the result). If a trailing unmatched tool_use's id is in
+     * this set, the normalizer signals `ready: false` instead of injecting
+     * a synthetic `[pending]` result. Default: empty (always synthesize).
+     */
+    pendingToolCallIds?: ReadonlySet<string>;
+    /**
+     * Telemetry callback fired once per normalization action. Lets the
+     * framework count/log normalizations without coupling Membrane to a
+     * specific logger. See `NormalizeEvent` for the event shapes.
+     */
+    onNormalize?: (event: NormalizeEvent) => void;
 }
+/**
+ * Events emitted by the tool-pair normalizer. Surfaced through
+ * `BuildOptions.onNormalize`. Every normalization action emits one
+ * event; treat non-zero counts as a producer-side bug to investigate.
+ */
+export type NormalizeEvent = {
+    kind: 'block_re_roled';
+    blockType: string;
+    from: 'user' | 'assistant';
+    to: 'user' | 'assistant';
+} | {
+    kind: 'tool_result_hoisted';
+    toolUseId: string;
+    fromEnvelope: number;
+    toEnvelope: number;
+} | {
+    kind: 'interloper_deferred';
+    blockType: string;
+    fromEnvelope: number;
+} | {
+    kind: 'synthetic_pending_result';
+    toolUseId: string;
+    reason: 'trailing' | 'mid_stream';
+} | {
+    kind: 'orphan_tool_result_textified';
+    toolUseId: string;
+} | {
+    kind: 'pending_in_flight';
+    toolUseId: string;
+} | {
+    kind: 'cache_suppressed_for_synthetic';
+    envelopeIndex: number;
+};
 export interface BuildResult {
     /** Messages in provider format */
     messages: ProviderMessage[];
@@ -65,6 +112,14 @@ export interface BuildResult {
     nativeTools?: unknown[];
     /** Number of cache control markers applied (for Anthropic prompt caching) */
     cacheMarkersApplied?: number;
+    /**
+     * `false` only when the tool-pair normalizer detected a trailing
+     * unmatched tool_use whose id is in `pendingToolCallIds` — i.e. the
+     * caller (yielding stream) is mid-cycle and the request should not be
+     * shipped yet. Callers that don't pass `pendingToolCallIds` will never
+     * see `false` here.
+     */
+    ready?: boolean;
 }
 export interface ProviderMessage {
     role: 'user' | 'assistant';

package/dist/formatters/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/formatters/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/formatters/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,iBAAiB,EACjB,YAAY,EACZ,cAAc,EACd,QAAQ,EACR,UAAU,EACV,UAAU,EACX,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EACV,SAAS,EACT,iBAAiB,EAClB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAGpF,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,iBAAiB,EAAE,cAAc,EAAE,CAAC;AAEzE,8CAA8C;AAC9C,MAAM,MAAM,SAAS,GAAG,iBAAiB,CAAC;AAM1C,MAAM,WAAW,eAAe;IAC9B,uEAAuE;IACvE,gBAAgB,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;IAErC,iDAAiD;IACjD,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IAC3B,0CAA0C;IAC1C,eAAe,EAAE,QAAQ,GAAG,WAAW,CAAC;IAExC,wCAAwC;IACxC,oBAAoB,EAAE,MAAM,CAAC;IAE7B,sDAAsD;IACtD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B,kCAAkC;IAClC,KAAK,CAAC,EAAE,cAAc,EAAE,CAAC;IAEzB,kCAAkC;IAClC,QAAQ,CAAC,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAEvD,4BAA4B;IAC5B,YAAY,CAAC,EAAE,MAAM,GAAG,YAAY,EAAE,CAAC;IAEvC,iDAAiD;IACjD,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB,mFAAmF;IACnF,QAAQ,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IAEvB,2CAA2C;IAC3C,uBAAuB,CAAC,EAAE,MAAM,EAAE,CAAC;IAEnC,wDAAwD;IACxD,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAEhC,yFAAyF;IACzF,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;uGAEmG;IACnG,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAE5B;;;;OAIG;IACH,cAAc,CAAC,EAAE,CAAC,OAAO,EAAE,iBAAiB,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;IAExE;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAEzC;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;CAC/C;AAED;;;;GAIG;AACH,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAAC,EAAE,EAAE,MAAM,GAAG,WAAW,CAAA;CAAE,GACnG;IAAE,IAAI,EAAE,qBAAqB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAC5F;IAAE,IAAI,EAAE,qBAAqB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GACxE;IAAE,IAAI,EAAE,0BAA0B,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,UAAU,GAAG,YAAY,CAAA;CAAE,GAC1F;IAAE,IAAI,EAAE,8BAA8B,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAC3D;IAAE,IAAI,EAAE,mBAAmB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAChD;IAAE,IAAI,EAAE,gCAAgC,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAAC;AAMtE,MAAM,WAAW,WAAW;IAC1B,kCAAkC;IAClC,QAAQ,EAAE,eAAe,EAAE,CAAC;IAE5B,iDAAiD;IACjD,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB,qEAAqE;IACrE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B,qCAAqC;IACrC,aAAa,EAAE,MAAM,EAAE,CAAC;IAExB,uDAAuD;IACvD,WAAW,CAAC,EAAE,OAAO,EAAE,CAAC;IAExB,6EAA6E;IAC7E,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAE7B;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,OAAO,EAAE,OAAO,CAAC;CAClB;AAMD,2CAA2C;AAC3C,MAAM,MAAM,WAAW,GAAG,kBAAkB,CAAC;AAE7C,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAAC;IAEzC;;OAEG;IACH,KAAK,IAAI,WAAW,CAAC;IAErB;;OAEG;IACH,cAAc,IAAI,MAAM,CAAC;IAEzB;;OAEG;IACH,KAAK,IAAI,IAAI,CAAC;IAEd;;OAEG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAE5B;;OAEG;IACH,mBAAmB,IAAI,SAAS,CAAC;IAEjC;;OAEG;IACH,aAAa,IAAI,MAAM,CAAC;IAExB;;OAEG;IACH,mBAAmB,IAAI,IAAI,CAAC;IAE5B;;;OAGG;IACH,aAAa,IAAI,OAAO,CAAC;IAEzB;;;OAGG;IACH,SAAS,IAAI;QAAE,aAAa,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAElF;;;;OAIG;IACH,oBAAoB,IAAI,IAAI,CAAC;CAC9B;AAMD,MAAM,WAAW,gBAAgB;IAC/B,wCAAwC;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,mEAAmE;IACnE,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAM9B;;OAEG;IACH,aAAa,CACX,QAAQ,EAAE,iBAAiB,EAAE,EAC7B,OAAO,EAAE,YAAY,GACpB,WAAW,CAAC;IAEf;;;OAGG;IACH,iBAAiB,CACf,OAAO,EAAE,UAAU,EAAE,EACrB,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GAC/B,MAAM,CAAC;IAMV;;;OAGG;IACH,kBAAkB,IAAI,YAAY,CAAC;IAEnC;;;OAGG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,EAAE,CAAC;IAE5C;;;OAGG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;IAErC;;;OAGG;IACH,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,EAAE,CAAC;CACrD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@animalabs/membrane",
-  "version": "0.5.52",
+  "version": "0.5.53",
   "description": "LLM middleware - a selective boundary that transforms what passes through",
   "repository": {
     "type": "git",

package/src/formatters/index.ts

@@ -17,3 +17,12 @@ export type {
 export { AnthropicXmlFormatter, type AnthropicXmlFormatterConfig } from './anthropic-xml.js';
 export { NativeFormatter, type NativeFormatterConfig } from './native.js';
 export { CompletionsFormatter, type CompletionsFormatterConfig } from './completions.js';
+
+export {
+  normalizeToolPairs,
+  MembraneNormalizerError,
+  type NormalizeOptions,
+  type NormalizeResult,
+  type ProviderBlock,
+} from './normalize-tool-pairs.js';
+export type { NormalizeEvent } from './types.js';

package/src/formatters/native.ts

@@ -28,6 +28,7 @@ import type {
   BlockEvent,
   StreamEmission,
 } from './types.js';
+import { normalizeToolPairs } from './normalize-tool-pairs.js';
 
 // ============================================================================
 // Configuration
@@ -245,8 +246,17 @@ export class NativeFormatter implements PrefillFormatter {
       }
     }
 
+    // Tool-pair normalizer: wire-boundary safety net for Anthropic's
+    // structural rules on tool cycles. See `normalize-tool-pairs.ts`
+    // for the full rationale. Runs BEFORE mergeConsecutiveRoles so the
+    // merge sees role-correct envelopes.
+    const normalized = normalizeToolPairs(providerMessages, {
+      pendingToolCallIds: options.pendingToolCallIds,
+      onEvent: options.onNormalize,
+    });
+
     // Merge consecutive same-role messages (API requires alternating)
-    const mergedMessages = this.mergeConsecutiveRoles(providerMessages);
+    const mergedMessages = this.mergeConsecutiveRoles(normalized.messages);
 
     // Build system content with optional cache control
     let systemContent: unknown;
@@ -279,6 +289,7 @@ export class NativeFormatter implements PrefillFormatter {
       systemContent,
       stopSequences: additionalStopSequences ?? [],
       nativeTools,
+      ready: normalized.ready,
     };
   }