@juspay/neurolink 9.34.0 → 9.35.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [9.35.0](https://github.com/juspay/neurolink/compare/v9.34.0...v9.35.0) (2026-03-28)
+
+### Features
+
+- **(proxy):** add auto-update with traffic-aware graceful restart ([e0ea718](https://github.com/juspay/neurolink/commit/e0ea71891f51cf3d0f1f4fbc0044efc839359eaf))
+
 ## [9.34.0](https://github.com/juspay/neurolink/compare/v9.33.0...v9.34.0) (2026-03-27)
 
 ### Features

package/dist/cli/commands/proxy.js

@@ -16,6 +16,9 @@ import chalk from "chalk";
 import ora from "ora";
 import { logger } from "../../lib/utils/logger.js";
 import { formatUptime, isProcessRunning, StateFileManager, } from "../utils/serverUtils.js";
+import { createRequire } from "node:module";
+const _require = createRequire(import.meta.url);
+const { version: PROXY_VERSION } = _require("../../../package.json");
 // =============================================================================
 // STATE MANAGEMENT
 // =============================================================================
@@ -193,7 +196,7 @@ function spawnFailOpenGuard(host, port, parentPid) {
         return undefined;
     }
     try {
-        const child = spawn(process.execPath, [
+        const args = [
             entryScript,
             "proxy",
             "guard",
@@ -204,7 +207,8 @@ function spawnFailOpenGuard(host, port, parentPid) {
             "--parent-pid",
             String(parentPid),
             "--quiet",
-        ], {
+        ];
+        const child = spawn(process.execPath, args, {
             detached: true,
             stdio: "ignore",
         });
@@ -545,6 +549,7 @@ export const proxyStartCommand = {
                 status: "ok",
                 strategy,
                 uptime: process.uptime(),
+                version: PROXY_VERSION,
             }));
             // Status endpoint (detailed)
             app.get("/status", async (c) => {
@@ -557,6 +562,7 @@ export const proxyStartCommand = {
                     host,
                     strategy,
                     uptime: process.uptime(),
+                    version: PROXY_VERSION,
                     stats: {
                         totalRequests: stats.totalRequests,
                         totalSuccess: stats.totalSuccess,
@@ -921,6 +927,146 @@ export const proxyGuardCommand = {
         if (!Number.isFinite(parentPid) || parentPid <= 0) {
             return;
         }
+        // ---------------------------------------------------------------
+        // Auto-update loop (runs concurrently with the health monitor)
+        // Always on — no flags needed. Hardcoded sensible defaults.
+        // ---------------------------------------------------------------
+        const UPDATE_CHECK_INTERVAL_MS = 2 * 60 * 60 * 1000; // 2 hours
+        const QUIET_THRESHOLD_MS = 120 * 1000; // 2 minutes of silence
+        const UPDATE_TIMEOUT_MS = 30 * 1000; // 30 seconds to come healthy
+        // Get running version from /health endpoint
+        let runningVersion = PROXY_VERSION; // fallback
+        try {
+            const healthResp = await fetch(`http://${host}:${port}/health`);
+            const healthData = (await healthResp.json());
+            runningVersion = healthData.version ?? PROXY_VERSION;
+        }
+        catch {
+            /* use fallback */
+        }
+        let updateInProgress = false;
+        let updateRestartInProgress = false;
+        const runUpdateCheck = async () => {
+            if (updateInProgress) {
+                return;
+            }
+            updateInProgress = true;
+            try {
+                // Lazy-load update modules so they're only imported at check time
+                const { checkForUpdate } = await import("../../lib/proxy/updateChecker.js");
+                const { checkTrafficQuiet } = await import("../../lib/proxy/quietDetector.js");
+                const { recordCheck, isVersionSuppressed, suppressVersion, recordSuccessfulUpdate, } = await import("../../lib/proxy/updateState.js");
+                // 1. Check for update
+                const result = await checkForUpdate(runningVersion);
+                recordCheck(result.latestVersion);
+                if (!result.updateAvailable) {
+                    return;
+                }
+                if (isVersionSuppressed(result.latestVersion)) {
+                    logger.debug(`[guard] version ${result.latestVersion} is suppressed, skipping`);
+                    return;
+                }
+                logger.always(`[guard] update available: ${runningVersion} → ${result.latestVersion}`);
+                // 2. Wait for quiet traffic
+                const maxQuietWaitMs = 60 * 60 * 1000; // 1 hour max wait
+                const quietPollMs = 10_000; // check every 10s
+                const quietStart = Date.now();
+                while (Date.now() - quietStart < maxQuietWaitMs) {
+                    // Bail out if parent proxy died during the wait
+                    if (getProcessStatus(parentPid) === "not_running") {
+                        logger.always(`[guard] parent process died during quiet-wait, aborting update`);
+                        return;
+                    }
+                    const quietStatus = checkTrafficQuiet(QUIET_THRESHOLD_MS);
+                    if (quietStatus.isQuiet) {
+                        break;
+                    }
+                    logger.debug(`[guard] traffic active (last activity ${Math.round(quietStatus.silenceDurationMs / 1000)}s ago), waiting...`);
+                    await new Promise((r) => setTimeout(r, quietPollMs));
+                }
+                const finalQuiet = checkTrafficQuiet(QUIET_THRESHOLD_MS);
+                if (!finalQuiet.isQuiet) {
+                    logger.always(`[guard] traffic didn't quiet down within 1 hour, skipping update cycle`);
+                    return;
+                }
+                // 3. Install update (validate version string before passing to shell)
+                if (!/^\d+\.\d+\.\d+$/.test(result.latestVersion)) {
+                    logger.always(`[guard] WARNING: invalid version format "${result.latestVersion}", skipping`);
+                    return;
+                }
+                logger.always(`[guard] traffic quiet, installing @juspay/neurolink@${result.latestVersion}...`);
+                const { execFileSync } = await import("node:child_process");
+                try {
+                    execFileSync("pnpm", ["add", "-g", `@juspay/neurolink@${result.latestVersion}`], {
+                        timeout: 120_000,
+                        stdio: "pipe",
+                    });
+                }
+                catch (installErr) {
+                    logger.always(`[guard] WARNING: pnpm install failed: ${installErr instanceof Error ? installErr.message : String(installErr)}`);
+                    suppressVersion(result.latestVersion, "install_failed");
+                    return;
+                }
+                // 4. Restart via launchctl
+                // Signal the health loop to not exit when it detects
+                // the parent PID is gone — we're intentionally restarting.
+                updateRestartInProgress = true;
+                logger.always(`[guard] restarting proxy via launchctl...`);
+                const uid = process.getuid?.() ?? 501;
+                try {
+                    execFileSync("launchctl", ["kickstart", "-k", `gui/${uid}/com.neurolink.proxy`], {
+                        timeout: 10_000,
+                        stdio: "pipe",
+                    });
+                }
+                catch {
+                    logger.always(`[guard] WARNING: launchctl kickstart failed`);
+                    suppressVersion(result.latestVersion, "restart_failed");
+                    return;
+                }
+                // 5. Wait for healthy restart
+                let healthy = false;
+                const restartStart = Date.now();
+                while (Date.now() - restartStart < UPDATE_TIMEOUT_MS) {
+                    await new Promise((r) => setTimeout(r, 2000));
+                    try {
+                        const resp = await fetch(`http://${host}:${port}/health`, {
+                            signal: AbortSignal.timeout(3000),
+                        });
+                        if (resp.ok) {
+                            const data = (await resp.json());
+                            if (data.version === result.latestVersion) {
+                                healthy = true;
+                                break;
+                            }
+                        }
+                    }
+                    catch {
+                        /* retry */
+                    }
+                }
+                if (healthy) {
+                    logger.always(`[guard] update successful: now running ${result.latestVersion}`);
+                    recordSuccessfulUpdate(result.latestVersion);
+                    // The new proxy will spawn its own guard. Exit this one.
+                    process.exit(0);
+                }
+                else {
+                    logger.always(`[guard] WARNING: proxy unhealthy after update to ${result.latestVersion}`);
+                    suppressVersion(result.latestVersion, "unhealthy_after_restart");
+                    updateRestartInProgress = false;
+                }
+            }
+            catch (err) {
+                logger.always(`[guard] update check error: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            finally {
+                updateInProgress = false;
+            }
+        };
+        // Run first check after a short delay, then on interval
+        setTimeout(runUpdateCheck, 30_000);
+        setInterval(runUpdateCheck, UPDATE_CHECK_INTERVAL_MS);
         const startedAt = Date.now();
         let parentStatus = getProcessStatus(parentPid);
         let consecutiveUnhealthy = 0;
@@ -933,8 +1079,9 @@ export const proxyGuardCommand = {
             else {
                 consecutiveUnhealthy += 1;
             }
-            if (parentStatus === "not_running") {
-                // Parent is gone. If endpoint is still healthy, another proxy took over.
+            if (parentStatus === "not_running" && !updateRestartInProgress) {
+                // Parent is gone (and we're not mid-update-restart).
+                // If endpoint is still healthy, another proxy took over.
                 if (healthy) {
                     return;
                 }

package/dist/lib/proxy/quietDetector.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Proxy Quiet Detector
+ * Determines whether the proxy has been idle (no traffic) for a given
+ * threshold by efficiently reading only the tail of today's debug log file.
+ * Used by the auto-update system to find safe windows for restarts.
+ */
+/** Result of a traffic-quiet check. */
+export interface QuietStatus {
+    isQuiet: boolean;
+    lastActivityAt: Date | null;
+    silenceDurationMs: number;
+}
+/**
+ * Check whether proxy traffic has been quiet (no requests) for at least
+ * `quietThresholdMs` milliseconds.
+ *
+ * Reads only the tail of today's debug log file for efficiency.
+ *
+ * @param quietThresholdMs  Silence duration (ms) to consider "quiet". Default: 120 000 (2 min).
+ * @returns QuietStatus with the idle analysis.
+ */
+export declare function checkTrafficQuiet(quietThresholdMs?: number): QuietStatus;

package/dist/lib/proxy/quietDetector.js

@@ -0,0 +1,112 @@
+/**
+ * Proxy Quiet Detector
+ * Determines whether the proxy has been idle (no traffic) for a given
+ * threshold by efficiently reading only the tail of today's debug log file.
+ * Used by the auto-update system to find safe windows for restarts.
+ */
+import { openSync, readSync, closeSync, fstatSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+/** Default quiet threshold: 2 minutes of no traffic. */
+const DEFAULT_QUIET_THRESHOLD_MS = 120_000;
+/** Maximum bytes to read from the tail of the log file. */
+const TAIL_READ_SIZE = 4096;
+/**
+ * Build the path to today's proxy debug log file.
+ * Format: ~/.neurolink/logs/proxy-debug-YYYY-MM-DD.jsonl
+ */
+function getTodayLogPath() {
+    const today = new Date().toISOString().split("T")[0];
+    return join(homedir(), ".neurolink", "logs", `proxy-debug-${today}.jsonl`);
+}
+/**
+ * Read the last complete line(s) from a file efficiently.
+ * Uses low-level fs to seek to end and read only the last TAIL_READ_SIZE bytes.
+ * Returns an array of the last non-empty lines (up to 2 for fallback).
+ */
+function readTailLines(filePath) {
+    let fd = null;
+    try {
+        fd = openSync(filePath, "r");
+        const stat = fstatSync(fd);
+        if (stat.size === 0) {
+            return [];
+        }
+        const readSize = Math.min(TAIL_READ_SIZE, stat.size);
+        const offset = stat.size - readSize;
+        const buffer = Buffer.alloc(readSize);
+        readSync(fd, buffer, 0, readSize, offset);
+        const chunk = buffer.toString("utf-8");
+        // Split into lines, filter out empty trailing entries
+        const lines = chunk.split("\n").filter((line) => line.trim().length > 0);
+        // Return last 2 lines (last + fallback)
+        return lines.slice(-2);
+    }
+    finally {
+        if (fd !== null) {
+            closeSync(fd);
+        }
+    }
+}
+/**
+ * Try to parse a JSON line and extract its ISO timestamp.
+ * Returns the timestamp as epoch ms, or null if parsing fails.
+ */
+function extractTimestamp(line) {
+    try {
+        const parsed = JSON.parse(line);
+        if (typeof parsed.timestamp === "string") {
+            const ms = Date.parse(parsed.timestamp);
+            if (!Number.isNaN(ms)) {
+                return ms;
+            }
+        }
+    }
+    catch {
+        // Malformed JSON — caller will handle fallback
+    }
+    return null;
+}
+/**
+ * Check whether proxy traffic has been quiet (no requests) for at least
+ * `quietThresholdMs` milliseconds.
+ *
+ * Reads only the tail of today's debug log file for efficiency.
+ *
+ * @param quietThresholdMs  Silence duration (ms) to consider "quiet". Default: 120 000 (2 min).
+ * @returns QuietStatus with the idle analysis.
+ */
+export function checkTrafficQuiet(quietThresholdMs = DEFAULT_QUIET_THRESHOLD_MS) {
+    const noActivityResult = {
+        isQuiet: true,
+        lastActivityAt: null,
+        silenceDurationMs: Infinity,
+    };
+    const logPath = getTodayLogPath();
+    if (!existsSync(logPath)) {
+        return noActivityResult;
+    }
+    const tailLines = readTailLines(logPath);
+    if (tailLines.length === 0) {
+        return noActivityResult;
+    }
+    // Try last line first, then fall back to the one before it
+    let timestampMs = null;
+    for (let i = tailLines.length - 1; i >= 0; i--) {
+        timestampMs = extractTimestamp(tailLines[i]);
+        if (timestampMs !== null) {
+            break;
+        }
+    }
+    if (timestampMs === null) {
+        // All tail lines are malformed — treat as quiet
+        return noActivityResult;
+    }
+    const silenceDurationMs = Date.now() - timestampMs;
+    return {
+        isQuiet: silenceDurationMs >= quietThresholdMs,
+        lastActivityAt: new Date(timestampMs),
+        silenceDurationMs,
+    };
+}
+//# sourceMappingURL=quietDetector.js.map

package/dist/lib/proxy/updateChecker.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Proxy auto-update version checker.
+ *
+ * Queries the npm registry for the latest published version of
+ * `@juspay/neurolink` and compares it against the currently running version.
+ * Designed to be non-blocking and failure-tolerant — any error (network,
+ * timeout, parse) silently returns `updateAvailable: false`.
+ */
+export interface UpdateCheckResult {
+    currentVersion: string;
+    latestVersion: string;
+    updateAvailable: boolean;
+}
+/**
+ * Query npm for the latest version of `@juspay/neurolink` and compare it
+ * against {@link currentVersion}.
+ *
+ * On **any** failure the function resolves (never rejects) with
+ * `{ updateAvailable: false, latestVersion: currentVersion }`.
+ */
+export declare function checkForUpdate(currentVersion: string): Promise<UpdateCheckResult>;

package/dist/lib/proxy/updateChecker.js

@@ -0,0 +1,98 @@
+/**
+ * Proxy auto-update version checker.
+ *
+ * Queries the npm registry for the latest published version of
+ * `@juspay/neurolink` and compares it against the currently running version.
+ * Designed to be non-blocking and failure-tolerant — any error (network,
+ * timeout, parse) silently returns `updateAvailable: false`.
+ */
+import { execFile as execFileCb } from "node:child_process";
+import { promisify } from "node:util";
+import { logger } from "../utils/logger.js";
+const execFile = promisify(execFileCb);
+/** Timeout (ms) for the `npm view` child process. */
+const NPM_VIEW_TIMEOUT_MS = 10_000;
+/**
+ * Parse a version string of the form `major.minor.patch` into numeric
+ * components. Returns `null` when the string does not match.
+ */
+function parseSemVer(version) {
+    const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(version.trim());
+    if (!match) {
+        return null;
+    }
+    return {
+        major: Number(match[1]),
+        minor: Number(match[2]),
+        patch: Number(match[3]),
+    };
+}
+/**
+ * Returns `true` when `latest` is strictly greater than `current`.
+ *
+ * Both arguments must be valid semver strings; returns `false` on any
+ * parse failure so the caller never sees a spurious "update available".
+ */
+function isNewerVersion(current, latest) {
+    const cur = parseSemVer(current);
+    const lat = parseSemVer(latest);
+    if (!cur || !lat) {
+        return false;
+    }
+    if (lat.major !== cur.major) {
+        return lat.major > cur.major;
+    }
+    if (lat.minor !== cur.minor) {
+        return lat.minor > cur.minor;
+    }
+    return lat.patch > cur.patch;
+}
+// ---------------------------------------------------------------------------
+// Core check
+// ---------------------------------------------------------------------------
+/**
+ * Query npm for the latest version of `@juspay/neurolink` and compare it
+ * against {@link currentVersion}.
+ *
+ * On **any** failure the function resolves (never rejects) with
+ * `{ updateAvailable: false, latestVersion: currentVersion }`.
+ */
+export async function checkForUpdate(currentVersion) {
+    const fail = {
+        currentVersion,
+        latestVersion: currentVersion,
+        updateAvailable: false,
+    };
+    try {
+        logger.debug("[UpdateChecker] Checking for updates", { currentVersion });
+        const { stdout } = await execFile("npm", ["view", "@juspay/neurolink", "version", "--json"], { timeout: NPM_VIEW_TIMEOUT_MS });
+        // `npm view ... --json` wraps the value in double-quotes, e.g. `"9.32.0"`
+        const parsed = JSON.parse(stdout);
+        if (typeof parsed !== "string") {
+            logger.warn("[UpdateChecker] Unexpected npm output type", {
+                type: typeof parsed,
+            });
+            return fail;
+        }
+        const latestVersion = parsed.trim();
+        if (!parseSemVer(latestVersion)) {
+            logger.warn("[UpdateChecker] Failed to parse latest version", {
+                latestVersion,
+            });
+            return fail;
+        }
+        const updateAvailable = isNewerVersion(currentVersion, latestVersion);
+        logger.debug("[UpdateChecker] Version check complete", {
+            currentVersion,
+            latestVersion,
+            updateAvailable,
+        });
+        return { currentVersion, latestVersion, updateAvailable };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        logger.warn("[UpdateChecker] Update check failed", { error: message });
+        return fail;
+    }
+}
+//# sourceMappingURL=updateChecker.js.map

package/dist/lib/proxy/updateState.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Update State Persistence
+ * Manages persistent state for the proxy auto-update feature.
+ * Tracks check timestamps, suppressed versions, and update history.
+ *
+ * State file location: ~/.neurolink/update-state.json
+ * Suppressed versions expire after 24 hours.
+ */
+export interface SuppressedVersion {
+    suppressedAt: string;
+    reason: string;
+}
+export interface UpdateState {
+    lastCheckAt: string;
+    lastCheckVersion: string;
+    suppressedVersions: Record<string, SuppressedVersion>;
+    lastUpdateAt: string | null;
+    lastUpdateVersion: string | null;
+}
+/**
+ * Return an empty/initial UpdateState.
+ */
+export declare function getDefaultUpdateState(): UpdateState;
+/**
+ * Load the update state from disk.
+ * Returns null if the file does not exist.
+ * Returns the default state if the file contains corrupt JSON.
+ *
+ * @param stateFilePath - Override path for testing (default: ~/.neurolink/update-state.json)
+ */
+export declare function loadUpdateState(stateFilePath?: string): UpdateState | null;
+/**
+ * Save the update state to disk.
+ *
+ * @param state - The UpdateState to persist
+ * @param stateFilePath - Override path for testing (default: ~/.neurolink/update-state.json)
+ */
+export declare function saveUpdateState(state: UpdateState, stateFilePath?: string): void;
+/**
+ * Check whether a version is currently suppressed (i.e., suppressed AND within the 24-hour window).
+ *
+ * @param version - Semver version string to check
+ * @param stateFilePath - Override path for testing
+ */
+export declare function isVersionSuppressed(version: string, stateFilePath?: string): boolean;
+/**
+ * Add a version to the suppressed list and persist.
+ *
+ * @param version - Semver version string to suppress
+ * @param reason - Human-readable reason for suppression
+ * @param stateFilePath - Override path for testing
+ */
+export declare function suppressVersion(version: string, reason: string, stateFilePath?: string): void;
+/**
+ * Record a successful update: set lastUpdateAt and lastUpdateVersion, then persist.
+ *
+ * @param version - The version that was successfully installed
+ * @param stateFilePath - Override path for testing
+ */
+export declare function recordSuccessfulUpdate(version: string, stateFilePath?: string): void;
+/**
+ * Record an update check: set lastCheckAt and lastCheckVersion, then persist.
+ *
+ * @param latestVersion - The latest version found during the check
+ * @param stateFilePath - Override path for testing
+ */
+export declare function recordCheck(latestVersion: string, stateFilePath?: string): void;

package/dist/lib/proxy/updateState.js

@@ -0,0 +1,153 @@
+/**
+ * Update State Persistence
+ * Manages persistent state for the proxy auto-update feature.
+ * Tracks check timestamps, suppressed versions, and update history.
+ *
+ * State file location: ~/.neurolink/update-state.json
+ * Suppressed versions expire after 24 hours.
+ */
+import fs from "fs";
+import os from "os";
+import path from "path";
+// ============================================
+// Constants
+// ============================================
+const STATE_FILENAME = "update-state.json";
+const SUPPRESSION_TTL_MS = 86_400_000; // 24 hours
+// ============================================
+// Internal Helpers
+// ============================================
+/**
+ * Resolve the path to the update state file.
+ * Accepts an override for testing; defaults to ~/.neurolink/update-state.json.
+ */
+function resolveStatePath(overridePath) {
+    if (overridePath) {
+        return overridePath;
+    }
+    return path.join(os.homedir(), ".neurolink", STATE_FILENAME);
+}
+/**
+ * Ensure the parent directory of the given file path exists.
+ */
+function ensureParentDir(filePath) {
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+}
+// ============================================
+// Exported Functions
+// ============================================
+/**
+ * Return an empty/initial UpdateState.
+ */
+export function getDefaultUpdateState() {
+    return {
+        lastCheckAt: new Date(0).toISOString(),
+        lastCheckVersion: "",
+        suppressedVersions: {},
+        lastUpdateAt: null,
+        lastUpdateVersion: null,
+    };
+}
+/**
+ * Load the update state from disk.
+ * Returns null if the file does not exist.
+ * Returns the default state if the file contains corrupt JSON.
+ *
+ * @param stateFilePath - Override path for testing (default: ~/.neurolink/update-state.json)
+ */
+export function loadUpdateState(stateFilePath) {
+    const filePath = resolveStatePath(stateFilePath);
+    try {
+        if (!fs.existsSync(filePath)) {
+            return null;
+        }
+        const content = fs.readFileSync(filePath, "utf8");
+        const parsed = JSON.parse(content);
+        // Minimal shape check — reject valid JSON that isn't an UpdateState
+        if (typeof parsed !== "object" ||
+            parsed === null ||
+            typeof parsed.suppressedVersions !== "object" ||
+            typeof parsed.lastCheckAt !== "string") {
+            return getDefaultUpdateState();
+        }
+        return parsed;
+    }
+    catch {
+        // Corrupt or unreadable JSON — return default state
+        return getDefaultUpdateState();
+    }
+}
+/**
+ * Save the update state to disk.
+ *
+ * @param state - The UpdateState to persist
+ * @param stateFilePath - Override path for testing (default: ~/.neurolink/update-state.json)
+ */
+export function saveUpdateState(state, stateFilePath) {
+    const filePath = resolveStatePath(stateFilePath);
+    ensureParentDir(filePath);
+    // Atomic write: write to temp file then rename to prevent corruption on crash
+    const tmpPath = filePath + ".tmp";
+    fs.writeFileSync(tmpPath, JSON.stringify(state, null, 2));
+    fs.renameSync(tmpPath, filePath);
+}
+/**
+ * Check whether a version is currently suppressed (i.e., suppressed AND within the 24-hour window).
+ *
+ * @param version - Semver version string to check
+ * @param stateFilePath - Override path for testing
+ */
+export function isVersionSuppressed(version, stateFilePath) {
+    const state = loadUpdateState(stateFilePath);
+    if (!state) {
+        return false;
+    }
+    const entry = state.suppressedVersions[version];
+    if (!entry) {
+        return false;
+    }
+    return Date.now() - Date.parse(entry.suppressedAt) < SUPPRESSION_TTL_MS;
+}
+/**
+ * Add a version to the suppressed list and persist.
+ *
+ * @param version - Semver version string to suppress
+ * @param reason - Human-readable reason for suppression
+ * @param stateFilePath - Override path for testing
+ */
+export function suppressVersion(version, reason, stateFilePath) {
+    const state = loadUpdateState(stateFilePath) ?? getDefaultUpdateState();
+    state.suppressedVersions[version] = {
+        suppressedAt: new Date().toISOString(),
+        reason,
+    };
+    saveUpdateState(state, stateFilePath);
+}
+/**
+ * Record a successful update: set lastUpdateAt and lastUpdateVersion, then persist.
+ *
+ * @param version - The version that was successfully installed
+ * @param stateFilePath - Override path for testing
+ */
+export function recordSuccessfulUpdate(version, stateFilePath) {
+    const state = loadUpdateState(stateFilePath) ?? getDefaultUpdateState();
+    state.lastUpdateAt = new Date().toISOString();
+    state.lastUpdateVersion = version;
+    saveUpdateState(state, stateFilePath);
+}
+/**
+ * Record an update check: set lastCheckAt and lastCheckVersion, then persist.
+ *
+ * @param latestVersion - The latest version found during the check
+ * @param stateFilePath - Override path for testing
+ */
+export function recordCheck(latestVersion, stateFilePath) {
+    const state = loadUpdateState(stateFilePath) ?? getDefaultUpdateState();
+    state.lastCheckAt = new Date().toISOString();
+    state.lastCheckVersion = latestVersion;
+    saveUpdateState(state, stateFilePath);
+}
+//# sourceMappingURL=updateState.js.map

package/dist/proxy/quietDetector.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Proxy Quiet Detector
+ * Determines whether the proxy has been idle (no traffic) for a given
+ * threshold by efficiently reading only the tail of today's debug log file.
+ * Used by the auto-update system to find safe windows for restarts.
+ */
+/** Result of a traffic-quiet check. */
+export interface QuietStatus {
+    isQuiet: boolean;
+    lastActivityAt: Date | null;
+    silenceDurationMs: number;
+}
+/**
+ * Check whether proxy traffic has been quiet (no requests) for at least
+ * `quietThresholdMs` milliseconds.
+ *
+ * Reads only the tail of today's debug log file for efficiency.
+ *
+ * @param quietThresholdMs  Silence duration (ms) to consider "quiet". Default: 120 000 (2 min).
+ * @returns QuietStatus with the idle analysis.
+ */
+export declare function checkTrafficQuiet(quietThresholdMs?: number): QuietStatus;

package/dist/proxy/quietDetector.js

@@ -0,0 +1,111 @@
+/**
+ * Proxy Quiet Detector
+ * Determines whether the proxy has been idle (no traffic) for a given
+ * threshold by efficiently reading only the tail of today's debug log file.
+ * Used by the auto-update system to find safe windows for restarts.
+ */
+import { openSync, readSync, closeSync, fstatSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+/** Default quiet threshold: 2 minutes of no traffic. */
+const DEFAULT_QUIET_THRESHOLD_MS = 120_000;
+/** Maximum bytes to read from the tail of the log file. */
+const TAIL_READ_SIZE = 4096;
+/**
+ * Build the path to today's proxy debug log file.
+ * Format: ~/.neurolink/logs/proxy-debug-YYYY-MM-DD.jsonl
+ */
+function getTodayLogPath() {
+    const today = new Date().toISOString().split("T")[0];
+    return join(homedir(), ".neurolink", "logs", `proxy-debug-${today}.jsonl`);
+}
+/**
+ * Read the last complete line(s) from a file efficiently.
+ * Uses low-level fs to seek to end and read only the last TAIL_READ_SIZE bytes.
+ * Returns an array of the last non-empty lines (up to 2 for fallback).
+ */
+function readTailLines(filePath) {
+    let fd = null;
+    try {
+        fd = openSync(filePath, "r");
+        const stat = fstatSync(fd);
+        if (stat.size === 0) {
+            return [];
+        }
+        const readSize = Math.min(TAIL_READ_SIZE, stat.size);
+        const offset = stat.size - readSize;
+        const buffer = Buffer.alloc(readSize);
+        readSync(fd, buffer, 0, readSize, offset);
+        const chunk = buffer.toString("utf-8");
+        // Split into lines, filter out empty trailing entries
+        const lines = chunk.split("\n").filter((line) => line.trim().length > 0);
+        // Return last 2 lines (last + fallback)
+        return lines.slice(-2);
+    }
+    finally {
+        if (fd !== null) {
+            closeSync(fd);
+        }
+    }
+}
+/**
+ * Try to parse a JSON line and extract its ISO timestamp.
+ * Returns the timestamp as epoch ms, or null if parsing fails.
+ */
+function extractTimestamp(line) {
+    try {
+        const parsed = JSON.parse(line);
+        if (typeof parsed.timestamp === "string") {
+            const ms = Date.parse(parsed.timestamp);
+            if (!Number.isNaN(ms)) {
+                return ms;
+            }
+        }
+    }
+    catch {
+        // Malformed JSON — caller will handle fallback
+    }
+    return null;
+}
+/**
+ * Check whether proxy traffic has been quiet (no requests) for at least
+ * `quietThresholdMs` milliseconds.
+ *
+ * Reads only the tail of today's debug log file for efficiency.
+ *
+ * @param quietThresholdMs  Silence duration (ms) to consider "quiet". Default: 120 000 (2 min).
+ * @returns QuietStatus with the idle analysis.
+ */
+export function checkTrafficQuiet(quietThresholdMs = DEFAULT_QUIET_THRESHOLD_MS) {
+    const noActivityResult = {
+        isQuiet: true,
+        lastActivityAt: null,
+        silenceDurationMs: Infinity,
+    };
+    const logPath = getTodayLogPath();
+    if (!existsSync(logPath)) {
+        return noActivityResult;
+    }
+    const tailLines = readTailLines(logPath);
+    if (tailLines.length === 0) {
+        return noActivityResult;
+    }
+    // Try last line first, then fall back to the one before it
+    let timestampMs = null;
+    for (let i = tailLines.length - 1; i >= 0; i--) {
+        timestampMs = extractTimestamp(tailLines[i]);
+        if (timestampMs !== null) {
+            break;
+        }
+    }
+    if (timestampMs === null) {
+        // All tail lines are malformed — treat as quiet
+        return noActivityResult;
+    }
+    const silenceDurationMs = Date.now() - timestampMs;
+    return {
+        isQuiet: silenceDurationMs >= quietThresholdMs,
+        lastActivityAt: new Date(timestampMs),
+        silenceDurationMs,
+    };
+}

package/dist/proxy/updateChecker.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Proxy auto-update version checker.
+ *
+ * Queries the npm registry for the latest published version of
+ * `@juspay/neurolink` and compares it against the currently running version.
+ * Designed to be non-blocking and failure-tolerant — any error (network,
+ * timeout, parse) silently returns `updateAvailable: false`.
+ */
+export interface UpdateCheckResult {
+    currentVersion: string;
+    latestVersion: string;
+    updateAvailable: boolean;
+}
+/**
+ * Query npm for the latest version of `@juspay/neurolink` and compare it
+ * against {@link currentVersion}.
+ *
+ * On **any** failure the function resolves (never rejects) with
+ * `{ updateAvailable: false, latestVersion: currentVersion }`.
+ */
+export declare function checkForUpdate(currentVersion: string): Promise<UpdateCheckResult>;

package/dist/proxy/updateChecker.js

@@ -0,0 +1,97 @@
+/**
+ * Proxy auto-update version checker.
+ *
+ * Queries the npm registry for the latest published version of
+ * `@juspay/neurolink` and compares it against the currently running version.
+ * Designed to be non-blocking and failure-tolerant — any error (network,
+ * timeout, parse) silently returns `updateAvailable: false`.
+ */
+import { execFile as execFileCb } from "node:child_process";
+import { promisify } from "node:util";
+import { logger } from "../utils/logger.js";
+const execFile = promisify(execFileCb);
+/** Timeout (ms) for the `npm view` child process. */
+const NPM_VIEW_TIMEOUT_MS = 10_000;
+/**
+ * Parse a version string of the form `major.minor.patch` into numeric
+ * components. Returns `null` when the string does not match.
+ */
+function parseSemVer(version) {
+    const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(version.trim());
+    if (!match) {
+        return null;
+    }
+    return {
+        major: Number(match[1]),
+        minor: Number(match[2]),
+        patch: Number(match[3]),
+    };
+}
+/**
+ * Returns `true` when `latest` is strictly greater than `current`.
+ *
+ * Both arguments must be valid semver strings; returns `false` on any
+ * parse failure so the caller never sees a spurious "update available".
+ */
+function isNewerVersion(current, latest) {
+    const cur = parseSemVer(current);
+    const lat = parseSemVer(latest);
+    if (!cur || !lat) {
+        return false;
+    }
+    if (lat.major !== cur.major) {
+        return lat.major > cur.major;
+    }
+    if (lat.minor !== cur.minor) {
+        return lat.minor > cur.minor;
+    }
+    return lat.patch > cur.patch;
+}
+// ---------------------------------------------------------------------------
+// Core check
+// ---------------------------------------------------------------------------
+/**
+ * Query npm for the latest version of `@juspay/neurolink` and compare it
+ * against {@link currentVersion}.
+ *
+ * On **any** failure the function resolves (never rejects) with
+ * `{ updateAvailable: false, latestVersion: currentVersion }`.
+ */
+export async function checkForUpdate(currentVersion) {
+    const fail = {
+        currentVersion,
+        latestVersion: currentVersion,
+        updateAvailable: false,
+    };
+    try {
+        logger.debug("[UpdateChecker] Checking for updates", { currentVersion });
+        const { stdout } = await execFile("npm", ["view", "@juspay/neurolink", "version", "--json"], { timeout: NPM_VIEW_TIMEOUT_MS });
+        // `npm view ... --json` wraps the value in double-quotes, e.g. `"9.32.0"`
+        const parsed = JSON.parse(stdout);
+        if (typeof parsed !== "string") {
+            logger.warn("[UpdateChecker] Unexpected npm output type", {
+                type: typeof parsed,
+            });
+            return fail;
+        }
+        const latestVersion = parsed.trim();
+        if (!parseSemVer(latestVersion)) {
+            logger.warn("[UpdateChecker] Failed to parse latest version", {
+                latestVersion,
+            });
+            return fail;
+        }
+        const updateAvailable = isNewerVersion(currentVersion, latestVersion);
+        logger.debug("[UpdateChecker] Version check complete", {
+            currentVersion,
+            latestVersion,
+            updateAvailable,
+        });
+        return { currentVersion, latestVersion, updateAvailable };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        logger.warn("[UpdateChecker] Update check failed", { error: message });
+        return fail;
+    }
+}

package/dist/proxy/updateState.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Update State Persistence
+ * Manages persistent state for the proxy auto-update feature.
+ * Tracks check timestamps, suppressed versions, and update history.
+ *
+ * State file location: ~/.neurolink/update-state.json
+ * Suppressed versions expire after 24 hours.
+ */
+export interface SuppressedVersion {
+    suppressedAt: string;
+    reason: string;
+}
+export interface UpdateState {
+    lastCheckAt: string;
+    lastCheckVersion: string;
+    suppressedVersions: Record<string, SuppressedVersion>;
+    lastUpdateAt: string | null;
+    lastUpdateVersion: string | null;
+}
+/**
+ * Return an empty/initial UpdateState.
+ */
+export declare function getDefaultUpdateState(): UpdateState;
+/**
+ * Load the update state from disk.
+ * Returns null if the file does not exist.
+ * Returns the default state if the file contains corrupt JSON.
+ *
+ * @param stateFilePath - Override path for testing (default: ~/.neurolink/update-state.json)
+ */
+export declare function loadUpdateState(stateFilePath?: string): UpdateState | null;
+/**
+ * Save the update state to disk.
+ *
+ * @param state - The UpdateState to persist
+ * @param stateFilePath - Override path for testing (default: ~/.neurolink/update-state.json)
+ */
+export declare function saveUpdateState(state: UpdateState, stateFilePath?: string): void;
+/**
+ * Check whether a version is currently suppressed (i.e., suppressed AND within the 24-hour window).
+ *
+ * @param version - Semver version string to check
+ * @param stateFilePath - Override path for testing
+ */
+export declare function isVersionSuppressed(version: string, stateFilePath?: string): boolean;
+/**
+ * Add a version to the suppressed list and persist.
+ *
+ * @param version - Semver version string to suppress
+ * @param reason - Human-readable reason for suppression
+ * @param stateFilePath - Override path for testing
+ */
+export declare function suppressVersion(version: string, reason: string, stateFilePath?: string): void;
+/**
+ * Record a successful update: set lastUpdateAt and lastUpdateVersion, then persist.
+ *
+ * @param version - The version that was successfully installed
+ * @param stateFilePath - Override path for testing
+ */
+export declare function recordSuccessfulUpdate(version: string, stateFilePath?: string): void;
+/**
+ * Record an update check: set lastCheckAt and lastCheckVersion, then persist.
+ *
+ * @param latestVersion - The latest version found during the check
+ * @param stateFilePath - Override path for testing
+ */
+export declare function recordCheck(latestVersion: string, stateFilePath?: string): void;

package/dist/proxy/updateState.js

@@ -0,0 +1,152 @@
+/**
+ * Update State Persistence
+ * Manages persistent state for the proxy auto-update feature.
+ * Tracks check timestamps, suppressed versions, and update history.
+ *
+ * State file location: ~/.neurolink/update-state.json
+ * Suppressed versions expire after 24 hours.
+ */
+import fs from "fs";
+import os from "os";
+import path from "path";
+// ============================================
+// Constants
+// ============================================
+const STATE_FILENAME = "update-state.json";
+const SUPPRESSION_TTL_MS = 86_400_000; // 24 hours
+// ============================================
+// Internal Helpers
+// ============================================
+/**
+ * Resolve the path to the update state file.
+ * Accepts an override for testing; defaults to ~/.neurolink/update-state.json.
+ */
+function resolveStatePath(overridePath) {
+    if (overridePath) {
+        return overridePath;
+    }
+    return path.join(os.homedir(), ".neurolink", STATE_FILENAME);
+}
+/**
+ * Ensure the parent directory of the given file path exists.
+ */
+function ensureParentDir(filePath) {
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+}
+// ============================================
+// Exported Functions
+// ============================================
+/**
+ * Return an empty/initial UpdateState.
+ */
+export function getDefaultUpdateState() {
+    return {
+        lastCheckAt: new Date(0).toISOString(),
+        lastCheckVersion: "",
+        suppressedVersions: {},
+        lastUpdateAt: null,
+        lastUpdateVersion: null,
+    };
+}
+/**
+ * Load the update state from disk.
+ * Returns null if the file does not exist.
+ * Returns the default state if the file contains corrupt JSON.
+ *
+ * @param stateFilePath - Override path for testing (default: ~/.neurolink/update-state.json)
+ */
+export function loadUpdateState(stateFilePath) {
+    const filePath = resolveStatePath(stateFilePath);
+    try {
+        if (!fs.existsSync(filePath)) {
+            return null;
+        }
+        const content = fs.readFileSync(filePath, "utf8");
+        const parsed = JSON.parse(content);
+        // Minimal shape check — reject valid JSON that isn't an UpdateState
+        if (typeof parsed !== "object" ||
+            parsed === null ||
+            typeof parsed.suppressedVersions !== "object" ||
+            typeof parsed.lastCheckAt !== "string") {
+            return getDefaultUpdateState();
+        }
+        return parsed;
+    }
+    catch {
+        // Corrupt or unreadable JSON — return default state
+        return getDefaultUpdateState();
+    }
+}
+/**
+ * Save the update state to disk.
+ *
+ * @param state - The UpdateState to persist
+ * @param stateFilePath - Override path for testing (default: ~/.neurolink/update-state.json)
+ */
+export function saveUpdateState(state, stateFilePath) {
+    const filePath = resolveStatePath(stateFilePath);
+    ensureParentDir(filePath);
+    // Atomic write: write to temp file then rename to prevent corruption on crash
+    const tmpPath = filePath + ".tmp";
+    fs.writeFileSync(tmpPath, JSON.stringify(state, null, 2));
+    fs.renameSync(tmpPath, filePath);
+}
+/**
+ * Check whether a version is currently suppressed (i.e., suppressed AND within the 24-hour window).
+ *
+ * @param version - Semver version string to check
+ * @param stateFilePath - Override path for testing
+ */
+export function isVersionSuppressed(version, stateFilePath) {
+    const state = loadUpdateState(stateFilePath);
+    if (!state) {
+        return false;
+    }
+    const entry = state.suppressedVersions[version];
+    if (!entry) {
+        return false;
+    }
+    return Date.now() - Date.parse(entry.suppressedAt) < SUPPRESSION_TTL_MS;
+}
+/**
+ * Add a version to the suppressed list and persist.
+ *
+ * @param version - Semver version string to suppress
+ * @param reason - Human-readable reason for suppression
+ * @param stateFilePath - Override path for testing
+ */
+export function suppressVersion(version, reason, stateFilePath) {
+    const state = loadUpdateState(stateFilePath) ?? getDefaultUpdateState();
+    state.suppressedVersions[version] = {
+        suppressedAt: new Date().toISOString(),
+        reason,
+    };
+    saveUpdateState(state, stateFilePath);
+}
+/**
+ * Record a successful update: set lastUpdateAt and lastUpdateVersion, then persist.
+ *
+ * @param version - The version that was successfully installed
+ * @param stateFilePath - Override path for testing
+ */
+export function recordSuccessfulUpdate(version, stateFilePath) {
+    const state = loadUpdateState(stateFilePath) ?? getDefaultUpdateState();
+    state.lastUpdateAt = new Date().toISOString();
+    state.lastUpdateVersion = version;
+    saveUpdateState(state, stateFilePath);
+}
+/**
+ * Record an update check: set lastCheckAt and lastCheckVersion, then persist.
+ *
+ * @param latestVersion - The latest version found during the check
+ * @param stateFilePath - Override path for testing
+ */
+export function recordCheck(latestVersion, stateFilePath) {
+    const state = loadUpdateState(stateFilePath) ?? getDefaultUpdateState();
+    state.lastCheckAt = new Date().toISOString();
+    state.lastCheckVersion = latestVersion;
+    saveUpdateState(state, stateFilePath);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "9.34.0",
+  "version": "9.35.0",
   "description": "Universal AI Development Platform with working MCP integration, multi-provider support, and professional CLI. Built-in tools operational, 58+ external MCP servers discoverable. Connect to filesystem, GitHub, database operations, and more. Build, test, and deploy AI applications with 13 providers: OpenAI, Anthropic, Google AI, AWS Bedrock, Azure, Hugging Face, Ollama, and Mistral AI.",
   "author": {
     "name": "Juspay Technologies",