@juspay/neurolink 9.41.0 → 9.42.1

package/dist/cli/commands/proxy.js

@@ -11,14 +11,17 @@
  */
 import { spawn } from "node:child_process";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import chalk from "chalk";
 import ora from "ora";
 import { logger } from "../../lib/utils/logger.js";
 import { formatUptime, isProcessRunning, StateFileManager, } from "../utils/serverUtils.js";
+import { loadProxyEnvFile, resolveProxyEnvFile, } from "../../lib/proxy/proxyEnv.js";
 import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
 const _require = createRequire(import.meta.url);
 const { version: PROXY_VERSION } = _require("../../../package.json");
+const PROXY_TELEMETRY_SCRIPT_PATH = fileURLToPath(new URL("../../../scripts/observability/manage-local-openobserve.sh", import.meta.url));
 // =============================================================================
 // STATE MANAGEMENT
 // =============================================================================
@@ -220,6 +223,32 @@ function spawnFailOpenGuard(host, port, parentPid) {
         return undefined;
     }
 }
+async function runProxyTelemetryManager(command) {
+    const { existsSync } = await import("fs");
+    if (!existsSync(PROXY_TELEMETRY_SCRIPT_PATH)) {
+        throw new Error("Proxy telemetry helper files were not found in this installation. Reinstall NeuroLink with observability assets included.");
+    }
+    await new Promise((resolve, reject) => {
+        const child = spawn("bash", [PROXY_TELEMETRY_SCRIPT_PATH, command], {
+            stdio: "inherit",
+            env: process.env,
+        });
+        child.on("error", (error) => {
+            reject(error);
+        });
+        child.on("exit", (code, signal) => {
+            if (signal) {
+                reject(new Error(`proxy telemetry ${command} terminated by signal ${signal}`));
+                return;
+            }
+            if (code !== 0) {
+                reject(new Error(`proxy telemetry ${command} exited with code ${code ?? 1}`));
+                return;
+            }
+            resolve();
+        });
+    });
+}
 // =============================================================================
 // STARTUP BANNER
 // =============================================================================
@@ -264,6 +293,535 @@ export function mapClaudeErrorTypeToStatus(errorType) {
             return 502;
     }
 }
