@juspay/neurolink 10.12.9 → 11.1.0

package/dist/lib/providers/googleVertex/client.js

@@ -2,7 +2,6 @@
 // Native SDK imports - no more @ai-sdk/google-vertex dependency
 import fs from "fs";
 import path from "path";
-import os from "os";
 import { AIProviderName, ErrorCategory, ErrorSeverity, } from "../../constants/enums.js";
 import { BaseProvider } from "../../core/baseProvider.js";
 import { unwrapImagePayload } from "../../adapters/imageFormatSupport.js";
@@ -14,6 +13,7 @@ import { isSchemaComplexityError } from "../../core/modules/structuredOutputPoli
 import { redactUrlForError, stringifyContentSafe, } from "../../utils/logSanitize.js";
 import { createProxyFetch } from "../../proxy/proxyFetch.js";
 import { AuthenticationError, InvalidModelError, NetworkError, ProviderError, RateLimitError, } from "../../types/index.js";
+import { classifyProviderError } from "../../utils/errorClassifier.js";
 import { ERROR_CODES, NeuroLinkError } from "../../utils/errorHandling.js";
 import { applyVertexAnthropicCacheBreakpoints } from "../../utils/anthropicCacheBreakpoints.js";
 import { FileDetector } from "../../utils/fileDetector.js";
@@ -368,167 +368,6 @@ const hasGoogleCredentials = () => {
         (process.env.GOOGLE_AUTH_CLIENT_EMAIL &&
             process.env.GOOGLE_AUTH_PRIVATE_KEY));
 };
-// Cache the runtime-created credentials file path so we don't write a new file
-// on every settings creation (which would leak files in /tmp). The file is also
-// cleaned up on process exit.
-let cachedRuntimeCredentialsFile = null;
-let credentialsCleanupRegistered = false;
-const registerCredentialsCleanup = (filePath) => {
-    if (credentialsCleanupRegistered) {
-        return;
-    }
-    credentialsCleanupRegistered = true;
-    const cleanup = () => {
-        try {
-            if (fs.existsSync(filePath)) {
-                fs.unlinkSync(filePath);
-            }
-        }
-        catch {
-            // Ignore cleanup errors — best-effort
-        }
-    };
-    process.once("exit", cleanup);
-    process.once("SIGINT", () => {
-        cleanup();
-        process.exit(130);
-    });
-    process.once("SIGTERM", () => {
-        cleanup();
-        process.exit(143);
-    });
-};
-// Enhanced Vertex settings creation with authentication fallback and proxy support
-const createVertexSettings = async (region) => {
-    const location = region || getVertexLocation();
-    const project = getVertexProjectId();
-    const baseSettings = {
-        project,
-        location,
-        fetch: createProxyFetch(),
-    };
-    // Note: Global endpoint handling is managed by the @google/genai SDK based on location parameter.
-    // Authentication is handled via GOOGLE_APPLICATION_CREDENTIALS environment variable
-    // or the temporary credentials file approach below.
-    // 🎯 OPTION 2: Create credentials file from environment variables at runtime
-    // This solves the problem where GOOGLE_APPLICATION_CREDENTIALS exists in ZSHRC locally
-    // but the file doesn't exist on production servers
-    // First, try to create credentials file from individual environment variables
-    const requiredEnvVarsForFile = {
-        type: process.env.GOOGLE_AUTH_TYPE,
-        project_id: process.env.GOOGLE_AUTH_BREEZE_PROJECT_ID,
-        private_key: process.env.GOOGLE_AUTH_PRIVATE_KEY,
-        client_email: process.env.GOOGLE_AUTH_CLIENT_EMAIL,
-        client_id: process.env.GOOGLE_AUTH_CLIENT_ID,
-        auth_uri: process.env.GOOGLE_AUTH_AUTH_URI,
-        token_uri: process.env.GOOGLE_AUTH_TOKEN_URI,
-        auth_provider_x509_cert_url: process.env.GOOGLE_AUTH_AUTH_PROVIDER_CERT_URL,
-        client_x509_cert_url: process.env.GOOGLE_AUTH_CLIENT_CERT_URL,
-        universe_domain: process.env.GOOGLE_AUTH_UNIVERSE_DOMAIN,
-    };
-    // If we have the essential fields, create a runtime credentials file
-    // (or reuse the one we already wrote earlier in this process)
-    if (requiredEnvVarsForFile.client_email &&
-        requiredEnvVarsForFile.private_key) {
-        try {
-            // Reuse cached file if it still exists on disk
-            if (cachedRuntimeCredentialsFile &&
-                fs.existsSync(cachedRuntimeCredentialsFile)) {
-                process.env.GOOGLE_APPLICATION_CREDENTIALS =
-                    cachedRuntimeCredentialsFile;
-                return baseSettings;
-            }
-            // Build complete service account credentials object
-            const serviceAccountCredentials = {
-                type: requiredEnvVarsForFile.type || "service_account",
-                project_id: requiredEnvVarsForFile.project_id || getVertexProjectId(),
-                private_key: requiredEnvVarsForFile.private_key.replace(/\\n/g, "\n"),
-                client_email: requiredEnvVarsForFile.client_email,
-                client_id: requiredEnvVarsForFile.client_id || "",
-                auth_uri: requiredEnvVarsForFile.auth_uri ||
-                    "https://accounts.google.com/o/oauth2/auth",
-                token_uri: requiredEnvVarsForFile.token_uri ||
-                    "https://oauth2.googleapis.com/token",
-                auth_provider_x509_cert_url: requiredEnvVarsForFile.auth_provider_x509_cert_url ||
-                    "https://www.googleapis.com/oauth2/v1/certs",
-                client_x509_cert_url: requiredEnvVarsForFile.client_x509_cert_url || "",
-                universe_domain: requiredEnvVarsForFile.universe_domain || "googleapis.com",
-            };
-            // Create temporary credentials file (once per process)
-            const tmpDir = os.tmpdir();
-            const credentialsFileName = `google-credentials-${Date.now()}-${Math.random().toString(36).substring(2, 11)}.json`;
-            const credentialsFilePath = path.join(tmpDir, credentialsFileName);
-            fs.writeFileSync(credentialsFilePath, JSON.stringify(serviceAccountCredentials, null, 2), 
-            // Owner read/write only — credentials should not be world-readable
-            { mode: 0o600 });
-            // Set the environment variable to point to our runtime-created file
-            process.env.GOOGLE_APPLICATION_CREDENTIALS = credentialsFilePath;
-            cachedRuntimeCredentialsFile = credentialsFilePath;
-            registerCredentialsCleanup(credentialsFilePath);
-            // Now continue with the normal flow - check if the file exists
-            const fileExists = fs.existsSync(credentialsFilePath);
-            if (fileExists) {
-                return baseSettings;
-            }
-        }
-        catch {
-            // Silent error handling for runtime credentials file creation
-        }
-    }
-    // 🎯 OPTION 1: Check for principal account authentication (Accept any valid GOOGLE_APPLICATION_CREDENTIALS file (service account OR ADC))
-    if (process.env.GOOGLE_APPLICATION_CREDENTIALS_NEUROLINK) {
-        const credentialsPath = process.env.GOOGLE_APPLICATION_CREDENTIALS_NEUROLINK;
-        // Check if the credentials file exists
-        let fileExists = false;
-        try {
-            fileExists = fs.existsSync(credentialsPath);
-        }
-        catch {
-            // fileExists remains false
-        }
-        if (fileExists) {
-            return baseSettings;
-        }
-    }
-    else {
-        if (process.env.GOOGLE_APPLICATION_CREDENTIALS) {
-            const credentialsPath = process.env.GOOGLE_APPLICATION_CREDENTIALS;
-            // Check if the credentials file exists
-            let fileExists = false;
-            try {
-                fileExists = fs.existsSync(credentialsPath);
-            }
-            catch {
-                // fileExists remains false
-            }
-            if (fileExists) {
-                return baseSettings;
-            }
-        }
-    }
-    // Log warning if no valid authentication is available
-    // Note: Authentication is handled via GOOGLE_APPLICATION_CREDENTIALS environment variable
-    // or the temporary credentials file approach (OPTION 2 above).
-    logger.warn("No valid authentication found for Google Vertex AI", {
-        authMethod: "none",
-        authenticationAttempts: {
-            principalAccountFile: {
-                envVarSet: !!process.env.GOOGLE_APPLICATION_CREDENTIALS,
-                filePath: process.env.GOOGLE_APPLICATION_CREDENTIALS || "NOT_SET",
-                fileExists: false, // We already checked above
-            },
-            explicitCredentials: {
-                hasClientEmail: !!process.env.GOOGLE_AUTH_CLIENT_EMAIL,
-                hasPrivateKey: !!process.env.GOOGLE_AUTH_PRIVATE_KEY,
-            },
-        },
-        troubleshooting: [
-            "1. Ensure GOOGLE_APPLICATION_CREDENTIALS points to an existing file, OR",
-            "2. Set individual environment variables: GOOGLE_AUTH_CLIENT_EMAIL and GOOGLE_AUTH_PRIVATE_KEY",
-        ],
-    });
-    return baseSettings;
-};
 // Create Anthropic-specific Vertex settings for native @anthropic-ai/vertex-sdk
 const createVertexAnthropicSettings = async (region, timeoutMs) => {
     const location = region || getVertexLocation();
@@ -805,209 +644,6 @@ export class GoogleVertexProvider extends BaseProvider {
             context: { provider: this.providerName, model: this.modelName },
         });
     }
