@animalabs/membrane 0.5.51 → 0.5.53

package/dist/yielding-stream.d.ts

@@ -0,0 +1,60 @@
+/**
+ * YieldingStream implementation
+ *
+ * Provides an async iterator interface for streaming inference that yields
+ * control back to the caller for tool execution.
+ */
+import type { StreamEvent, YieldingStream, YieldingStreamOptions, ToolCallsEvent } from './types/yielding-stream.js';
+import type { ToolResult } from './types/tools.js';
+/**
+ * Implementation of the YieldingStream interface.
+ *
+ * This class manages:
+ * - An event queue for yielding events to the consumer
+ * - A promise-based handshake for tool results
+ * - Cancellation via AbortController
+ * - State tracking for debugging and validation
+ */
+export declare class YieldingStreamImpl implements YieldingStream {
+    private readonly options;
+    private readonly runInference;
+    private state;
+    private eventQueue;
+    private pendingToolResults;
+    private abortController;
+    private _toolDepth;
+    private eventWaiter;
+    private producerDone;
+    constructor(options: YieldingStreamOptions, runInference: (stream: YieldingStreamImpl) => Promise<void>);
+    get isWaitingForTools(): boolean;
+    get pendingToolCallIds(): string[];
+    get toolDepth(): number;
+    /**
+     * Get the abort signal for use in internal operations.
+     */
+    get signal(): AbortSignal;
+    provideToolResults(results: ToolResult[]): void;
+    cancel(): void;
+    [Symbol.asyncIterator](): AsyncIterator<StreamEvent>;
+    /**
+     * Push an event to be yielded to the consumer.
+     */
+    emit(event: StreamEvent): void;
+    /**
+     * Request tool execution and wait for results.
+     * Called by the inference loop when tool calls are detected.
+     */
+    requestToolExecution(event: ToolCallsEvent): Promise<ToolResult[]>;
+    /**
+     * Mark the producer as done (inference loop finished).
+     */
+    markDone(): void;
+    /**
+     * Check if the stream has been cancelled.
+     */
+    get isCancelled(): boolean;
+    private startInference;
+    private waitForEvent;
+    private notifyEventWaiter;
+}
+//# sourceMappingURL=yielding-stream.d.ts.map

package/dist/yielding-stream.js