+async function ensureProxyStartAllowed(spinner) {
+    const existingState = loadProxyState();
+    if (existingState) {
+        if (isProcessRunning(existingState.pid)) {
+            if (spinner) {
+                spinner.fail(chalk.red(`Proxy already running on port ${existingState.port} (PID: ${existingState.pid})`));
+            }
+            logger.always(chalk.yellow("Stop it first or use 'neurolink proxy status' to inspect"));
+            process.exit(process.ppid === 1 ? 0 : 1);
+        }
+        clearProxyState();
+    }
+    if (process.ppid === 1 || !(await isLaunchdManaging())) {
+        return;
+    }
+    if (spinner) {
+        spinner.fail(chalk.red("Proxy is managed by launchd. Manual start would cause port conflicts."));
+    }
+    logger.always(chalk.yellow("Use 'neurolink proxy uninstall' to remove the service first, " +
+        "or 'launchctl kickstart gui/$(id -u)/com.neurolink.proxy' to restart."));
+    process.exit(1);
+}
+async function loadProxyStartEnv(argv, spinner) {
+    try {
+        const envResult = await loadProxyEnvFile({
+            explicitEnvFile: argv.envFile,
+        });
+        if (spinner && envResult.path) {
+            spinner.text = `Loaded proxy env from ${envResult.path}`;
+        }
+        return envResult.path;
+    }
+    catch (error) {
+        if (spinner) {
+            spinner.fail(chalk.red(error instanceof Error ? error.message : String(error)));
+        }
+        process.exit(1);
+    }
+}
+async function createProxyNeurolinkRuntime() {
+    process.env.NEUROLINK_SKIP_MCP = "true";
+    const { NeuroLink } = await import("../../lib/neurolink.js");
+    const neurolink = new NeuroLink();
+    const { initRequestLogger, cleanupLogs } = await import("../../lib/proxy/requestLogger.js");
+    initRequestLogger(true);
+    cleanupLogs(7, 500);
+    return { neurolink, cleanupLogs };
+}
+async function loadProxyStartConfiguration(argv, spinner) {
+    const configPath = argv.config ?? join(homedir(), ".neurolink", "proxy-config.yaml");
+    let proxyConfig = null;
+    try {
+        const { loadProxyConfig } = await import("../../lib/proxy/proxyConfig.js");
+        proxyConfig = (await loadProxyConfig(configPath));
+        if (spinner) {
+            spinner.text = `Loaded proxy config from ${configPath}`;
+        }
+    }
+    catch (configError) {
+        if (argv.config) {
+            if (spinner) {
+                spinner.fail(chalk.red(`Failed to load proxy config: ${configPath}`));
+            }
+            process.exit(1);
+        }
+        const isNotFound = configError instanceof Error &&
+            "code" in configError &&
+            configError.code === "ENOENT";
+        if (!isNotFound) {
+            logger.warn(`[proxy] Ignoring default config ${configPath}: ${configError instanceof Error ? configError.message : String(configError)}`);
+        }
+    }
+    const strategy = (argv.strategy ??
+        proxyConfig?.routing?.strategy ??
+        "fill-first");
+    let modelRouter;
+    if (proxyConfig?.routing) {
+        const { ModelRouter } = await import("../../lib/proxy/modelRouter.js");
+        modelRouter = new ModelRouter({
+            strategy,
+            modelMappings: proxyConfig.routing.modelMappings ?? [],
+            fallbackChain: proxyConfig.routing.fallbackChain ?? [],
+            passthroughModels: proxyConfig.routing.passthroughModels,
+        });
+    }
+    return {
+        configPath,
+        proxyConfig,
+        strategy,
+        modelRouter,
+        passthrough: argv.passthrough ?? false,
+    };
+}
+async function createProxyStartApp(params) {
+    const { createClaudeProxyRoutes } = await import("../../lib/server/routes/claudeProxyRoutes.js");
+    const { Hono } = await import("hono");
+    const app = new Hono();
+    app.onError((err, c) => {
+        const errMsg = err instanceof Error ? err.message : String(err);
+        logger.always(`[proxy] unhandled error: ${errMsg}`);
+        if (err instanceof Error && err.stack) {
+            logger.debug(`[proxy] stack: ${err.stack}`);
+        }
+        return c.json({
+            type: "error",
+            error: {
+                type: "api_error",
+                message: `Proxy internal error: ${errMsg}`,
+            },
+        }, 502);
+    });
+    const routeGroup = createClaudeProxyRoutes(params.modelRouter, "", params.strategy, params.passthrough);
+    for (const route of routeGroup.routes) {
+        const method = route.method.toLowerCase();
+        app[method](route.path, async (c) => {
+            const emptyBody = {};
+            let body;
+            let rawBody;
+            if (method === "post") {
+                rawBody = await c.req.text().catch(() => undefined);
+                try {
+                    body = rawBody ? JSON.parse(rawBody) : emptyBody;
+                }
+                catch {
+                    return c.json({
+                        type: "error",
+                        error: {
+                            type: "invalid_request_error",
+                            message: "Request body must be valid JSON",
+                        },
+                    }, 400);
+                }
+            }
+            const model = body?.model ?? "-";
+            const stream = body?.stream
+                ? "stream"
+                : "non-stream";
+            const bodyRec = body;
+            const toolCount = Array.isArray(bodyRec?.tools)
+                ? bodyRec.tools.length
+                : 0;
+            logger.always(`[proxy] ${c.req.method} ${c.req.path} → model=${model} ${stream} tools=${toolCount}`);
+            const ctx = {
+                requestId: crypto.randomUUID(),
+                method: c.req.method,
+                path: c.req.path,
+                headers: Object.fromEntries(c.req.raw.headers.entries()),
+                query: Object.fromEntries(new URL(c.req.url).searchParams.entries()),
+                params: c.req.param(),
+                body,
+                rawBody,
+                neurolink: params.neurolink,
+                toolRegistry: params.neurolink.getToolRegistry(),
+                timestamp: Date.now(),
+                metadata: {},
+            };
+            const result = await route.handler(ctx);
+            if (result instanceof Response) {
+                return result;
+            }
+            if (result &&
+                typeof result === "object" &&
+                Symbol.asyncIterator in Object(result)) {
+                const iterator = result[Symbol.asyncIterator]();
+                let cancelled = false;
+                const responseStream = new ReadableStream({
+                    async start(controller) {
+                        try {
+                            while (!cancelled) {
+                                const { value, done } = await iterator.next();
+                                if (done) {
+                                    break;
+                                }
+                                controller.enqueue(new TextEncoder().encode(value));
+                            }
+                            controller.close();
+                        }
+                        catch (streamErr) {
+                            if (cancelled) {
+                                controller.close();
+                                return;
+                            }
+                            const errMsg = streamErr instanceof Error
+                                ? streamErr.message
+                                : String(streamErr);
+                            const errorEvent = `event: error\ndata: ${JSON.stringify({ type: "error", error: { type: "api_error", message: `Stream interrupted: ${errMsg}` } })}\n\n`;
+                            try {
+                                controller.enqueue(new TextEncoder().encode(errorEvent));
+                            }
+                            catch {
+                                // Controller already errored — ignore
+                            }
+                            controller.close();
+                        }
+                    },
+                    async cancel() {
+                        cancelled = true;
+                        await iterator.return?.();
+                    },
+                });
+                return new Response(responseStream, {
+                    headers: {
+                        "Content-Type": "text/event-stream",
+                        "Cache-Control": "no-cache",
+                        Connection: "keep-alive",
+                    },
+                });
+            }
+            if (result &&
+                typeof result === "object" &&
+                "httpStatus" in result) {
+                const httpResult = result;
+                const status = httpResult.httpStatus ?? 200;
+                delete httpResult.httpStatus;
+                return c.json(result, status);
+            }
+            if (result &&
+                typeof result === "object" &&
+                "type" in result &&
+                result.type === "error") {
+                const errorResult = result;
+                const status = mapClaudeErrorTypeToStatus(errorResult.error?.type);
+                return c.json(result, status);
+            }
+            return c.json(result ?? {});
+        });
+    }
+    app.get("/health", (c) => c.json({
+        status: "ok",
+        strategy: params.strategy,
+        uptime: process.uptime(),
+        version: PROXY_VERSION,
+    }));
+    app.get("/status", async (c) => {
+        const { getStats } = await import("../../lib/proxy/usageStats.js");
+        const stats = getStats();
+        return c.json({
+            status: "running",
+            pid: process.pid,
+            port: params.port,
+            host: params.host,
+            strategy: params.strategy,
+            uptime: process.uptime(),
+            version: PROXY_VERSION,
+            stats: {
+                totalAttempts: stats.totalAttempts,
+                totalRequests: stats.totalRequests,
+                totalSuccess: stats.totalSuccess,
+                totalErrors: stats.totalErrors,
+                totalRateLimits: stats.totalRateLimits,
+                accounts: Object.values(stats.accounts).map((account) => ({
+                    label: account.label,
+                    type: account.type,
+                    attempts: account.attemptCount,
+                    requests: account.attemptCount,
+                    success: account.successCount,
+                    errors: account.errorCount,
+                    rateLimits: account.rateLimitCount,
+                    backoffLevel: account.currentBackoffLevel,
+                    cooling: account.coolingUntil
+                        ? account.coolingUntil > Date.now()
+                        : false,
+                })),
+            },
+            config: params.proxyConfig
+                ? { hasRouting: !!params.proxyConfig.routing }
+                : null,
+        });
+    });
+    return { app };
+}
+async function initializeProxyOpenTelemetry() {
+    try {
+        const otlpEndpoint = process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
+        if (!process.env.OTEL_SERVICE_NAME) {
+            process.env.OTEL_SERVICE_NAME = "neurolink-proxy";
+        }
+        process.env.OTEL_RESOURCE_ATTRIBUTES = [
+            "service.name=neurolink-proxy",
+            `service.version=${PROXY_VERSION}`,
+            "deployment.environment=local",
+            process.env.OTEL_RESOURCE_ATTRIBUTES,
+        ]
+            .filter(Boolean)
+            .join(",");
+        const { initializeOpenTelemetry, isOpenTelemetryInitialized } = await import("../../lib/services/server/ai/observability/instrumentation.js");
+        const { buildObservabilityConfigFromEnv } = await import("../../lib/utils/observabilityHelpers.js");
+        if (isOpenTelemetryInitialized()) {
+            return;
+        }
+        const observabilityConfig = buildObservabilityConfigFromEnv();
+        const langfuseConfig = observabilityConfig?.langfuse;
+        const langfuseEnabled = langfuseConfig?.enabled === true;
+        initializeOpenTelemetry({
+            enabled: langfuseEnabled,
+            publicKey: langfuseConfig?.publicKey || "",
+            secretKey: langfuseConfig?.secretKey || "",
+            baseUrl: langfuseConfig?.baseUrl,
+            environment: "proxy",
+            release: PROXY_VERSION,
+            userId: "neurolink-proxy",
+            autoDetectOperationName: true,
+        });
+        if (langfuseEnabled) {
+            logger.always(`[proxy] Langfuse enabled — exporting to ${langfuseConfig.baseUrl || "https://cloud.langfuse.com"} (environment=proxy)`);
+        }
+        if (otlpEndpoint) {
+            logger.always(`[proxy] OTLP exporter enabled — exporting to ${otlpEndpoint} (service.name=neurolink-proxy)`);
+        }
+        if (!langfuseEnabled && !otlpEndpoint) {
+            logger.always("[proxy] OpenTelemetry exporters disabled — set OTEL_EXPORTER_OTLP_ENDPOINT or Langfuse credentials to enable proxy observability");
+        }
+    }
+    catch (error) {
+        logger.debug(`[proxy] OpenTelemetry init failed (non-fatal): ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+async function refreshProxyTokensInBackground() {
+    const { needsRefresh, refreshToken, persistTokens } = await import("../../lib/proxy/tokenRefresh.js");
+    const { tokenStore } = await import("../../lib/auth/tokenStore.js");
+    try {
+        const allKeys = await tokenStore.listProviders();
+        const anthropicKeys = allKeys.filter((key) => key.startsWith("anthropic:"));
+        for (const key of anthropicKeys) {
+            try {
+                const tokens = await tokenStore.loadTokens(key);
+                if (!tokens) {
+                    continue;
+                }
+                const account = {
+                    label: key,
+                    token: tokens.accessToken,
+                    refreshToken: tokens.refreshToken,
+                    expiresAt: tokens.expiresAt,
+                };
+                if (needsRefresh(account)) {
+                    const result = await refreshToken(account);
+                    if (result.success) {
+                        await persistTokens({ providerKey: key }, account);
+                        logger.debug(`[proxy] background token refresh succeeded for ${key}`);
+                    }
+                }
+            }
+            catch {
+                // non-fatal per-account
+            }
+        }
+    }
+    catch {
+        // non-fatal
+    }
+    try {
+        const credPath = join(homedir(), ".neurolink", "anthropic-credentials.json");
+        const { readFileSync } = await import("fs");
+        const creds = JSON.parse(readFileSync(credPath, "utf8"));
+        if (!creds.oauth) {
+            return;
+        }
+        const account = {
+            label: "background",
+            token: creds.oauth.accessToken,
+            refreshToken: creds.oauth.refreshToken,
+            expiresAt: creds.oauth.expiresAt,
+        };
+        if (needsRefresh(account)) {
+            const result = await refreshToken(account);
+            if (result.success) {
+                await persistTokens(credPath, account);
+                logger.debug("[proxy] background token refresh succeeded");
+            }
+        }
+    }
+    catch {
+        // non-fatal
+    }
+}
+function startProxyBackgroundMaintenance(cleanupLogs) {
+    const refreshInterval = setInterval(() => {
+        void refreshProxyTokensInBackground();
+    }, 30_000);
+    const logCleanupInterval = setInterval(() => {
+        cleanupLogs(7, 500);
+    }, 60 * 60 * 1000);
+    return { refreshInterval, logCleanupInterval };
+}
+function registerProxyShutdownHandlers(params) {
+    const shutdown = async (signal) => {
+        clearInterval(params.refreshInterval);
+        clearInterval(params.logCleanupInterval);
+        logger.always(`\nShutting down proxy (${signal})...`);
+        try {
+            const { flushOpenTelemetry, shutdownOpenTelemetry } = await import("../../lib/services/server/ai/observability/instrumentation.js");
+            await flushOpenTelemetry();
+            await shutdownOpenTelemetry();
+        }
+        catch {
+            // non-fatal — proxy shutdown must not block on OTel
+        }
+        if (signal === "SIGINT") {
+            try {
+                const shutdownHost = params.host === "0.0.0.0" ? "localhost" : params.host;
+                await clearClaudeProxySettings(`http://${shutdownHost}:${params.port}`);
+            }
+            catch {
+                // non-fatal
+            }
+        }
+        try {
+            params.server.close?.();
+        }
+        catch {
+            // Best-effort close
+        }
+        clearProxyState();
+        process.exit(signal === "SIGINT" ? 0 : 1);
+    };
+    process.on("SIGTERM", () => {
+        void shutdown("SIGTERM");
+    });
+    process.on("SIGINT", () => {
+        void shutdown("SIGINT");
+    });
+}
+async function startProxyRuntime(params) {
+    const { serve } = await import("@hono/node-server");
+    const server = serve({
+        fetch: params.app.fetch,
+        port: params.port,
+        hostname: params.host,
+    });
+    const guardPid = spawnFailOpenGuard(params.host, params.port, process.pid);
+    const fallbackChain = params.proxyConfig?.routing?.fallbackChain?.map((entry) => ({
+        provider: entry.provider,
+        model: entry.model,
+    }));
+    saveProxyState({
+        pid: process.pid,
+        port: params.port,
+        host: params.host,
+        strategy: params.strategy,
+        startTime: new Date().toISOString(),
+        envFile: params.loadedEnvFile,
+        fallbackChain,
+        guardPid,
+        managedBy: process.platform === "darwin" && process.ppid === 1
+            ? "launchd"
+            : "manual",
+        passthrough: params.passthrough,
+    });
+    if (params.spinner) {
+        params.spinner.succeed(chalk.green("Claude proxy started successfully"));
+    }
+    const normalizedHost = params.host === "0.0.0.0" ? "localhost" : params.host;
+    const url = `http://${normalizedHost}:${params.port}`;
+    printProxyBanner(url, params.strategy);
+    logger.always(`  ${chalk.bold("Mode:")}       ${chalk.cyan(params.passthrough ? "passthrough" : "full")}`);
+    if (params.passthrough) {
+        logger.always(chalk.yellow("  ! Passthrough mode forwards client auth directly to Anthropic"));
+        logger.always(chalk.dim("    Stored proxy OAuth/API credentials are ignored; clients need their own valid Anthropic auth."));
+    }
+    if (params.loadedEnvFile) {
+        logger.always(`  ${chalk.bold("Env File:")}   ${chalk.cyan(params.loadedEnvFile)}`);
+    }
+    try {
+        await setClaudeProxySettings(url);
+        logger.always(chalk.green("  ✓ Auto-configured Claude Code settings"));
+        logger.always(chalk.dim("    Restart Claude Code to connect through proxy"));
+    }
+    catch (error) {
+        logger.debug("[proxy] Failed to auto-configure Claude Code: " +
+            (error instanceof Error ? error.message : String(error)));
+    }
+    const maintenance = startProxyBackgroundMaintenance(params.cleanupLogs);
+    registerProxyShutdownHandlers({
+        server,
+        host: params.host,
+        port: params.port,
+        ...maintenance,
+    });
+}
+async function startProxyCommandHandler(argv) {
+    const spinner = argv.quiet ? null : ora("Starting Claude proxy...").start();
+    try {
+        await ensureProxyStartAllowed(spinner);
+        const loadedEnvFile = await loadProxyStartEnv(argv, spinner);
+        const { neurolink, cleanupLogs } = await createProxyNeurolinkRuntime();
+        const { proxyConfig, strategy, modelRouter, passthrough } = await loadProxyStartConfiguration(argv, spinner);
+        if (spinner) {
+            spinner.text = "Configuring server...";
+        }
+        const port = argv.port ?? 55669;
+        const host = argv.host ?? "127.0.0.1";
+        const { app } = await createProxyStartApp({
+            neurolink,
+            modelRouter,
+            strategy,
+            passthrough,
+            port,
+            host,
+            proxyConfig,
+        });
+        await initializeProxyOpenTelemetry();
+        if (spinner) {
+            spinner.text = `Starting proxy on ${host}:${port}...`;
+        }
+        await startProxyRuntime({
+            argv,
+            spinner,
+            app,
+            host,
+            port,
+            strategy,
+            proxyConfig,
+            loadedEnvFile,
+            passthrough,
+            cleanupLogs,
+        });
+    }
+    catch (error) {
+        if (spinner) {
+            spinner.fail(chalk.red("Failed to start proxy"));
+        }
+        logger.error(chalk.red(`Error: ${error instanceof Error ? error.message : String(error)}`));
+        if (argv.debug && error instanceof Error && error.stack) {
+            logger.error(chalk.gray(error.stack));
+        }
+        process.exit(1);
+    }
+}
 // =============================================================================
 // PROXY START COMMAND
 // =============================================================================
