repoburg 1.0.69 → 1.1.0

package/backend/packages/gemini-core/src/utils/errors.ts

@@ -0,0 +1,112 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+interface GaxiosError {
+  response?: {
+    data?: unknown;
+  };
+}
+
+export function isNodeError(error: unknown): error is NodeJS.ErrnoException {
+  return error instanceof Error && 'code' in error;
+}
+
+export function getErrorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  try {
+    return String(error);
+  } catch {
+    return 'Failed to get error details';
+  }
+}
+
+export class FatalError extends Error {
+  constructor(
+    message: string,
+    readonly exitCode: number,
+  ) {
+    super(message);
+  }
+}
+
+export class FatalAuthenticationError extends FatalError {
+  constructor(message: string) {
+    super(message, 41);
+  }
+}
+export class FatalInputError extends FatalError {
+  constructor(message: string) {
+    super(message, 42);
+  }
+}
+export class FatalSandboxError extends FatalError {
+  constructor(message: string) {
+    super(message, 44);
+  }
+}
+export class FatalConfigError extends FatalError {
+  constructor(message: string) {
+    super(message, 52);
+  }
+}
+export class FatalTurnLimitedError extends FatalError {
+  constructor(message: string) {
+    super(message, 53);
+  }
+}
+export class FatalToolExecutionError extends FatalError {
+  constructor(message: string) {
+    super(message, 54);
+  }
+}
+export class FatalCancellationError extends FatalError {
+  constructor(message: string) {
+    super(message, 130); // Standard exit code for SIGINT
+  }
+}
+
+export class ForbiddenError extends Error {}
+export class UnauthorizedError extends Error {}
+export class BadRequestError extends Error {}
+
+interface ResponseData {
+  error?: {
+    code?: number;
+    message?: string;
+  };
+}
+
+export function toFriendlyError(error: unknown): unknown {
+  if (error && typeof error === 'object' && 'response' in error) {
+    const gaxiosError = error as GaxiosError;
+    const data = parseResponseData(gaxiosError);
+    if (data.error && data.error.message && data.error.code) {
+      switch (data.error.code) {
+        case 400:
+          return new BadRequestError(data.error.message);
+        case 401:
+          return new UnauthorizedError(data.error.message);
+        case 403:
+          // It's import to pass the message here since it might
+          // explain the cause like "the cloud project you're
+          // using doesn't have code assist enabled".
+          return new ForbiddenError(data.error.message);
+        default:
+      }
+    }
+  }
+  return error;
+}
+
+function parseResponseData(error: GaxiosError): ResponseData {
+  // Inexplicably, Gaxios sometimes doesn't JSONify the response data.
+  if (typeof error.response?.data === 'string') {
+    return JSON.parse(error.response?.data) as ResponseData;
+  }
+  return error.response?.data as ResponseData;
+}

package/backend/packages/gemini-core/src/utils/partUtils.ts

