@anthropic-field/core 0.1.0

package/dist/src/utils/retry.js

@@ -0,0 +1,267 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ApiError } from '@google/genai';
+import { TerminalQuotaError, RetryableQuotaError, ValidationRequiredError, classifyGoogleError, } from './googleQuotaErrors.js';
+import { delay, createAbortError } from './delay.js';
+import { debugLogger } from './debugLogger.js';
+import { getErrorStatus, ModelNotFoundError } from './httpErrors.js';
+const DEFAULT_RETRY_OPTIONS = {
+    maxAttempts: 3,
+    initialDelayMs: 5000,
+    maxDelayMs: 30000, // 30 seconds
+    shouldRetryOnError: isRetryableError,
+};
+const RETRYABLE_NETWORK_CODES = [
+    'ECONNRESET',
+    'ETIMEDOUT',
+    'EPIPE',
+    'ENOTFOUND',
+    'EAI_AGAIN',
+    'ECONNREFUSED',
+];
+function getNetworkErrorCode(error) {
+    const getCode = (obj) => {
+        if (typeof obj !== 'object' || obj === null) {
+            return undefined;
+        }
+        if ('code' in obj && typeof obj.code === 'string') {
+            return obj.code;
+        }
+        return undefined;
+    };
+    const directCode = getCode(error);
+    if (directCode) {
+        return directCode;
+    }
+    if (typeof error === 'object' && error !== null && 'cause' in error) {
+        return getCode(error.cause);
+    }
+    return undefined;
+}
+const FETCH_FAILED_MESSAGE = 'fetch failed';
+/**
+ * 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 function isRetryableError(error, retryFetchErrors) {
+    // Check for common network error codes
+    const errorCode = getNetworkErrorCode(error);
+    if (errorCode && RETRYABLE_NETWORK_CODES.includes(errorCode)) {
+        return true;
+    }
+    if (retryFetchErrors && error instanceof Error) {
+        // Check for generic fetch failed message (case-insensitive)
+        if (error.message.toLowerCase().includes(FETCH_FAILED_MESSAGE)) {
+            return true;
+        }
+    }
+    // Priority check for ApiError
+    if (error instanceof ApiError) {
+        // Explicitly do not retry 400 (Bad Request)
+        if (error.status === 400)
+            return false;
+        return error.status === 429 || (error.status >= 500 && error.status < 600);
+    }
+    // Check for status using helper (handles other error shapes)
+    const status = getErrorStatus(error);
+    if (status !== undefined) {
+        return status === 429 || (status >= 500 && status < 600);
+    }
+    return false;
+}
+/**
+ * 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(fn, options) {
+    if (options?.signal?.aborted) {
+        throw createAbortError();
+    }
+    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, onPersistent429, onValidationRequired, authType, shouldRetryOnError, shouldRetryOnContent, retryFetchErrors, signal, getAvailabilityContext, onRetry, } = {
+        ...DEFAULT_RETRY_OPTIONS,
+        shouldRetryOnError: isRetryableError,
+        ...cleanOptions,
+    };
+    let attempt = 0;
+    let currentDelay = initialDelayMs;
+    while (attempt < maxAttempts) {
+        if (signal?.aborted) {
+            throw createAbortError();
+        }
+        attempt++;
+        try {
+            const result = await fn();
+            if (shouldRetryOnContent &&
+                shouldRetryOnContent(result)) {
+                const jitter = currentDelay * 0.3 * (Math.random() * 2 - 1);
+                const delayWithJitter = Math.max(0, currentDelay + jitter);
+                if (onRetry) {
+                    onRetry(attempt, new Error('Invalid content'), delayWithJitter);
+                }
+                await delay(delayWithJitter, signal);
+                currentDelay = Math.min(maxDelayMs, currentDelay * 2);
+                continue;
+            }
+            const successContext = getAvailabilityContext?.();
+            if (successContext) {
+                successContext.service.markHealthy(successContext.policy.model);
+            }
+            return result;
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === 'AbortError') {
+                throw error;
+            }
+            const classifiedError = classifyGoogleError(error);
+            const errorCode = getErrorStatus(error);
+            if (classifiedError instanceof TerminalQuotaError ||
+                classifiedError instanceof ModelNotFoundError) {
+                if (onPersistent429) {
+                    try {
+                        const fallbackModel = await onPersistent429(authType, classifiedError);
+                        if (fallbackModel) {
+                            attempt = 0; // Reset attempts and retry with the new model.
+                            currentDelay = initialDelayMs;
+                            continue;
+                        }
+                    }
+                    catch (fallbackError) {
+                        debugLogger.warn('Fallback to Flash model failed:', fallbackError);
+                    }
+                }
+                // Terminal/not_found already recorded; nothing else to mark here.
+                throw classifiedError; // Throw if no fallback or fallback failed.
+            }
+            // Handle ValidationRequiredError - user needs to verify before proceeding
+            if (classifiedError instanceof ValidationRequiredError) {
+                if (onValidationRequired) {
+                    try {
+                        const intent = await onValidationRequired(classifiedError);
+                        if (intent === 'verify') {
+                            // User verified, retry the request
+                            attempt = 0;
+                            currentDelay = initialDelayMs;
+                            continue;
+                        }
+                        // 'change_auth' or 'cancel' - mark as handled and throw
+                        classifiedError.userHandled = true;
+                    }
+                    catch (validationError) {
+                        debugLogger.warn('Validation handler failed:', validationError);
+                    }
+                }
+                throw classifiedError;
+            }
+            const is500 = errorCode !== undefined && errorCode >= 500 && errorCode < 600;
+            if (classifiedError instanceof RetryableQuotaError || is500) {
+                if (attempt >= maxAttempts) {
+                    const errorMessage = classifiedError instanceof Error ? classifiedError.message : '';
+                    debugLogger.warn(`Attempt ${attempt} failed${errorMessage ? `: ${errorMessage}` : ''}. Max attempts reached`);
+                    if (onPersistent429) {
+                        try {
+                            const fallbackModel = await onPersistent429(authType, classifiedError);
+                            if (fallbackModel) {
+                                attempt = 0; // Reset attempts and retry with the new model.
+                                currentDelay = initialDelayMs;
+                                continue;
+                            }
+                        }
+                        catch (fallbackError) {
+                            debugLogger.warn('Model fallback failed:', fallbackError);
+                        }
+                    }
+                    throw classifiedError instanceof RetryableQuotaError
+                        ? classifiedError
+                        : error;
+                }
+                if (classifiedError instanceof RetryableQuotaError &&
+                    classifiedError.retryDelayMs !== undefined) {
+                    debugLogger.warn(`Attempt ${attempt} failed: ${classifiedError.message}. Retrying after ${classifiedError.retryDelayMs}ms...`);
+                    if (onRetry) {
+                        onRetry(attempt, error, classifiedError.retryDelayMs);
+                    }
+                    await delay(classifiedError.retryDelayMs, signal);
+                    continue;
+                }
+                else {
+                    const errorStatus = getErrorStatus(error);
+                    logRetryAttempt(attempt, error, errorStatus);
+                    // Exponential backoff with jitter for non-quota errors
+                    const jitter = currentDelay * 0.3 * (Math.random() * 2 - 1);
+                    const delayWithJitter = Math.max(0, currentDelay + jitter);
+                    if (onRetry) {
+                        onRetry(attempt, error, delayWithJitter);
+                    }
+                    await delay(delayWithJitter, signal);
+                    currentDelay = Math.min(maxDelayMs, currentDelay * 2);
+                    continue;
+                }
+            }
+            // Generic retry logic for other errors
+            if (attempt >= maxAttempts ||
+                !shouldRetryOnError(error, retryFetchErrors)) {
+                throw error;
+            }
+            const errorStatus = getErrorStatus(error);
+            logRetryAttempt(attempt, error, errorStatus);
+            // Exponential backoff with jitter for non-quota errors
+            const jitter = currentDelay * 0.3 * (Math.random() * 2 - 1);
+            const delayWithJitter = Math.max(0, currentDelay + jitter);
+            if (onRetry) {
+                onRetry(attempt, error, delayWithJitter);
+            }
+            await delay(delayWithJitter, signal);
+            currentDelay = Math.min(maxDelayMs, currentDelay * 2);
+        }
+    }
+    throw new Error('Retry attempts exhausted');
+}
+/**
+ * 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, error, errorStatus) {
+    let message = `Attempt ${attempt} failed. Retrying with backoff...`;
+    if (errorStatus) {
+        message = `Attempt ${attempt} failed with status ${errorStatus}. Retrying with backoff...`;
+    }
+    if (errorStatus === 429) {
+        debugLogger.warn(message, error);
+    }
+    else if (errorStatus && errorStatus >= 500 && errorStatus < 600) {
+        debugLogger.warn(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')) {
+            debugLogger.warn(`Attempt ${attempt} failed with 429 error (no Retry-After header). Retrying with backoff...`, error);
+        }
+        else if (error.message.match(/5\d{2}/)) {
+            debugLogger.warn(`Attempt ${attempt} failed with 5xx error. Retrying with backoff...`, error);
+        }
+        else {
+            debugLogger.warn(message, error); // Default to warn for other errors
+        }
+    }
+    else {
+        debugLogger.warn(message, error); // Default to warn if error type is unknown
+    }
+}
+//# sourceMappingURL=retry.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../../src/utils/retry.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,uBAAuB,EACvB,mBAAmB,GACpB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAyBrE,MAAM,qBAAqB,GAAiB;IAC1C,WAAW,EAAE,CAAC;IACd,cAAc,EAAE,IAAI;IACpB,UAAU,EAAE,KAAK,EAAE,aAAa;IAChC,kBAAkB,EAAE,gBAAgB;CACrC,CAAC;AAEF,MAAM,uBAAuB,GAAG;IAC9B,YAAY;IACZ,WAAW;IACX,OAAO;IACP,WAAW;IACX,WAAW;IACX,cAAc;CACf,CAAC;AAEF,SAAS,mBAAmB,CAAC,KAAc;IACzC,MAAM,OAAO,GAAG,CAAC,GAAY,EAAsB,EAAE;QACnD,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;YAC5C,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,IAAI,MAAM,IAAI,GAAG,IAAI,OAAQ,GAAyB,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACzE,OAAQ,GAAwB,CAAC,IAAI,CAAC;QACxC,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC,CAAC;IAEF,MAAM,UAAU,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IAClC,IAAI,UAAU,EAAE,CAAC;QACf,OAAO,UAAU,CAAC;IACpB,CAAC;IAED,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,EAAE,CAAC;QACpE,OAAO,OAAO,CAAE,KAA4B,CAAC,KAAK,CAAC,CAAC;IACtD,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,oBAAoB,GAAG,cAAc,CAAC;AAE5C;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAC9B,KAAsB,EACtB,gBAA0B;IAE1B,uCAAuC;IACvC,MAAM,SAAS,GAAG,mBAAmB,CAAC,KAAK,CAAC,CAAC;IAC7C,IAAI,SAAS,IAAI,uBAAuB,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;QAC7D,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,gBAAgB,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC/C,4DAA4D;QAC5D,IAAI,KAAK,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,CAAC;YAC/D,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED,8BAA8B;IAC9B,IAAI,KAAK,YAAY,QAAQ,EAAE,CAAC;QAC9B,4CAA4C;QAC5C,IAAI,KAAK,CAAC,MAAM,KAAK,GAAG;YAAE,OAAO,KAAK,CAAC;QACvC,OAAO,KAAK,CAAC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,IAAI,GAAG,IAAI,KAAK,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC;IAC7E,CAAC;IAED,6DAA6D;IAC7D,MAAM,MAAM,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;IACrC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,OAAO,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,IAAI,GAAG,IAAI,MAAM,GAAG,GAAG,CAAC,CAAC;IAC3D,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,EAAoB,EACpB,OAA+B;IAE/B,IAAI,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;QAC7B,MAAM,gBAAgB,EAAE,CAAC;IAC3B,CAAC;IAED,IAAI,OAAO,EAAE,WAAW,KAAK,SAAS,IAAI,OAAO,CAAC,WAAW,IAAI,CAAC,EAAE,CAAC;QACnE,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;IAC5D,CAAC;IAED,MAAM,YAAY,GAAG,OAAO;QAC1B,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC;QAC3E,CAAC,CAAC,EAAE,CAAC;IAEP,MAAM,EACJ,WAAW,EACX,cAAc,EACd,UAAU,EACV,eAAe,EACf,oBAAoB,EACpB,QAAQ,EACR,kBAAkB,EAClB,oBAAoB,EACpB,gBAAgB,EAChB,MAAM,EACN,sBAAsB,EACtB,OAAO,GACR,GAAG;QACF,GAAG,qBAAqB;QACxB,kBAAkB,EAAE,gBAAgB;QACpC,GAAG,YAAY;KAChB,CAAC;IAEF,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,IAAI,YAAY,GAAG,cAAc,CAAC;IAElC,OAAO,OAAO,GAAG,WAAW,EAAE,CAAC;QAC7B,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;YACpB,MAAM,gBAAgB,EAAE,CAAC;QAC3B,CAAC;QACD,OAAO,EAAE,CAAC;QACV,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,EAAE,EAAE,CAAC;YAE1B,IACE,oBAAoB;gBACpB,oBAAoB,CAAC,MAAiC,CAAC,EACvD,CAAC;gBACD,MAAM,MAAM,GAAG,YAAY,GAAG,GAAG,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;gBAC5D,MAAM,eAAe,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,YAAY,GAAG,MAAM,CAAC,CAAC;gBAC3D,IAAI,OAAO,EAAE,CAAC;oBACZ,OAAO,CAAC,OAAO,EAAE,IAAI,KAAK,CAAC,iBAAiB,CAAC,EAAE,eAAe,CAAC,CAAC;gBAClE,CAAC;gBACD,MAAM,KAAK,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC;gBACrC,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,YAAY,GAAG,CAAC,CAAC,CAAC;gBACtD,SAAS;YACX,CAAC;YAED,MAAM,cAAc,GAAG,sBAAsB,EAAE,EAAE,CAAC;YAClD,IAAI,cAAc,EAAE,CAAC;gBACnB,cAAc,CAAC,OAAO,CAAC,WAAW,CAAC,cAAc,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAClE,CAAC;YAED,OAAO,MAAM,CAAC;QAChB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,KAAK,YAAY,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;gBAC1D,MAAM,KAAK,CAAC;YACd,CAAC;YAED,MAAM,eAAe,GAAG,mBAAmB,CAAC,KAAK,CAAC,CAAC;YAEnD,MAAM,SAAS,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;YAExC,IACE,eAAe,YAAY,kBAAkB;gBAC7C,eAAe,YAAY,kBAAkB,EAC7C,CAAC;gBACD,IAAI,eAAe,EAAE,CAAC;oBACpB,IAAI,CAAC;wBACH,MAAM,aAAa,GAAG,MAAM,eAAe,CACzC,QAAQ,EACR,eAAe,CAChB,CAAC;wBACF,IAAI,aAAa,EAAE,CAAC;4BAClB,OAAO,GAAG,CAAC,CAAC,CAAC,+CAA+C;4BAC5D,YAAY,GAAG,cAAc,CAAC;4BAC9B,SAAS;wBACX,CAAC;oBACH,CAAC;oBAAC,OAAO,aAAa,EAAE,CAAC;wBACvB,WAAW,CAAC,IAAI,CAAC,iCAAiC,EAAE,aAAa,CAAC,CAAC;oBACrE,CAAC;gBACH,CAAC;gBACD,kEAAkE;gBAClE,MAAM,eAAe,CAAC,CAAC,2CAA2C;YACpE,CAAC;YAED,0EAA0E;YAC1E,IAAI,eAAe,YAAY,uBAAuB,EAAE,CAAC;gBACvD,IAAI,oBAAoB,EAAE,CAAC;oBACzB,IAAI,CAAC;wBACH,MAAM,MAAM,GAAG,MAAM,oBAAoB,CAAC,eAAe,CAAC,CAAC;wBAC3D,IAAI,MAAM,KAAK,QAAQ,EAAE,CAAC;4BACxB,mCAAmC;4BACnC,OAAO,GAAG,CAAC,CAAC;4BACZ,YAAY,GAAG,cAAc,CAAC;4BAC9B,SAAS;wBACX,CAAC;wBACD,wDAAwD;wBACxD,eAAe,CAAC,WAAW,GAAG,IAAI,CAAC;oBACrC,CAAC;oBAAC,OAAO,eAAe,EAAE,CAAC;wBACzB,WAAW,CAAC,IAAI,CAAC,4BAA4B,EAAE,eAAe,CAAC,CAAC;oBAClE,CAAC;gBACH,CAAC;gBACD,MAAM,eAAe,CAAC;YACxB,CAAC;YAED,MAAM,KAAK,GACT,SAAS,KAAK,SAAS,IAAI,SAAS,IAAI,GAAG,IAAI,SAAS,GAAG,GAAG,CAAC;YAEjE,IAAI,eAAe,YAAY,mBAAmB,IAAI,KAAK,EAAE,CAAC;gBAC5D,IAAI,OAAO,IAAI,WAAW,EAAE,CAAC;oBAC3B,MAAM,YAAY,GAChB,eAAe,YAAY,KAAK,CAAC,CAAC,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;oBAClE,WAAW,CAAC,IAAI,CACd,WAAW,OAAO,UAAU,YAAY,CAAC,CAAC,CAAC,KAAK,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,wBAAwB,CAC5F,CAAC;oBACF,IAAI,eAAe,EAAE,CAAC;wBACpB,IAAI,CAAC;4BACH,MAAM,aAAa,GAAG,MAAM,eAAe,CACzC,QAAQ,EACR,eAAe,CAChB,CAAC;4BACF,IAAI,aAAa,EAAE,CAAC;gCAClB,OAAO,GAAG,CAAC,CAAC,CAAC,+CAA+C;gCAC5D,YAAY,GAAG,cAAc,CAAC;gCAC9B,SAAS;4BACX,CAAC;wBACH,CAAC;wBAAC,OAAO,aAAa,EAAE,CAAC;4BACvB,WAAW,CAAC,IAAI,CAAC,wBAAwB,EAAE,aAAa,CAAC,CAAC;wBAC5D,CAAC;oBACH,CAAC;oBACD,MAAM,eAAe,YAAY,mBAAmB;wBAClD,CAAC,CAAC,eAAe;wBACjB,CAAC,CAAC,KAAK,CAAC;gBACZ,CAAC;gBAED,IACE,eAAe,YAAY,mBAAmB;oBAC9C,eAAe,CAAC,YAAY,KAAK,SAAS,EAC1C,CAAC;oBACD,WAAW,CAAC,IAAI,CACd,WAAW,OAAO,YAAY,eAAe,CAAC,OAAO,oBAAoB,eAAe,CAAC,YAAY,OAAO,CAC7G,CAAC;oBACF,IAAI,OAAO,EAAE,CAAC;wBACZ,OAAO,CAAC,OAAO,EAAE,KAAK,EAAE,eAAe,CAAC,YAAY,CAAC,CAAC;oBACxD,CAAC;oBACD,MAAM,KAAK,CAAC,eAAe,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;oBAClD,SAAS;gBACX,CAAC;qBAAM,CAAC;oBACN,MAAM,WAAW,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;oBAC1C,eAAe,CAAC,OAAO,EAAE,KAAK,EAAE,WAAW,CAAC,CAAC;oBAE7C,uDAAuD;oBACvD,MAAM,MAAM,GAAG,YAAY,GAAG,GAAG,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;oBAC5D,MAAM,eAAe,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,YAAY,GAAG,MAAM,CAAC,CAAC;oBAC3D,IAAI,OAAO,EAAE,CAAC;wBACZ,OAAO,CAAC,OAAO,EAAE,KAAK,EAAE,eAAe,CAAC,CAAC;oBAC3C,CAAC;oBACD,MAAM,KAAK,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC;oBACrC,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,YAAY,GAAG,CAAC,CAAC,CAAC;oBACtD,SAAS;gBACX,CAAC;YACH,CAAC;YAED,uCAAuC;YACvC,IACE,OAAO,IAAI,WAAW;gBACtB,CAAC,kBAAkB,CAAC,KAAc,EAAE,gBAAgB,CAAC,EACrD,CAAC;gBACD,MAAM,KAAK,CAAC;YACd,CAAC;YAED,MAAM,WAAW,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;YAC1C,eAAe,CAAC,OAAO,EAAE,KAAK,EAAE,WAAW,CAAC,CAAC;YAE7C,uDAAuD;YACvD,MAAM,MAAM,GAAG,YAAY,GAAG,GAAG,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;YAC5D,MAAM,eAAe,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,YAAY,GAAG,MAAM,CAAC,CAAC;YAC3D,IAAI,OAAO,EAAE,CAAC;gBACZ,OAAO,CAAC,OAAO,EAAE,KAAK,EAAE,eAAe,CAAC,CAAC;YAC3C,CAAC;YACD,MAAM,KAAK,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC;YACrC,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,YAAY,GAAG,CAAC,CAAC,CAAC;QACxD,CAAC;IACH,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,0BAA0B,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;GAKG;AACH,SAAS,eAAe,CACtB,OAAe,EACf,KAAc,EACd,WAAoB;IAEpB,IAAI,OAAO,GAAG,WAAW,OAAO,mCAAmC,CAAC;IACpE,IAAI,WAAW,EAAE,CAAC;QAChB,OAAO,GAAG,WAAW,OAAO,uBAAuB,WAAW,4BAA4B,CAAC;IAC7F,CAAC;IAED,IAAI,WAAW,KAAK,GAAG,EAAE,CAAC;QACxB,WAAW,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IACnC,CAAC;SAAM,IAAI,WAAW,IAAI,WAAW,IAAI,GAAG,IAAI,WAAW,GAAG,GAAG,EAAE,CAAC;QAClE,WAAW,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IACnC,CAAC;SAAM,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAClC,sEAAsE;QACtE,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YAClC,WAAW,CAAC,IAAI,CACd,WAAW,OAAO,0EAA0E,EAC5F,KAAK,CACN,CAAC;QACJ,CAAC;aAAM,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;YACzC,WAAW,CAAC,IAAI,CACd,WAAW,OAAO,kDAAkD,EACpE,KAAK,CACN,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,WAAW,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,mCAAmC;QACvE,CAAC;IACH,CAAC;SAAM,CAAC;QACN,WAAW,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,2CAA2C;IAC/E,CAAC;AACH,CAAC"}

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

@@ -0,0 +1,13 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export declare function safeJsonStringify(obj: unknown, space?: string | number): string;
+/**
+ * Safely stringifies an object to JSON, retaining only non-null, Boolean-valued members.
+ *
+ * @param obj - The object to stringify
+ * @returns JSON string with circular references skipped and only non-null, Boolean member values retained.
+ */
+export declare function safeJsonStringifyBooleanValuesOnly(obj: any): string;

