@animalabs/membrane 0.5.77 → 0.5.79

package/src/membrane.ts

@@ -105,6 +105,10 @@ export class Membrane {
     const startTime = Date.now();
     let attempts = 0;
     let rawRequest: unknown;
+    // Counted separately from `attempts` (the transport-error budget): a
+    // refusal is a successful HTTP call with an unwanted verdict, and letting
+    // it consume error retries would couple two unrelated budgets.
+    let refusalRetriesUsed = 0;
 
     while (true) {
       attempts++;
@@ -140,6 +144,19 @@ export class Membrane {
           rawRequest
         );
 
+        // Re-issue a content-policy refusal (opt-in, default off). Safe here
+        // in a way the streaming paths are not: nothing has reached the
+        // caller yet, so the abandoned attempt leaves no trace to retract.
+        // Deliberately BEFORE afterResponse — a hook that logs or transforms
+        // should see the attempt that actually stands, not the discarded one.
+        if (
+          response.stopReason === 'refusal' &&
+          refusalRetriesUsed < Math.max(0, options.refusalRetries ?? 0)
+        ) {
+          refusalRetriesUsed++;
+          continue;
+        }
+
         // Call afterResponse hook
         if (this.config.hooks?.afterResponse) {
           return await this.config.hooks.afterResponse(response, providerResponse.raw);
@@ -391,10 +408,16 @@ export class Membrane {
     // Track the initial prefill length so we can extract only NEW content for response
     // Also track what block type we're inside at the end of prefill
     let initialPrefillLength = 0;
+    // Watermark for per-round delta text (ToolContext.roundPreamble): start of
+    // the CURRENT round's model text in parser-accumulated coordinates.
+    // Advanced past each round's injected results push, so injected
+    // <function_results> XML never enters a round's delta.
+    let roundStartLen = 0;
     let initialBlockType: 'thinking' | 'tool_call' | 'tool_result' | null = null;
     if (prefillResult.assistantPrefill) {
       parser.push(prefillResult.assistantPrefill);
       initialPrefillLength = prefillResult.assistantPrefill.length;
+      roundStartLen = initialPrefillLength;
       // Capture what block type we're inside after prefill (if any)
       if (parser.isInsideBlock()) {
         const blockType = parser.getCurrentBlockType();
@@ -682,6 +705,7 @@ export class Membrane {
             const context: ToolContext = {
               rawText: parsed.fullMatch,
               preamble: parsed.beforeText.slice(initialPrefillLength),
+              roundPreamble: parsed.beforeText.slice(roundStartLen),
               depth: toolDepth,
               previousResults: executedToolResults,
               accumulated: parser.getAccumulated().slice(initialPrefillLength),
@@ -694,6 +718,14 @@ export class Membrane {
               );
             }
 
+            // Backfill tool names for the legacy XML result rendering
+            // (<result><tool_name>…</tool_name><stdout>…) when the executor
+            // didn't supply them.
+            const callNames = new Map(parsed.calls.map((c) => [c.id, c.name]));
+            for (const r of results) {
+              if (!r.toolName) r.toolName = callNames.get(r.toolUseId);
+            }
+
             // Track the tool results
             executedToolResults.push(...results);
 
@@ -815,6 +847,10 @@ export class Membrane {
               );
             }
 
+            // Next round's model text starts after everything injected this
+            // round (results XML, image-split tags, thinking opener).
+            roundStartLen = parser.getAccumulated().length;
+
             // Reset parser state for new streaming iteration. Tool rounds
             // are the caller's work — they count against maxToolDepth only,
             // never against the resumption guards (issue #39 review).
@@ -1681,6 +1717,23 @@ export class Membrane {
        * separate `streamOnceWithoutHook` so the bypass is intentional.
        */
       normalizedRequest: NormalizedRequest;
+      /**
+       * Re-issue this attempt when the provider ends it with
+       * `stop_reason: 'refusal'` (see RetryingEvent). Default 0 = off, so
+       * every existing caller keeps byte-identical behaviour.
+       */
+      refusalRetries?: number;
+      /**
+       * REQUIRED to enable streaming retries. Called immediately before a
+       * re-issue so the caller can discard the abandoned attempt: reset its
+       * accumulators and tell its own consumer to drop what it emitted.
+       *
+       * Without it a retry would silently concatenate two attempts, so a
+       * caller that does not pass this simply does not get retries — an
+       * unaware consumer can never be corrupted by enabling the option
+       * somewhere upstream.
+       */
+      onRetrying?: (info: { attempt: number; maxAttempts: number; category?: string }) => void;
     }
   ) {
     // Strip `normalizedRequest` before forwarding to the adapter — it's
@@ -1688,9 +1741,21 @@ 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, ...adapterOptions } = options;
+    const { normalizedRequest, refusalRetries, onRetrying, ...adapterOptions } = options;
     const finalRequest = (await this.applyBeforeRequestHook(normalizedRequest, request)) as typeof request;
-    return await this.adapter.stream(finalRequest, callbacks, adapterOptions);
+
+    // 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;
+    while (true) {
+      const result = await this.adapter.stream(finalRequest, callbacks, adapterOptions);
+      if (result.stopReason !== 'refusal' || retried >= maxAttempts) return result;
+      retried++;
+      const category = (result.raw as { response?: { stop_details?: { category?: string } } } | undefined)
+        ?.response?.stop_details?.category;
+      onRetrying!({ attempt: retried, maxAttempts, category });
+    }
   }
 
   private buildContinuationRequest(
@@ -2172,6 +2237,18 @@ export class Membrane {
   ): YieldingStream {
     const toolMode = this.resolveToolMode(request);
 
+    // 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,
+    // and a partial implementation would corrupt the turn instead of
+    // retrying it. Fail LOUD and OFF rather than silently mis-retrying.
+    if (toolMode !== 'native' && (options.refusalRetries ?? 0) > 0) {
+      (this.config.logger ?? console).warn(
+        '[membrane] refusalRetries is ignored in XML tool mode ' +
+        '(native-only for now) — the turn will surface the refusal as before.',
+      );
+    }
+
     // Create the yielding stream with the appropriate inference runner
     const runInference = toolMode === 'native'
       ? (stream: YieldingStreamImpl) => this.runNativeToolsYielding(request, options, stream)
@@ -2256,10 +2333,14 @@ export class Membrane {
 
     // Initialize parser with prefill content
     let initialPrefillLength = 0;
+    // Watermark for per-round delta text (ToolContext.roundPreamble) — see
+    // streamWithXmlTools for rationale. Advanced past each results push.
+    let roundStartLen = 0;
     let initialBlockType: 'thinking' | 'tool_call' | 'tool_result' | null = null;
     if (prefillResult.assistantPrefill) {
       parser.push(prefillResult.assistantPrefill);
       initialPrefillLength = prefillResult.assistantPrefill.length;
+      roundStartLen = initialPrefillLength;
       if (parser.isInsideBlock()) {
         const blockType = parser.getCurrentBlockType();
         if (blockType === 'thinking' || blockType === 'tool_call' || blockType === 'tool_result') {
@@ -2506,6 +2587,7 @@ export class Membrane {
             const context: ToolContext = {
               rawText: parsed.fullMatch,
               preamble: parsed.beforeText.slice(initialPrefillLength),
+              roundPreamble: parsed.beforeText.slice(roundStartLen),
               depth: toolDepth,
               previousResults: executedToolResults,
               accumulated: parser.getAccumulated().slice(initialPrefillLength),
@@ -2520,6 +2602,14 @@ export class Membrane {
 
             const { results, injectedMessages } = await stream.requestToolExecution(toolCallsEvent);
 
+            // Backfill tool names for the legacy XML result rendering
+            // (<result><tool_name>…</tool_name><stdout>…) when the executor
+            // didn't supply them.
+            const yieldCallNames = new Map(parsed.calls.map((c) => [c.id, c.name]));
+            for (const r of results) {
+              if (!r.toolName) r.toolName = yieldCallNames.get(r.toolUseId);
+            }
+
             // Mid-turn injected messages are not supported on the XML prefill
             // path: the continuation is an assistant prefill over an XML
             // transcript, not a message array, so there is no user envelope
@@ -2667,6 +2757,10 @@ export class Membrane {
               );
             }
 
+            // Next round's model text starts after everything injected this
+            // round (results XML, image-split tags, thinking opener).
+            roundStartLen = parser.getAccumulated().length;
+
             // Tool rounds are the caller's work — they count against
             // maxToolDepth only, never against the resumption guards
             // (issue #39 review: the uncapped tool-loop contract stands).
@@ -2824,6 +2918,9 @@ export class Membrane {
         // 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
         // every token chunk is tagged with the membrane block it belongs to.
         // Without this, thinking_delta chunks get mislabelled as 'text' and
@@ -2902,6 +2999,25 @@ export class Membrane {
             idleTimeoutMs: options.idleTimeoutMs,
             normalizedRequest: request,
             onRequest: (req: unknown) => { rawRequest = req; },
+            refusalRetries: options.refusalRetries,
+            // Discard the refused attempt: roll the accumulators back to
+            // where this attempt began and tell the consumer to drop what it
+            // already received. `allTextAccumulated` spans the whole tool
+            // loop, so it is truncated rather than cleared.
+            onRetrying: (info) => {
+              allTextAccumulated = allTextAccumulated.slice(0, allTextBefore);
+              textAccumulated = '';
+              blockIndex = 0;
+              currentBlockType = 'text';
+              seenBlockIndices.clear();
+              stream.emit({
+                type: 'retrying',
+                attempt: info.attempt,
+                maxAttempts: info.maxAttempts,
+                reason: 'refusal',
+                ...(info.category ? { category: info.category } : {}),
+              });
+            },
           }
         );
 

package/src/providers/anthropic.ts

@@ -780,7 +780,7 @@ function toAnthropicToolResultContent(
  *  can lose or mislabel mediaType (e.g. a PNG tagged image/jpeg), which the
  *  Anthropic API rejects with a 400. Trust the bytes; fall back to the declared
  *  type, then jpeg. */
-function detectImageMediaType(data: string | undefined, fallback?: string): string {
+export function detectImageMediaType(data: string | undefined, fallback?: string): string {
   try {
     const b = Buffer.from((data || "").slice(0, 24), "base64");
     if (b[0]===0x89&&b[1]===0x50&&b[2]===0x4e&&b[3]===0x47) return "image/png";

package/src/providers/bedrock.ts

@@ -25,6 +25,7 @@ import {
   INTERLEAVED_THINKING_BETA,
   needsInterleavedThinkingBeta,
   thinkingEnabled,
+  detectImageMediaType,
 } from './anthropic.js';
 
 // ============================================================================
@@ -322,8 +323,9 @@ export class BedrockAdapter implements ProviderAdapter {
 
     // If already in Bedrock format, use as-is
     // Supports both direct model IDs (anthropic.claude-...) and
-    // cross-region inference profile IDs (us.anthropic.claude-..., eu.anthropic.claude-..., apac.anthropic.claude-...)
-    if (modelId.startsWith('anthropic.') || /^[a-z]{2,4}\.anthropic\./.test(modelId)) {
+    // cross-region inference profile IDs (us.anthropic.claude-..., eu.anthropic.claude-...,
+    // apac.anthropic.claude-..., global.anthropic.claude-... — `global` is 6 chars, hence {2,6}).
+    if (modelId.startsWith('anthropic.') || /^[a-z]{2,6}\.anthropic\./.test(modelId)) {
       return modelId;
     }
 
@@ -403,6 +405,25 @@ export class BedrockAdapter implements ProviderAdapter {
     // caching works without the field, so strip just the ttl and keep the
     // breakpoint. Transport quirks belong to the transport, not to every
     // caller that sets cacheTtl. (Connectome issue #35.)
+    // Bedrock is strict about the wire shape of image sources: internal blocks
+    // carry camelCase `mediaType`, the API requires snake_case `media_type`.
+    // The Anthropic adapter converts on both paths (toAnthropicContent /
+    // toAnthropicToolResultContent); without the same conversion here a
+    // tool-returned image 400s with "media_type: Field required" mid-turn
+    // (observed on eidoverse snapshot results, 2026-08-08). Applies to
+    // top-level image blocks AND images nested inside tool_result content.
+    const toWireImage = (block: any): any => {
+      const source = block.source;
+      if (!source || source.type !== 'base64') return block;
+      const { mediaType, media_type, ...restSource } = source;
+      return {
+        ...block,
+        source: {
+          ...restSource,
+          media_type: detectImageMediaType(source.data, (media_type ?? mediaType) as string),
+        },
+      };
+    };
     const sanitizedMessages = (request.messages as any[]).map((msg: any) => {
       if (!Array.isArray(msg.content)) return msg;
       return {
@@ -410,7 +431,18 @@ export class BedrockAdapter implements ProviderAdapter {
         content: msg.content.map((block: any) => {
           if (block.type === 'image' && block.sourceUrl !== undefined) {
             const { sourceUrl, ...rest } = block;
-            return stripCacheTtl(rest);
+            return stripCacheTtl(toWireImage(rest));
+          }
+          if (block.type === 'image') {
+            return stripCacheTtl(toWireImage(block));
+          }
+          if (block.type === 'tool_result' && Array.isArray(block.content)) {
+            return stripCacheTtl({
+              ...block,
+              content: block.content.map((inner: any) =>
+                inner?.type === 'image' ? toWireImage(inner) : inner,
+              ),
+            });
           }
           return stripCacheTtl(block);
         }),

package/src/types/content.ts

@@ -128,6 +128,11 @@ export interface ToolUseContent {
 export interface ToolResultContent {
   type: 'tool_result';
   toolUseId: string;
+  /**
+   * Tool name, persisted so XML replay can reconstruct the legacy
+   * `<tool_name>` element byte-identically to the live injection.
+   */
+  toolName?: string;
   content: string | ContentBlock[];
   isError?: boolean;
   /**

package/src/types/streaming.ts

@@ -262,6 +262,21 @@ export interface CompleteOptions {
   /** Abort signal for cancellation */
   signal?: AbortSignal;
 
+  /**
+   * Re-issue the request when it ends with `stop_reason: 'refusal'`, up to
+   * this many times. Default 0 (off).
+   *
+   * Safe and invisible on this path: nothing has been emitted to the caller
+   * yet, so a discarded attempt leaves no trace beyond its output tokens
+   * (the replay is cache-warm on input). The streaming equivalent needs the
+   * caller to handle `RetryingEvent` — see YieldingStreamOptions.
+   *
+   * Near the content-policy threshold a refusal is probabilistic rather than
+   * a property of the payload, so re-asking is the cheapest correct response
+   * — cheaper and far less invasive than rewriting the conversation.
+   */
+  refusalRetries?: number;
+
   /** Request timeout */
   timeoutMs?: number;
 

package/src/types/tools.ts

@@ -37,6 +37,13 @@ export interface ToolCall {
 
 export interface ToolResult {
   toolUseId: string;
+  /**
+   * Tool name, for the legacy XML result rendering
+   * (`<result><tool_name>…</tool_name><stdout>…</stdout></result>`).
+   * Optional: XML paths backfill it from the round's parsed calls when the
+   * executor didn't supply it.
+   */
+  toolName?: string;
   /**
    * Result content - can be string or structured content blocks (for images).
    * For XML mode, images are noted in text. For native mode, passed as content blocks.
@@ -63,6 +70,19 @@ export interface ToolContext {
   /** Text before the tool calls (already streamed to user) */
   preamble: string;
 
+  /**
+   * XML mode only: THIS round's model-authored text — the slice of the
+   * turn between the end of the previous round's injected results and this
+   * round's <function_calls> opener. Unlike `preamble` (cumulative: the
+   * whole turn so far, including harness-injected <function_results> XML),
+   * this never repeats earlier rounds and never contains injected results.
+   * Consumers persisting per-round assistant text must prefer this field —
+   * persisting the cumulative `preamble` per round stores each round's text
+   * N times and re-persists injected results as model text (the Evander
+   * 2026-08-08 scaffold-leak pyramid).
+   */
+  roundPreamble?: string;
+
   /** Current depth in tool execution loop */
   depth: number;
 

package/src/types/yielding-stream.ts

@@ -69,6 +69,35 @@ export interface ErrorEvent {
   error: Error;
 }
 
+/**
+ * Retrying event — the provider ended the attempt with
+ * `stop_reason: 'refusal'` and membrane is re-issuing it (opt-in via
+ * `refusalRetries`).
+ *
+ * **The consumer MUST discard everything this call has emitted so far**:
+ * `tokens`, `block`, and any partially built assistant content belong to an
+ * attempt that no longer exists. A fresh sequence follows. Consumers that
+ * have already shown those tokens to a human (a TUI, a chat surface) must
+ * retract or overwrite them.
+ *
+ * Why this exists: near the classifier threshold a refusal is probabilistic
+ * rather than a property of the payload — the same bytes pass and refuse
+ * minutes apart — so re-asking is the cheapest correct response. Retrying
+ * silently would corrupt any consumer that already rendered the discarded
+ * attempt, which is why it is opt-in and announced rather than invisible.
+ */
+export interface RetryingEvent {
+  type: 'retrying';
+  /** 1-based index of the retry about to be issued. */
+  attempt: number;
+  /** Configured maximum number of retries. */
+  maxAttempts: number;
+  /** Always 'refusal' today; widened only if other retryable stops appear. */
+  reason: 'refusal';
+  /** Provider's refusal category when it supplies one (e.g. 'cyber'). */
+  category?: string;
+}
+
 /**
  * Aborted event - stream was cancelled.
  */
@@ -87,6 +116,7 @@ export interface AbortedEvent {
 export type StreamEvent =
   | TokensEvent
   | StreamBlockEvent
+  | RetryingEvent
   | ToolCallsEvent
   | UsageEvent
   | CompleteEvent
@@ -225,6 +255,23 @@ export interface YieldingStreamOptions {
   /** Request ID for correlation/logging */
   requestId?: string;
 
+  /**
+   * Re-issue an attempt that ends with `stop_reason: 'refusal'`, up to this
+   * many times. Default 0 (off).
+   *
+   * Enabling it means the stream can emit `RetryingEvent` — **consumers MUST
+   * handle it and discard what they have received for the call**, or two
+   * attempts will be concatenated. That is why it is off by default and why
+   * turning it on is a per-call decision by a consumer that has been updated.
+   *
+   * Rationale: near the content-policy threshold a refusal is probabilistic,
+   * not a property of the payload — identical bytes pass and refuse minutes
+   * apart. Re-asking is cheaper and less invasive than rewriting the
+   * conversation, and the replay is cache-warm, so only the discarded output
+   * tokens are real spend.
+   */
+  refusalRetries?: number;
+
   /**
    * Maximum tool execution depth. Default: unlimited.
    *