@anthropic-field/core 0.1.0

package/dist/src/utils/paths.js

@@ -0,0 +1,311 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import path from 'node:path';
+import os from 'node:os';
+import process from 'node:process';
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+export const GEMINI_DIR = '.gemini';
+export const GOOGLE_ACCOUNTS_FILENAME = 'google_accounts.json';
+/**
+ * Special characters that need to be escaped in file paths for shell compatibility.
+ * Includes: spaces, parentheses, brackets, braces, semicolons, ampersands, pipes,
+ * asterisks, question marks, dollar signs, backticks, quotes, hash, and other shell metacharacters.
+ */
+export const SHELL_SPECIAL_CHARS = /[ \t()[\]{};|*?$`'"#&<>!~]/;
+/**
+ * Returns the home directory.
+ * If GEMINI_CLI_HOME environment variable is set, it returns its value.
+ * Otherwise, it returns the user's home directory.
+ */
+export function homedir() {
+    const envHome = process.env['GEMINI_CLI_HOME'];
+    if (envHome) {
+        return envHome;
+    }
+    return os.homedir();
+}
+/**
+ * Returns the operating system's default directory for temporary files.
+ */
+export function tmpdir() {
+    return os.tmpdir();
+}
+/**
+ * Replaces the home directory with a tilde.
+ * @param path - The path to tildeify.
+ * @returns The tildeified path.
+ */
+export function tildeifyPath(path) {
+    const homeDir = homedir();
+    if (path.startsWith(homeDir)) {
+        return path.replace(homeDir, '~');
+    }
+    return path;
+}
+/**
+ * Shortens a path string if it exceeds maxLen, prioritizing the start and end segments.
+ * Example: /path/to/a/very/long/file.txt -> /path/.../long/file.txt
+ */
+export function shortenPath(filePath, maxLen = 35) {
+    if (filePath.length <= maxLen) {
+        return filePath;
+    }
+    const simpleTruncate = () => {
+        const keepLen = Math.floor((maxLen - 3) / 2);
+        if (keepLen <= 0) {
+            return filePath.substring(0, maxLen - 3) + '...';
+        }
+        const start = filePath.substring(0, keepLen);
+        const end = filePath.substring(filePath.length - keepLen);
+        return `${start}...${end}`;
+    };
+    const truncateComponent = (component, targetLength, mode) => {
+        if (component.length <= targetLength) {
+            return component;
+        }
+        if (targetLength <= 0) {
+            return '';
+        }
+        if (targetLength <= 3) {
+            if (mode === 'end') {
+                return component.slice(-targetLength);
+            }
+            return component.slice(0, targetLength);
+        }
+        if (mode === 'start') {
+            return `${component.slice(0, targetLength - 3)}...`;
+        }
+        if (mode === 'end') {
+            return `...${component.slice(component.length - (targetLength - 3))}`;
+        }
+        const front = Math.ceil((targetLength - 3) / 2);
+        const back = targetLength - 3 - front;
+        return `${component.slice(0, front)}...${component.slice(component.length - back)}`;
+    };
+    const parsedPath = path.parse(filePath);
+    const root = parsedPath.root;
+    const separator = path.sep;
+    // Get segments of the path *after* the root
+    const relativePath = filePath.substring(root.length);
+    const segments = relativePath.split(separator).filter((s) => s !== ''); // Filter out empty segments
+    // Handle cases with no segments after root (e.g., "/", "C:\") or only one segment
+    if (segments.length <= 1) {
+        // Fall back to simple start/end truncation for very short paths or single segments
+        return simpleTruncate();
+    }
+    const firstDir = segments[0];
+    const lastSegment = segments[segments.length - 1];
+    const startComponent = root + firstDir;
+    const endPartSegments = [lastSegment];
+    let endPartLength = lastSegment.length;
+    // Iterate backwards through the middle segments
+    for (let i = segments.length - 2; i > 0; i--) {
+        const segment = segments[i];
+        const newLength = startComponent.length +
+            separator.length +
+            3 + // for "..."
+            separator.length +
+            endPartLength +
+            separator.length +
+            segment.length;
+        if (newLength <= maxLen) {
+            endPartSegments.unshift(segment);
+            endPartLength += separator.length + segment.length;
+        }
+        else {
+            break;
+        }
+    }
+    const components = [firstDir, ...endPartSegments];
+    const componentModes = components.map((_, index) => {
+        if (index === 0) {
+            return 'start';
+        }
+        if (index === components.length - 1) {
+            return 'end';
+        }
+        return 'center';
+    });
+    const separatorsCount = endPartSegments.length + 1;
+    const fixedLen = root.length + separatorsCount * separator.length + 3; // ellipsis length
+    const availableForComponents = maxLen - fixedLen;
+    const trailingFallback = () => {
+        const ellipsisTail = `...${separator}${lastSegment}`;
+        if (ellipsisTail.length <= maxLen) {
+            return ellipsisTail;
+        }
+        if (root) {
+            const rootEllipsisTail = `${root}...${separator}${lastSegment}`;
+            if (rootEllipsisTail.length <= maxLen) {
+                return rootEllipsisTail;
+            }
+        }
+        if (root && `${root}${lastSegment}`.length <= maxLen) {
+            return `${root}${lastSegment}`;
+        }
+        if (lastSegment.length <= maxLen) {
+            return lastSegment;
+        }
+        // As a final resort (e.g., last segment itself exceeds maxLen), fall back to simple truncation.
+        return simpleTruncate();
+    };
+    if (availableForComponents <= 0) {
+        return trailingFallback();
+    }
+    const minLengths = components.map((component, index) => {
+        if (index === 0) {
+            return Math.min(component.length, 1);
+        }
+        if (index === components.length - 1) {
+            return component.length; // Never truncate the last segment when possible.
+        }
+        return Math.min(component.length, 1);
+    });
+    const minTotal = minLengths.reduce((sum, len) => sum + len, 0);
+    if (availableForComponents < minTotal) {
+        return trailingFallback();
+    }
+    const budgets = components.map((component) => component.length);
+    let currentTotal = budgets.reduce((sum, len) => sum + len, 0);
+    const pickIndexToReduce = () => {
+        let bestIndex = -1;
+        let bestScore = -Infinity;
+        for (let i = 0; i < budgets.length; i++) {
+            if (budgets[i] <= minLengths[i]) {
+                continue;
+            }
+            const isLast = i === budgets.length - 1;
+            const score = (isLast ? 0 : 1_000_000) + budgets[i];
+            if (score > bestScore) {
+                bestScore = score;
+                bestIndex = i;
+            }
+        }
+        return bestIndex;
+    };
+    while (currentTotal > availableForComponents) {
+        const index = pickIndexToReduce();
+        if (index === -1) {
+            return trailingFallback();
+        }
+        budgets[index]--;
+        currentTotal--;
+    }
+    const truncatedComponents = components.map((component, index) => truncateComponent(component, budgets[index], componentModes[index]));
+    const truncatedFirst = truncatedComponents[0];
+    const truncatedEnd = truncatedComponents.slice(1).join(separator);
+    const result = `${root}${truncatedFirst}${separator}...${separator}${truncatedEnd}`;
+    if (result.length > maxLen) {
+        return trailingFallback();
+    }
+    return result;
+}
+/**
+ * Calculates the relative path from a root directory to a target path.
+ * If targetPath is relative, it is returned as-is.
+ * Returns '.' if the target path is the same as the root directory.
+ *
+ * @param targetPath The absolute or relative path to make relative.
+ * @param rootDirectory The absolute path of the directory to make the target path relative to.
+ * @returns The relative path from rootDirectory to targetPath.
+ */
+export function makeRelative(targetPath, rootDirectory) {
+    if (!path.isAbsolute(targetPath)) {
+        return targetPath;
+    }
+    const resolvedRootDirectory = path.resolve(rootDirectory);
+    const relativePath = path.relative(resolvedRootDirectory, targetPath);
+    // If the paths are the same, path.relative returns '', return '.' instead
+    return relativePath || '.';
+}
+/**
+ * Escapes special characters in a file path like macOS terminal does.
+ * Escapes: spaces, parentheses, brackets, braces, semicolons, ampersands, pipes,
+ * asterisks, question marks, dollar signs, backticks, quotes, hash, and other shell metacharacters.
+ */
+export function escapePath(filePath) {
+    let result = '';
+    for (let i = 0; i < filePath.length; i++) {
+        const char = filePath[i];
+        // Count consecutive backslashes before this character
+        let backslashCount = 0;
+        for (let j = i - 1; j >= 0 && filePath[j] === '\\'; j--) {
+            backslashCount++;
+        }
+        // Character is already escaped if there's an odd number of backslashes before it
+        const isAlreadyEscaped = backslashCount % 2 === 1;
+        // Only escape if not already escaped
+        if (!isAlreadyEscaped && SHELL_SPECIAL_CHARS.test(char)) {
+            result += '\\' + char;
+        }
+        else {
+            result += char;
+        }
+    }
+    return result;
+}
+/**
+ * Unescapes special characters in a file path.
+ * Removes backslash escaping from shell metacharacters.
+ */
+export function unescapePath(filePath) {
+    return filePath.replace(new RegExp(`\\\\([${SHELL_SPECIAL_CHARS.source.slice(1, -1)}])`, 'g'), '$1');
+}
+/**
+ * Generates a unique hash for a project based on its root path.
+ * @param projectRoot The absolute path to the project's root directory.
+ * @returns A SHA256 hash of the project root path.
+ */
+export function getProjectHash(projectRoot) {
+    return crypto.createHash('sha256').update(projectRoot).digest('hex');
+}
+/**
+ * Checks if a path is a subpath of another path.
+ * @param parentPath The parent path.
+ * @param childPath The child path.
+ * @returns True if childPath is a subpath of parentPath, false otherwise.
+ */
+export function isSubpath(parentPath, childPath) {
+    const isWindows = os.platform() === 'win32';
+    const pathModule = isWindows ? path.win32 : path;
+    // On Windows, path.relative is case-insensitive. On POSIX, it's case-sensitive.
+    const relative = pathModule.relative(parentPath, childPath);
+    return (!relative.startsWith(`..${pathModule.sep}`) &&
+        relative !== '..' &&
+        !pathModule.isAbsolute(relative));
+}
+/**
+ * Resolves a path to its real path, sanitizing it first.
+ * - Removes 'file://' protocol if present.
+ * - Decodes URI components (e.g. %20 -> space).
+ * - Resolves symbolic links using fs.realpathSync.
+ *
+ * @param pathStr The path string to resolve.
+ * @returns The resolved real path.
+ */
+export function resolveToRealPath(path) {
+    let resolvedPath = path;
+    try {
+        if (resolvedPath.startsWith('file://')) {
+            resolvedPath = fileURLToPath(resolvedPath);
+        }
+        resolvedPath = decodeURIComponent(resolvedPath);
+    }
+    catch (_e) {
+        // Ignore error (e.g. malformed URI), keep path from previous step
+    }
+    try {
+        return fs.realpathSync(resolvedPath);
+    }
+    catch (_e) {
+        // If realpathSync fails, it might be because the path doesn't exist.
+        // In that case, we can fall back to the path processed.
+        return resolvedPath;
+    }
+}
+//# sourceMappingURL=paths.js.map

package/dist/src/utils/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../../src/utils/paths.ts"],"names":[],"mappings":"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"}

package/dist/src/utils/process-utils.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/** Default timeout for SIGKILL escalation on Unix systems. */
+export declare const SIGKILL_TIMEOUT_MS = 200;
+/** Configuration for process termination. */
+export interface KillOptions {
+    /** The process ID to terminate. */
+    pid: number;
+    /** Whether to attempt SIGTERM before SIGKILL on Unix systems. */
+    escalate?: boolean;
+    /** Initial signal to use (defaults to SIGTERM if escalate is true, else SIGKILL). */
+    signal?: NodeJS.Signals | number;
+    /** Callback to check if the process has already exited. */
+    isExited?: () => boolean;
+    /** Optional PTY object for PTY-specific kill methods. */
+    pty?: {
+        kill: (signal?: string) => void;
+    };
+}
+/**
+ * Robustly terminates a process or process group across platforms.
+ *
+ * On Windows, it uses `taskkill /f /t` to ensure the entire tree is terminated,
+ * or the PTY's built-in kill method.
+ *
+ * On Unix, it attempts to kill the process group (using -pid) with escalation
+ * from SIGTERM to SIGKILL if requested.
+ */
+export declare function killProcessGroup(options: KillOptions): Promise<void>;

package/dist/src/utils/process-utils.js

@@ -0,0 +1,88 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import os from 'node:os';
+import { spawn as cpSpawn } from 'node:child_process';
+/** Default timeout for SIGKILL escalation on Unix systems. */
+export const SIGKILL_TIMEOUT_MS = 200;
+/**
+ * Robustly terminates a process or process group across platforms.
+ *
+ * On Windows, it uses `taskkill /f /t` to ensure the entire tree is terminated,
+ * or the PTY's built-in kill method.
+ *
+ * On Unix, it attempts to kill the process group (using -pid) with escalation
+ * from SIGTERM to SIGKILL if requested.
+ */
+export async function killProcessGroup(options) {
+    const { pid, escalate = false, isExited = () => false, pty } = options;
+    const isWindows = os.platform() === 'win32';
+    if (isWindows) {
+        if (pty) {
+            try {
+                pty.kill();
+            }
+            catch {
+                // Ignore errors for dead processes
+            }
+        }
+        else {
+            cpSpawn('taskkill', ['/pid', pid.toString(), '/f', '/t']);
+        }
+        return;
+    }
+    // Unix logic
+    try {
+        const initialSignal = options.signal || (escalate ? 'SIGTERM' : 'SIGKILL');
+        // Try killing the process group first (-pid)
+        process.kill(-pid, initialSignal);
+        if (escalate && !isExited()) {
+            await new Promise((res) => setTimeout(res, SIGKILL_TIMEOUT_MS));
+            if (!isExited()) {
+                try {
+                    process.kill(-pid, 'SIGKILL');
+                }
+                catch {
+                    // Ignore
+                }
+            }
+        }
+    }
+    catch (_e) {
+        // Fallback to specific process kill if group kill fails or on error
+        if (!isExited()) {
+            if (pty) {
+                if (escalate) {
+                    try {
+                        pty.kill('SIGTERM');
+                        await new Promise((res) => setTimeout(res, SIGKILL_TIMEOUT_MS));
+                        if (!isExited())
+                            pty.kill('SIGKILL');
+                    }
+                    catch {
+                        // Ignore
+                    }
+                }
+                else {
+                    try {
+                        pty.kill('SIGKILL');
+                    }
+                    catch {
+                        // Ignore
+                    }
+                }
+            }
+            else {
+                try {
+                    process.kill(pid, 'SIGKILL');
+                }
+                catch {
+                    // Ignore
+                }
+            }
+        }
+    }
+}
+//# sourceMappingURL=process-utils.js.map

package/dist/src/utils/process-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-utils.js","sourceRoot":"","sources":["../../../src/utils/process-utils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,EAAE,KAAK,IAAI,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAEtD,8DAA8D;AAC9D,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAG,CAAC;AAgBtC;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,OAAoB;IACzD,MAAM,EAAE,GAAG,EAAE,QAAQ,GAAG,KAAK,EAAE,QAAQ,GAAG,GAAG,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC;IACvE,MAAM,SAAS,GAAG,EAAE,CAAC,QAAQ,EAAE,KAAK,OAAO,CAAC;IAE5C,IAAI,SAAS,EAAE,CAAC;QACd,IAAI,GAAG,EAAE,CAAC;YACR,IAAI,CAAC;gBACH,GAAG,CAAC,IAAI,EAAE,CAAC;YACb,CAAC;YAAC,MAAM,CAAC;gBACP,mCAAmC;YACrC,CAAC;QACH,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,UAAU,EAAE,CAAC,MAAM,EAAE,GAAG,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;QAC5D,CAAC;QACD,OAAO;IACT,CAAC;IAED,aAAa;IACb,IAAI,CAAC;QACH,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QAE3E,6CAA6C;QAC7C,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,aAAa,CAAC,CAAC;QAElC,IAAI,QAAQ,IAAI,CAAC,QAAQ,EAAE,EAAE,CAAC;YAC5B,MAAM,IAAI,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,kBAAkB,CAAC,CAAC,CAAC;YAChE,IAAI,CAAC,QAAQ,EAAE,EAAE,CAAC;gBAChB,IAAI,CAAC;oBACH,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;gBAChC,CAAC;gBAAC,MAAM,CAAC;oBACP,SAAS;gBACX,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAAC,OAAO,EAAE,EAAE,CAAC;QACZ,oEAAoE;QACpE,IAAI,CAAC,QAAQ,EAAE,EAAE,CAAC;YAChB,IAAI,GAAG,EAAE,CAAC;gBACR,IAAI,QAAQ,EAAE,CAAC;oBACb,IAAI,CAAC;wBACH,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;wBACpB,MAAM,IAAI,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,kBAAkB,CAAC,CAAC,CAAC;wBAChE,IAAI,CAAC,QAAQ,EAAE;4BAAE,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;oBACvC,CAAC;oBAAC,MAAM,CAAC;wBACP,SAAS;oBACX,CAAC;gBACH,CAAC;qBAAM,CAAC;oBACN,IAAI,CAAC;wBACH,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;oBACtB,CAAC;oBAAC,MAAM,CAAC;wBACP,SAAS;oBACX,CAAC;gBACH,CAAC;YACH,CAAC;iBAAM,CAAC;gBACN,IAAI,CAAC;oBACH,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;gBAC/B,CAAC;gBAAC,MAAM,CAAC;oBACP,SAAS;gBACX,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/src/utils/promptIdContext.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+export declare const promptIdContext: AsyncLocalStorage<string>;
+/**
+ * Retrieves the prompt ID from the context, or generates a fallback if not found.
+ * @param componentName The name of the component requesting the ID (used for the fallback prefix).
+ * @returns The retrieved or generated prompt ID.
+ */
+export declare function getPromptIdWithFallback(componentName: string): string;

package/dist/src/utils/promptIdContext.js

@@ -0,0 +1,23 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { debugLogger } from './debugLogger.js';
+export const promptIdContext = new AsyncLocalStorage();
+/**
+ * Retrieves the prompt ID from the context, or generates a fallback if not found.
+ * @param componentName The name of the component requesting the ID (used for the fallback prefix).
+ * @returns The retrieved or generated prompt ID.
+ */
+export function getPromptIdWithFallback(componentName) {
+    const promptId = promptIdContext.getStore();
+    if (promptId) {
+        return promptId;
+    }
+    const fallbackId = `${componentName}-fallback-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+    debugLogger.warn(`Could not find promptId in context for ${componentName}. This is unexpected. Using a fallback ID: ${fallbackId}`);
+    return fallbackId;
+}
+//# sourceMappingURL=promptIdContext.js.map

