@animalabs/membrane 0.5.80 → 0.5.81

package/dist/membrane.d.ts

@@ -36,7 +36,43 @@ export declare class Membrane {
      */
     stream(request: NormalizedRequest, options?: StreamOptions): Promise<NormalizedResponse | AbortedResponse>;
     /**
-     * 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.
+     */
+    private resolveActiveFormatter;
+    /**
+     * 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.
      */
     private resolveToolMode;
     /**
@@ -51,14 +87,31 @@ export declare class Membrane {
      * Stream with native API tool execution
      */
     private streamWithNativeTools;
-    /** See the floating-cache-marker block in buildNativeToolRequest. */
-    private floatBudgetWarned;
+    /**
+     * 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.
+     */
+    private floatBudgetWarnState;
+    private static readonly FLOAT_BUDGET_WARN_INTERVAL_MS;
+    private warnFloatBudgetExhausted;
     /**
      * 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.
      */
     private buildNativeToolRequest;
     /**
@@ -74,10 +127,32 @@ export declare class Membrane {
     private captureProviderThinkingBlocks;
     /**
      * 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).
@@ -114,7 +189,13 @@ export declare class Membrane {
      */
     private buildThinkingParam;
     /**
-     * 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.
      */
     private transformRequest;
     private streamOnce;
@@ -138,9 +219,48 @@ export declare class Membrane {
      */
     private buildContinuationRequestWithImages;
     private transformResponse;
+    /**
+     * 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.
+     */
+    private reportToolParseDiagnostics;
     private buildFinalResponse;
+    /**
+     * 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.
+     */
+    private mergeDiscardedAttempts;
+    /** One provider call's usage as a single-attempt discard record. */
+    private discardedAttemptFrom;
+    /** Price the discarded spend so a caller can read it without re-deriving. */
+    private pricedDiscardedAttempts;
     private mapStopReason;
     private calculateCacheHitRatio;
+    /**
+     * 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.
+     */
     private resolvePricing;
     /** Resolve pricing + calculate cost in one call (for one-shot use outside loops). */
     private estimateCost;
@@ -151,6 +271,15 @@ export declare class Membrane {
      * Check if an error is an abort error
      */
     private isAbortError;
+    /**
+     * 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.
+     */
+    private abortReason;
     /**
      * Build an AbortedResponse from current execution state
      */

package/dist/membrane.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"membrane.d.ts","sourceRoot":"","sources":["../src/membrane.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EAEf,eAAe,EAEf,cAAc,EACd,aAAa,EACb,eAAe,EAYhB,MAAM,kBAAkB,CAAC;AAqB1B,OAAO,KAAK,EACV,cAAc,EACd,qBAAqB,EAGtB,MAAM,4BAA4B,CAAC;AAiBpC,qBAAa,QAAQ;IACnB,OAAO,CAAC,OAAO,CAAkB;IACjC,OAAO,CAAC,QAAQ,CAAC,CAAgB;IACjC,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,SAAS,CAAmB;gBAGlC,OAAO,EAAE,eAAe,EACxB,MAAM,GAAE,cAAmB;IAkB7B;;OAEG;IACG,QAAQ,CACZ,OAAO,EAAE,iBAAiB,EAC1B,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,kBAAkB,CAAC;IAyG9B;;;;;;;;;;;;;;;;;OAiBG;IACG,MAAM,CACV,OAAO,EAAE,iBAAiB,EAC1B,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,kBAAkB,GAAG,eAAe,CAAC;IA8FhD;;OAEG;IACH,OAAO,CAAC,eAAe;IAsBvB;;;;;;OAMG;YACW,kBAAkB;IAimBhC;;OAEG;YACW,qBAAqB;IAwOnC,qEAAqE;IACrE,OAAO,CAAC,iBAAiB,CAAS;IAElC;;;;;;OAMG;IACH,OAAO,CAAC,sBAAsB;IAuT9B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAuD5B;;;;;OAKG;IACH,OAAO,CAAC,6BAA6B;IAkBrC;;;;;;;;;OASG;IACH,OAAO,CAAC,2BAA2B;IA+BnC;;;;;;;OAOG;YACW,sBAAsB;IASpC;;;OAGG;IACH,OAAO,CAAC,qBAAqB;IAoB7B;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,qBAAqB;IAIpC;;;;;;;;OAQG;IACH,OAAO,CAAC,kBAAkB;IAqB1B;;OAEG;IACH,OAAO,CAAC,gBAAgB;YA4EV,UAAU;IA4DxB,OAAO,CAAC,wBAAwB;IA8ChC;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,kCAAkC;IAoD1C,OAAO,CAAC,iBAAiB;IAqIzB,OAAO,CAAC,kBAAkB;IAkF1B,OAAO,CAAC,aAAa;IAoBrB,OAAO,CAAC,sBAAsB;IAO9B,OAAO,CAAC,cAAc;IAItB,qFAAqF;IACrF,OAAO,CAAC,YAAY;IAKpB,OAAO,CAAC,mBAAmB;IAW3B,OAAO,CAAC,gBAAgB;IAMxB,OAAO,CAAC,KAAK;IAcb;;OAEG;IACH,OAAO,CAAC,YAAY;IAcpB;;OAEG;IACH,OAAO,CAAC,oBAAoB;IA4B5B;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,cAAc,CACZ,OAAO,EAAE,iBAAiB,EAC1B,OAAO,GAAE,qBAA0B,GAClC,cAAc;IAuBjB;;OAEG;YACW,mBAAmB;IAqlBjC;;OAEG;YACW,sBAAsB;CA2UrC"}
+{"version":3,"file":"membrane.d.ts","sourceRoot":"","sources":["../src/membrane.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EAEf,eAAe,EAGf,cAAc,EACd,aAAa,EACb,eAAe,EAYhB,MAAM,kBAAkB,CAAC;AAoC1B,OAAO,KAAK,EACV,cAAc,EACd,qBAAqB,EAGtB,MAAM,4BAA4B,CAAC;AAmHpC,qBAAa,QAAQ;IACnB,OAAO,CAAC,OAAO,CAAkB;IACjC,OAAO,CAAC,QAAQ,CAAC,CAAgB;IACjC,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,SAAS,CAAmB;gBAGlC,OAAO,EAAE,eAAe,EACxB,MAAM,GAAE,cAAmB;IAkB7B;;OAEG;IACG,QAAQ,CACZ,OAAO,EAAE,iBAAiB,EAC1B,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,kBAAkB,CAAC;IAiJ9B;;;;;;;;;;;;;;;;;OAiBG;IACG,MAAM,CACV,OAAO,EAAE,iBAAiB,EAC1B,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,kBAAkB,GAAG,eAAe,CAAC;IAkIhD;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,sBAAsB;IAO9B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,eAAe;IA8BvB;;;;;;OAMG;YACW,kBAAkB;IAgnBhC;;OAEG;YACW,qBAAqB;IAuQnC;;;;;;;;;OASG;IACH,OAAO,CAAC,oBAAoB,CAAiD;IAC7E,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,6BAA6B,CAAU;IAE/D,OAAO,CAAC,wBAAwB;IAmBhC;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,sBAAsB;IAgT9B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAmE5B;;;;;OAKG;IACH,OAAO,CAAC,6BAA6B;IAkBrC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,OAAO,CAAC,2BAA2B;IAgFnC;;;;;;;OAOG;YACW,sBAAsB;IASpC;;;OAGG;IACH,OAAO,CAAC,qBAAqB;IAoB7B;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,qBAAqB;IAIpC;;;;;;;;OAQG;IACH,OAAO,CAAC,kBAAkB;IAqB1B;;;;;;;;OAQG;IACH,OAAO,CAAC,gBAAgB;YAsEV,UAAU;IA4GxB,OAAO,CAAC,wBAAwB;IAqDhC;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,kCAAkC;IA8E1C,OAAO,CAAC,iBAAiB;IA6IzB;;;;;;;OAOG;IACH,OAAO,CAAC,0BAA0B;IA8ClC,OAAO,CAAC,kBAAkB;IAyF1B;;;OAGG;IACH,OAAO,CAAC,sBAAsB;IAoB9B,oEAAoE;IACpE,OAAO,CAAC,oBAAoB;IAW5B,6EAA6E;IAC7E,OAAO,CAAC,uBAAuB;IAS/B,OAAO,CAAC,aAAa;IAoBrB,OAAO,CAAC,sBAAsB;IAI9B;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,cAAc;IAgBtB,qFAAqF;IACrF,OAAO,CAAC,YAAY;IAiBpB,OAAO,CAAC,mBAAmB;IAW3B,OAAO,CAAC,gBAAgB;IAMxB,OAAO,CAAC,KAAK;IAcb;;OAEG;IACH,OAAO,CAAC,YAAY;IAkBpB;;;;;;;OAOG;IACH,OAAO,CAAC,WAAW;IAMnB;;OAEG;IACH,OAAO,CAAC,oBAAoB;IA4B5B;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,cAAc,CACZ,OAAO,EAAE,iBAAiB,EAC1B,OAAO,GAAE,qBAA0B,GAClC,cAAc;IA4BjB;;OAEG;YACW,mBAAmB;IA4lBjC;;OAEG;YACW,sBAAsB;CA4TrC"}