@@ -0,0 +1,169 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {
+  GenerateContentResponse,
+  PartListUnion,
+  Part,
+  PartUnion,
+} from '@google/genai';
+
+/**
+ * Converts a PartListUnion into a string.
+ * If verbose is true, includes summary representations of non-text parts.
+ */
+export function partToString(
+  value: PartListUnion,
+  options?: { verbose?: boolean },
+): string {
+  if (!value) {
+    return '';
+  }
+  if (typeof value === 'string') {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map((part) => partToString(part, options)).join('');
+  }
+
+  // Cast to Part, assuming it might contain project-specific fields
+  const part = value as Part & {
+    videoMetadata?: unknown;
+    thought?: string;
+    codeExecutionResult?: unknown;
+    executableCode?: unknown;
+  };
+
+  if (options?.verbose) {
+    if (part.videoMetadata !== undefined) {
+      return `[Video Metadata]`;
+    }
+    if (part.thought !== undefined) {
+      return `[Thought: ${part.thought}]`;
+    }
+    if (part.codeExecutionResult !== undefined) {
+      return `[Code Execution Result]`;
+    }
+    if (part.executableCode !== undefined) {
+      return `[Executable Code]`;
+    }
+
+    // Standard Part fields
+    if (part.fileData !== undefined) {
+      return `[File Data]`;
+    }
+    if (part.functionCall !== undefined) {
+      return `[Function Call: ${part.functionCall.name}]`;
+    }
+    if (part.functionResponse !== undefined) {
+      return `[Function Response: ${part.functionResponse.name}]`;
+    }
+    if (part.inlineData !== undefined) {
+      return `<${part.inlineData.mimeType}>`;
+    }
+  }
+
+  return part.text ?? '';
+}
+
+export function getResponseText(
+  response: GenerateContentResponse,
+): string | null {
+  if (response.candidates && response.candidates.length > 0) {
+    const candidate = response.candidates[0];
+
+    if (
+      candidate.content &&
+      candidate.content.parts &&
+      candidate.content.parts.length > 0
+    ) {
+      return candidate.content.parts
+        .filter((part) => part.text)
+        .map((part) => part.text)
+        .join('');
+    }
+  }
+  return null;
+}
+
+/**
+ * Asynchronously maps over a PartListUnion, applying a transformation function
+ * to the text content of each text-based part.
+ *
+ * @param parts The PartListUnion to process.
+ * @param transform A function that takes a string of text and returns a Promise
+ *   resolving to an array of new PartUnions.
+ * @returns A Promise that resolves to a new array of PartUnions with the
+ *   transformations applied.
+ */
+export async function flatMapTextParts(
+  parts: PartListUnion,
+  transform: (text: string) => Promise<PartUnion[]>,
+): Promise<PartUnion[]> {
+  const result: PartUnion[] = [];
+  const partArray = Array.isArray(parts)
+    ? parts
+    : typeof parts === 'string'
+      ? [{ text: parts }]
+      : [parts];
+
+  for (const part of partArray) {
+    let textToProcess: string | undefined;
+    if (typeof part === 'string') {
+      textToProcess = part;
+    } else if ('text' in part) {
+      textToProcess = part.text;
+    }
+
+    if (textToProcess !== undefined) {
+      const transformedParts = await transform(textToProcess);
+      result.push(...transformedParts);
+    } else {
+      // Pass through non-text parts unmodified.
+      result.push(part);
+    }
+  }
+  return result;
+}
+
+/**
+ * Appends a string of text to the last text part of a prompt, or adds a new
+ * text part if the last part is not a text part.
+ *
+ * @param prompt The prompt to modify.
+ * @param textToAppend The text to append to the prompt.
+ * @param separator The separator to add between existing text and the new text.
+ * @returns The modified prompt.
+ */
+export function appendToLastTextPart(
+  prompt: PartUnion[],
+  textToAppend: string,
+  separator = '\n\n',
+): PartUnion[] {
+  if (!textToAppend) {
+    return prompt;
+  }
+
+  if (prompt.length === 0) {
+    return [{ text: textToAppend }];
+  }
+
+  const newPrompt = [...prompt];
+  const lastPart = newPrompt.at(-1);
+
+  if (typeof lastPart === 'string') {
+    newPrompt[newPrompt.length - 1] = `${lastPart}${separator}${textToAppend}`;
+  } else if (lastPart && 'text' in lastPart) {
+    newPrompt[newPrompt.length - 1] = {
+      ...lastPart,
+      text: `${lastPart.text}${separator}${textToAppend}`,
+    };
+  } else {
+    newPrompt.push({ text: `${separator}${textToAppend}` });
+  }
+
+  return newPrompt;
+}

package/backend/packages/gemini-core/src/utils/quotaErrorDetection.ts