@@ -313,440 +871,31 @@ export const proxyStartCommand = {
             alias: "c",
             description: "Path to proxy config file (YAML/JSON)",
             defaultDescription: "~/.neurolink/proxy-config.yaml",
+        })
+            .option("env-file", {
+            type: "string",
+            alias: "envFile",
+            description: "Path to proxy provider env file (overrides cwd .env for the proxy process)",
+        })
+            .option("passthrough", {
+            type: "boolean",
+            default: false,
+            description: "Run in transparent passthrough mode (no retry, no rotation, no polyfill)",
         })
             .example("neurolink proxy start", "Start proxy on default port 55669 with fill-first strategy")
             .example("neurolink proxy start -p 8080 -s fill-first", "Start proxy on port 8080 with fill-first")
             .example("neurolink proxy start --health-interval 60", "Start proxy with 60-second health checks");
     },
     handler: async (argv) => {
-        const spinner = argv.quiet ? null : ora("Starting Claude proxy...").start();
-        try {
-            // Guard: proxy already running
-            const existingState = loadProxyState();
-            if (existingState) {
-                if (isProcessRunning(existingState.pid)) {
-                    if (spinner) {
-                        spinner.fail(chalk.red(`Proxy already running on port ${existingState.port} (PID: ${existingState.pid})`));
-                    }
-                    logger.always(chalk.yellow("Stop it first or use 'neurolink proxy status' to inspect"));
-                    // Exit cleanly when managed by launchd so it doesn't treat this
-                    // as a crash and spam-restart every ThrottleInterval seconds.
-                    // For manual invocations, use non-zero so scripts/CI detect failure.
-                    process.exit(process.ppid === 1 ? 0 : 1);
-                }
-                else {
-                    // Stale state file from a previous process that is no longer running.
-                    // Clear it so subsequent startup logic doesn't get confused.
-                    clearProxyState();
-                }
-            }
-            // Guard: launchd is managing the service — don't start manually.
-            // Skip this guard when WE are the process launchd is managing
-            // (PPID 1 = launched by launchd on macOS).
-            if (process.ppid !== 1 && (await isLaunchdManaging())) {
-                if (spinner) {
-                    spinner.fail(chalk.red("Proxy is managed by launchd. Manual start would cause port conflicts."));
-                }
-                logger.always(chalk.yellow("Use 'neurolink proxy uninstall' to remove the service first, " +
-                    "or 'launchctl kickstart gui/$(id -u)/com.neurolink.proxy' to restart."));
-                // This guard only runs for manual invocations (ppid !== 1),
-                // so launchd KeepAlive is unaffected. Use non-zero exit code
-                // so scripts/CI can detect that the proxy was not started.
-                process.exit(1);
-            }
-            // -----------------------------------------------------------------
-            // 1. Create NeuroLink instance — reads all env vars automatically
-            // -----------------------------------------------------------------
-            // Skip MCP initialization for proxy — tools come from Claude Code, not MCP servers
-            process.env.NEUROLINK_SKIP_MCP = "true";
-            const { NeuroLink } = await import("../../lib/neurolink.js");
-            const neurolink = new NeuroLink();
-            // Initialize request logger and usage stats
-            const { initRequestLogger, cleanupLogs } = await import("../../lib/proxy/requestLogger.js");
-            const { getStats: _getStats, resetStats: _resetStats } = await import("../../lib/proxy/usageStats.js");
-            initRequestLogger(true);
-            cleanupLogs(7, 500); // Delete logs older than 7 days or if total exceeds 500 MB
-            // -----------------------------------------------------------------
-            // 2. Load proxy config file (if --config or default exists)
-            // -----------------------------------------------------------------
-            const configPath = argv.config ?? join(homedir(), ".neurolink", "proxy-config.yaml");
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            let proxyConfig = null;
-            try {
-                const { loadProxyConfig } = await import("../../lib/proxy/proxyConfig.js");
-                proxyConfig = await loadProxyConfig(configPath);
-                if (spinner) {
-                    spinner.text = `Loaded proxy config from ${configPath}`;
-                }
-            }
-            catch (configError) {
-                if (argv.config) {
-                    if (spinner) {
-                        spinner.fail(chalk.red(`Failed to load proxy config: ${configPath}`));
-                    }
-                    process.exit(1);
-                }
-                // Only silently ignore file-not-found for the default config path.
-                // Log a warning for other errors (parse failures, permission issues, etc.)
-                const isNotFound = configError instanceof Error &&
-                    "code" in configError &&
-                    configError.code === "ENOENT";
-                if (!isNotFound) {
-                    logger.warn(`[proxy] Ignoring default config ${configPath}: ${configError instanceof Error ? configError.message : String(configError)}`);
-                }
-            }
-            // -----------------------------------------------------------------
-            // 3. Create ModelRouter from config (if routing configured)
-            // -----------------------------------------------------------------
-            const strategy = argv.strategy ?? proxyConfig?.routing?.strategy ?? "fill-first";
-            let modelRouter;
-            if (proxyConfig?.routing) {
-                const { ModelRouter } = await import("../../lib/proxy/modelRouter.js");
-                modelRouter = new ModelRouter({
-                    strategy: strategy,
-                    modelMappings: proxyConfig.routing.modelMappings ?? [],
-                    fallbackChain: proxyConfig.routing.fallbackChain ?? [],
-                    passthroughModels: proxyConfig.routing.passthroughModels,
-                });
-            }
-            if (spinner) {
-                spinner.text = "Configuring server...";
-            }
-            // -----------------------------------------------------------------
-            // 4. Build Hono app with Claude proxy routes and NeuroLink context
-            // -----------------------------------------------------------------
-            const { createClaudeProxyRoutes } = await import("../../lib/server/routes/claudeProxyRoutes.js");
-            const { Hono } = await import("hono");
-            const { serve } = await import("@hono/node-server");
-            const app = new Hono();
-            app.onError((err, c) => {
-                const errMsg = err instanceof Error ? err.message : String(err);
-                logger.always(`[proxy] unhandled error: ${errMsg}`);
-                if (err instanceof Error && err.stack) {
-                    logger.debug(`[proxy] stack: ${err.stack}`);
-                }
-                return c.json({
-                    type: "error",
-                    error: {
-                        type: "api_error",
-                        message: `Proxy internal error: ${errMsg}`,
-                    },
-                }, 502);
-            });
-            const routeGroup = createClaudeProxyRoutes(modelRouter, "", strategy);
-            // Register proxy routes — inject NeuroLink into ServerContext
-            for (const route of routeGroup.routes) {
-                const method = route.method.toLowerCase();
-                app[method](route.path, async (c) => {
-                    const emptyBody = {};
-                    const body = method === "post"
-                        ? await c.req.json().catch(() => emptyBody)
-                        : undefined;
-                    // Log incoming request
-                    const model = body?.model ?? "-";
-                    const stream = body?.stream
-                        ? "stream"
-                        : "non-stream";
-                    const bodyRec = body;
-                    const toolCount = Array.isArray(bodyRec?.tools)
-                        ? bodyRec.tools.length
-                        : 0;
-                    logger.always(`[proxy] ${c.req.method} ${c.req.path} → model=${model} ${stream} tools=${toolCount}`);
-                    // Build ServerContext with the real NeuroLink instance
-                    const ctx = {
-                        requestId: crypto.randomUUID(),
-                        method: c.req.method,
-                        path: c.req.path,
-                        headers: Object.fromEntries(c.req.raw.headers.entries()),
-                        query: Object.fromEntries(new URL(c.req.url).searchParams.entries()),
-                        params: c.req.param(),
-                        body,
-                        neurolink, // NeuroLink instance for generate/stream
-                        toolRegistry: neurolink.getToolRegistry(),
-                        timestamp: Date.now(),
-                        metadata: {},
-                    };
-                    const result = await route.handler(ctx);
-                    // Handle raw Response objects (passthrough streaming from upstream)
-                    if (result instanceof Response) {
-                        return result;
-                    }
-                    // Handle streaming response (async iterable)
-                    if (result &&
-                        typeof result === "object" &&
-                        Symbol.asyncIterator in Object(result)) {
-                        const iterator = result[Symbol.asyncIterator]();
-                        let cancelled = false;
-                        const stream = new ReadableStream({
-                            async start(controller) {
-                                try {
-                                    while (!cancelled) {
-                                        const { value, done } = await iterator.next();
-                                        if (done) {
-                                            break;
-                                        }
-                                        controller.enqueue(new TextEncoder().encode(value));
-                                    }
-                                    controller.close();
-                                }
-                                catch (streamErr) {
-                                    if (cancelled) {
-                                        // Client disconnected — just close
-                                        controller.close();
-                                        return;
-                                    }
-                                    // Emit an SSE error frame so the client gets a meaningful
-                                    // error instead of a silent EOF / connection drop.
-                                    const errMsg = streamErr instanceof Error
-                                        ? streamErr.message
-                                        : String(streamErr);
-                                    const errorEvent = `event: error\ndata: ${JSON.stringify({ type: "error", error: { type: "api_error", message: `Stream interrupted: ${errMsg}` } })}\n\n`;
-                                    try {
-                                        controller.enqueue(new TextEncoder().encode(errorEvent));
-                                    }
-                                    catch {
-                                        // Controller already errored — ignore
-                                    }
-                                    controller.close();
-                                }
-                            },
-                            async cancel() {
-                                cancelled = true;
-                                await iterator.return?.();
-                            },
-                        });
-                        return new Response(stream, {
-                            headers: {
-                                "Content-Type": "text/event-stream",
-                                "Cache-Control": "no-cache",
-                                Connection: "keep-alive",
-                            },
-                        });
-                    }
-                    // Handle error responses with httpStatus field
-                    if (result &&
-                        typeof result === "object" &&
-                        "httpStatus" in result) {
-                        const httpResult = result;
-                        const status = httpResult.httpStatus ?? 200;
-                        delete httpResult.httpStatus;
-                        return c.json(result, status);
-                    }
-                    // Handle Anthropic-style error responses
-                    if (result &&
-                        typeof result === "object" &&
-                        "type" in result &&
-                        result.type === "error") {
-                        const errorResult = result;
-                        const status = mapClaudeErrorTypeToStatus(errorResult.error?.type);
-                        return c.json(result, status);
-                    }
-                    return c.json(result ?? {});
-                });
-            }
-            // Health endpoint
-            app.get("/health", (c) => c.json({
-                status: "ok",
-                strategy,
-                uptime: process.uptime(),
-                version: PROXY_VERSION,
-            }));
-            // Status endpoint (detailed)
-            app.get("/status", async (c) => {
-                const { getStats } = await import("../../lib/proxy/usageStats.js");
-                const stats = getStats();
-                return c.json({
-                    status: "running",
-                    pid: process.pid,
-                    port,
-                    host,
-                    strategy,
-                    uptime: process.uptime(),
-                    version: PROXY_VERSION,
-                    stats: {
-                        totalRequests: stats.totalRequests,
-                        totalSuccess: stats.totalSuccess,
-                        totalErrors: stats.totalErrors,
-                        totalRateLimits: stats.totalRateLimits,
-                        accounts: Object.values(stats.accounts).map((a) => ({
-                            label: a.label,
-                            type: a.type,
-                            requests: a.requestCount,
-                            success: a.successCount,
-                            errors: a.errorCount,
-                            rateLimits: a.rateLimitCount,
-                            backoffLevel: a.currentBackoffLevel,
-                            cooling: a.coolingUntil ? a.coolingUntil > Date.now() : false,
-                        })),
-                    },
-                    config: proxyConfig ? { hasRouting: !!proxyConfig.routing } : null,
-                });
-            });
-            // -----------------------------------------------------------------
-            // 5. Start listening
-            // -----------------------------------------------------------------
-            const port = argv.port ?? 55669;
-            const host = argv.host ?? "127.0.0.1";
-            if (spinner) {
-                spinner.text = `Starting proxy on ${host}:${port}...`;
-            }
-            const server = serve({
-                fetch: app.fetch,
-                port,
-                hostname: host,
-            });
-            const guardPid = spawnFailOpenGuard(host, port, process.pid);
-            // Extract fallback chain from proxy config (if available)
-            const fallbackChain = proxyConfig?.routing?.fallbackChain?.map((e) => ({
-                provider: e.provider,
-                model: e.model,
-            }));
-            // Persist state (including fallback chain for `proxy status`)
-            const state = {
-                pid: process.pid,
-                port,
-                host,
-                strategy,
-                startTime: new Date().toISOString(),
-                fallbackChain,
-                guardPid,
-                managedBy: "manual",
-            };
-            saveProxyState(state);
-            if (spinner) {
-                spinner.succeed(chalk.green("Claude proxy started successfully"));
-            }
-            const normalizedHost = host === "0.0.0.0" ? "localhost" : host;
-            const url = `http://${normalizedHost}:${port}`;
-            printProxyBanner(url, strategy);
-            // Auto-configure Claude Code — use the normalized URL (localhost, not 0.0.0.0)
-            try {
-                await setClaudeProxySettings(url);
-                logger.always(chalk.green("  ✓ Auto-configured Claude Code settings"));
-                logger.always(chalk.dim("    Restart Claude Code to connect through proxy"));
-            }
-            catch (e) {
-                logger.debug("[proxy] Failed to auto-configure Claude Code: " +
-                    (e instanceof Error ? e.message : String(e)));
-            }
-            // -----------------------------------------------------------------
-            // 6. Background token refresh (every 30 seconds)
-            // -----------------------------------------------------------------
-            const { needsRefresh, refreshToken, persistTokens } = await import("../../lib/proxy/tokenRefresh.js");
-            const { tokenStore } = await import("../../lib/auth/tokenStore.js");
-            const refreshInterval = setInterval(async () => {
-                // Refresh token-pool accounts
-                try {
-                    const allKeys = await tokenStore.listProviders();
-                    const anthropicKeys = allKeys.filter((k) => k.startsWith("anthropic:"));
-                    for (const key of anthropicKeys) {
-                        try {
-                            const tokens = await tokenStore.loadTokens(key);
-                            if (!tokens) {
-                                continue;
-                            }
-                            const account = {
-                                label: key,
-                                token: tokens.accessToken,
-                                refreshToken: tokens.refreshToken,
-                                expiresAt: tokens.expiresAt,
-                            };
-                            if (needsRefresh(account)) {
-                                const result = await refreshToken(account);
-                                if (result.success) {
-                                    await persistTokens({ providerKey: key }, account);
-                                    logger.debug(`[proxy] background token refresh succeeded for ${key}`);
-                                }
-                            }
-                        }
-                        catch {
-                            /* non-fatal per-account */
-                        }
-                    }
-                }
-                catch {
-                    /* non-fatal */
-                }
-                // Refresh legacy credentials file
-                try {
-                    const credPath = join(homedir(), ".neurolink", "anthropic-credentials.json");
-                    const { readFileSync } = await import("fs");
-                    const creds = JSON.parse(readFileSync(credPath, "utf8"));
-                    if (creds.oauth) {
-                        const account = {
-                            label: "background",
-                            token: creds.oauth.accessToken,
-                            refreshToken: creds.oauth.refreshToken,
-                            expiresAt: creds.oauth.expiresAt,
-                        };
-                        if (needsRefresh(account)) {
-                            const result = await refreshToken(account);
-                            if (result.success) {
-                                await persistTokens(credPath, account);
-                                logger.debug("[proxy] background token refresh succeeded");
-                            }
-                        }
-                    }
-                }
-                catch {
-                    /* non-fatal */
-                }
-            }, 30_000);
-            // Hourly log cleanup
-            const logCleanupInterval = setInterval(() => {
-                cleanupLogs(7, 500);
-            }, 60 * 60 * 1000);
-            // -----------------------------------------------------------------
-            // 7. Graceful shutdown
-            // -----------------------------------------------------------------
-            const shutdown = async (signal) => {
-                clearInterval(refreshInterval);
-                clearInterval(logCleanupInterval);
-                logger.always(`\nShutting down proxy (${signal})...`);
-                // Only clear Claude settings on user-initiated stop (SIGINT).
-                // On SIGTERM (launchd restart cycle), leave settings intact so
-                // the restarted proxy picks up seamlessly.
-                if (signal === "SIGINT") {
-                    try {
-                        const shutdownHost = host === "0.0.0.0" ? "localhost" : host;
-                        await clearClaudeProxySettings(`http://${shutdownHost}:${port}`);
-                    }
-                    catch {
-                        /* non-fatal */
-                    }
-                }
-                try {
-                    if (server &&
-                        typeof server.close === "function") {
-                        server.close();
-                    }
-                }
-                catch {
-                    // Best-effort close
-                }
-                clearProxyState();
-                // SIGINT = user pressed Ctrl+C → exit 0 (launchd won't restart)
-                // SIGTERM = launchd/system stop → exit 1 (launchd WILL restart)
-                process.exit(signal === "SIGINT" ? 0 : 1);
-            };
-            process.on("SIGTERM", () => shutdown("SIGTERM"));
-            process.on("SIGINT", () => shutdown("SIGINT"));
-        }
-        catch (error) {
-            if (spinner) {
-                spinner.fail(chalk.red("Failed to start proxy"));
-            }
-            logger.error(chalk.red(`Error: ${error instanceof Error ? error.message : String(error)}`));
-            if (argv.debug && error instanceof Error && error.stack) {
-                logger.error(chalk.gray(error.stack));
-            }
-            process.exit(1);
-        }
+        await startProxyCommandHandler(argv);
     },
 };
 function printStatusStats(stats) {
     console.info(`\n  Stats:`);
-    console.info(`    Requests:    ${stats.totalRequests} total, ${stats.totalSuccess} success, ${stats.totalErrors} errors`);
+    if (stats.totalAttempts !== undefined) {
+        console.info(`    Attempts:    ${stats.totalAttempts}`);
+    }
+    console.info(`    Completed:   ${stats.totalRequests} total, ${stats.totalSuccess} success, ${stats.totalErrors} errors`);
     console.info(`    Rate limits: ${stats.totalRateLimits}`);
     if (stats.accounts?.length) {
         console.info(`\n  Accounts:`);
@@ -754,7 +903,11 @@ function printStatusStats(stats) {
             const acctStatus = a.cooling
                 ? chalk.red("cooling")
                 : chalk.green("active");
-            console.info(`    ${a.label.padEnd(20)} ${a.type.padEnd(8)} ${String(a.requests).padEnd(6)} reqs  ${acctStatus}`);
+            const attempts = a.attempts ?? a.requests ?? 0;
+            const success = a.success ?? 0;
+            const errors = a.errors ?? 0;
+            const rateLimits = a.rateLimits ?? 0;
+            console.info(`    ${a.label.padEnd(20)} ${a.type.padEnd(8)} ${String(attempts).padEnd(6)} attempts  ${String(success).padEnd(6)} success  ${String(errors).padEnd(6)} errors  ${String(rateLimits).padEnd(6)} rl  ${acctStatus}`);
         }
     }
 }
