@falai/agent 2.6.1 → 3.0.0

package/src/providers/errorClassification.ts

@@ -1,172 +0,0 @@
-/**
- * Shared provider error utilities: classification of SDK/HTTP errors onto
- * normalized ProviderErrorCode values, backup-model eligibility, and
- * wrapping of terminal failures in ProviderError.
- *
- * The classification is derived once and reused for both backup-model
- * decisions and final error wrapping, so the two can never drift apart.
- */
-
-import { ProviderError, type ProviderErrorCode } from "../types/errors";
-
-/**
- * Shape of errors with status/code properties thrown by provider SDKs
- */
-export interface ErrorWithStatus {
-  status?: number;
-  code?: string;
-  message?: string;
-  type?: string;
-}
-
-/**
- * Type guard to check if error is ErrorWithStatus
- */
-export function isErrorWithStatus(error: unknown): error is ErrorWithStatus {
-  return (
-    typeof error === "object" &&
-    error !== null &&
-    ("status" in error || "code" in error || "message" in error)
-  );
-}
-
-/**
- * Safely extract error message
- */
-export function getErrorMessage(error: unknown): string {
-  if (error instanceof Error) {
-    return error.message;
-  }
-  if (isErrorWithStatus(error) && error.message) {
-    return error.message;
-  }
-  return String(error);
-}
-
-/**
- * Provider-specific signals treated as "overloaded/unavailable", in
- * addition to the shared defaults (HTTP 500/503 and the common message
- * substrings below).
- */
-export interface ErrorClassificationOptions {
-  /** Extra HTTP statuses treated as overloaded (e.g. Anthropic's 529) */
-  overloadedStatuses?: readonly number[];
-  /** Error `code` values treated as overloaded/unavailable (e.g. "model_not_found") */
-  overloadedCodes?: readonly string[];
-  /** Error `type` values treated as overloaded (e.g. Anthropic's "overloaded_error") */
-  overloadedTypes?: readonly string[];
-  /** Extra message substrings treated as overloaded (e.g. OpenRouter's "capacity") */
-  overloadedMessages?: readonly string[];
-}
-
-/**
- * Message substrings every provider historically treated as
- * overloaded/unavailable for backup-model purposes.
- */
-const DEFAULT_OVERLOADED_MESSAGES: readonly string[] = [
-  "overloaded",
-  "unavailable",
-  "internal error",
-  "Internal error",
-];
-
-/**
- * Classify an unknown error into a normalized ProviderErrorCode.
- *
- * Overload/availability checks run first so that backup-model decisions
- * (rate_limited/overloaded) match the historical shouldUseBackupModel
- * predicate exactly.
- */
-export function classifyProviderError(
-  error: unknown,
-  options: ErrorClassificationOptions = {}
-): ProviderErrorCode {
-  if (!isErrorWithStatus(error)) {
-    return "unknown";
-  }
-
-  const { status, code, type } = error;
-  const message = getErrorMessage(error);
-
-  // Server errors / overload
-  if (status === 500 || status === 503) {
-    return "overloaded";
-  }
-
-  // Rate limiting
-  if (status === 429) {
-    return "rate_limited";
-  }
-
-  // Provider-specific overload/unavailability signals
-  if (status !== undefined && options.overloadedStatuses?.includes(status)) {
-    return "overloaded";
-  }
-  if (code !== undefined && options.overloadedCodes?.includes(code)) {
-    return "overloaded";
-  }
-  if (type !== undefined && options.overloadedTypes?.includes(type)) {
-    return "overloaded";
-  }
-  const overloadedMessages = options.overloadedMessages
-    ? [...DEFAULT_OVERLOADED_MESSAGES, ...options.overloadedMessages]
-    : DEFAULT_OVERLOADED_MESSAGES;
-  if (overloadedMessages.some((pattern) => message.includes(pattern))) {
-    return "overloaded";
-  }
-
-  // Non-retriable classifications (never triggered backup models)
-  if (status === 401 || status === 403) {
-    return "auth";
-  }
-  if (status === 400 || status === 404 || status === 422) {
-    return "invalid_request";
-  }
-  if (
-    status === 408 ||
-    message.includes("timed out") ||
-    message.includes("timeout")
-  ) {
-    return "timeout";
-  }
-  if (
-    message.includes("fetch failed") ||
-    message.includes("ECONNREFUSED") ||
-    message.includes("ECONNRESET") ||
-    message.includes("ETIMEDOUT") ||
-    message.includes("network")
-  ) {
-    return "network";
-  }
-
-  return "unknown";
-}
-
-/**
- * Whether an error code qualifies for trying backup models.
- * Mirrors the historical shouldUseBackupModel predicate.
- */
-export function isBackupEligible(code: ProviderErrorCode): boolean {
-  return code === "rate_limited" || code === "overloaded";
-}
-
-/**
- * Wrap a terminal failure (after retries/backup exhaustion) in a
- * normalized ProviderError, preserving the original error as `cause`.
- * Already-wrapped errors pass through untouched.
- */
-export function toProviderError(
-  error: unknown,
-  provider: string,
-  options?: ErrorClassificationOptions
-): ProviderError {
-  if (error instanceof ProviderError) {
-    return error;
-  }
-  return new ProviderError(
-    classifyProviderError(error, options),
-    provider,
-    getErrorMessage(error),
-    error
-  );
-}