-    /**
-     * Initialize model creation tracking
-     */
-    initializeModelCreationLogging() {
-        const modelCreationId = `vertex-model-${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
-        const modelCreationStartTime = Date.now();
-        const modelCreationHrTimeStart = process.hrtime.bigint();
-        const modelName = this.modelName || getDefaultVertexModel();
-        return {
-            modelCreationId,
-            modelCreationStartTime,
-            modelCreationHrTimeStart,
-            modelName,
-        };
-    }
-    /**
-     * Check if model is Anthropic-based and attempt creation
-     */
-    async attemptAnthropicModelCreation(modelName, modelCreationId, modelCreationStartTime, modelCreationHrTimeStart) {
-        const isAnthropic = isAnthropicModel(modelName);
-        if (!isAnthropic) {
-            return null;
-        }
-        logger.debug("Creating Anthropic model using vertexAnthropic provider", {
-            modelName,
-        });
-        if (!hasAnthropicSupport()) {
-            logger.warn(`[GoogleVertexProvider] Anthropic support not available, falling back to Google model`);
-            return null;
-        }
-        try {
-            const anthropicModel = await this.createAnthropicModel(modelName);
-            if (anthropicModel) {
-                return anthropicModel;
-            }
-            // Anthropic model creation returned null, falling back to Google model
-        }
-        catch (error) {
-            logger.error(`[GoogleVertexProvider] ❌ LOG_POINT_V006_ANTHROPIC_MODEL_ERROR`, {
-                logPoint: "V006_ANTHROPIC_MODEL_ERROR",
-                modelCreationId,
-                timestamp: new Date().toISOString(),
-                elapsedMs: Date.now() - modelCreationStartTime,
-                elapsedNs: (process.hrtime.bigint() - modelCreationHrTimeStart).toString(),
-                modelName,
-                error: error instanceof Error ? error.message : String(error),
-                errorName: error instanceof Error ? error.name : "UnknownError",
-                errorStack: error instanceof Error ? error.stack : undefined,
-                fallbackToGoogle: true,
-                message: "Anthropic model creation failed - falling back to Google model",
-            });
-        }
-        // Fall back to regular model if Anthropic not available
-        logger.warn(`Anthropic model ${modelName} requested but not available, falling back to Google model`);
-        return null;
-    }
-    /**
-     * Create Google Vertex model with comprehensive logging and error handling
-     */
-    async createGoogleVertexModel(modelName, modelCreationId, modelCreationStartTime, modelCreationHrTimeStart) {
-        logger.debug("Creating Google Vertex model", {
-            modelName,
-            project: this.projectId,
-            location: this.location,
-        });
-        const vertexSettingsStartTime = process.hrtime.bigint();
-        logger.debug(`[GoogleVertexProvider] ⚙️ LOG_POINT_V008_VERTEX_SETTINGS_START`, {
-            logPoint: "V008_VERTEX_SETTINGS_START",
-            modelCreationId,
-            timestamp: new Date().toISOString(),
-            elapsedMs: Date.now() - modelCreationStartTime,
-            elapsedNs: (process.hrtime.bigint() - modelCreationHrTimeStart).toString(),
-            vertexSettingsStartTimeNs: vertexSettingsStartTime.toString(),
-            // Network configuration analysis
-            networkConfig: {
-                projectId: this.projectId,
-                location: this.location,
-                expectedEndpoint: `https://${this.location}-aiplatform.googleapis.com`,
-                httpProxy: process.env.HTTP_PROXY || process.env.http_proxy,
-                httpsProxy: process.env.HTTPS_PROXY || process.env.https_proxy,
-                noProxy: process.env.NO_PROXY || process.env.no_proxy,
-                proxyConfigured: !!(process.env.HTTP_PROXY ||
-                    process.env.HTTPS_PROXY ||
-                    process.env.http_proxy ||
-                    process.env.https_proxy),
-            },
-            message: "Starting Vertex settings creation with network configuration analysis",
-        });
-        try {
-            const vertexSettings = await createVertexSettings(this.location);
-            const vertexSettingsEndTime = process.hrtime.bigint();
-            const vertexSettingsDurationNs = vertexSettingsEndTime - vertexSettingsStartTime;
-            logger.debug(`[GoogleVertexProvider] ✅ LOG_POINT_V009_VERTEX_SETTINGS_SUCCESS`, {
-                logPoint: "V009_VERTEX_SETTINGS_SUCCESS",
-                modelCreationId,
-                timestamp: new Date().toISOString(),
-                elapsedMs: Date.now() - modelCreationStartTime,
-                elapsedNs: (process.hrtime.bigint() - modelCreationHrTimeStart).toString(),
-                vertexSettingsDurationNs: vertexSettingsDurationNs.toString(),
-                vertexSettingsDurationMs: Number(vertexSettingsDurationNs) / 1000000,
-                // Settings analysis
-                vertexSettingsAnalysis: {
-                    hasSettings: !!vertexSettings,
-                    settingsType: typeof vertexSettings,
-                    settingsKeys: vertexSettings ? Object.keys(vertexSettings) : [],
-                    projectId: vertexSettings?.project,
-                    location: vertexSettings?.location,
-                    hasFetch: !!vertexSettings?.fetch,
-                    settingsSize: vertexSettings
-                        ? JSON.stringify(vertexSettings).length
-                        : 0,
-                },
-                message: "Vertex settings created successfully",
-            });
-            return await this.createVertexInstance(vertexSettings, modelName, modelCreationId, modelCreationStartTime, modelCreationHrTimeStart);
-        }
-        catch (error) {
-            const vertexSettingsErrorTime = process.hrtime.bigint();
-            const vertexSettingsDurationNs = vertexSettingsErrorTime - vertexSettingsStartTime;
-            const totalErrorDurationNs = vertexSettingsErrorTime - modelCreationHrTimeStart;
-            logger.error(`[GoogleVertexProvider] ❌ LOG_POINT_V014_VERTEX_SETTINGS_ERROR`, {
-                logPoint: "V014_VERTEX_SETTINGS_ERROR",
-                modelCreationId,
-                timestamp: new Date().toISOString(),
-                totalElapsedMs: Date.now() - modelCreationStartTime,
-                totalElapsedNs: totalErrorDurationNs.toString(),
-                totalErrorDurationMs: Number(totalErrorDurationNs) / 1000000,
-                vertexSettingsDurationNs: vertexSettingsDurationNs.toString(),
-                vertexSettingsDurationMs: Number(vertexSettingsDurationNs) / 1000000,
-                // Comprehensive error analysis
-                error: error instanceof Error ? error.message : String(error),
-                errorName: error instanceof Error ? error.name : "UnknownError",
-                errorStack: error instanceof Error ? error.stack : undefined,
-                // Network diagnostic information
-                networkDiagnostics: {
-                    errorCode: error?.code || "UNKNOWN",
-                    errorErrno: error?.errno || "UNKNOWN",
-                    errorAddress: error?.address || "UNKNOWN",
-                    errorPort: error?.port || "UNKNOWN",
-                    errorSyscall: error?.syscall || "UNKNOWN",
-                    errorHostname: error?.hostname || "UNKNOWN",
-                    isTimeoutError: error instanceof Error &&
-                        (error.message.includes("timeout") ||
-                            error.message.includes("ETIMEDOUT")),
-                    isNetworkError: error instanceof Error &&
-                        (error.message.includes("ENOTFOUND") ||
-                            error.message.includes("ECONNREFUSED") ||
-                            error.message.includes("ETIMEDOUT")),
-                    isAuthError: error instanceof Error &&
-                        (error.message.includes("PERMISSION_DENIED") ||
-                            error.message.includes("401") ||
-                            error.message.includes("403")),
-                    infrastructureIssue: error instanceof Error &&
-                        error.message.includes("ETIMEDOUT") &&
-                        error.message.includes("aiplatform.googleapis.com"),
-                },
-                // Environment at error time
-                errorEnvironment: {
-                    httpProxy: process.env.HTTP_PROXY || process.env.http_proxy,
-                    httpsProxy: process.env.HTTPS_PROXY || process.env.https_proxy,
-                    googleAppCreds: process.env.GOOGLE_APPLICATION_CREDENTIALS_NEUROLINK ||
-                        process.env.GOOGLE_APPLICATION_CREDENTIALS ||
-                        "NOT_SET",
-                    hasGoogleServiceKey: !!process.env.GOOGLE_SERVICE_ACCOUNT_KEY,
-                    nodeVersion: process.version,
-                    memoryUsage: process.memoryUsage(),
-                    uptime: process.uptime(),
-                },
-                message: "Vertex settings creation failed - critical network/authentication error",
-            });
-            throw error;
-        }
-    }
-    /**
-     * @deprecated This method is no longer used. All models now use native SDKs.
-     */
-    async createVertexInstance(_vertexSettings, _modelName, _modelCreationId, _modelCreationStartTime, _modelCreationHrTimeStart) {
-        // This method is dead code - all models now route to native SDK methods.
-        throw new NeuroLinkError({
-            code: ERROR_CODES.INVALID_CONFIGURATION,
-            message: "createVertexInstance is deprecated. Use executeNativeGemini3Stream/Generate or executeNativeAnthropicStream/Generate instead.",
-            category: ErrorCategory.CONFIGURATION,
-            severity: ErrorSeverity.CRITICAL,
-            retriable: false,
-            context: { provider: this.providerName },
-        });
-    }
-    /**
-     * Gets the appropriate model instance (Google or Anthropic)
-     * Uses dual provider architecture for proper model routing
-     * Creates fresh instances for each request to ensure proper authentication
-     */
-    async getModel() {
-        // Initialize logging and setup
-        const { modelCreationId, modelCreationStartTime, modelCreationHrTimeStart, modelName, } = this.initializeModelCreationLogging();
-        // Check if this is an Anthropic model and attempt creation
-        const anthropicModel = await this.attemptAnthropicModelCreation(modelName, modelCreationId, modelCreationStartTime, modelCreationHrTimeStart);
-        if (anthropicModel) {
-            return anthropicModel;
-        }
-        // Fall back to Google Vertex model creation
-        return await this.createGoogleVertexModel(modelName, modelCreationId, modelCreationStartTime, modelCreationHrTimeStart);
-    }
     // executeGenerate removed - BaseProvider handles all generation with tools
     /**
      * Validate stream options
@@ -6463,110 +6099,117 @@ export class GoogleVertexProvider extends BaseProvider {
     }
     formatProviderError(error) {
         const errorRecord = error;
-        if (typeof errorRecord?.name === "string" &&
-            errorRecord.name === "TimeoutError") {
-            return new NetworkError(`Google Vertex AI request timed out. Consider increasing timeout or using a lighter model.`, this.providerName);
-        }
-        const message = typeof errorRecord?.message === "string"
-            ? errorRecord.message
-            : "Unknown error occurred";
         const statusCode = typeof errorRecord?.status === "number"
             ? errorRecord.status
             : typeof errorRecord?.statusCode === "number"
                 ? errorRecord.statusCode
                 : undefined;
-        // Authentication and permission errors
-        if (message.includes("PERMISSION_DENIED") ||
-            message.includes("UNAUTHENTICATED") ||
-            message.includes("Invalid API key") ||
-            statusCode === 401 ||
-            statusCode === 403) {
-            return new AuthenticationError(`Google Vertex AI Permission Denied. Your Google Cloud credentials don't have permission to access Vertex AI. ` +
-                `Required Steps: 1. Ensure your service account has Vertex AI User role ` +
-                `2. Check if Vertex AI API is enabled in your project ` +
-                `3. Verify your project ID is correct ` +
-                `4. Confirm your location/region has Vertex AI available`, this.providerName);
-        }
-        // Model not found errors
-        if (message.includes("NOT_FOUND") ||
-            message.includes("model not found") ||
-            message.includes("Model not found") ||
-            statusCode === 404) {
-            const modelSuggestions = this.getModelSuggestions(this.modelName);
-            return new InvalidModelError(`Model '${this.modelName}' is not available in region ${this.location}. ` +
-                `Suggested alternatives: ${modelSuggestions}. ` +
-                `Troubleshooting: 1. Check model name spelling and format ` +
-                `2. Verify model is available in your region ` +
-                `3. Ensure your project has access to the model ` +
-                `4. For Claude models, enable Anthropic integration in Google Cloud Console`, this.providerName);
-        }
-        // Rate limit / quota / capacity errors. Anthropic-on-Vertex capacity
-        // exhaustion surfaces as overloaded_error (HTTP 529) — same operational
-        // meaning as a 429, so classify it here instead of the generic 5xx branch.
-        if (message.includes("QUOTA_EXCEEDED") ||
-            message.includes("RATE_LIMIT_EXCEEDED") ||
-            message.includes("rate limit") ||
-            message.includes("429") ||
-            statusCode === 429 ||
-            statusCode === 529 ||
-            /overloaded/i.test(message)) {
-            // Surface retry guidance when the SDK error carries it. @google/genai
-            // ApiError nests RetryInfo inside the JSON error body's details array,
-            // so fall back to scraping retryDelay out of the raw message.
-            const retryDelay = typeof errorRecord?.retryDelay === "string"
-                ? errorRecord.retryDelay
-                : (/["']?retryDelay["']?\s*[:=]\s*["']?(\d+(?:\.\d+)?s)/.exec(message)?.[1] ?? undefined);
-            // Prefer the per-request context the native catches attach to the
-            // error (this.modelName can be stale when options.model overrides the
-            // instance default). Gemini models are force-routed to the "global"
-            // endpoint regardless of configured location — report the region the
-            // request actually hit.
-            const requestModel = typeof errorRecord?.requestModel === "string"
-                ? errorRecord.requestModel
-                : this.modelName;
-            const effectiveRegion = typeof errorRecord?.requestRegion === "string"
-                ? errorRecord.requestRegion
-                : resolveVertexRegionForModel(requestModel, this.location);
-            return new RateLimitError(`Google Vertex AI rate limit / shared-capacity exhausted (429 RESOURCE_EXHAUSTED / overloaded) ` +
-                `for model '${requestModel}' in region '${effectiveRegion}'.` +
-                (retryDelay
-                    ? ` Upstream suggests retrying after ${retryDelay}.`
-                    : "") +
-                ` Solutions: 1. Retry with backoff ` +
-                `2. Check your Vertex AI quotas in Google Cloud Console (shared-capacity 429s can occur below quota) ` +
-                `3. Try a different region or model ` +
-                `4. Request provisioned throughput for sustained load`, this.providerName);
-        }
-        // Network connectivity errors
-        if (message.includes("ECONNRESET") ||
-            message.includes("ENOTFOUND") ||
-            message.includes("ETIMEDOUT") ||
-            message.includes("ECONNREFUSED") ||
-            message.includes("network") ||
-            message.includes("connection")) {
-            return new NetworkError(`Connection error: ${message}`, this.providerName);
-        }
-        // Server errors (5xx)
-        if (message.includes("500") ||
-            message.includes("502") ||
-            message.includes("503") ||
-            message.includes("504") ||
-            message.includes("server error") ||
-            message.includes("Internal Server Error") ||
-            message.includes("INTERNAL") ||
-            message.includes("UNAVAILABLE") ||
-            (statusCode && statusCode >= 500 && statusCode < 600)) {
-            return new ProviderError(`Google Vertex AI server error: ${message}. Please try again later.`, this.providerName);
-        }
-        // Invalid argument errors
-        if (message.includes("INVALID_ARGUMENT")) {
-            return new ProviderError(`Google Vertex AI Invalid Request: ${message}. ` +
-                `Check: 1. Request parameters are within model limits ` +
-                `2. Input text is properly formatted ` +
-                `3. Temperature and other settings are valid ` +
-                `4. Model supports your request type`, this.providerName);
-        }
-        return new ProviderError(`Google Vertex AI error: ${message}`, this.providerName);
+        const rules = [
+            {
+                // Duck-typed on .name rather than `instanceof TimeoutError` —
+                // Vertex's own `withTimeout` (../../utils/async/index.js) throws a
+                // TimeoutError class distinct from the one classifyProviderError's
+                // built-in fast path checks (../../utils/timeout.js), so that fast
+                // path never fires for a real Vertex timeout. This rule preserves
+                // the pre-migration duck-typed match (both classes set
+                // `.name = "TimeoutError"`) and the original Vertex-specific
+                // message — see task-4-report.md for the full writeup.
+                match: (ctx) => ctx.errorName === "TimeoutError",
+                errorClass: NetworkError,
+                message: "Google Vertex AI request timed out. Consider increasing timeout or using a lighter model.",
+            },
+            {
+                match: (ctx) => /PERMISSION_DENIED|UNAUTHENTICATED|Invalid API key/i.test(ctx.message) ||
+                    statusCode === 401 ||
+                    statusCode === 403,
+                errorClass: AuthenticationError,
+                message: () => `Google Vertex AI Permission Denied. Your Google Cloud credentials don't have permission to access Vertex AI. ` +
+                    `Required Steps: 1. Ensure your service account has Vertex AI User role ` +
+                    `2. Check if Vertex AI API is enabled in your project ` +
+                    `3. Verify your project ID is correct ` +
+                    `4. Confirm your location/region has Vertex AI available`,
+            },
+            {
+                match: (ctx) => /NOT_FOUND|model not found|Model not found/i.test(ctx.message) ||
+                    statusCode === 404,
+                errorClass: InvalidModelError,
+                message: () => {
+                    const modelSuggestions = this.getModelSuggestions(this.modelName);
+                    return (`Model '${this.modelName}' is not available in region ${this.location}. ` +
+                        `Suggested alternatives: ${modelSuggestions}. ` +
+                        `Troubleshooting: 1. Check model name spelling and format ` +
+                        `2. Verify model is available in your region ` +
+                        `3. Ensure your project has access to the model ` +
+                        `4. For Claude models, enable Anthropic integration in Google Cloud Console`);
+                },
+            },
+            {
+                // Rate limit / quota / capacity errors. Anthropic-on-Vertex capacity
+                // exhaustion surfaces as overloaded_error (HTTP 529) — same
+                // operational meaning as a 429, so classify it here instead of the
+                // generic 5xx branch below.
+                match: (ctx) => /QUOTA_EXCEEDED|RATE_LIMIT_EXCEEDED|rate limit|429/i.test(ctx.message) ||
+                    statusCode === 429 ||
+                    statusCode === 529 ||
+                    /overloaded/i.test(ctx.message),
+                errorClass: RateLimitError,
+                message: (ctx) => {
+                    // Surface retry guidance when the SDK error carries it.
+                    // @google/genai ApiError nests RetryInfo inside the JSON error
+                    // body's details array, so fall back to scraping retryDelay out
+                    // of the raw message.
+                    const retryDelay = typeof errorRecord?.retryDelay === "string"
+                        ? errorRecord.retryDelay
+                        : (/["']?retryDelay["']?\s*[:=]\s*["']?(\d+(?:\.\d+)?s)/.exec(ctx.message)?.[1] ?? undefined);
+                    // Prefer the per-request context the native catches attach to the
+                    // error (this.modelName can be stale when options.model overrides
+                    // the instance default). Gemini models are force-routed to the
+                    // "global" endpoint regardless of configured location — report
+                    // the region the request actually hit.
+                    const requestModel = typeof errorRecord?.requestModel === "string"
+                        ? errorRecord.requestModel
+                        : this.modelName;
+                    const effectiveRegion = typeof errorRecord?.requestRegion === "string"
+                        ? errorRecord.requestRegion
+                        : resolveVertexRegionForModel(requestModel, this.location);
+                    return (`Google Vertex AI rate limit / shared-capacity exhausted (429 RESOURCE_EXHAUSTED / overloaded) ` +
+                        `for model '${requestModel}' in region '${effectiveRegion}'.` +
+                        (retryDelay
+                            ? ` Upstream suggests retrying after ${retryDelay}.`
+                            : "") +
+                        ` Solutions: 1. Retry with backoff ` +
+                        `2. Check your Vertex AI quotas in Google Cloud Console (shared-capacity 429s can occur below quota) ` +
+                        `3. Try a different region or model ` +
+                        `4. Request provisioned throughput for sustained load`);
+                },
+            },
+            {
+                match: (ctx) => /ECONNRESET|ENOTFOUND|ETIMEDOUT|ECONNREFUSED|network|connection/i.test(ctx.message),
+                errorClass: NetworkError,
+                message: (ctx) => `Connection error: ${ctx.message}`,
+            },
+            {
+                match: (ctx) => /500|502|503|504|server error|Internal Server Error|INTERNAL|UNAVAILABLE/i.test(ctx.message) ||
+                    (statusCode !== undefined && statusCode >= 500 && statusCode < 600),
+                errorClass: ProviderError,
+                message: (ctx) => `Google Vertex AI server error: ${ctx.message}. Please try again later.`,
+            },
+            {
+                match: (ctx) => /INVALID_ARGUMENT/i.test(ctx.message),
+                errorClass: ProviderError,
+                message: (ctx) => `Google Vertex AI Invalid Request: ${ctx.message}. ` +
+                    `Check: 1. Request parameters are within model limits ` +
+                    `2. Input text is properly formatted ` +
+                    `3. Temperature and other settings are valid ` +
+                    `4. Model supports your request type`,
+            },
+            {
+                match: () => true,
+                errorClass: ProviderError,
+                message: (ctx) => `Google Vertex AI error: ${ctx.message}`,
+            },
+        ];
+        return classifyProviderError(error, rules, this.providerName, this.modelName);
     }
     /**
      * Memory-safe cache management for model configurations
@@ -6662,319 +6305,6 @@ export class GoogleVertexProvider extends BaseProvider {
     async hasAnthropicSupport() {
         return hasAnthropicSupport();
     }
-    /**
-     * @deprecated This method is no longer used. Claude models now use native @anthropic-ai/vertex-sdk
-     * via executeNativeAnthropicStream and executeNativeAnthropicGenerate.
-     */
-    async createAnthropicModel(_modelName) {
-        // This method is dead code - all Claude models now route to native SDK methods.
-        // Throwing an error to catch any unexpected calls to this method.
-        throw new NeuroLinkError({
-            code: ERROR_CODES.INVALID_CONFIGURATION,
-            message: "createAnthropicModel is deprecated. Use executeNativeAnthropicStream or executeNativeAnthropicGenerate instead.",
-            category: ErrorCategory.CONFIGURATION,
-            severity: ErrorSeverity.CRITICAL,
-            retriable: false,
-            context: { provider: this.providerName },
-        });
-    }
-    /**
-     * Validate Vertex AI authentication configuration
-     */
-    async validateVertexAuthentication() {
-        const result = {
-            isValid: false,
-            method: "none",
-            issues: [],
-        };
-        try {
-            // Check for service account file authentication (preferred)
-            if (process.env.GOOGLE_APPLICATION_CREDENTIALS_NEUROLINK ||
-                process.env.GOOGLE_APPLICATION_CREDENTIALS) {
-                const credentialsPath = process.env
-                    .GOOGLE_APPLICATION_CREDENTIALS_NEUROLINK
-                    ? process.env.GOOGLE_APPLICATION_CREDENTIALS_NEUROLINK
-                    : process.env.GOOGLE_APPLICATION_CREDENTIALS || "";
-                try {
-                    if (fs.existsSync(credentialsPath)) {
-                        // Validate JSON structure
-                        const credentialsContent = fs.readFileSync(credentialsPath, "utf8");
-                        const credentials = JSON.parse(credentialsContent);
-                        if (credentials.type === "service_account" &&
-                            credentials.project_id &&
-                            credentials.client_email &&
-                            credentials.private_key) {
-                            result.isValid = true;
-                            result.method = "service_account_file";
-                            return result;
-                        }
-                        else if (credentials.client_id &&
-                            credentials.client_secret &&
-                            credentials.refresh_token &&
-                            credentials.type !== "service_account") {
-                            result.isValid = true;
-                            result.method = "application_default_credentials";
-                            return result;
-                        }
-                        else {
-                            result.issues.push("Credentials file missing required fields (not service account or ADC format)");
-                        }
-                    }
-                    else {
-                        result.issues.push(`Service account file not found: ${credentialsPath}`);
-                    }
-                }
-                catch (fileError) {
-                    result.issues.push(`Service account file validation failed: ${fileError}`);
-                }
-            }
-            // Check for individual environment variables
-            if (process.env.GOOGLE_AUTH_CLIENT_EMAIL &&
-                process.env.GOOGLE_AUTH_PRIVATE_KEY) {
-                const email = process.env.GOOGLE_AUTH_CLIENT_EMAIL;
-                const privateKey = process.env.GOOGLE_AUTH_PRIVATE_KEY;
-                if (email.includes("@") && privateKey.includes("BEGIN PRIVATE KEY")) {
-                    result.isValid = true;
-                    result.method = "environment_variables";
-                    return result;
-                }
-                else {
-                    result.issues.push("Individual credentials format validation failed");
-                }
-            }
-            else {
-                result.issues.push("Missing individual credential environment variables");
-            }
-            if (!result.isValid) {
-                result.issues.push("No valid authentication method found");
-            }
-        }
-        catch (error) {
-            result.issues.push(`Authentication validation error: ${error}`);
-        }
-        return result;
-    }
-    /**
-     * Validate Vertex AI project configuration
-     */
-    async validateVertexProjectConfiguration() {
-        const result = {
-            isValid: false,
-            projectId: undefined,
-            region: undefined,
-            issues: [],
-        };
-        // Check project ID
-        const projectId = process.env.GOOGLE_VERTEX_PROJECT ||
-            process.env.GOOGLE_CLOUD_PROJECT_ID ||
-            process.env.GOOGLE_PROJECT_ID ||
-            process.env.GOOGLE_CLOUD_PROJECT;
-        if (projectId) {
-            result.projectId = projectId;
-            // Validate project ID format
-            const projectIdPattern = /^[a-z][a-z0-9-]{4,28}[a-z0-9]$/;
-            if (projectIdPattern.test(projectId)) {
-                result.isValid = true;
-            }
-            else {
-                result.issues.push(`Invalid project ID format: ${projectId}`);
-            }
-        }
-        else {
-            result.issues.push("No project ID configured");
-        }
-        // Check region/location
-        const region = process.env.GOOGLE_CLOUD_LOCATION ||
-            process.env.VERTEX_LOCATION ||
-            process.env.GOOGLE_VERTEX_LOCATION ||
-            "us-central1";
-        result.region = region;
-        // Validate region format (regional format like us-central1 or global endpoint)
-        const regionPattern = /^([a-z]+-[a-z]+\d+|global)$/;
-        if (!regionPattern.test(region)) {
-            result.issues.push(`Invalid region format: ${region} (expected format: 'us-central1' or 'global')`);
-            result.isValid = false;
-        }
-        return result;
-    }
-    /**
-     * Check if the specified region supports Anthropic models
-     */
-    async checkVertexRegionalSupport(region = "us-central1") {
-        // Based on Google Cloud documentation, these regions support Anthropic models
-        const supportedRegions = [
-            // North America
-            "us-central1",
-            "us-east1",
-            "us-east4",
-            "us-east5",
-            "us-south1",
-            "us-west1",
-            "us-west4",
-            "northamerica-northeast1",
-            "northamerica-northeast2",
-            // Europe
-            "europe-west1",
-            "europe-west2",
-            "europe-west3",
-            "europe-west4",
-            "europe-west6",
-            "europe-west8",
-            "europe-west9",
-            "europe-north1",
-            "europe-central2",
-            "europe-southwest1",
-            // Asia Pacific
-            "asia-east1",
-            "asia-east2",
-            "asia-northeast1",
-            "asia-northeast2",
-            "asia-northeast3",
-            "asia-south1",
-            "asia-southeast1",
-            "asia-southeast2",
-            "australia-southeast1",
-            "australia-southeast2",
-            // Middle East & Africa
-            "me-west1",
-            "me-central1",
-            "africa-south1",
-            // South America
-            "southamerica-east1",
-            "southamerica-west1",
-        ];
-        return supportedRegions.includes(region);
-    }
-    /**
-     * Validate Anthropic model name format and availability
-     */
-    validateAnthropicModelName(modelName) {
-        if (!modelName || typeof modelName !== "string") {
-            return {
-                isValid: false,
-                issue: "Model name is required and must be a string",
-            };
-        }
-        // Check if it's a Claude model
-        if (!modelName.toLowerCase().includes("claude")) {
-            return {
-                isValid: false,
-                issue: 'Model name must be a Claude model (should contain "claude")',
-            };
-        }
-        // Validate against known Claude model patterns
-        const validPatterns = [
-            /^claude-sonnet-4@\d{8}$/,
-            /^claude-sonnet-4-5@\d{8}$/,
-            /^claude-opus-4@\d{8}$/,
-            /^claude-opus-4-1@\d{8}$/,
-            /^claude-3-7-sonnet@\d{8}$/,
-            /^claude-3-5-sonnet-\d{8}$/,
-            /^claude-3-5-haiku-\d{8}$/,
-            /^claude-3-sonnet-\d{8}$/,
-            /^claude-3-haiku-\d{8}$/,
-            /^claude-3-opus-\d{8}$/,
-        ];
-        const isValidFormat = validPatterns.some((pattern) => pattern.test(modelName));
-        if (!isValidFormat) {
-            return {
-                isValid: false,
-                issue: `Model name format not recognized. Expected formats like "claude-3-5-sonnet-20241022" or "claude-sonnet-4@20250514"`,
-            };
-        }
-        return { isValid: true };
-    }
-    /**
-     * Analyze Anthropic model creation errors for detailed troubleshooting
-     */
-    analyzeAnthropicCreationError(error, context) {
-        const errorMessage = error instanceof Error ? error.message : String(error);
-        const errorName = error instanceof Error ? error.name : "UnknownError";
-        const analysis = {
-            error: errorMessage,
-            errorName,
-            errorType: "UNKNOWN",
-            isNetworkError: false,
-            isAuthError: false,
-            isConfigurationError: false,
-            isModelError: false,
-            isRegionalError: false,
-            specificIssue: "Unknown error occurred",
-            errorStack: error instanceof Error ? error.stack : undefined,
-        };
-        // Network-related errors
-        if (errorMessage.includes("ETIMEDOUT") ||
-            errorMessage.includes("ECONNREFUSED") ||
-            errorMessage.includes("ENOTFOUND") ||
-            errorMessage.includes("timeout")) {
-            analysis.errorType = "NETWORK";
-            analysis.isNetworkError = true;
-            analysis.specificIssue =
-                "Network connectivity issue - cannot reach Google Cloud endpoints";
-        }
-        // Authentication errors
-        else if (errorMessage.includes("PERMISSION_DENIED") ||
-            errorMessage.includes("401") ||
-            errorMessage.includes("403") ||
-            errorMessage.includes("Unauthorized") ||
-            errorMessage.includes("Forbidden")) {
-            analysis.errorType = "AUTHENTICATION";
-            analysis.isAuthError = true;
-            analysis.specificIssue =
-                "Authentication failed - invalid credentials or insufficient permissions";
-        }
-        // Model availability errors
-        else if (errorMessage.includes("NOT_FOUND") ||
-            errorMessage.includes("404") ||
-            (errorMessage.includes("model") && errorMessage.includes("not available"))) {
-            analysis.errorType = "MODEL_AVAILABILITY";
-            analysis.isModelError = true;
-            analysis.specificIssue = `Model "${context.modelName}" not available in region "${context.region}"`;
-        }
-        // Regional/quota errors
-        else if (errorMessage.includes("QUOTA_EXCEEDED") ||
-            errorMessage.includes("quota") ||
-            errorMessage.includes("limit")) {
-            analysis.errorType = "QUOTA";
-            analysis.isRegionalError = true;
-            analysis.specificIssue = "Quota exceeded or rate limit reached";
-        }
-        // Configuration errors
-        else if (errorMessage.includes("INVALID_ARGUMENT") ||
-            errorMessage.includes("BadRequest") ||
-            errorMessage.includes("400")) {
-            analysis.errorType = "CONFIGURATION";
-            analysis.isConfigurationError = true;
-            analysis.specificIssue = "Invalid configuration or request parameters";
-        }
-        return analysis;
-    }
-    /**
-     * Get detailed troubleshooting steps based on error analysis
-     */
-    getAnthropicTroubleshootingSteps(errorAnalysis) {
-        const steps = [];
-        switch (errorAnalysis.errorType) {
-            case "NETWORK":
-                steps.push("🌐 Network Troubleshooting:", "1. Check internet connectivity", "2. Verify proxy configuration if behind corporate firewall", "3. Ensure firewall allows HTTPS to *.googleapis.com", "4. Try different network or wait for network issues to resolve", "5. Check if using VPN that might block Google Cloud endpoints");
-                break;
-            case "AUTHENTICATION":
-                steps.push("🔐 Authentication Troubleshooting:", "1. Verify GOOGLE_APPLICATION_CREDENTIALS file exists and is valid", "2. Check individual credentials: GOOGLE_AUTH_CLIENT_EMAIL, GOOGLE_AUTH_PRIVATE_KEY", '3. Ensure service account has "Vertex AI User" role', "4. Verify project ID matches the one in your credentials", "5. Enable Vertex AI API: https://console.cloud.google.com/apis/library/aiplatform.googleapis.com");
-                break;
-            case "MODEL_AVAILABILITY":
-                steps.push("🤖 Model Availability Troubleshooting:", "1. Verify model name format and spelling", "2. Check if Anthropic integration is enabled in your project", "3. Enable Claude models: https://console.cloud.google.com/vertex-ai/publishers/anthropic", "4. Try a different region if current region lacks Anthropic support", "5. Accept Anthropic terms and conditions in Google Cloud Console");
-                break;
-            case "QUOTA":
-                steps.push("📊 Quota Troubleshooting:", "1. Check Vertex AI quotas in Google Cloud Console", "2. Request quota increase if needed", "3. Try a different model with lower resource requirements", "4. Wait before retrying if rate limited", "5. Consider using a different region with available quota");
-                break;
-            case "CONFIGURATION":
-                steps.push("⚙️ Configuration Troubleshooting:", "1. Verify all required environment variables are set", "2. Check project ID and region format", "3. Ensure model name follows correct format", "4. Verify request parameters are within model limits", "5. Verify @google-cloud/vertexai and @anthropic-ai/vertex-sdk versions");
-                break;
-            default:
-                steps.push("🔧 General Troubleshooting:", "1. Verify native SDK packages are properly installed", "2. Check Google Cloud service status", "3. Verify all authentication and configuration", "4. Try with a simple Claude model like claude-3-haiku-20240307", "5. Enable debug logging with NEUROLINK_DEBUG=true");
-        }
-        return steps;
-    }
     /**
      * Register a tool with the AI provider
      * @param name The name of the tool