@@ -789,10 +942,12 @@ export const proxyStatusCommand = {
                 pid: null,
                 port: null,
                 host: null,
+                mode: null,
                 strategy: null,
                 uptime: null,
                 startTime: null,
                 url: null,
+                envFile: null,
                 fallbackChain: null,
             };
             if (state && isProcessRunning(state.pid)) {
@@ -800,14 +955,30 @@ export const proxyStatusCommand = {
                 status.pid = state.pid;
                 status.port = state.port;
                 status.host = state.host;
+                status.mode = state.passthrough ? "passthrough" : "full";
                 status.strategy = state.strategy;
                 status.startTime = state.startTime;
                 status.uptime = Date.now() - new Date(state.startTime).getTime();
                 status.url = `http://${state.host === "0.0.0.0" ? "localhost" : state.host}:${state.port}`;
+                status.envFile = state.envFile ?? null;
                 status.fallbackChain = state.fallbackChain ?? null;
             }
+            // Fetch live stats before rendering (JSON or text)
+            let liveStats = null;
+            if (status.running && status.url) {
+                try {
+                    const statusResp = await fetch(`${status.url}/status`);
+                    if (statusResp.ok) {
+                        const statusData = (await statusResp.json());
+                        liveStats = statusData.stats;
+                    }
+                }
+                catch {
+                    // Non-fatal — live stats unavailable
+                }
+            }
             if (argv.format === "json") {
-                logger.always(JSON.stringify(status, null, 2));
+                logger.always(JSON.stringify({ ...status, stats: liveStats }, null, 2));
                 return;
             }
             // Text format
@@ -820,8 +991,12 @@ export const proxyStatusCommand = {
                 logger.always(`  ${chalk.bold("PID:")}        ${chalk.cyan(status.pid)}`);
                 logger.always(`  ${chalk.bold("URL:")}        ${chalk.cyan(status.url)}`);
                 logger.always(`  ${chalk.bold("Strategy:")}   ${chalk.cyan(status.strategy)}`);
+                logger.always(`  ${chalk.bold("Mode:")}       ${chalk.cyan(status.mode ?? "full")}`);
                 logger.always(`  ${chalk.bold("Started:")}    ${chalk.cyan(status.startTime)}`);
                 logger.always(`  ${chalk.bold("Uptime:")}     ${chalk.cyan(formatUptime(status.uptime ?? 0))}`);
+                if (status.envFile) {
+                    logger.always(`  ${chalk.bold("Env File:")}   ${chalk.cyan(status.envFile)}`);
+                }
                 // Display fallback chain if configured
                 if (status.fallbackChain && status.fallbackChain.length > 0) {
                     logger.always("");
@@ -875,6 +1050,58 @@ export const proxyStatusCommand = {
     },
 };
 // =============================================================================
+// PROXY TELEMETRY COMMAND
+// =============================================================================
+const PROXY_TELEMETRY_ACTIONS = [
+    "setup",
+    "start",
+    "stop",
+    "status",
+    "logs",
+    "import-dashboard",
+];
+export const proxyTelemetryCommand = {
+    command: "telemetry <action>",
+    describe: "Manage the local OpenObserve stack and dashboard for proxy observability",
+    builder: (yargs) => yargs
+        .positional("action", {
+        type: "string",
+        choices: [...PROXY_TELEMETRY_ACTIONS],
+        describe: "Telemetry action: setup, start, stop, status, logs, or import-dashboard",
+    })
+        .option("quiet", {
+        type: "boolean",
+        alias: "q",
+        default: false,
+        description: "Suppress the local CLI spinner and delegate directly",
+    })
+        .example("neurolink proxy telemetry setup", "Start OpenObserve, start the OTEL collector, and import the dashboard")
+        .example("neurolink proxy telemetry start", "Start the local proxy telemetry stack without re-importing the dashboard")
+        .example("neurolink proxy telemetry stop", "Stop the local OpenObserve and OTEL collector containers"),
+    handler: async (argv) => {
+        const action = argv.action;
+        const spinner = argv.quiet
+            ? null
+            : ora(`Running proxy telemetry ${action}...`).start();
+        try {
+            if (spinner) {
+                spinner.stop();
+            }
+            await runProxyTelemetryManager(action);
+            if (spinner) {
+                spinner.succeed(`proxy telemetry ${action} completed`);
+            }
+        }
+        catch (error) {
+            if (spinner) {
+                spinner.fail(`proxy telemetry ${action} failed`);
+            }
+            logger.error(chalk.red(`Error: ${error instanceof Error ? error.message : String(error)}`));
+            process.exit(1);
+        }
+    },
+};
+// =============================================================================
 // PROXY FAIL-OPEN GUARD COMMAND (HIDDEN)
 // =============================================================================
 export const proxyGuardCommand = {
@@ -1152,6 +1379,11 @@ export const proxySetupCommand = {
             type: "boolean",
             default: false,
             description: "Skip service installation and start proxy in foreground instead",
+        })
+            .option("env-file", {
+            type: "string",
+            alias: "envFile",
+            description: "Path to proxy provider env file to persist for the proxy",
         })
             .example("neurolink proxy setup", "Full setup with defaults")
             .example("neurolink proxy setup -p 9000", "Setup on custom port")
@@ -1253,9 +1485,27 @@ export const proxySetupCommand = {
 // =============================================================================
 // PROXY INSTALL / UNINSTALL — launchd service (macOS)
 // =============================================================================
-function buildPlist(port, host) {
-    const nodeExec = process.execPath;
-    const entryScript = process.argv[1] ?? join(__dirname, "..", "index.js");
+function escapeXml(s) {
+    return s
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&apos;");
+}
+function buildPlist(port, host, envFile, configFile) {
+    const nodeExec = escapeXml(process.execPath);
+    const entryScript = escapeXml(process.argv[1] ?? join(__dirname, "..", "index.js"));
+    const envFileArgs = envFile
+        ? `
+    <string>--env-file</string>
+    <string>${escapeXml(envFile)}</string>`
+        : "";
+    const configArgs = configFile
+        ? `
+    <string>--config</string>
+    <string>${escapeXml(configFile)}</string>`
+        : "";
     return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
   "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
@@ -1274,6 +1524,8 @@ function buildPlist(port, host) {
     <string>${port}</string>
     <string>--host</string>
     <string>${host}</string>
+${envFileArgs}
+${configArgs}
     <string>--quiet</string>
   </array>
 
@@ -1320,6 +1572,15 @@ export const proxyInstallCommand = {
             type: "string",
             default: "127.0.0.1",
             description: "Proxy host",
+        })
+            .option("env-file", {
+            type: "string",
+            alias: "envFile",
+            description: "Path to proxy provider env file to persist for the service",
+        })
+            .option("config", {
+            type: "string",
+            description: "Path to proxy routing config file to persist for the service",
         })
             .example("neurolink proxy install", "Install with defaults (port 55669)")
             .example("neurolink proxy install -p 9000", "Install on custom port");
@@ -1333,6 +1594,23 @@ export const proxyInstallCommand = {
             process.exit(1);
         }
         const { writeFileSync, mkdirSync, existsSync } = await import("fs");
+        const envResolution = resolveProxyEnvFile({
+            explicitEnvFile: argv.envFile,
+        });
+        const envFile = envResolution.path;
+        const explicitConfig = argv.config;
+        const configPath = explicitConfig
+            ? resolve(explicitConfig)
+            : join(homedir(), ".neurolink", "proxy-config.yaml");
+        if (explicitConfig && !existsSync(configPath)) {
+            console.info(chalk.red(`Proxy config file not found: ${configPath}`));
+            process.exit(1);
+        }
+        const configFile = existsSync(configPath) ? configPath : undefined;
+        if (envFile && !existsSync(envFile)) {
+            console.info(chalk.red(`Proxy env file not found: ${envFile}`));
+            process.exit(1);
+        }
         const logsDir = join(homedir(), ".neurolink", "logs");
         if (!existsSync(logsDir)) {
             mkdirSync(logsDir, { recursive: true });
@@ -1340,9 +1618,12 @@ export const proxyInstallCommand = {
         if (!existsSync(PLIST_DIR)) {
             mkdirSync(PLIST_DIR, { recursive: true });
         }
-        const plist = buildPlist(port, host);
+        const plist = buildPlist(port, host, envFile, configFile);
         writeFileSync(PLIST_PATH, plist, "utf-8");
         console.info(chalk.green(`✓ Plist written to ${PLIST_PATH}`));
+        if (envFile) {
+            console.info(chalk.green(`✓ Proxy env file: ${envFile}`));
+        }
         try {
             const { execFileSync } = await import("node:child_process");
             execFileSync("launchctl", ["unload", PLIST_PATH], {
@@ -1375,6 +1656,7 @@ export const proxyInstallCommand = {
                     host,
                     strategy: "fill-first",
                     startTime: new Date().toISOString(),
+                    envFile,
                     managedBy: "launchd",
                 });
             }