package/dist/src/utils/safeJsonStringify.js

@@ -0,0 +1,49 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export function safeJsonStringify(obj, space) {
+    const seen = new WeakSet();
+    return JSON.stringify(obj, (key, value) => {
+        if (typeof value === 'object' && value !== null) {
+            if (seen.has(value)) {
+                return '[Circular]';
+            }
+            seen.add(value);
+        }
+        return value;
+    }, space);
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function removeEmptyObjects(data) {
+    const cleanedObject = {};
+    for (const k in data) {
+        const v = data[k];
+        if (v !== null && v !== undefined && typeof v === 'boolean') {
+            cleanedObject[k] = v;
+        }
+    }
+    return cleanedObject;
+}
+/**
+ * Safely stringifies an object to JSON, retaining only non-null, Boolean-valued members.
+ *
+ * @param obj - The object to stringify
+ * @returns JSON string with circular references skipped and only non-null, Boolean member values retained.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function safeJsonStringifyBooleanValuesOnly(obj) {
+    let configSeen = false;
+    return JSON.stringify(removeEmptyObjects(obj), (key, value) => {
+        if (value !== null && !configSeen) {
+            configSeen = true;
+            return value;
+        }
+        if (typeof value === 'boolean') {
+            return value;
+        }
+        return '';
+    });
+}
+//# sourceMappingURL=safeJsonStringify.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"safeJsonStringify.js","sourceRoot":"","sources":["../../../src/utils/safeJsonStringify.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAWH,MAAM,UAAU,iBAAiB,CAC/B,GAAY,EACZ,KAAuB;IAEvB,MAAM,IAAI,GAAG,IAAI,OAAO,EAAE,CAAC;IAC3B,OAAO,IAAI,CAAC,SAAS,CACnB,GAAG,EACH,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE;QACb,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YAChD,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;gBACpB,OAAO,YAAY,CAAC;YACtB,CAAC;YACD,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAClB,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC,EACD,KAAK,CACN,CAAC;AACJ,CAAC;AAED,8DAA8D;AAC9D,SAAS,kBAAkB,CAAC,IAAS;IACnC,MAAM,aAAa,GAA+B,EAAE,CAAC;IACrD,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,SAAS,IAAI,OAAO,CAAC,KAAK,SAAS,EAAE,CAAC;YAC5D,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAED,OAAO,aAAa,CAAC;AACvB,CAAC;AAED;;;;;GAKG;AACH,8DAA8D;AAC9D,MAAM,UAAU,kCAAkC,CAAC,GAAQ;IACzD,IAAI,UAAU,GAAG,KAAK,CAAC;IACvB,OAAO,IAAI,CAAC,SAAS,CAAC,kBAAkB,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE;QAC5D,IAAK,KAAgB,KAAK,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YAC9C,UAAU,GAAG,IAAI,CAAC;YAClB,OAAO,KAAK,CAAC;QACf,CAAC;QACD,IAAI,OAAO,KAAK,KAAK,SAAS,EAAE,CAAC;YAC/B,OAAO,KAAK,CAAC;QACf,CAAC;QACD,OAAO,EAAE,CAAC;IACZ,CAAC,CAAC,CAAC;AACL,CAAC"}

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

@@ -0,0 +1,21 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { type AnySchema } from 'ajv';
+/**
+ * Simple utility to validate objects against JSON Schemas
+ */
+export declare class SchemaValidator {
+    /**
+     * Returns null if the data conforms to the schema described by schema (or if schema
+     *  is null). Otherwise, returns a string describing the error.
+     */
+    static validate(schema: unknown | undefined, data: unknown): string | null;
+    /**
+     * Validates a JSON schema itself. Returns null if the schema is valid,
+     * otherwise returns a string describing the validation errors.
+     */
+    static validateSchema(schema: AnySchema | undefined): string | null;
+}

package/dist/src/utils/schemaValidator.js

@@ -0,0 +1,59 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import AjvPkg, {} from 'ajv';
+import * as addFormats from 'ajv-formats';
+// Ajv's ESM/CJS interop: use 'any' for compatibility as recommended by Ajv docs
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const AjvClass = AjvPkg.default || AjvPkg;
+const ajValidator = new AjvClass(
+// See: https://ajv.js.org/options.html#strict-mode-options
+{
+    // strictSchema defaults to true and prevents use of JSON schemas that
+    // include unrecognized keywords. The JSON schema spec specifically allows
+    // for the use of non-standard keywords and the spec-compliant behavior
+    // is to ignore those keywords. Note that setting this to false also
+    // allows use of non-standard or custom formats (the unknown format value
+    // will be logged but the schema will still be considered valid).
+    strictSchema: false,
+});
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const addFormatsFunc = addFormats.default || addFormats;
+addFormatsFunc(ajValidator);
+/**
+ * Simple utility to validate objects against JSON Schemas
+ */
+export class SchemaValidator {
+    /**
+     * Returns null if the data conforms to the schema described by schema (or if schema
+     *  is null). Otherwise, returns a string describing the error.
+     */
+    static validate(schema, data) {
+        if (!schema) {
+            return null;
+        }
+        if (typeof data !== 'object' || data === null) {
+            return 'Value of params must be an object';
+        }
+        const validate = ajValidator.compile(schema);
+        const valid = validate(data);
+        if (!valid && validate.errors) {
+            return ajValidator.errorsText(validate.errors, { dataVar: 'params' });
+        }
+        return null;
+    }
+    /**
+     * Validates a JSON schema itself. Returns null if the schema is valid,
+     * otherwise returns a string describing the validation errors.
+     */
+    static validateSchema(schema) {
+        if (!schema) {
+            return null;
+        }
+        const isValid = ajValidator.validateSchema(schema);
+        return isValid ? null : ajValidator.errorsText(ajValidator.errors);
+    }
+}
+//# sourceMappingURL=schemaValidator.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schemaValidator.js","sourceRoot":"","sources":["../../../src/utils/schemaValidator.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,MAAM,EAAE,EAAkB,MAAM,KAAK,CAAC;AAC7C,OAAO,KAAK,UAAU,MAAM,aAAa,CAAC;AAC1C,gFAAgF;AAChF,8DAA8D;AAC9D,MAAM,QAAQ,GAAI,MAAc,CAAC,OAAO,IAAI,MAAM,CAAC;AACnD,MAAM,WAAW,GAAG,IAAI,QAAQ;AAC9B,2DAA2D;AAC3D;IACE,sEAAsE;IACtE,0EAA0E;IAC1E,uEAAuE;IACvE,oEAAoE;IACpE,yEAAyE;IACzE,iEAAiE;IACjE,YAAY,EAAE,KAAK;CACpB,CACF,CAAC;AACF,8DAA8D;AAC9D,MAAM,cAAc,GAAI,UAAkB,CAAC,OAAO,IAAI,UAAU,CAAC;AACjE,cAAc,CAAC,WAAW,CAAC,CAAC;AAE5B;;GAEG;AACH,MAAM,OAAO,eAAe;IAC1B;;;OAGG;IACH,MAAM,CAAC,QAAQ,CAAC,MAA2B,EAAE,IAAa;QACxD,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,IAAI,CAAC;QACd,CAAC;QACD,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YAC9C,OAAO,mCAAmC,CAAC;QAC7C,CAAC;QACD,MAAM,QAAQ,GAAG,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAC7C,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC7B,IAAI,CAAC,KAAK,IAAI,QAAQ,CAAC,MAAM,EAAE,CAAC;YAC9B,OAAO,WAAW,CAAC,UAAU,CAAC,QAAQ,CAAC,MAAM,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAC;QACxE,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,cAAc,CAAC,MAA6B;QACjD,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,IAAI,CAAC;QACd,CAAC;QACD,MAAM,OAAO,GAAG,WAAW,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;QACnD,OAAO,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC,UAAU,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IACrE,CAAC;CACF"}

package/dist/src/utils/secure-browser-launcher.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Opens a URL in the default browser using platform-specific commands.
+ * This implementation avoids shell injection vulnerabilities by:
+ * 1. Validating the URL to ensure it's HTTP/HTTPS only
+ * 2. Using execFile instead of exec to avoid shell interpretation
+ * 3. Passing the URL as an argument rather than constructing a command string
+ *
+ * @param url The URL to open
+ * @throws Error if the URL is invalid or if opening the browser fails
+ */
+export declare function openBrowserSecurely(url: string): Promise<void>;
+/**
+ * Checks if the current environment should attempt to launch a browser.
+ * This is the same logic as in browser.ts for consistency.
+ *
+ * @returns True if the tool should attempt to launch a browser
+ */
+export declare function shouldLaunchBrowser(): boolean;

package/dist/src/utils/secure-browser-launcher.js

@@ -0,0 +1,165 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { platform } from 'node:os';
+import { URL } from 'node:url';
+const execFileAsync = promisify(execFile);
+/**
+ * Validates that a URL is safe to open in a browser.
+ * Only allows HTTP and HTTPS URLs to prevent command injection.
+ *
+ * @param url The URL to validate
+ * @throws Error if the URL is invalid or uses an unsafe protocol
+ */
+function validateUrl(url) {
+    let parsedUrl;
+    try {
+        parsedUrl = new URL(url);
+    }
+    catch (_error) {
+        throw new Error(`Invalid URL: ${url}`);
+    }
+    // Only allow HTTP and HTTPS protocols
+    if (parsedUrl.protocol !== 'http:' && parsedUrl.protocol !== 'https:') {
+        throw new Error(`Unsafe protocol: ${parsedUrl.protocol}. Only HTTP and HTTPS are allowed.`);
+    }
+    // Additional validation: ensure no newlines or control characters
+    // eslint-disable-next-line no-control-regex
+    if (/[\r\n\x00-\x1f]/.test(url)) {
+        throw new Error('URL contains invalid characters');
+    }
+}
+/**
+ * Opens a URL in the default browser using platform-specific commands.
+ * This implementation avoids shell injection vulnerabilities by:
+ * 1. Validating the URL to ensure it's HTTP/HTTPS only
+ * 2. Using execFile instead of exec to avoid shell interpretation
+ * 3. Passing the URL as an argument rather than constructing a command string
+ *
+ * @param url The URL to open
+ * @throws Error if the URL is invalid or if opening the browser fails
+ */
+export async function openBrowserSecurely(url) {
+    // Validate the URL first
+    validateUrl(url);
+    const platformName = platform();
+    let command;
+    let args;
+    switch (platformName) {
+        case 'darwin':
+            // macOS
+            command = 'open';
+            args = [url];
+            break;
+        case 'win32':
+            // Windows - use PowerShell with Start-Process
+            // This avoids the cmd.exe shell which is vulnerable to injection
+            command = 'powershell.exe';
+            args = [
+                '-NoProfile',
+                '-NonInteractive',
+                '-WindowStyle',
+                'Hidden',
+                '-Command',
+                `Start-Process '${url.replace(/'/g, "''")}'`,
+            ];
+            break;
+        case 'linux':
+        case 'freebsd':
+        case 'openbsd':
+            // Linux and BSD variants
+            // Try xdg-open first, fall back to other options
+            command = 'xdg-open';
+            args = [url];
+            break;
+        default:
+            throw new Error(`Unsupported platform: ${platformName}`);
+    }
+    const options = {
+        // Don't inherit parent's environment to avoid potential issues
+        env: {
+            ...process.env,
+            // Ensure we're not in a shell that might interpret special characters
+            SHELL: undefined,
+        },
+        // Detach the browser process so it doesn't block
+        detached: true,
+        stdio: 'ignore',
+    };
+    try {
+        await execFileAsync(command, args, options);
+    }
+    catch (error) {
+        // For Linux, try fallback commands if xdg-open fails
+        if ((platformName === 'linux' ||
+            platformName === 'freebsd' ||
+            platformName === 'openbsd') &&
+            command === 'xdg-open') {
+            const fallbackCommands = [
+                'gnome-open',
+                'kde-open',
+                'firefox',
+                'chromium',
+                'google-chrome',
+            ];
+            for (const fallbackCommand of fallbackCommands) {
+                try {
+                    await execFileAsync(fallbackCommand, [url], options);
+                    return; // Success!
+                }
+                catch {
+                    // Try next command
+                    continue;
+                }
+            }
+        }
+        // Re-throw the error if all attempts failed
+        throw new Error(`Failed to open browser: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+}
+/**
+ * Checks if the current environment should attempt to launch a browser.
+ * This is the same logic as in browser.ts for consistency.
+ *
+ * @returns True if the tool should attempt to launch a browser
+ */
+export function shouldLaunchBrowser() {
+    // A list of browser names that indicate we should not attempt to open a
+    // web browser for the user.
+    const browserBlocklist = ['www-browser'];
+    const browserEnv = process.env['BROWSER'];
+    if (browserEnv && browserBlocklist.includes(browserEnv)) {
+        return false;
+    }
+    // Common environment variables used in CI/CD or other non-interactive shells.
+    if (process.env['CI'] ||
+        process.env['DEBIAN_FRONTEND'] === 'noninteractive') {
+        return false;
+    }
+    // The presence of SSH_CONNECTION indicates a remote session.
+    // We should not attempt to launch a browser unless a display is explicitly available
+    // (checked below for Linux).
+    const isSSH = !!process.env['SSH_CONNECTION'];
+    // On Linux, the presence of a display server is a strong indicator of a GUI.
+    if (platform() === 'linux') {
+        // These are environment variables that can indicate a running compositor on Linux.
+        const displayVariables = ['DISPLAY', 'WAYLAND_DISPLAY', 'MIR_SOCKET'];
+        const hasDisplay = displayVariables.some((v) => !!process.env[v]);
+        if (!hasDisplay) {
+            return false;
+        }
+    }
+    // If in an SSH session on a non-Linux OS (e.g., macOS), don't launch browser.
+    // The Linux case is handled above (it's allowed if DISPLAY is set).
+    if (isSSH && platform() !== 'linux') {
+        return false;
+    }
+    // For non-Linux OSes, we generally assume a GUI is available
+    // unless other signals (like SSH) suggest otherwise.
+    return true;
+}
+//# sourceMappingURL=secure-browser-launcher.js.map

package/dist/src/utils/secure-browser-launcher.js.map

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

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

@@ -0,0 +1,16 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export interface SecurityCheckResult {
+    secure: boolean;
+    reason?: string;
+}
+/**
+ * Verifies if a directory is secure (owned by root and not writable by others).
+ *
+ * @param dirPath The path to the directory to check.
+ * @returns A promise that resolves to a SecurityCheckResult.
+ */
+export declare function isDirectorySecure(dirPath: string): Promise<SecurityCheckResult>;