@sprqvntrs/llm 3.13.0

package/src/utils/errors.ts

@@ -0,0 +1,508 @@
+/**
+ * Enhanced error classes for LLM operations with rich debugging context
+ */
+
+export interface LlmErrorContext {
+  /**
+   * The client type that encountered the error
+   */
+  clientType: 'openai' | 'anthropic' | 'openrouter';
+
+  /**
+   * The model being used
+   */
+  model: string;
+
+  /**
+   * Time elapsed before error (in milliseconds)
+   */
+  elapsedMs: number;
+
+  /**
+   * Timeout configuration (in milliseconds)
+   */
+  timeoutMs?: number;
+
+  /**
+   * Operation that failed
+   */
+  operation: string;
+
+  /**
+   * Request correlation ID for tracking
+   */
+  requestId?: string;
+
+  /**
+   * Additional metadata
+   */
+  metadata?: {
+    promptSize?: number;
+    schemaComplexity?: string;
+    attempt?: number;
+    maxAttempts?: number;
+    [key: string]: any;
+  };
+}
+
+/**
+ * Base error class for all LLM-related errors with enhanced context
+ */
+export class LlmError extends Error {
+  public readonly context: LlmErrorContext;
+  public readonly originalError?: Error;
+  public readonly timestamp: string;
+
+  constructor(message: string, context: LlmErrorContext, originalError?: Error) {
+    super(message);
+    this.name = 'LlmError';
+    this.context = context;
+    this.originalError = originalError;
+    this.timestamp = new Date().toISOString();
+
+    // Maintain proper stack trace
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+
+    // Append original stack if available
+    if (originalError?.stack) {
+      this.stack = `${this.stack}\n\nCaused by: ${originalError.stack}`;
+    }
+  }
+
+  /**
+   * Get a formatted error message with full context
+   */
+  getDetailedMessage(): string {
+    const lines = [
+      `[${this.context.clientType.toUpperCase()}] ${this.message}`,
+      `Model: ${this.context.model}`,
+      `Operation: ${this.context.operation}`,
+      `Elapsed: ${this.context.elapsedMs}ms`,
+    ];
+
+    if (this.context.timeoutMs) {
+      lines.push(`Timeout: ${this.context.timeoutMs}ms`);
+      const percentage = ((this.context.elapsedMs / this.context.timeoutMs) * 100).toFixed(1);
+      lines.push(`Progress: ${percentage}% of timeout`);
+    }
+
+    if (this.context.requestId) {
+      lines.push(`Request ID: ${this.context.requestId}`);
+    }
+
+    if (this.context.metadata) {
+      if (this.context.metadata.attempt && this.context.metadata.maxAttempts) {
+        lines.push(`Attempt: ${this.context.metadata.attempt}/${this.context.metadata.maxAttempts}`);
+      }
+      if (this.context.metadata.promptSize) {
+        lines.push(`Prompt size: ${this.context.metadata.promptSize} chars`);
+      }
+    }
+
+    if (this.originalError) {
+      lines.push(`Original error: ${this.originalError.message}`);
+    }
+
+    return lines.join('\n  ');
+  }
+
+  /**
+   * Get a JSON representation of the error for logging
+   */
+  toJSON(): Record<string, any> {
+    return {
+      name: this.name,
+      message: this.message,
+      timestamp: this.timestamp,
+      context: this.context,
+      originalError: this.originalError
+        ? {
+            name: this.originalError.name,
+            message: this.originalError.message,
+            stack: this.originalError.stack,
+          }
+        : undefined,
+      stack: this.stack,
+    };
+  }
+}
+
+/**
+ * Error thrown when a request times out
+ */
+export class LlmTimeoutError extends LlmError {
+  constructor(context: LlmErrorContext, originalError?: Error) {
+    const message = `Request timed out after ${context.elapsedMs}ms (timeout: ${context.timeoutMs}ms)`;
+    super(message, context, originalError);
+    this.name = 'LlmTimeoutError';
+  }
+}
+
+/**
+ * Error thrown when response validation fails
+ */
+export class LlmValidationError extends LlmError {
+  constructor(context: LlmErrorContext, originalError?: Error) {
+    const message = 'Response validation failed';
+    super(message, context, originalError);
+    this.name = 'LlmValidationError';
+  }
+}
+
+/**
+ * Details extracted from a provider error response.
+ */
+export interface LlmApiErrorDetails {
+  /** Human-readable reason from the provider (e.g. "Key limit exceeded (monthly limit)") */
+  providerMessage?: string;
+  /** Numeric or string error code from the provider */
+  providerCode?: string | number;
+  /** Raw response body as received (string or object) */
+  body?: unknown;
+}
+
+/**
+ * Error thrown when the API returns an error
+ */
+export class LlmApiError extends LlmError {
+  public readonly statusCode?: number;
+  public readonly providerMessage?: string;
+  public readonly providerCode?: string | number;
+  public readonly body?: unknown;
+
+  constructor(
+    context: LlmErrorContext,
+    statusCode?: number,
+    originalError?: Error,
+    details?: LlmApiErrorDetails,
+  ) {
+    const base = statusCode ? `API error (status ${statusCode})` : 'API error';
+    const message =
+      details?.providerMessage ? `${base}: ${details.providerMessage}` : base;
+    super(message, context, originalError);
+    this.name = 'LlmApiError';
+    this.statusCode = statusCode;
+    this.providerMessage = details?.providerMessage;
+    this.providerCode = details?.providerCode;
+    this.body = details?.body;
+  }
+}
+
+/**
+ * Reads the `data` payload from an axios-style `error.response`, if present.
+ */
+function extractResponseData(response: unknown): unknown {
+  if (response === null || typeof response !== 'object') {
+    return undefined;
+  }
+  return (response as Record<string, unknown>)['data'];
+}
+
+/**
+ * Extracts provider-specific error details from an unknown SDK error object.
+ *
+ * Priority order for providerMessage:
+ *  1. error.error?.message         — OpenRouter typed subclass / OpenAI-ish
+ *  2. parsed error.body            — OpenRouter base class (body is a JSON string)
+ *  3. error.body?.error?.message   — body already an object
+ *  4. error.response?.data?.error?.message — axios-style
+ *
+ * Returns {} for non-object / null inputs.
+ */
+export function extractProviderError(error: unknown): LlmApiErrorDetails {
+  if (error === null || typeof error !== 'object') {
+    return {};
+  }
+
+  const err = error as Record<string, unknown>;
+
+  // --- providerMessage resolution (priority order) ---
+
+  // 1. error.error?.message (OpenRouter typed subclass)
+  const errorField = err['error'];
+  if (
+    errorField !== null &&
+    typeof errorField === 'object' &&
+    typeof (errorField as Record<string, unknown>)['message'] === 'string'
+  ) {
+    const code = (errorField as Record<string, unknown>)['code'];
+    return {
+      providerMessage: (errorField as Record<string, unknown>)['message'] as string,
+      providerCode: typeof code === 'string' || typeof code === 'number' ? code : undefined,
+      body: err['body'] ?? extractResponseData(err['response']),
+    };
+  }
+
+  // 2. Parse error.body if it is a JSON string
+  const rawBody = err['body'];
+  if (typeof rawBody === 'string') {
+    try {
+      const parsed = JSON.parse(rawBody) as unknown;
+      if (
+        parsed !== null &&
+        typeof parsed === 'object'
+      ) {
+        const parsedObj = parsed as Record<string, unknown>;
+        const parsedError = parsedObj['error'];
+        if (
+          parsedError !== null &&
+          typeof parsedError === 'object' &&
+          typeof (parsedError as Record<string, unknown>)['message'] === 'string'
+        ) {
+          const code = (parsedError as Record<string, unknown>)['code'];
+          return {
+            providerMessage: (parsedError as Record<string, unknown>)['message'] as string,
+            providerCode: typeof code === 'string' || typeof code === 'number' ? code : undefined,
+            body: rawBody,
+          };
+        }
+      }
+    } catch {
+      // JSON.parse failed — move on
+    }
+  }
+
+  // 3. error.body?.error?.message (body already an object)
+  if (
+    rawBody !== null &&
+    typeof rawBody === 'object'
+  ) {
+    const bodyObj = rawBody as Record<string, unknown>;
+    const bodyError = bodyObj['error'];
+    if (
+      bodyError !== null &&
+      typeof bodyError === 'object' &&
+      typeof (bodyError as Record<string, unknown>)['message'] === 'string'
+    ) {
+      const code = (bodyError as Record<string, unknown>)['code'];
+      return {
+        providerMessage: (bodyError as Record<string, unknown>)['message'] as string,
+        providerCode: typeof code === 'string' || typeof code === 'number' ? code : undefined,
+        body: rawBody,
+      };
+    }
+  }
+
+  // 4. error.response?.data?.error?.message (axios-style)
+  const response = err['response'];
+  if (response !== null && typeof response === 'object') {
+    const data = (response as Record<string, unknown>)['data'];
+    if (data !== null && typeof data === 'object') {
+      const dataError = (data as Record<string, unknown>)['error'];
+      if (
+        dataError !== null &&
+        typeof dataError === 'object' &&
+        typeof (dataError as Record<string, unknown>)['message'] === 'string'
+      ) {
+        const code = (dataError as Record<string, unknown>)['code'];
+        return {
+          providerMessage: (dataError as Record<string, unknown>)['message'] as string,
+          providerCode: typeof code === 'string' || typeof code === 'number' ? code : undefined,
+          body: data,
+        };
+      }
+    }
+  }
+
+  return {};
+}
+
+/**
+ * Error thrown when model output is truncated due to token limits
+ */
+export class LlmOutputTruncatedError extends LlmError {
+  public readonly contentLength: number;
+
+  constructor(context: LlmErrorContext, contentLength: number) {
+    const message =
+      `Model output was truncated (finish_reason: length). The ${contentLength}-char response exceeded the model's ` +
+      'maximum output token limit. Consider reducing input size or using a model with higher output limits.';
+    super(message, context);
+    this.name = 'LlmOutputTruncatedError';
+    this.contentLength = contentLength;
+  }
+}
+
+/**
+ * Error thrown when model returns invalid JSON.
+ *
+ * Whether to retry depends on the likely cause:
+ * - If `finish_reason` is `'stop'`, the provider claims the response completed
+ *   cleanly, so the JSON is complete-but-malformed — a model/prompt problem that
+ *   retrying will not fix.
+ * - If `finish_reason` is missing, `'unknown'`, or any non-`'stop'` value, the
+ *   response may have been truncated mid-stream (network cut, provider hiccup).
+ *   In that case, an empty/whitespace-only body or an "Unexpected end of JSON input"
+ *   parse error is a strong signal of transient truncation worth retrying.
+ *
+ * Use `isLikelyTruncation` to distinguish the two cases.
+ */
+export class LlmJsonParseError extends LlmError {
+  public readonly rawContent: string;
+  public readonly parseError: SyntaxError;
+
+  constructor(context: LlmErrorContext, rawContent: string, parseError: SyntaxError) {
+    super(
+      `Model returned invalid JSON (${rawContent.length} chars, ` +
+        `finish_reason: ${context.metadata?.finishReason ?? 'unknown'}): ${parseError.message}`,
+      context,
+    );
+    this.name = 'LlmJsonParseError';
+    this.rawContent = rawContent;
+    this.parseError = parseError;
+  }
+
+  /**
+   * Returns `true` when the parse failure looks like transient truncation rather
+   * than a genuinely malformed model response.
+   *
+   * Heuristic:
+   * - If `finish_reason === 'stop'`, the provider claims the response completed
+   *   normally. Retrying consistently malformed output wastes tokens and is
+   *   unlikely to help, so this returns `false`.
+   * - Otherwise (finish_reason missing, `'unknown'`, or any other non-`'stop'`
+   *   value), a truncated/empty response is transient (network cut, provider
+   *   hiccup) and worth one retry. Returns `true` if EITHER:
+   *   - the parse error message includes `'Unexpected end of JSON input'`
+   *     (abrupt-end failure), OR
+   *   - `rawContent.trim()` is empty (empty or whitespace-only response).
+   */
+  get isLikelyTruncation(): boolean {
+    if (this.context.metadata?.finishReason === 'stop') {
+      return false;
+    }
+
+    const isAbruptEnd = this.parseError.message.includes('Unexpected end of JSON input');
+    const isEmptyContent = this.rawContent.trim().length === 0;
+    return isAbruptEnd || isEmptyContent;
+  }
+}
+
+/**
+ * Error thrown when configuration is invalid
+ */
+export class LlmConfigurationError extends LlmError {
+  constructor(context: LlmErrorContext, originalError?: Error) {
+    const message = 'Invalid client configuration';
+    super(message, context, originalError);
+    this.name = 'LlmConfigurationError';
+  }
+}
+
+/**
+ * Helper function to generate request IDs
+ */
+export function generateRequestId(): string {
+  return `${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+}
+
+/**
+ * Helper function to determine if an error is a timeout error
+ */
+export function isTimeoutError(error: unknown): boolean {
+  if (error instanceof LlmTimeoutError) {
+    return true;
+  }
+
+  if (error instanceof Error) {
+    const message = error.message.toLowerCase();
+    const name = error.name?.toLowerCase() || '';
+    return (
+      message.includes('timeout') ||
+      message.includes('timed out') ||
+      name.includes('timeout') ||
+      name === 'apiconnectiontimeouterror'
+    );
+  }
+
+  return false;
+}
+
+/**
+ * Helper function to wrap SDK errors with enhanced context.
+ * Extracts additional information from SDK error objects (status codes, error types,
+ * request IDs) and creates the appropriate LlmError subclass.
+ */
+export function wrapSdkError(
+  error: unknown,
+  context: LlmErrorContext,
+): LlmError {
+  // If already wrapped, return as-is
+  if (error instanceof LlmError) {
+    return error;
+  }
+
+  const originalError = error instanceof Error ? error : new Error(String(error));
+
+  // Extract additional context from SDK errors (OpenAI, Anthropic SDKs)
+  const errorCode = (error as any)?.code as string | undefined;
+  const errorType = (error as any)?.type || (error as any)?.error?.type;
+  const providerRequestId =
+    (error as any)?.headers?.['x-request-id'] ||
+    (error as any)?.headers?.get?.('x-request-id');
+
+  // Enrich metadata with SDK error details
+  if (errorCode || errorType || providerRequestId) {
+    context.metadata = {
+      ...context.metadata,
+      ...(errorCode && { errorCode }),
+      ...(errorType && { errorType }),
+      ...(providerRequestId && { providerRequestId }),
+    };
+  }
+
+  // Detect timeout errors
+  if (isTimeoutError(error)) {
+    return new LlmTimeoutError(context, originalError);
+  }
+
+  // Detect API errors (check for status codes)
+  const statusCode = (error as any)?.status || (error as any)?.statusCode;
+  if (statusCode) {
+    return new LlmApiError(context, statusCode, originalError, extractProviderError(error));
+  }
+
+  // Detect validation errors
+  if (originalError.name === 'ZodError' || originalError.message.includes('validation')) {
+    return new LlmValidationError(context, originalError);
+  }
+
+  // Default to generic LlmError
+  return new LlmError(originalError.message, context, originalError);
+}
+
+/**
+ * Determines whether an error is retryable (transient) or permanent.
+ *
+ * Retryable: timeouts, 5xx server errors, 429 rate limits, generic/unknown errors,
+ * and JSON parse errors that look like transient truncation (finish_reason missing/
+ * unknown and content is empty or fails with "Unexpected end of JSON input").
+ *
+ * Non-retryable: validation errors, config errors, output truncation, 4xx client
+ * errors, and JSON parse errors where finish_reason is 'stop' (complete-but-malformed
+ * output is a model/prompt problem that retrying will not fix).
+ */
+export function isRetryableError(error: unknown): boolean {
+  // Non-retryable error types — these won't resolve on retry
+  if (error instanceof LlmConfigurationError) return false;
+  if (error instanceof LlmValidationError) return false;
+  if (error instanceof LlmOutputTruncatedError) return false;
+  if (error instanceof LlmJsonParseError) return error.isLikelyTruncation;
+
+  // API errors: retry on 5xx and 429, not on other 4xx
+  if (error instanceof LlmApiError) {
+    if (!error.statusCode) return true;
+    if (error.statusCode === 429) return true;
+    if (error.statusCode >= 500) return true;
+    return false;
+  }
+
+  // Timeouts are retryable
+  if (error instanceof LlmTimeoutError) return true;
+
+  // Generic LlmError (e.g. transient "An error occurred while processing the request")
+  // and unknown errors — assume retryable
+  return true;
+}

package/src/utils/normalize-null-strings.ts

@@ -0,0 +1,103 @@
+import { z } from 'zod/v4';
+
+/**
+ * Recursively walks parsed JSON alongside a Zod v4 schema and replaces
+ * the literal string `"null"` with actual `null` wherever the schema
+ * declares `.nullable()`.
+ *
+ * Gemini models return the literal string `"null"` instead of JSON `null`
+ * for nullable fields in structured output. This function normalises
+ * the parsed data **in-place** before Zod validation so that `.nullable()`
+ * fields validate correctly.
+ *
+ * Because we access Zod v4 internals (`_zod.def`), `any` casts are
+ * unavoidable for the schema introspection paths.
+ */
+export function normalizeNullStrings(data: unknown, schema: z.ZodType): unknown {
+  const def = (schema as any)._zod.def;
+  const type: string = def.type;
+
+  switch (type) {
+    case 'nullable': {
+      if (data === 'null') {
+        return null;
+      }
+      return normalizeNullStrings(data, def.innerType);
+    }
+
+    case 'optional':
+    case 'default': {
+      return normalizeNullStrings(data, def.innerType);
+    }
+
+    case 'object': {
+      if (data === null || typeof data !== 'object' || Array.isArray(data)) {
+        return data;
+      }
+      const shape: Record<string, z.ZodType> = def.shape;
+      const record = data as Record<string, unknown>;
+      for (const key of Object.keys(shape)) {
+        if (key in record) {
+          record[key] = normalizeNullStrings(record[key], shape[key]!);
+        }
+      }
+      return data;
+    }
+
+    case 'array': {
+      if (!Array.isArray(data)) {
+        return data;
+      }
+      const element: z.ZodType = def.element;
+      for (let i = 0; i < data.length; i++) {
+        data[i] = normalizeNullStrings(data[i], element);
+      }
+      return data;
+    }
+
+    case 'union': {
+      const options: readonly z.ZodType[] = def.options;
+      // Find a nullable (or nullable-containing) option and recurse with it.
+      for (const option of options) {
+        const optDef = (option as any)._zod.def;
+        if (optDef.type === 'nullable') {
+          return normalizeNullStrings(data, option);
+        }
+      }
+      // No nullable option found — try each option for structural recursion
+      for (const option of options) {
+        const optDef = (option as any)._zod.def;
+        if (optDef.type === 'object' || optDef.type === 'array') {
+          return normalizeNullStrings(data, option);
+        }
+      }
+      return data;
+    }
+
+    case 'tuple': {
+      if (!Array.isArray(data)) {
+        return data;
+      }
+      const items: readonly z.ZodType[] = def.items;
+      for (let i = 0; i < items.length && i < data.length; i++) {
+        data[i] = normalizeNullStrings(data[i], items[i]!);
+      }
+      return data;
+    }
+
+    case 'record': {
+      if (data === null || typeof data !== 'object' || Array.isArray(data)) {
+        return data;
+      }
+      const valueType: z.ZodType = def.valueType;
+      const record = data as Record<string, unknown>;
+      for (const key of Object.keys(record)) {
+        record[key] = normalizeNullStrings(record[key], valueType);
+      }
+      return data;
+    }
+
+    default:
+      return data;
+  }
+}

package/src/utils/resolve-refs.ts

@@ -0,0 +1,91 @@
+// Resolves JSON Schema $ref/$defs by inlining all references and converts
+// anyOf nullable patterns ({ anyOf: [T, { type: "null" }] }) for Gemini compatibility.
+
+const MAX_INLINE_DEPTH = 50;
+
+export function resolveRefs(
+  schema: Record<string, unknown>,
+): Record<string, unknown> {
+  const defs = ((schema.$defs ?? schema.definitions ?? {}) as Record<
+    string,
+    unknown
+  >);
+
+  function inline(node: unknown, depth: number): unknown {
+    if (depth > MAX_INLINE_DEPTH) {
+      throw new Error(
+        `resolveRefs: exceeded max inline depth of ${MAX_INLINE_DEPTH} — possible circular $ref`,
+      );
+    }
+
+    if (Array.isArray(node)) {
+      return node.map((item) => inline(item, depth + 1));
+    }
+
+    if (node === null || typeof node !== "object") {
+      return node;
+    }
+
+    const obj = node as Record<string, unknown>;
+
+    // Resolve $ref
+    if (typeof obj.$ref === "string") {
+      const refPath = obj.$ref;
+      const match = refPath.match(/^#\/(\$defs|definitions)\/(.+)$/);
+      if (!match) {
+        return obj;
+      }
+      const defName = match[2]!;
+      const definition = defs[defName];
+      if (definition === undefined) {
+        throw new Error(`resolveRefs: missing definition for "${defName}"`);
+      }
+      return inline(structuredClone(definition), depth + 1);
+    }
+
+    // Convert anyOf nullable pattern: { anyOf: [T, { type: "null" }] }
+    if (Array.isArray(obj.anyOf) && obj.anyOf.length === 2) {
+      const [first, second] = obj.anyOf as [
+        Record<string, unknown>,
+        Record<string, unknown>,
+      ];
+
+      let realType: Record<string, unknown> | null = null;
+
+      if (
+        second !== null &&
+        typeof second === "object" &&
+        second.type === "null"
+      ) {
+        realType = first;
+      } else if (
+        first !== null &&
+        typeof first === "object" &&
+        first.type === "null"
+      ) {
+        realType = second;
+      }
+
+      if (realType !== null) {
+        const { anyOf: _, ...rest } = obj;
+        const resolved = inline(realType, depth + 1) as Record<
+          string,
+          unknown
+        >;
+        return { ...rest, ...resolved, nullable: true };
+      }
+    }
+
+    // Recurse into all properties
+    const result: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(obj)) {
+      result[key] = inline(value, depth + 1);
+    }
+    return result;
+  }
+
+  const resolved = inline(schema, 0) as Record<string, unknown>;
+  delete resolved.$defs;
+  delete resolved.definitions;
+  return resolved;
+}