package/src/utils/retry.ts

@@ -1,274 +0,0 @@
-/**
- * Retry utility with exponential backoff
- */
-import {logger} from './logger'
-
-export interface RetryOptions<T> {
-  operation: () => Promise<T>;
-  maxRetries: number;
-  delay: (attempt: number) => number;
-  onRetry?: (attempt: number, error: unknown) => void;
-  onFailure?: (error: unknown) => boolean;
-}
-
-/** Provider timeout (ms) + retry count, after defaults are applied. */
-export interface RetryConfig {
-  timeout: number;
-  retries: number;
-}
-
-const DEFAULT_RETRY_CONFIG: RetryConfig = {
-  timeout: 60000,
-  retries: 3,
-};
-
-/**
- * Normalize a provider's optional retry config against the defaults. `timeout`
- * uses `||` (a 0ms timeout is degenerate — it aborts every call immediately — so
- * fall back to the default), while `retries` uses `??` so an explicit
- * `retries: 0` (disable retries) is honored rather than treated as unset. Single
- * definition so this distinction can't drift between providers.
- */
-export function resolveRetryConfig(input?: {
-  timeout?: number;
-  retries?: number;
-}): RetryConfig {
-  return {
-    timeout: input?.timeout || DEFAULT_RETRY_CONFIG.timeout,
-    retries: input?.retries ?? DEFAULT_RETRY_CONFIG.retries,
-  };
-}
-
-export async function retry<T>(options: RetryOptions<T>): Promise<T> {
-  const { operation, maxRetries, delay, onRetry, onFailure } = options;
-
-  let lastError: unknown;
-
-  for (let attempt = 0; attempt <= maxRetries; attempt++) {
-    try {
-      return await operation();
-    } catch (error: unknown) {
-      lastError = error;
-
-      if (attempt === maxRetries) {
-        const shouldRethrow = onFailure ? onFailure(lastError) : true;
-        if (shouldRethrow) {
-          throw lastError;
-        }
-        break;
-      }
-
-      if (onRetry) {
-        onRetry(attempt, lastError);
-      }
-
-      const delayMs = delay(attempt);
-      await new Promise((resolve) => setTimeout(resolve, delayMs));
-    }
-  }
-
-  // eslint-disable-next-line @typescript-eslint/only-throw-error
-  throw lastError ?? new Error("Operation failed");
-}
-
-/** Capped exponential backoff (1s, 2s, 4s, … max 5s) shared by the retry helpers. */
-const defaultBackoff = (attempt: number): number =>
-  Math.min(1000 * Math.pow(2, attempt), 5000);
-
-/**
- * Combine abort signals into one that aborts as soon as any input aborts.
- * `undefined` inputs are skipped, so a caller can pass an optional caller-signal
- * alongside a required per-attempt one. Returns the sole signal when only one is
- * present (no wrapper), or `undefined` when none are.
- *
- * Prefers the platform `AbortSignal.any`, which cleans up its listeners via weak
- * refs — so merging onto a long-lived caller signal that's reused across many
- * calls can't accumulate listeners. Falls back to a manual controller on older
- * runtimes (< Node 20.3); there the listeners live until a source aborts or is
- * garbage-collected, which is fine for the usual per-request signal.
- */
-export function combineAbortSignals(
-  ...signals: Array<AbortSignal | undefined>
-): AbortSignal | undefined {
-  const present = signals.filter((s): s is AbortSignal => s != null);
-  if (present.length <= 1) return present[0];
-  if (typeof AbortSignal.any === "function") return AbortSignal.any(present);
-
-  const controller = new AbortController();
-  for (const signal of present) {
-    if (signal.aborted) {
-      controller.abort(signal.reason);
-      break;
-    }
-    signal.addEventListener("abort", () => controller.abort(signal.reason), {
-      once: true,
-    });
-  }
-  return controller.signal;
-}
-
-export const withTimeoutAndRetry = async <T>(
-  operation: (signal: AbortSignal) => Promise<T>,
-  timeoutMs: number = 60000,
-  maxRetries: number = 3,
-  operationName: string = "AI operation"
-): Promise<T> => {
-  const createTimeoutOperation = () => async (): Promise<T> => {
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => {
-      controller.abort();
-    }, timeoutMs);
-
-    try {
-      // Hand the operation the timeout signal so the in-flight upstream call is
-      // actually cancelled when the deadline fires — otherwise the abandoned
-      // attempt keeps running while the retry stacks a second concurrent call.
-      const result = await Promise.race([
-        operation(controller.signal),
-        new Promise<never>((_, reject) => {
-          controller.signal.addEventListener("abort", () => {
-            reject(new Error(`Operation timed out after ${timeoutMs}ms`));
-          });
-        }),
-      ]);
-
-      clearTimeout(timeoutId);
-      return result;
-    } catch (error: unknown) {
-      clearTimeout(timeoutId);
-      throw error;
-    }
-  };
-
-  return retry<T>({
-    operation: createTimeoutOperation(),
-    maxRetries,
-    delay: defaultBackoff,
-    onRetry: (attempt: number, error: unknown) => {
-      const message = error instanceof Error ? error.message : String(error);
-      logger.error(
-        `[${operationName}] Failed attempt ${attempt + 1}:`,
-        message
-      );
-      const delay = defaultBackoff(attempt);
-      logger.debug(`[${operationName}] Retrying in ${delay}ms...`);
-      logger.debug(
-        `[${operationName}] Attempt ${attempt + 2}/${maxRetries + 1}`
-      );
-    },
-    onFailure: (_error: unknown) => {
-      logger.error(`[${operationName}] All ${maxRetries + 1} attempts failed`);
-      return true;
-    },
-  });
-};
-
-export interface StreamRetryOptions {
-  /** Maximum number of retries after the first attempt. Defaults to 3. */
-  maxRetries?: number;
-  /** Backoff before the next attempt, in ms. Defaults to capped exponential. */
-  delay?: (attempt: number) => number;
-  /** Label used in retry logs. */
-  operationName?: string;
-  /**
-   * Max ms to wait for the *first* chunk (time-to-first-token) before treating
-   * the attempt as failed. Guards a provider that opens a stream and then
-   * stalls. Only the first chunk is bounded — later chunks are unbounded so a
-   * long but healthy stream is never cut off. `0`/omitted disables the deadline.
-   */
-  firstChunkTimeoutMs?: number;
-}
-
-/** Reject if `next` hasn't settled within `timeoutMs`; always clears its timer. */
-function raceFirstChunk<T>(
-  next: Promise<IteratorResult<T>>,
-  timeoutMs: number,
-  operationName: string
-): Promise<IteratorResult<T>> {
-  let timer: ReturnType<typeof setTimeout> | undefined;
-  const timeout = new Promise<never>((_, reject) => {
-    timer = setTimeout(
-      () =>
-        reject(
-          new Error(
-            `[${operationName}] Stream timed out: no first chunk within ${timeoutMs}ms`
-          )
-        ),
-      timeoutMs
-    );
-  });
-  return Promise.race([next, timeout]).finally(() => clearTimeout(timer));
-}
-
-/**
- * Streaming analog of {@link withTimeoutAndRetry}. Re-runs an async-generator
- * factory as long as it fails *before yielding its first chunk* — an empty
- * completion that throws "No response", an error while establishing the stream,
- * or (with `firstChunkTimeoutMs`) a stall before the first token. Once any chunk
- * has been yielded the stream is committed and further errors propagate, so a
- * retry can never double-emit deltas the consumer has already received.
- *
- * This mirrors the non-streaming path, where the provider throws on an empty
- * completion inside `withTimeoutAndRetry` and is retried on the same model
- * before the caller falls through to backup models.
- */
-export async function* withStreamRetry<T>(
-  factory: (signal: AbortSignal) => AsyncGenerator<T>,
-  options: StreamRetryOptions = {}
-): AsyncGenerator<T> {
-  const {
-    maxRetries = 3,
-    delay = defaultBackoff,
-    operationName = "AI stream",
-    firstChunkTimeoutMs,
-  } = options;
-
-  for (let attempt = 0; attempt <= maxRetries; attempt++) {
-    // One controller per attempt: aborting it on abandon cancels the upstream
-    // SDK call so a retry can't stack a second concurrent stream.
-    const controller = new AbortController();
-    const iterator = factory(controller.signal);
-    let yielded = false;
-    let completed = false;
-    try {
-      // Drive the iterator by hand so the first chunk can be raced against a
-      // deadline; for-await would give no hook for that.
-      for (;;) {
-        const result =
-          !yielded && firstChunkTimeoutMs
-            ? await raceFirstChunk(iterator.next(), firstChunkTimeoutMs, operationName)
-            : await iterator.next();
-        if (result.done) {
-          completed = true;
-          return;
-        }
-        yielded = true;
-        yield result.value;
-      }
-    } catch (error: unknown) {
-      // Can't retry once deltas are out, and don't retry past the budget.
-      if (yielded || attempt === maxRetries) {
-        throw error;
-      }
-      const message = error instanceof Error ? error.message : String(error);
-      logger.error(`[${operationName}] Failed attempt ${attempt + 1}:`, message);
-      const delayMs = delay(attempt);
-      logger.debug(
-        `[${operationName}] Retrying in ${delayMs}ms... (attempt ${attempt + 2}/${maxRetries + 1})`
-      );
-      await new Promise((resolve) => setTimeout(resolve, delayMs));
-    } finally {
-      // Abandoning an attempt (first-chunk timeout, pre-yield error before a
-      // retry, or a consumer that breaks early): abort the upstream SDK call
-      // first so it's actually torn down — not left running while we retry —
-      // then dispose the iterator. Aborting also unblocks a stalled
-      // iterator.next() so return() can run the generator's cleanup. Both are
-      // fire-and-forget: a wedged generator's return() may never settle, so we
-      // must not await it.
-      if (!completed) {
-        controller.abort();
-        void iterator.return?.(undefined)?.catch(() => undefined);
-      }
-    }
-  }
-}