@animalabs/membrane 0.5.76 → 0.5.77

package/src/types/config.ts

@@ -15,17 +15,53 @@ import type { PrefillFormatter } from '../formatters/types.js';
 export interface RetryConfig {
   /** Maximum number of retry attempts (default: 3) */
   maxRetries: number;
-  
+
   /** Initial retry delay in milliseconds (default: 1000) */
   retryDelayMs: number;
-  
+
   /** Backoff multiplier (default: 2) */
   backoffMultiplier: number;
-  
+
   /** Maximum retry delay (default: 30000) */
   maxRetryDelayMs: number;
+
+  /**
+   * Separate, longer schedule for provider capacity errors (529
+   * overloaded_error). Capacity storms last minutes, not seconds — the
+   * standard schedule's 30s ceiling turns one into a dead turn. Overloaded
+   * retries are always attempted (mirroring the forced 429 retries), with
+   * jitter so a fleet backing off doesn't re-create the stampede in sync.
+   *
+   * maxRetries: 0 here disables this dedicated policy entirely: 529s then
+   * follow the base retry config like any other retryable server error
+   * (no forced retries, base schedule, no stream-path retry) — the exact
+   * pre-policy behavior.
+   */
+  overloaded: OverloadedRetryConfig;
 }
 
+export interface OverloadedRetryConfig {
+  /** Attempt bound for overloaded errors, applied even when the base
+   *  maxRetries is 0. Like the base maxRetries (and the forced 429 path),
+   *  this bounds TOTAL attempts, not retries-after-the-first (default: 7) */
+  maxRetries: number;
+
+  /** Initial overloaded retry delay in milliseconds (default: 10000) */
+  retryDelayMs: number;
+
+  /** Backoff multiplier (default: 2) */
+  backoffMultiplier: number;
+
+  /** Maximum overloaded retry delay (default: 300000 — 5 minutes) */
+  maxRetryDelayMs: number;
+}
+
+/** Shape accepted by MembraneConfig.retry — every field optional, including
+ *  inside the nested overloaded schedule. */
+export type RetryConfigInput = Partial<Omit<RetryConfig, 'overloaded'>> & {
+  overloaded?: Partial<OverloadedRetryConfig>;
+};
+
 // ============================================================================
 // Media Processing Config
 // ============================================================================
@@ -152,7 +188,7 @@ export interface MembraneConfig {
   formatter?: PrefillFormatter;
 
   /** Retry configuration */
-  retry?: Partial<RetryConfig>;
+  retry?: RetryConfigInput;
 
   /** Media processing configuration */
   media?: Partial<MediaConfig>;
@@ -176,6 +212,14 @@ export const DEFAULT_RETRY_CONFIG: RetryConfig = {
   retryDelayMs: 1000,
   backoffMultiplier: 2,
   maxRetryDelayMs: 30000,
+  // 7 attempts = 6 waits: 10s → 20s → 40s → 80s → 160s → 300s, ~10 minutes
+  // of patience in total — the scale capacity storms actually resolve on.
+  overloaded: {
+    maxRetries: 7,
+    retryDelayMs: 10_000,
+    backoffMultiplier: 2,
+    maxRetryDelayMs: 300_000,
+  },
 };
 
 export const DEFAULT_MEDIA_CONFIG: MediaConfig = {

package/src/types/errors.ts

@@ -239,6 +239,24 @@ export function unsupportedError(message: string, rawRequest?: unknown): Membran
 // Error Classification
 // ============================================================================
 
+/**
+ * Provider capacity exhaustion — Anthropic 529 overloaded_error, whichever
+ * path it arrived by (structured status from the provider handler, or the
+ * message-matched fallbacks in classifyError). Used only to CHOOSE the retry
+ * schedule among already-retryable errors, never to decide retryability.
+ * Matches the same deliberately narrow tokens as classifyError's fallback
+ * (status/`529`/exact `overloaded_error`) — a bare 'overloaded' in prose
+ * (e.g. "worker pool overloaded") must not put an unrelated error onto the
+ * ~10-minute schedule. The provider handlers' own bare-'overloaded' safety
+ * nets attach httpStatus 529, so those still land here via the status check.
+ */
+export function isOverloadedError(info: ErrorInfo): boolean {
+  if (!info.retryable) return false;
+  if (info.httpStatus === 529) return true;
+  const m = info.message.toLowerCase();
+  return m.includes('529') || m.includes('overloaded_error');
+}
+
 export function classifyError(error: unknown): ErrorInfo {
   if (error instanceof MembraneError) {
     return error.toErrorInfo();

package/src/types/index.ts

@@ -165,6 +165,7 @@ export {
   safetyError,
   unsupportedError,
   classifyError,
+  isOverloadedError,
 } from './errors.js';
 
 // Config

package/src/types/response.ts

@@ -15,7 +15,11 @@ export type StopReason =
   | 'stop_sequence'  // Hit stop sequence
   | 'tool_use'       // Stopped for tool use
   | 'refusal'        // Content refused by safety
-  | 'abort';         // Request was aborted
+  | 'abort'          // Request was aborted
+  | 'no_progress'    // Stall guard ended the turn (issue #39): consecutive
+                     // automatic resumptions re-sent context without advancing
+  | 'round_limit';   // Resumption round cap ended the turn: the turn kept
+                     // resuming (with progress) past maxResumptionRounds
 
 // ============================================================================
 // Usage Information

package/src/types/streaming.ts

@@ -231,6 +231,17 @@ export interface StreamOptions {
   /** Maximum tool execution depth (default: 10) */
   maxToolDepth?: number;
 
+  /**
+   * Cap on AUTOMATIC false-positive stop-sequence resumptions per turn —
+   * membrane's own re-streams, not the caller's work. Tool rounds are
+   * deliberately not counted: they are governed by maxToolDepth and caller
+   * policy. Distinct from maxToolDepth on purpose: raising the tool budget
+   * for deep chains must not also raise how often a turn may re-send its
+   * full context on membrane's own initiative (issue #39). Exceeding it
+   * ends the turn with stopReason 'round_limit'. Default: 24.
+   */
+  maxResumptionRounds?: number;
+
   /** Timeout for each tool execution */
   toolTimeoutMs?: number;
 

package/src/types/yielding-stream.ts

@@ -237,6 +237,19 @@ export interface YieldingStreamOptions {
    */
   maxToolDepth?: number;
 
+  /**
+   * Cap on AUTOMATIC false-positive stop-sequence resumptions per turn —
+   * membrane's own re-streams, not the caller's tool work. Tool rounds are
+   * deliberately NOT counted: this path's uncapped-by-default tool-loop
+   * contract stands (the caller budgets its own work via maxToolDepth).
+   * What this bounds is membrane's own failure surface — how many times a
+   * turn may re-send its full context on membrane's initiative; an
+   * unlimited resumption bound is how the 43-round Ash spin happened
+   * (issue #39). Exceeding it ends the turn with stopReason 'round_limit'.
+   * Default: 24. `-1` for unlimited, at your own risk.
+   */
+  maxResumptionRounds?: number;
+
   /**
    * Whether to emit 'tokens' events.
    * Set to false if you only care about tool calls and final response.