@animalabs/membrane 0.5.52 → 0.5.54

package/src/formatters/types.ts

@@ -81,8 +81,38 @@ 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 };
+
 // ============================================================================
 // Build Result
 // ============================================================================
@@ -105,6 +135,15 @@ export interface BuildResult {
 
   /** 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 {

package/src/membrane.ts

@@ -52,6 +52,7 @@ import type {
 } from './types/yielding-stream.js';
 import type { PrefillFormatter, StreamParser } from './formatters/types.js';
 import { AnthropicXmlFormatter } from './formatters/anthropic-xml.js';
+import { normalizeToolPairs, mergeConsecutiveRoles } from './formatters/normalize-tool-pairs.js';
 import { YieldingStreamImpl } from './yielding-stream.js';
 import { calculateCost } from './utils/cost.js';
 import { getDefaultPricing } from './registry/default-pricing.js';
@@ -1030,7 +1031,29 @@ export class Membrane {
 
       providerMessages.push({ role, content });
     }
-    
+
+    // Wire-boundary safety net: repair upstream-produced violations of
+    // Anthropic's tool-cycle structural rules (orphan tool_use, mis-roled
+    // blocks, consecutive same-role envelopes from upstream chunkers that
+    // dropped a tool_result). Mirrors NativeFormatter.buildMessages — the
+    // streaming-native path (runNativeToolsYielding) used to bypass this
+    // and exposed every agent inference to the 400 family.
+    //
+    // Synthesized [pending] tool_results land in fresh user envelopes;
+    // the normalizer also suppresses cache_control on those envelopes
+    // so an in-flight gap can't poison the prompt cache. Merging after
+    // normalize collapses any same-role neighbours the upstream may have
+    // produced before they reach the API's alternating-role check.
+    //
+    // `pendingToolCallIds` is intentionally not threaded here: by the
+    // time runNativeToolsYielding rebuilds the request between
+    // tool-execution rounds, it has already appended the corresponding
+    // 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);
+    const mergedMessages = mergeConsecutiveRoles(normalized.messages);
+
     // 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.
@@ -1073,7 +1096,7 @@ export class Membrane {
       model: request.config.model,
       maxTokens: request.config.maxTokens,
       temperature,
-      messages: providerMessages,
+      messages: mergedMessages,
       system,
       tools,
       thinking,