@@ -0,0 +1,102 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export interface StructuredError {
+  message: string;
+  status?: number;
+}
+export interface ApiError {
+  error: {
+    code: number;
+    message: string;
+    status: string;
+    details: unknown[];
+  };
+}
+
+export function isApiError(error: unknown): error is ApiError {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    'error' in error &&
+    typeof (error as ApiError).error === 'object' &&
+    'message' in (error as ApiError).error
+  );
+}
+
+export function isStructuredError(error: unknown): error is StructuredError {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    'message' in error &&
+    typeof (error as StructuredError).message === 'string'
+  );
+}
+
+export function isProQuotaExceededError(error: unknown): boolean {
+  // Check for Pro quota exceeded errors by looking for the specific pattern
+  // This will match patterns like:
+  // - "Quota exceeded for quota metric 'Gemini 2.5 Pro Requests'"
+  // - "Quota exceeded for quota metric 'Gemini 2.5-preview Pro Requests'"
+  // We use string methods instead of regex to avoid ReDoS vulnerabilities
+
+  const checkMessage = (message: string): boolean =>
+    message.includes("Quota exceeded for quota metric 'Gemini") &&
+    message.includes("Pro Requests'");
+
+  if (typeof error === 'string') {
+    return checkMessage(error);
+  }
+
+  if (isStructuredError(error)) {
+    return checkMessage(error.message);
+  }
+
+  if (isApiError(error)) {
+    return checkMessage(error.error.message);
+  }
+
+  // Check if it's a Gaxios error with response data
+  if (error && typeof error === 'object' && 'response' in error) {
+    const gaxiosError = error as {
+      response?: {
+        data?: unknown;
+      };
+    };
+    if (gaxiosError.response && gaxiosError.response.data) {
+      if (typeof gaxiosError.response.data === 'string') {
+        return checkMessage(gaxiosError.response.data);
+      }
+      if (
+        typeof gaxiosError.response.data === 'object' &&
+        gaxiosError.response.data !== null &&
+        'error' in gaxiosError.response.data
+      ) {
+        const errorData = gaxiosError.response.data as {
+          error?: { message?: string };
+        };
+        return checkMessage(errorData.error?.message || '');
+      }
+    }
+  }
+  return false;
+}
+
+export function isGenericQuotaExceededError(error: unknown): boolean {
+  if (typeof error === 'string') {
+    return error.includes('Quota exceeded for quota metric');
+  }
+
+  if (isStructuredError(error)) {
+    return error.message.includes('Quota exceeded for quota metric');
+  }
+
+  if (isApiError(error)) {
+    return error.error.message.includes('Quota exceeded for quota metric');
+  }
+
+  return false;
+}

package/backend/packages/gemini-core/src/utils/retry.ts