@@ -0,0 +1,206 @@
+/**
+ * YieldingStream implementation
+ *
+ * Provides an async iterator interface for streaming inference that yields
+ * control back to the caller for tool execution.
+ */
+// ============================================================================
+// YieldingStreamImpl
+// ============================================================================
+/**
+ * Implementation of the YieldingStream interface.
+ *
+ * This class manages:
+ * - An event queue for yielding events to the consumer
+ * - A promise-based handshake for tool results
+ * - Cancellation via AbortController
+ * - State tracking for debugging and validation
+ */
+export class YieldingStreamImpl {
+    options;
+    runInference;
+    state = { status: 'idle' };
+    eventQueue = [];
+    pendingToolResults = null;
+    abortController;
+    _toolDepth = 0;
+    // Promise/resolver for the async iterator to wait on new events
+    eventWaiter = null;
+    // Flag indicating the stream producer is done
+    producerDone = false;
+    constructor(options, runInference) {
+        this.options = options;
+        this.runInference = runInference;
+        this.abortController = new AbortController();
+        // Link external signal if provided
+        if (options.signal) {
+            options.signal.addEventListener('abort', () => {
+                this.cancel();
+            });
+        }
+    }
+    // ============================================================================
+    // Public Interface
+    // ============================================================================
+    get isWaitingForTools() {
+        return this.state.status === 'waiting_for_tools';
+    }
+    get pendingToolCallIds() {
+        if (this.state.status === 'waiting_for_tools') {
+            return this.state.pendingCallIds;
+        }
+        return [];
+    }
+    get toolDepth() {
+        return this._toolDepth;
+    }
+    /**
+     * Get the abort signal for use in internal operations.
+     */
+    get signal() {
+        return this.abortController.signal;
+    }
+    provideToolResults(results) {
+        if (this.state.status !== 'waiting_for_tools') {
+            throw new Error(`Cannot provide tool results: stream is not waiting for tools (status: ${this.state.status})`);
+        }
+        if (!this.pendingToolResults) {
+            throw new Error('Internal error: no pending tool results promise');
+        }
+        // Validate that results match pending call IDs
+        const pendingIds = new Set(this.state.pendingCallIds);
+        const providedIds = new Set(results.map((r) => r.toolUseId));
+        for (const id of pendingIds) {
+            if (!providedIds.has(id)) {
+                throw new Error(`Missing tool result for call ID: ${id}`);
+            }
+        }
+        // Resolve the promise and transition state
+        this.pendingToolResults.resolve(results);
+        this.pendingToolResults = null;
+        this.state = { status: 'streaming' };
+        this._toolDepth++;
+    }
+    cancel() {
+        if (this.state.status === 'done' || this.state.status === 'error') {
+            return; // Already terminated
+        }
+        this.abortController.abort();
+        // If waiting for tools, reject the pending promise
+        if (this.pendingToolResults) {
+            this.pendingToolResults.reject(new Error('Stream cancelled'));
+            this.pendingToolResults = null;
+        }
+        // Emit aborted event and wake the iterator so it can deliver it
+        this.emit({ type: 'aborted', reason: 'user' });
+        this.producerDone = true;
+        this.state = { status: 'done' };
+    }
+    // ============================================================================
+    // Async Iterator Implementation
+    // ============================================================================
+    [Symbol.asyncIterator]() {
+        // Start the inference loop when iteration begins
+        this.startInference();
+        return {
+            next: async () => {
+                while (true) {
+                    // Check for queued events
+                    const event = this.eventQueue.shift();
+                    if (event) {
+                        // Check if this is a terminal event
+                        if (event.type === 'complete' ||
+                            event.type === 'error' ||
+                            event.type === 'aborted') {
+                            this.state = { status: 'done' };
+                        }
+                        return { value: event, done: false };
+                    }
+                    // If producer is done and queue is empty, we're done
+                    if (this.producerDone) {
+                        return { value: undefined, done: true };
+                    }
+                    // Wait for more events
+                    await this.waitForEvent();
+                }
+            },
+        };
+    }
+    // ============================================================================
+    // Internal Methods (called by the inference loop)
+    // ============================================================================
+    /**
+     * Push an event to be yielded to the consumer.
+     */
+    emit(event) {
+        this.eventQueue.push(event);
+        this.notifyEventWaiter();
+    }
+    /**
+     * Request tool execution and wait for results.
+     * Called by the inference loop when tool calls are detected.
+     */
+    async requestToolExecution(event) {
+        // Emit the tool calls event
+        this.emit(event);
+        // Transition to waiting state
+        this.state = {
+            status: 'waiting_for_tools',
+            pendingCallIds: event.calls.map((c) => c.id),
+        };
+        // Create a promise that will be resolved by provideToolResults()
+        return new Promise((resolve, reject) => {
+            this.pendingToolResults = { resolve, reject };
+        });
+    }
+    /**
+     * Mark the producer as done (inference loop finished).
+     */
+    markDone() {
+        this.producerDone = true;
+        this.notifyEventWaiter();
+    }
+    /**
+     * Check if the stream has been cancelled.
+     */
+    get isCancelled() {
+        return this.abortController.signal.aborted;
+    }
+    // ============================================================================
+    // Private Helpers
+    // ============================================================================
+    startInference() {
+        if (this.state.status !== 'idle') {
+            return; // Already started
+        }
+        this.state = { status: 'streaming' };
+        // Run the inference loop in the background
+        this.runInference(this)
+            .then(() => {
+            this.markDone();
+        })
+            .catch((error) => {
+            if (!this.isCancelled) {
+                this.emit({ type: 'error', error });
+            }
+            this.markDone();
+        });
+    }
+    waitForEvent() {
+        if (!this.eventWaiter) {
+            let resolve;
+            const promise = new Promise((r) => {
+                resolve = r;
+            });
+            this.eventWaiter = { resolve: resolve, promise };
+        }
+        return this.eventWaiter.promise;
+    }
+    notifyEventWaiter() {
+        if (this.eventWaiter) {
+            this.eventWaiter.resolve();
+            this.eventWaiter = null;
+        }
+    }
+}
+//# sourceMappingURL=yielding-stream.js.map