package/dist/src/utils/promptIdContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"promptIdContext.js","sourceRoot":"","sources":["../../../src/utils/promptIdContext.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE/C,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,iBAAiB,EAAU,CAAC;AAE/D;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CAAC,aAAqB;IAC3D,MAAM,QAAQ,GAAG,eAAe,CAAC,QAAQ,EAAE,CAAC;IAC5C,IAAI,QAAQ,EAAE,CAAC;QACb,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,MAAM,UAAU,GAAG,GAAG,aAAa,aAAa,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IACpG,WAAW,CAAC,IAAI,CACd,0CAA0C,aAAa,8CAA8C,UAAU,EAAE,CAClH,CAAC;IACF,OAAO,UAAU,CAAC;AACpB,CAAC"}

package/dist/src/utils/quotaErrorDetection.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { StructuredError } from '../core/turn.js';
+export interface ApiError {
+    error: {
+        code: number;
+        message: string;
+        status: string;
+        details: unknown[];
+    };
+}
+export declare function isApiError(error: unknown): error is ApiError;
+export declare function isStructuredError(error: unknown): error is StructuredError;

package/dist/src/utils/quotaErrorDetection.js

@@ -0,0 +1,19 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export function isApiError(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        'error' in error &&
+        typeof error.error === 'object' &&
+        'message' in error.error);
+}
+export function isStructuredError(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        'message' in error &&
+        typeof error.message === 'string');
+}
+//# sourceMappingURL=quotaErrorDetection.js.map