@@ -0,0 +1,265 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { GenerateContentResponse } from '@google/genai';
+
+export interface HttpError extends Error {
+  status?: number;
+}
+
+export interface RetryOptions {
+  maxAttempts: number;
+  initialDelayMs: number;
+  maxDelayMs: number;
+  shouldRetryOnError: (error: Error) => boolean;
+  shouldRetryOnContent?: (content: GenerateContentResponse) => boolean;
+  authType?: string;
+}
+
+const DEFAULT_RETRY_OPTIONS: RetryOptions = {
+  maxAttempts: 5,
+  initialDelayMs: 5000,
+  maxDelayMs: 30000, // 30 seconds
+  shouldRetryOnError: defaultShouldRetry,
+};
+
+/**
+ * Default predicate function to determine if a retry should be attempted.
+ * Retries on 429 (Too Many Requests) and 5xx server errors.
+ * @param error The error object.
+ * @returns True if the error is a transient error, false otherwise.
+ */
+function defaultShouldRetry(error: Error | unknown): boolean {
+  // Check for common transient error status codes either in message or a status property
+  if (error && typeof (error as { status?: number }).status === 'number') {
+    const status = (error as { status: number }).status;
+    if (status === 429 || (status >= 500 && status < 600)) {
+      return true;
+    }
+  }
+  if (error instanceof Error && error.message) {
+    if (error.message.includes('429')) return true;
+    if (error.message.match(/5\d{2}/)) return true;
+  }
+  return false;
+}
+
+/**
+ * Delays execution for a specified number of milliseconds.
+ * @param ms The number of milliseconds to delay.
+ * @returns A promise that resolves after the delay.
+ */
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Retries a function with exponential backoff and jitter.
+ * @param fn The asynchronous function to retry.
+ * @param options Optional retry configuration.
+ * @returns A promise that resolves with the result of the function if successful.
+ * @throws The last error encountered if all attempts fail.
+ */
+export async function retryWithBackoff<T>(
+  fn: () => Promise<T>,
+  options?: Partial<RetryOptions>,
+): Promise<T> {
+  if (options?.maxAttempts !== undefined && options.maxAttempts <= 0) {
+    throw new Error('maxAttempts must be a positive number.');
+  }
+
+  const cleanOptions = options
+    ? Object.fromEntries(Object.entries(options).filter(([_, v]) => v != null))
+    : {};
+
+  const {
+    maxAttempts,
+    initialDelayMs,
+    maxDelayMs,
+    shouldRetryOnError,
+    shouldRetryOnContent,
+  } = {
+    ...DEFAULT_RETRY_OPTIONS,
+    ...cleanOptions,
+  };
+
+  let attempt = 0;
+  let currentDelay = initialDelayMs;
+
+  while (attempt < maxAttempts) {
+    attempt++;
+    try {
+      const result = await fn();
+
+      if (
+        shouldRetryOnContent &&
+        shouldRetryOnContent(result as GenerateContentResponse)
+      ) {
+        const jitter = currentDelay * 0.3 * (Math.random() * 2 - 1);
+        const delayWithJitter = Math.max(0, currentDelay + jitter);
+        await delay(delayWithJitter);
+        currentDelay = Math.min(maxDelayMs, currentDelay * 2);
+        continue;
+      }
+
+      return result;
+    } catch (error) {
+      // Check if we've exhausted retries or shouldn't retry
+      if (attempt >= maxAttempts || !shouldRetryOnError(error as Error)) {
+        throw error;
+      }
+
+      const { delayDurationMs, errorStatus: delayErrorStatus } =
+        getDelayDurationAndStatus(error);
+
+      if (delayDurationMs > 0) {
+        // Respect Retry-After header if present and parsed
+        console.warn(
+          `Attempt ${attempt} failed with status ${delayErrorStatus ?? 'unknown'}. Retrying after explicit delay of ${delayDurationMs}ms...`,
+          error,
+        );
+        await delay(delayDurationMs);
+        // Reset currentDelay for next potential non-429 error, or if Retry-After is not present next time
+        currentDelay = initialDelayMs;
+      } else {
+        // Fall back to exponential backoff with jitter
+        const errorStatus = getErrorStatus(error);
+        logRetryAttempt(attempt, error, errorStatus);
+        // Add jitter: +/- 30% of currentDelay
+        const jitter = currentDelay * 0.3 * (Math.random() * 2 - 1);
+        const delayWithJitter = Math.max(0, currentDelay + jitter);
+        await delay(delayWithJitter);
+        currentDelay = Math.min(maxDelayMs, currentDelay * 2);
+      }
+    }
+  }
+  // This line should theoretically be unreachable due to the throw in the catch block.
+  // Added for type safety and to satisfy the compiler that a promise is always returned.
+  throw new Error('Retry attempts exhausted');
+}
+
+/**
+ * Extracts the HTTP status code from an error object.
+ * @param error The error object.
+ * @returns The HTTP status code, or undefined if not found.
+ */
+export function getErrorStatus(error: unknown): number | undefined {
+  if (typeof error === 'object' && error !== null) {
+    if ('status' in error && typeof error.status === 'number') {
+      return error.status;
+    }
+    // Check for error.response.status (common in axios errors)
+    if (
+      'response' in error &&
+      typeof (error as { response?: unknown }).response === 'object' &&
+      (error as { response?: unknown }).response !== null
+    ) {
+      const response = (
+        error as { response: { status?: unknown; headers?: unknown } }
+      ).response;
+      if ('status' in response && typeof response.status === 'number') {
+        return response.status;
+      }
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Extracts the Retry-After delay from an error object's headers.
+ * @param error The error object.
+ * @returns The delay in milliseconds, or 0 if not found or invalid.
+ */
+function getRetryAfterDelayMs(error: unknown): number {
+  if (typeof error === 'object' && error !== null) {
+    // Check for error.response.headers (common in axios errors)
+    if (
+      'response' in error &&
+      typeof (error as { response?: unknown }).response === 'object' &&
+      (error as { response?: unknown }).response !== null
+    ) {
+      const response = (error as { response: { headers?: unknown } }).response;
+      if (
+        'headers' in response &&
+        typeof response.headers === 'object' &&
+        response.headers !== null
+      ) {
+        const headers = response.headers as { 'retry-after'?: unknown };
+        const retryAfterHeader = headers['retry-after'];
+        if (typeof retryAfterHeader === 'string') {
+          const retryAfterSeconds = parseInt(retryAfterHeader, 10);
+          if (!isNaN(retryAfterSeconds)) {
+            return retryAfterSeconds * 1000;
+          }
+          // It might be an HTTP date
+          const retryAfterDate = new Date(retryAfterHeader);
+          if (!isNaN(retryAfterDate.getTime())) {
+            return Math.max(0, retryAfterDate.getTime() - Date.now());
+          }
+        }
+      }
+    }
+  }
+  return 0;
+}
+
+/**
+ * Determines the delay duration based on the error, prioritizing Retry-After header.
+ * @param error The error object.
+ * @returns An object containing the delay duration in milliseconds and the error status.
+ */
+function getDelayDurationAndStatus(error: unknown): {
+  delayDurationMs: number;
+  errorStatus: number | undefined;
+} {
+  const errorStatus = getErrorStatus(error);
+  let delayDurationMs = 0;
+
+  if (errorStatus === 429) {
+    delayDurationMs = getRetryAfterDelayMs(error);
+  }
+  return { delayDurationMs, errorStatus };
+}
+
+/**
+ * Logs a message for a retry attempt when using exponential backoff.
+ * @param attempt The current attempt number.
+ * @param error The error that caused the retry.
+ * @param errorStatus The HTTP status code of the error, if available.
+ */
+function logRetryAttempt(
+  attempt: number,
+  error: unknown,
+  errorStatus?: number,
+): void {
+  let message = `Attempt ${attempt} failed. Retrying with backoff...`;
+  if (errorStatus) {
+    message = `Attempt ${attempt} failed with status ${errorStatus}. Retrying with backoff...`;
+  }
+
+  if (errorStatus === 429) {
+    console.warn(message, error);
+  } else if (errorStatus && errorStatus >= 500 && errorStatus < 600) {
+    console.error(message, error);
+  } else if (error instanceof Error) {
+    // Fallback for errors that might not have a status but have a message
+    if (error.message.includes('429')) {
+      console.warn(
+        `Attempt ${attempt} failed with 429 error (no Retry-After header). Retrying with backoff...`,
+        error,
+      );
+    } else if (error.message.match(/5\d{2}/)) {
+      console.error(
+        `Attempt ${attempt} failed with 5xx error. Retrying with backoff...`,
+        error,
+      );
+    } else {
+      console.warn(message, error); // Default to warn for other errors
+    }
+  } else {
+    console.warn(message, error); // Default to warn if error type is unknown
+  }
+}

package/backend/packages/gemini-core/src/utils/session.ts

@@ -0,0 +1,9 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { randomUUID } from 'node:crypto';
+
+export const sessionId = randomUUID();