package/dist/yielding-stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"yielding-stream.js","sourceRoot":"","sources":["../src/yielding-stream.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA0BH,+EAA+E;AAC/E,qBAAqB;AACrB,+EAA+E;AAE/E;;;;;;;;GAQG;AACH,MAAM,OAAO,kBAAkB;IAiBV;IACA;IAjBX,KAAK,GAAgB,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IACxC,UAAU,GAAkB,EAAE,CAAC;IAC/B,kBAAkB,GAA8B,IAAI,CAAC;IACrD,eAAe,CAAkB;IACjC,UAAU,GAAG,CAAC,CAAC;IAEvB,gEAAgE;IACxD,WAAW,GAGR,IAAI,CAAC;IAEhB,8CAA8C;IACtC,YAAY,GAAG,KAAK,CAAC;IAE7B,YACmB,OAA8B,EAC9B,YAA2D;QAD3D,YAAO,GAAP,OAAO,CAAuB;QAC9B,iBAAY,GAAZ,YAAY,CAA+C;QAE5E,IAAI,CAAC,eAAe,GAAG,IAAI,eAAe,EAAE,CAAC;QAE7C,mCAAmC;QACnC,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;YACnB,OAAO,CAAC,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE;gBAC5C,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,CAAC,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,+EAA+E;IAC/E,mBAAmB;IACnB,+EAA+E;IAE/E,IAAI,iBAAiB;QACnB,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,mBAAmB,CAAC;IACnD,CAAC;IAED,IAAI,kBAAkB;QACpB,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,mBAAmB,EAAE,CAAC;YAC9C,OAAO,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC;QACnC,CAAC;QACD,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAED;;OAEG;IACH,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC;IACrC,CAAC;IAED,kBAAkB,CAAC,OAAqB;QACtC,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,mBAAmB,EAAE,CAAC;YAC9C,MAAM,IAAI,KAAK,CACb,yEAAyE,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAC9F,CAAC;QACJ,CAAC;QAED,IAAI,CAAC,IAAI,CAAC,kBAAkB,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;QACrE,CAAC;QAED,+CAA+C;QAC/C,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;QACtD,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;QAE7D,KAAK,MAAM,EAAE,IAAI,UAAU,EAAE,CAAC;YAC5B,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;gBACzB,MAAM,IAAI,KAAK,CAAC,oCAAoC,EAAE,EAAE,CAAC,CAAC;YAC5D,CAAC;QACH,CAAC;QAED,2CAA2C;QAC3C,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QACzC,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAAC;QAC/B,IAAI,CAAC,KAAK,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;QACrC,IAAI,CAAC,UAAU,EAAE,CAAC;IACpB,CAAC;IAED,MAAM;QACJ,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,MAAM,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,OAAO,EAAE,CAAC;YAClE,OAAO,CAAC,qBAAqB;QAC/B,CAAC;QAED,IAAI,CAAC,eAAe,CAAC,KAAK,EAAE,CAAC;QAE7B,mDAAmD;QACnD,IAAI,IAAI,CAAC,kBAAkB,EAAE,CAAC;YAC5B,IAAI,CAAC,kBAAkB,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,kBAAkB,CAAC,CAAC,CAAC;YAC9D,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAAC;QACjC,CAAC;QAED,gEAAgE;QAChE,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;QAC/C,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;QACzB,IAAI,CAAC,KAAK,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAClC,CAAC;IAED,+EAA+E;IAC/E,gCAAgC;IAChC,+EAA+E;IAE/E,CAAC,MAAM,CAAC,aAAa,CAAC;QACpB,iDAAiD;QACjD,IAAI,CAAC,cAAc,EAAE,CAAC;QAEtB,OAAO;YACL,IAAI,EAAE,KAAK,IAA0C,EAAE;gBACrD,OAAO,IAAI,EAAE,CAAC;oBACZ,0BAA0B;oBAC1B,MAAM,KAAK,GAAG,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;oBACtC,IAAI,KAAK,EAAE,CAAC;wBACV,oCAAoC;wBACpC,IACE,KAAK,CAAC,IAAI,KAAK,UAAU;4BACzB,KAAK,CAAC,IAAI,KAAK,OAAO;4BACtB,KAAK,CAAC,IAAI,KAAK,SAAS,EACxB,CAAC;4BACD,IAAI,CAAC,KAAK,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;wBAClC,CAAC;wBACD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;oBACvC,CAAC;oBAED,qDAAqD;oBACrD,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;wBACtB,OAAO,EAAE,KAAK,EAAE,SAAmC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;oBACpE,CAAC;oBAED,uBAAuB;oBACvB,MAAM,IAAI,CAAC,YAAY,EAAE,CAAC;gBAC5B,CAAC;YACH,CAAC;SACF,CAAC;IACJ,CAAC;IAED,+EAA+E;IAC/E,kDAAkD;IAClD,+EAA+E;IAE/E;;OAEG;IACH,IAAI,CAAC,KAAkB;QACrB,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC5B,IAAI,CAAC,iBAAiB,EAAE,CAAC;IAC3B,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,oBAAoB,CAAC,KAAqB;QAC9C,4BAA4B;QAC5B,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAEjB,8BAA8B;QAC9B,IAAI,CAAC,KAAK,GAAG;YACX,MAAM,EAAE,mBAAmB;YAC3B,cAAc,EAAE,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC7C,CAAC;QAEF,iEAAiE;QACjE,OAAO,IAAI,OAAO,CAAe,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACnD,IAAI,CAAC,kBAAkB,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;QAChD,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,QAAQ;QACN,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;QACzB,IAAI,CAAC,iBAAiB,EAAE,CAAC;IAC3B,CAAC;IAED;;OAEG;IACH,IAAI,WAAW;QACb,OAAO,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,OAAO,CAAC;IAC7C,CAAC;IAED,+EAA+E;IAC/E,kBAAkB;IAClB,+EAA+E;IAEvE,cAAc;QACpB,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;YACjC,OAAO,CAAC,kBAAkB;QAC5B,CAAC;QAED,IAAI,CAAC,KAAK,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;QAErC,2CAA2C;QAC3C,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC;aACpB,IAAI,CAAC,GAAG,EAAE;YACT,IAAI,CAAC,QAAQ,EAAE,CAAC;QAClB,CAAC,CAAC;aACD,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;YACf,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;gBACtB,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;YACtC,CAAC;YACD,IAAI,CAAC,QAAQ,EAAE,CAAC;QAClB,CAAC,CAAC,CAAC;IACP,CAAC;IAEO,YAAY;QAClB,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YACtB,IAAI,OAAmB,CAAC;YACxB,MAAM,OAAO,GAAG,IAAI,OAAO,CAAO,CAAC,CAAC,EAAE,EAAE;gBACtC,OAAO,GAAG,CAAC,CAAC;YACd,CAAC,CAAC,CAAC;YACH,IAAI,CAAC,WAAW,GAAG,EAAE,OAAO,EAAE,OAAQ,EAAE,OAAO,EAAE,CAAC;QACpD,CAAC;QACD,OAAO,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC;IAClC,CAAC;IAEO,iBAAiB;QACvB,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACrB,IAAI,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC;YAC3B,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;QAC1B,CAAC;IACH,CAAC;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@animalabs/membrane",
-  "version": "0.5.51",
+  "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,
     };
   }