package/dist/src/utils/quotaErrorDetection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"quotaErrorDetection.js","sourceRoot":"","sources":["../../../src/utils/quotaErrorDetection.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAaH,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,OAAO,IAAI,KAAK;QAChB,OAAQ,KAAkB,CAAC,KAAK,KAAK,QAAQ;QAC7C,SAAS,IAAK,KAAkB,CAAC,KAAK,CACvC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,SAAS,IAAI,KAAK;QAClB,OAAQ,KAAyB,CAAC,OAAO,KAAK,QAAQ,CACvD,CAAC;AACJ,CAAC"}

package/dist/src/utils/retry.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { GenerateContentResponse } from '@google/genai';
+import { ValidationRequiredError } from './googleQuotaErrors.js';
+import type { RetryAvailabilityContext } from '../availability/modelPolicy.js';
+export type { RetryAvailabilityContext };
+export interface RetryOptions {
+    maxAttempts: number;
+    initialDelayMs: number;
+    maxDelayMs: number;
+    shouldRetryOnError: (error: Error, retryFetchErrors?: boolean) => boolean;
+    shouldRetryOnContent?: (content: GenerateContentResponse) => boolean;
+    onPersistent429?: (authType?: string, error?: unknown) => Promise<string | boolean | null>;
+    onValidationRequired?: (error: ValidationRequiredError) => Promise<'verify' | 'change_auth' | 'cancel'>;
+    authType?: string;
+    retryFetchErrors?: boolean;
+    signal?: AbortSignal;
+    getAvailabilityContext?: () => RetryAvailabilityContext | undefined;
+    onRetry?: (attempt: number, error: unknown, delayMs: number) => void;
+}
+/**
+ * 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.
+ * @param retryFetchErrors Whether to retry on specific fetch errors.
+ * @returns True if the error is a transient error, false otherwise.
+ */
+export declare function isRetryableError(error: Error | unknown, retryFetchErrors?: boolean): boolean;
+/**
+ * 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 declare function retryWithBackoff<T>(fn: () => Promise<T>, options?: Partial<RetryOptions>): Promise<T>;