@juspay/neurolink 12.44.5 → 12.44.7

package/dist/proxy/proxyPackagePolyfills.js

@@ -0,0 +1,334 @@
+import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync, writeFileSync, renameSync, mkdirSync, } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+import { applyPatch, structuredPatch } from "diff";
+const BASELINE_NAME = ".neurolink-proxy-baseline.json";
+const MAX_FILES = 4096;
+const MAX_FILE_BYTES = 2 * 1024 * 1024;
+const MAX_TOTAL_BYTES = 64 * 1024 * 1024;
+const MAX_CHANGED_FILES = 64;
+/** Locate the package without importing its executable or provider graph. */
+export function proxyPackageRoot(entryScript) {
+    let directory = dirname(realpathSync(entryScript));
+    for (;;) {
+        const manifest = join(directory, "package.json");
+        if (existsSync(manifest)) {
+            let value;
+            try {
+                value = JSON.parse(readFileSync(manifest, "utf8"));
+            }
+            catch {
+                throw new Error("Proxy package manifest is unreadable or invalid");
+            }
+            if (value &&
+                typeof value === "object" &&
+                "name" in value &&
+                value.name === "@juspay/neurolink") {
+                return directory;
+            }
+        }
+        const parent = dirname(directory);
+        if (parent === directory) {
+            throw new Error("Proxy package manifest not found");
+        }
+        directory = parent;
+    }
+}
+function sorted(value) {
+    if (Array.isArray(value)) {
+        return value.map(sorted);
+    }
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([key, item]) => [key, sorted(item)]));
+    }
+    return value;
+}
+function safePath(path) {
+    return (!isAbsolute(path) &&
+        !path.includes("\\") &&
+        path
+            .split("/")
+            .every((part) => part !== "" && part !== "." && part !== ".."));
+}
+function runtimePath(path, entryRelative) {
+    return (safePath(path) &&
+        /\.(?:[cm]?js|json)$/.test(path) &&
+        (path === entryRelative ||
+            (path.startsWith("dist/") && !path.startsWith("dist/browser/")) ||
+            path.startsWith("scripts/observability/")));
+}
+/** Bounded baseline of shipped proxy code; operator config and dependencies are excluded. */
+export function snapshotProxyPackage(selection) {
+    const root = proxyPackageRoot(selection.entryScript);
+    const manifest = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+    // Release numbers and npm bookkeeping are not runtime compatibility edits.
+    const comparable = Object.fromEntries(Object.entries(manifest).filter(([key]) => key !== "version" && key !== "gitHead" && !key.startsWith("_")));
+    const entryRelative = relative(root, realpathSync(selection.entryScript))
+        .split("\\")
+        .join("/");
+    if (!safePath(entryRelative)) {
+        throw new Error("Proxy executable escapes package");
+    }
+    const files = {};
+    let bytes = 0;
+    const read = (path) => {
+        if (!runtimePath(path, entryRelative) || Object.hasOwn(files, path)) {
+            return;
+        }
+        const file = join(root, path);
+        const stat = lstatSync(file);
+        if (!stat.isFile() || stat.isSymbolicLink()) {
+            throw new Error(`Proxy runtime file is not a regular file: ${path}`);
+        }
+        if (stat.size > MAX_FILE_BYTES ||
+            bytes + stat.size > MAX_TOTAL_BYTES ||
+            Object.keys(files).length >= MAX_FILES) {
+            throw new Error("Proxy runtime baseline exceeds its size limit");
+        }
+        const data = readFileSync(file);
+        files[path] = new TextDecoder("utf-8", {
+            fatal: true,
+            ignoreBOM: true,
+        }).decode(data);
+        bytes += data.length;
+    };
+    const walk = (path) => {
+        if (!existsSync(join(root, path))) {
+            return;
+        }
+        if (lstatSync(join(root, path)).isSymbolicLink()) {
+            throw new Error(`Proxy runtime directory is a symbolic link: ${path}`);
+        }
+        for (const item of readdirSync(join(root, path), {
+            withFileTypes: true,
+        }).sort((a, b) => a.name.localeCompare(b.name))) {
+            const next = `${path}/${item.name}`;
+            if (next === "dist/browser" || item.name === "node_modules") {
+                continue;
+            }
+            if (item.isSymbolicLink()) {
+                throw new Error(`Proxy runtime path is a symbolic link: ${next}`);
+            }
+            if (item.isDirectory()) {
+                walk(next);
+            }
+            else {
+                read(next);
+            }
+        }
+    };
+    walk("dist");
+    walk("scripts/observability");
+    read(entryRelative);
+    return {
+        schemaVersion: 1,
+        version: selection.version,
+        manifest: JSON.stringify(sorted(comparable)),
+        entryRelative,
+        files,
+    };
+}
+/** Invalid or missing baseline must never be silently replaced with edited files. */
+export function readProxyPackageBaseline(selection) {
+    const path = join(proxyPackageRoot(selection.entryScript), BASELINE_NAME);
+    if (!existsSync(path)) {
+        return null;
+    }
+    const stat = lstatSync(path);
+    if (!stat.isFile() ||
+        stat.isSymbolicLink() ||
+        stat.size > MAX_TOTAL_BYTES * 2) {
+        throw new Error("Proxy package baseline is invalid");
+    }
+    let value;
+    try {
+        value = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        throw new Error("Proxy package baseline is unreadable or invalid");
+    }
+    if (value.schemaVersion !== 1 ||
+        typeof value.version !== "string" ||
+        typeof value.manifest !== "string" ||
+        typeof value.entryRelative !== "string" ||
+        !safePath(value.entryRelative) ||
+        !value.files ||
+        typeof value.files !== "object" ||
+        Array.isArray(value.files)) {
+        throw new Error("Proxy package baseline is invalid");
+    }
+    let bytes = 0;
+    const entries = Object.entries(value.files);
+    if (entries.length > MAX_FILES) {
+        throw new Error("Proxy package baseline exceeds its size limit");
+    }
+    for (const [name, content] of entries) {
+        if (!runtimePath(name, value.entryRelative) ||
+            typeof content !== "string" ||
+            Buffer.byteLength(content) > MAX_FILE_BYTES) {
+            throw new Error("Proxy package baseline contains an invalid file");
+        }
+        bytes += Buffer.byteLength(content);
+    }
+    if (bytes > MAX_TOTAL_BYTES) {
+        throw new Error("Proxy package baseline exceeds its size limit");
+    }
+    return value;
+}
+export function writeProxyPackageBaseline(selection, baseline) {
+    const path = join(proxyPackageRoot(selection.entryScript), BASELINE_NAME);
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    writeFileSync(temporary, JSON.stringify(baseline), {
+        mode: 0o600,
+        flag: "wx",
+    });
+    renameSync(temporary, path);
+}
+/** Operator supplies the pristine base for a legacy local build; this does not activate it. */
+export function captureProxyPackageBaseline(base, patched) {
+    const original = snapshotProxyPackage(base);
+    const current = snapshotProxyPackage(patched);
+    if (original.manifest !== current.manifest ||
+        original.entryRelative !== current.entryRelative) {
+        throw new Error("Local package metadata differs from its base; runtime polyfills cannot change dependencies or the executable");
+    }
+    const existing = readProxyPackageBaseline(patched);
+    if (existing &&
+        (existing.manifest !== original.manifest ||
+            JSON.stringify(sorted(existing.files)) !==
+                JSON.stringify(sorted(original.files)))) {
+        throw new Error("A different proxy package baseline is already recorded");
+    }
+    const changed = changedProxyRuntimeFiles(original, current);
+    writeProxyPackageBaseline(patched, original);
+    return changed;
+}
+export function changedProxyRuntimeFiles(base, current) {
+    if (base.manifest !== current.manifest ||
+        base.entryRelative !== current.entryRelative) {
+        throw new Error("Local package metadata changed; refusing upgrade rather than discarding it");
+    }
+    return [
+        ...new Set([...Object.keys(base.files), ...Object.keys(current.files)]),
+    ]
+        .sort()
+        .filter((path) => base.files[path] !== current.files[path]);
+}
+function occurrences(content, lines) {
+    if (!lines.length) {
+        return 0;
+    }
+    const haystack = content.split("\n");
+    let count = 0;
+    for (let start = 0; start + lines.length <= haystack.length; start++) {
+        if (lines.every((line, offset) => line === haystack[start + offset])) {
+            count++;
+        }
+        if (count > 1) {
+            break;
+        }
+    }
+    return count;
+}
+/** Apply exact local hunks, leaving independent upstream changes intact. */
+export function reconcileProxyPackagePolyfills(base, local, candidate) {
+    const changed = changedProxyRuntimeFiles(base, local);
+    if (changed.length > MAX_CHANGED_FILES) {
+        throw new Error("Proxy polyfill exceeds the 64-file compatibility diff limit");
+    }
+    const files = {};
+    const report = {
+        applied: [],
+        alreadyIncluded: [],
+    };
+    for (const path of changed) {
+        if (!runtimePath(path, candidate.entryRelative)) {
+            throw new Error(`Proxy polyfill path is outside the candidate runtime: ${path}`);
+        }
+        const before = base.files[path];
+        const after = local.files[path];
+        const upstream = candidate.files[path];
+        if (upstream === after) {
+            report.alreadyIncluded.push(path);
+            continue;
+        }
+        if (upstream === before) {
+            files[path] = after ?? null;
+            report.applied.push(path);
+            continue;
+        }
+        if (before === undefined ||
+            after === undefined ||
+            upstream === undefined ||
+            before === "" ||
+            after === "") {
+            throw new Error(`Proxy polyfill conflicts with the release: ${path}`);
+        }
+        const patch = structuredPatch(path, path, before, after, "", "", {
+            context: 3,
+            timeout: 1000,
+            maxEditLength: 20_000,
+        });
+        if (!patch || patch.hunks.length > 128) {
+            throw new Error(`Proxy polyfill exceeds its diff budget: ${path}`);
+        }
+        let content = upstream;
+        let applied = false;
+        for (const hunk of patch.hunks) {
+            const oldLines = hunk.lines
+                .filter((line) => line[0] === " " || line[0] === "-")
+                .map((line) => line.slice(1));
+            const newLines = hunk.lines
+                .filter((line) => line[0] === " " || line[0] === "+")
+                .map((line) => line.slice(1));
+            const oldMatches = occurrences(content, oldLines);
+            const newMatches = occurrences(content, newLines);
+            if (newMatches === 1 && oldMatches === 0) {
+                continue;
+            }
+            if (oldMatches !== 1 || newMatches !== 0) {
+                throw new Error(`Proxy polyfill conflicts with the release: ${path}`);
+            }
+            const result = applyPatch(content, { ...patch, hunks: [hunk] }, { fuzzFactor: 0 });
+            if (result === false) {
+                throw new Error(`Proxy polyfill conflicts with the release: ${path}`);
+            }
+            content = result;
+            applied = true;
+        }
+        if (applied) {
+            files[path] = content;
+            report.applied.push(path);
+        }
+        else {
+            report.alreadyIncluded.push(path);
+        }
+    }
+    return { files, report };
+}
+/** Writes are confined to a new staged copy, never the serving package. */
+export function writeProxyPolyfilledFile(root, path, content) {
+    root = realpathSync(root);
+    if (!safePath(path)) {
+        throw new Error("Invalid proxy polyfill path");
+    }
+    const target = resolve(root, path);
+    if (!target.startsWith(`${realpathSync(root)}/`)) {
+        throw new Error("Proxy polyfill escapes its package");
+    }
+    // A candidate cannot redirect a patch through a symlinked parent.
+    let parent = dirname(target);
+    while (parent !== root) {
+        if (existsSync(parent) && lstatSync(parent).isSymbolicLink()) {
+            throw new Error("Proxy polyfill parent is a symbolic link");
+        }
+        parent = dirname(parent);
+    }
+    if (existsSync(target) && lstatSync(target).isSymbolicLink()) {
+        throw new Error("Proxy polyfill target is a symbolic link");
+    }
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, content);
+}

package/dist/server/routes/claudeProxyRoutes.js

@@ -773,8 +773,13 @@ function hasScopedOnlyExhaustion(quota, now, policy = overagePolicy) {
         isOverageUsable(quota, policy)) {
         return false;
     }
-    return (quota.windows ?? []).some((window) => window.kind === "weekly_scoped" &&
-        typeof window.scopeModel === "string" &&
+    // Same notion of "scoped" as the request path: header windows (which carry
+    // both a display scope and the wire id) and usage-API windows (often only
+    // one of them) must classify alike, or a 429 is scoped when routed and
+    // account-wide when reconciled.
+    return (quota.windows ?? []).some((window) => (window.kind === "weekly_scoped" || window.kind === "session_scoped") &&
+        (typeof window.scopeModel === "string" ||
+            typeof window.scopeModelId === "string") &&
         now - scopedWindowObservedAt(quota, window) <=
             QUOTA_SNAPSHOT_FRESHNESS_MS &&
         isScopedWindowExhausted(window, now));

package/dist/server/routes/codexProxyRoutes.js

@@ -151,21 +151,25 @@ function buildCodexErrorResponse(status, message, code) {
     }), { status, headers: { "content-type": "application/json" } });
 }
 /**
- * Build a terminal Codex Responses SSE stream for a quota-exhaustion failure
- * that never reached an upstream request (every pooled account is cooling).
+ * Build a terminal Codex Responses SSE stream for a failure that never reached
+ * an upstream request (every pooled account is cooling).
  * A bare non-2xx status with no body reads to the Codex CLI as a dropped
  * connection, so it shows "Reconnecting... waiting for network" forever
  * instead of a real error. Emitting a well-formed `response.failed` event —
  * the same terminal shape the CLI already parses out of a live stream —
  * lets it render the actual failure instead.
+ *
+ * The code is what the client keys on: `insufficient_quota` tells it the plan
+ * is spent, so it is reserved for a pool that is out of quota. Accounts parked
+ * by a transient auth failure report `server_error` instead.
  */
-function buildCodexQuotaExhaustedResponse(message, retryAfterSec) {
+function buildCodexPoolCoolingResponse(message, retryAfterSec, code) {
     const payload = {
         type: "response.failed",
         response: {
             error: {
-                type: "insufficient_quota",
-                code: "insufficient_quota",
+                type: code,
+                code,
                 message,
             },
         },
@@ -1333,14 +1337,26 @@ loopbackPort, internalDispatch) {
                 });
                 return buildCodexErrorResponse(413, outbound.message, "request_too_large");
             }
+            const resetAt = soonest ? new Date(soonest).toISOString() : undefined;
+            // A refresh that failed transiently, or a 401 with no refresh token to
+            // retry with, parks the account as "auth". Reporting that as spent quota
+            // would tell the user the plan is exhausted when it is not.
+            if (ordered.every((account) => account.coolingReason === "auth")) {
+                await recordFinalOutcome(undefined, 503, {
+                    errorType: "all_accounts_auth_cooling",
+                    errorMessage: "All Codex accounts are cooling after an auth failure",
+                });
+                return buildCodexPoolCoolingResponse(resetAt
+                    ? `Codex authentication is temporarily unavailable for every account. Retry after ${resetAt}, or run \`neurolink auth login codex\` if it persists.`
+                    : "Codex authentication is temporarily unavailable for every account. Retry shortly, or run `neurolink auth login codex` if it persists.", retryAfterSec, "server_error");
+            }
             await recordFinalOutcome(undefined, 429, {
                 errorType: "all_accounts_cooling",
                 errorMessage: "All Codex accounts are rate-limited",
             });
-            const resetAt = soonest ? new Date(soonest).toISOString() : undefined;
-            return buildCodexQuotaExhaustedResponse(resetAt
+            return buildCodexPoolCoolingResponse(resetAt
                 ? `Codex quota exhausted: all accounts are rate-limited. Resets at ${resetAt}.`
-                : "Codex quota exhausted: all accounts are rate-limited.", retryAfterSec);
+                : "Codex quota exhausted: all accounts are rate-limited.", retryAfterSec, "insufficient_quota");
         }
         let attempt = 0;
         let lastErrorMessage = "All Codex accounts failed";

package/dist/types/proxy.d.ts

@@ -4437,6 +4437,32 @@ export type ProxyStagedInstallOptions = {
         outputBytes: number;
     }) => void;
 };
+/** Original proxy runtime files retained before any local compatibility edits. */
+export type ProxyPackageBaseline = {
+    schemaVersion: 1;
+    version: string;
+    manifest: string;
+    entryRelative: string;
+    files: Record<string, string>;
+};
+/** A candidate carries only local diff hunks that its release still needs. */
+export type ProxyPackagePolyfillReport = {
+    applied: string[];
+    alreadyIncluded: string[];
+};
+/** Staged upgrade that reconciles recorded local edits before publication. */
+export type ProxyPackageUpgradeOptions = ProxyStagedInstallOptions & {
+    activePackage: ProxyPackageSelection;
+    isCurrentOwner?: () => boolean;
+    onPolyfills?: (report: ProxyPackagePolyfillReport) => void;
+};
+/** Capture a trusted baseline for a locally patched package without activation. */
+export type ProxyPolyfillArgs = {
+    action: "capture";
+    base: string;
+    patched: string;
+    format: "text" | "json";
+};
 /** Saved launchd settings retained when installing the service again. */
 export type ProxyServiceInstallSettings = {
     envFile?: string;

package/docs-site/static/search-index.json

@@ -2289,9 +2289,10 @@
 {"objectID":"9d37e7d66f60fa6af16eaee381757f1d39b03c29d805748d72980fc766a80afc","title":"Acceptance evidence","url":"/docs/development/proxy-incident-verification#acceptance-evidence","content":"Local verification on macOS, Node 24.14.1, September 7, 2026. All network fixtures\nuse ephemeral loopback listeners and isolated storage. No installed proxy,\nprovider account, launchd service, or production request was used.\n\n| Requirement                                               | Evidence                                                                                                                                                                                 |\n| --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Delayed acceptance gets its own full commit deadline      | Actual child-process IPC fixture; no failed transfer or worker replacement                                                                                                               |\n| A failed commit preserves unrelated streams               | Actual shipped worker runtime; affected connection closes, other stream delivers every byte, replacement serves requests; commit timeouts and IPC write failures retain distinct reasons |\n| Accepted work remains identifiable after worker death     | Confirmed admission append, fixture SIGKILL, independent parent exit journal, built analyzer joins by process instance                                                                   |\n| Unknown outcomes remain unknown                           | Missing terminal plus worker exit is reported as unconfirmedAtWorkerExit; conflicting exit evidence is excluded                                                                        |\n| Storage failures cannot dispatch unrecorded upstream work | HTTP fixture returns classified 503 after admission write failure; upstream invocation count stays zero                                                                                  |\n| Time-window analysis does not f","hierarchy":{"lvl0":"Development","lvl1":"Proxy incident reliability verification","lvl2":"Acceptance evidence","lvl3":""}},
 {"objectID":"e445d51bde52184ea947c95c6b1f2105e1c1dd67b2ed01509cbfa320d3a396db","title":"Performance observations","url":"/docs/development/proxy-incident-verification#performance-observations","content":"The existing lifecycle gate wrote 100,000 events for 25,000 requests with zero\ndrops or uncertain writes. Enqueue p95 was 12 microseconds; added response-tracking\np95 was 49 microseconds. The statistics gate reconciled 50,000 requests exactly.\nThe loopback transport gate added 1.69 ms p95 against its 5 ms budget.\n\nThe first rolling gate preserved all traffic but failed the sustained latency\nbudget: 51.28 ms added p95 against 25 ms. We then ran three alternating comparisons\nagainst unchanged release 382217975c39433df058e2b2c2fb91b283230725, using the\nsame fixture, machine and background scheduling priority. No budgets were changed.\n\n| Round | Release added p95 under sustained load | Patched added p95 under sustained load |\n| ----- | -------------------------------------: | -------------------------------------: |\n| 1     |                               6.042 ms |                              24.840 ms |\n| 2     |                               6.826 ms |                               5.355 ms |\n| 3     |                               9.827 ms |                               4.811 ms |\n\nEvery comparison passed the existing budgets, preserved the active stream, and\nreported zero dropped requests. The fixture includes 100 concurrent handoff\nrequests and 64-way sustained traffic. These observations expose variability;\nthey do not certify a latency ceiling under arbitrary host contention.","hierarchy":{"lvl0":"Development","lvl1":"Proxy incident reliability verification","lvl2":"Performance observations","lvl3":""}},
 {"objectID":"5cb2fe62f38e8943b94facdd1ddd6a4a968fbbb161744152fe47c3c269d575cf","title":"Interpretation limits","url":"/docs/development/proxy-incident-verification#interpretation-limits","content":"The CLI has one signal owner. Proxy workers and supervisors own their drain and\nexit; the ordinary CLI telemetry cleanup cannot exit alongside them. Repeated\nSIGINT/SIGTERM signals reuse that shutdown. Ordinary command cleanup catches\nflush failures and uses a five-second deadline. Worker and supervisor telemetry\ncleanup also has a deadline after request draining. Supervisor SIGHUP forwards a\nreload to the ready serving worker, while a candidate loads configuration during\nstartup. Isolated subprocess fixtures in test:proxy-restart exercise reload,\nduplicate signals, failed flushes, stalled flushes and drain failures. If startup\nregisters a shutdown owner during ordinary cleanup, the original signal is\ndelegated to that owner after cleanup settles, including rejection or timeout.\nSignal-triggered ordinary cleanup preserves an existing command failure code.\nSupervisor SIGHUP handling is installed before startup awaits, ignores reloads\nuntil a serving worker is ready, and forwards them during control-plane setup.\nSupervisor shutdown ownership is also registered before startup awaits. A stop\nprevents later setup stages, waits for already-started resource creation, and\ncloses the resulting resources before exiting. Cleanup continues after an\nindividual close failure and exits unsuccessfully when a resource cannot close.\nIsolated child-process regressions signal bootstrap, pending worker startup,\npending restart-control setup, and updater startup, including duplicate signals\nand a rejected control close.\nResource cleanup runs concurrently: worker creation and drain have a 35-second\ndeadline, and control cleanup has a 5-second deadline. Telemetry then has its\n5-second budget, leaving headroom inside the launchd service's 45-second stop\ntimeout. A stalled resource is reported and causes an unsuccessful exit; a late\nresource returned while telemetry is flushing is still closed without extending\nthe exit deadline. Fixtures cover permanently pending worker/control setup and a\n","hierarchy":{"lvl0":"Development","lvl1":"Proxy incident reliability verification","lvl2":"Interpretation limits","lvl3":""}},
-{"objectID":"e8a7f76ea9249969c4e7f7f8767fd2cac18478baca29ee921e7a7ca73825db69","title":"Proxy package updates and token budgets","url":"/docs/development/proxy-updates-and-token-budgets","content":"Proxy package updates and token budgets\n\nAutomatic updates prepare a separate package before asking the supervisor to\nactivate it. They do not run a global package replacement over files used by\nserving workers. These changes take effect after the release is installed and\nits supervisor is activated; merging a PR does not change a running service.\n\nUpdate and restart behavior\n\nThe updater installs the current running version, when needed for rollback, and\nthe candidate under ~/.neurolink/proxy-packages/<version>. Installation uses a\nprivate temporary directory and publishes the version directory only after the\npackage name, version, executable location, and JavaScript syntax validate.\nA candidate with missing dependencies can still fail startup: actual worker\nreadiness remains the activation gate, and the serving generation is retained\nwhen replacement fails.\n\nThe package-manager process runs asynchronously. Output progress renews a\ntwo-minute inactivity deadline; a fifteen-minute maximum still bounds an\ninstaller that emits output forever. A timed-out installer and its process group\nare stopped, its unpublished directory is removed, and transient errors receive\nthe updater's bounded retry schedule. Progress telemetry contains byte counts and\ntiming, not raw package-manager output that may contain authenticated URLs.\n\nThe stable launcher selects one validated package. Its --version check reads\npackage metadata in a minimal Node process; it does not initialize provider,\ntelemetry, or proxy code. Each worker is spawned from its expected package, so a\nnew candidate cannot silently change the recovery executable of an older worker.\nRollback restores the previous selection rather than reinstalling over live\nfiles. Proxy auto-update does not change the global CLI package; invoking an older\nglobal CLI to reinstall the service retains the selected proxy package instead\nof downgrading it or rejecting its version. Version directories are intentionally retained: they can still be needed\nby active/draining generations or rollback. This increases package disk usage;\nthere is currently no automatic garbage collection of retained versions.\n\nBefore refreshing a supervisor, all of the following must be settled:\nActive requests in the current worker.\nEvery draining worker generation.\nQueued sockets and pending socket transfers.\nAny candidate worker.\n\nIncomplete rolling status is not evidence of idleness. A drain attempt lasts at\nmost thirty seconds before deferral and admission recovery; it never kills an\nolder stream to make the update proceed. The worker also has a ninety-second\nadmission recovery lease if the updater disappears. Package installation and\nvalidation finish before a legacy service closes admission.\n\nUse neurolink proxy restart --check for a read-only restart preflight and\nneurolink proxy restart for a supervisor-owned rolling replacement. A failed\ncheck does not fall back to a forced process restart. The result distinguishes a\nverified replacement from an activated worker whose final verification failed.\nA worker restart does not, by itself, upgrade the supervisor.\n\nStatus separates diskPackageVersion (metadata at the executable used by the\nreporting process), selectedPackageVersion (next launcher selection),\nvalidatedVersion (last updater-validated package), candidateVersion, the\nserving worker version, and the supervisor version. A changed disk manifest or a\nvalidated package does not prove live adoption.\n\nReinstall first refuses any running worker, draining generation, or loaded launchd\njob before writing files or changing processes. Unknown/permission-denied process\nor launchd state also refuses. Use the rolling restart command for a live service;\nexplicitly stop and unload it before an intended reinstall.\n\nFor a stopped service, reinstall reads the saved definition before writing it. Existing\nhost/port, environment-file path, routing-config path, and operator OTel/proxy\nvariables become defaults; explicit arguments and current environment values\nwin. An unreadable service definition aborts reinstall instead of silently\nremoving its settings. Worker IPC identity is not persisted. This includes\nNEUROLINK_PROXY_OTLP_BODIES_ENDPOINT, NEUROLINK_PROXY_CONTEXT_POLICY, and\nNEUROLINK_PROXY_TOKEN_BUDGET.\n\nOptional token reservations\n\nNEUROLINK_PROXY_TOKEN_BUDGET accepts a JSON object. No token cap is enabled by\ndefault. For example, an operator could configure:\n\nThese numbers are illustrative, not recommended account allowances. Supported\nfields must be positive safe integers; an invalid configuration fails closed.\nmaxInFlightTokens is per provider/account. accountWindowTokens caps charged\ntokens in that account's fixed window. sessionWindowTokens applies across\naccounts and providers for the same client session. The default window is one\nhour when a cap is set without windowMs.\n\nBefore each native upstream attempt or translated SDK invocation, the proxy\nreserves estimated input plus the output allowance. An SDK ","hierarchy":{"lvl0":"Development","lvl1":"Proxy package updates and token budgets","lvl2":"","lvl3":""}},
+{"objectID":"e8a7f76ea9249969c4e7f7f8767fd2cac18478baca29ee921e7a7ca73825db69","title":"Proxy package updates and token budgets","url":"/docs/development/proxy-updates-and-token-budgets","content":"Proxy package updates and token budgets\n\nAutomatic updates prepare a separate package before asking the supervisor to\nactivate it. They do not run a global package replacement over files used by\nserving workers. These changes take effect after the release is installed and\nits supervisor is activated; merging a PR does not change a running service.\n\nUpdate and restart behavior\n\nThe updater installs the current running version, when needed for rollback, and\nthe candidate under ~/.neurolink/proxy-packages/<version>. Installation uses a\nprivate temporary directory and publishes the version directory only after the\npackage name, version, executable location, and JavaScript syntax validate.\nA candidate with missing dependencies can still fail startup: actual worker\nreadiness remains the activation gate, and the serving generation is retained\nwhen replacement fails.\n\nThe package-manager process runs asynchronously. Output progress renews a\ntwo-minute inactivity deadline; a fifteen-minute maximum still bounds an\ninstaller that emits output forever. A timed-out installer and its process group\nare stopped, its unpublished directory is removed, and transient errors receive\nthe updater's bounded retry schedule. Progress telemetry contains byte counts and\ntiming, not raw package-manager output that may contain authenticated URLs.\n\nThe stable launcher selects one validated package. Its --version check reads\npackage metadata in a minimal Node process; it does not initialize provider,\ntelemetry, or proxy code. Each worker is spawned from its expected package, so a\nnew candidate cannot silently change the recovery executable of an older worker.\nRollback restores the previous selection rather than reinstalling over live\nfiles. Proxy auto-update does not change the global CLI package; invoking an older\nglobal CLI to reinstall the service retains the selected proxy package instead\nof downgrading it or rejecting its version. Version directories are intentionally retained: they can still be needed\nby active/draining generations or rollback. This increases package disk usage;\nthere is currently no automatic garbage collection of retained versions.\n\nBefore refreshing a supervisor, all of the following must be settled:\nActive requests in the current worker.\nEvery draining worker generation.\nQueued sockets and pending socket transfers.\nAny candidate worker.\n\nIncomplete rolling status is not evidence of idleness. A drain attempt lasts at\nmost thirty seconds before deferral and admission recovery; it never kills an\nolder stream to make the update proceed. The worker also has a ninety-second\nadmission recovery lease if the updater disappears. Package installation and\nvalidation finish before a legacy service closes admission.\n\nUse neurolink proxy restart --check for a read-only restart preflight and\nneurolink proxy restart for a supervisor-owned rolling replacement. A failed\ncheck does not fall back to a forced process restart. The result distinguishes a\nverified replacement from an activated worker whose final verification failed.\nA worker restart does not, by itself, upgrade the supervisor.\n\nStatus separates diskPackageVersion (metadata at the executable used by the\nreporting process), selectedPackageVersion (next launcher selection),\nvalidatedVersion (last updater-validated package), candidateVersion, the\nserving worker version, and the supervisor version. A changed disk manifest or a\nvalidated package does not prove live adoption.\n\nReinstall first refuses any running worker, draining generation, or loaded launchd\njob before writing files or changing processes. Unknown/permission-denied process\nor launchd state also refuses. Use the rolling restart command for a live service;\nexplicitly stop and unload it before an intended reinstall.\n\nFor a stopped service, reinstall reads the saved definition before writing it. Existing\nhost/port, environment-file path, routing-config path, and operator OTel/proxy\nvariables become defaults; explicit arguments and current environment values\nwin. An unreadable service definition aborts reinstall instead of silently\nremoving its settings. Worker IPC identity is not persisted. This includes\nNEUROLINK_PROXY_OTLP_BODIES_ENDPOINT, NEUROLINK_PROXY_CONTEXT_POLICY, and\nNEUROLINK_PROXY_TOKEN_BUDGET.\n\nLocal compatibility polyfills\n\nAn automatic package upgrade leaves the routing config, environment file, and\nlaunchd definition intact. It also preserves the exact previous package path,\nincluding when a local build and an official build share a version number.\nManaged service starts and worker replacements do not reapply CLI client\nconfiguration. User changes to Codex, Claude Code, and other client settings\nremain in place. Use explicit proxy setup or foreground proxy start to\nconfigure client routing.\n\nEach freshly staged package records its original proxy runtime files. When a\nlater upgrade is available, the updater compares the serving package with that\nbaseline and applies only the remaining local diff hunk","hierarchy":{"lvl0":"Development","lvl1":"Proxy package updates and token budgets","lvl2":"","lvl3":""}},
 {"objectID":"d8b758e463be06d23598c7f1722e82d46f3d5f2df3c3c98058f400923f83ac8f","title":"Proxy package updates and token budgets","url":"/docs/development/proxy-updates-and-token-budgets#proxy-package-updates-and-token-budgets","content":"Automatic updates prepare a separate package before asking the supervisor to\nactivate it. They do not run a global package replacement over files used by\nserving workers. These changes take effect after the release is installed and\nits supervisor is activated; merging a PR does not change a running service.","hierarchy":{"lvl0":"Development","lvl1":"Proxy package updates and token budgets","lvl2":"Proxy package updates and token budgets","lvl3":""}},
 {"objectID":"b31737c456bf0dd066337629bccccd40c4572b96ad3b51fdf48de2c44d45e82a","title":"Update and restart behavior","url":"/docs/development/proxy-updates-and-token-budgets#update-and-restart-behavior","content":"The updater installs the current running version, when needed for rollback, and\nthe candidate under ~/.neurolink/proxy-packages/<version>. Installation uses a\nprivate temporary directory and publishes the version directory only after the\npackage name, version, executable location, and JavaScript syntax validate.\nA candidate with missing dependencies can still fail startup: actual worker\nreadiness remains the activation gate, and the serving generation is retained\nwhen replacement fails.\n\nThe package-manager process runs asynchronously. Output progress renews a\ntwo-minute inactivity deadline; a fifteen-minute maximum still bounds an\ninstaller that emits output forever. A timed-out installer and its process group\nare stopped, its unpublished directory is removed, and transient errors receive\nthe updater's bounded retry schedule. Progress telemetry contains byte counts and\ntiming, not raw package-manager output that may contain authenticated URLs.\n\nThe stable launcher selects one validated package. Its --version check reads\npackage metadata in a minimal Node process; it does not initialize provider,\ntelemetry, or proxy code. Each worker is spawned from its expected package, so a\nnew candidate cannot silently change the recovery executable of an older worker.\nRollback restores the previous selection rather than reinstalling over live\nfiles. Proxy auto-update does not change the global CLI package; invoking an older\nglobal CLI to reinstall the service retains the selected proxy package instead\nof downgrading it or rejecting its version. Version directories are intentionally retained: they can still be needed\nby active/draining generations or rollback. This increases package disk usage;\nthere is currently no automatic garbage collection of retained versions.\n\nBefore refreshing a supervisor, all of the following must be settled:\nActive requests in the current worker.\nEvery draining worker generation.\nQueued sockets and pending socket transfers.\nAny candidate worker.\n\nIncom","hierarchy":{"lvl0":"Development","lvl1":"Proxy package updates and token budgets","lvl2":"Update and restart behavior","lvl3":""}},
+{"objectID":"69e1f9556ad4141f30fa78e44edc0297f70c1dcc1e775c5955e44c912f79a0b6","title":"Local compatibility polyfills","url":"/docs/development/proxy-updates-and-token-budgets#local-compatibility-polyfills","content":"An automatic package upgrade leaves the routing config, environment file, and\nlaunchd definition intact. It also preserves the exact previous package path,\nincluding when a local build and an official build share a version number.\nManaged service starts and worker replacements do not reapply CLI client\nconfiguration. User changes to Codex, Claude Code, and other client settings\nremain in place. Use explicit proxy setup or foreground proxy start to\nconfigure client routing.\n\nEach freshly staged package records its original proxy runtime files. When a\nlater upgrade is available, the updater compares the serving package with that\nbaseline and applies only the remaining local diff hunks to a new candidate.\nIndependent release changes remain intact. A fix already present in the release\nis skipped and disappears from the local diff on subsequent upgrades. The\nserving package is never edited during this reconciliation.\n\nAn overlapping change, ambiguous patch context, unsupported dependency change,\nor invalid JavaScript aborts candidate preparation. The current worker,\nlauncher, config, and rollback selection remain in place. Automatic staging\nlogs the number of files applied or already included without logging their\ncontents. Runtime JavaScript and JSON are supported; dependency trees and\nbrowser bundles are not local proxy polyfills.\n\nClean legacy installations bootstrap their baseline by comparing with a\nseparately staged registry package of the same version. An edited legacy build\ncannot be safely compared without its actual original base, so its upgrade is\nretained until that base is recorded explicitly:\n\nThis command records the original files; it does not apply edits, select a\npackage, or restart a service. Supply the pristine package from which the local\nedit was made. A different existing baseline is refused rather than overwritten.","hierarchy":{"lvl0":"Development","lvl1":"Proxy package updates and token budgets","lvl2":"Local compatibility polyfills","lvl3":""}},
 {"objectID":"82a142fcb5a4a408bcc1ef4a742c15da227f7efe0ca8039f32786bd317776acc","title":"Optional token reservations","url":"/docs/development/proxy-updates-and-token-budgets#optional-token-reservations","content":"NEUROLINK_PROXY_TOKEN_BUDGET accepts a JSON object. No token cap is enabled by\ndefault. For example, an operator could configure:\n\nThese numbers are illustrative, not recommended account allowances. Supported\nfields must be positive safe integers; an invalid configuration fails closed.\nmaxInFlightTokens is per provider/account. accountWindowTokens caps charged\ntokens in that account's fixed window. sessionWindowTokens applies across\naccounts and providers for the same client session. The default window is one\nhour when a cap is set without windowMs.\n\nBefore each native upstream attempt or translated SDK invocation, the proxy\nreserves estimated input plus the output allowance. An SDK invocation can contain\nprovider-internal retries that the proxy cannot observe individually; its single\nreservation does not prove or cap the combined tokens of those hidden retries. Tool definitions and instructions contribute to the input\nestimate. This is an estimate with recorded provenance, not an exact provider\ntokenization or a guarantee of monetary cost. A configured estimated input maximum\nis not a hard maximum on actual provider input tokens, especially for images,\naudio, and files. Model/context policy is configured\nseparately with NEUROLINK_PROXY_CONTEXT_POLICY; it must use the actual serving\nmodel. Provider-reported total input plus output replaces the estimate once when\ncomplete usage is known. Reasoning is already part of output and is not added a\nsecond time. Missing or uncertain usage retains the estimate. Cancellation\nbefore dispatch refunds the unused reservation; cancellation after dispatch does\nnot presume that the provider billed zero.\n\nActive and draining workers reserve atomically against one in-memory supervisor\ncoordinator. Outstanding reservations remain charged across a window boundary;\na reset cannot create new capacity for requests that are still running. Worker\nexit retains estimated spending for its unresolved calls while releasing its\nin-flight occupancy.","hierarchy":{"lvl0":"Development","lvl1":"Proxy package updates and token budgets","lvl2":"Optional token reservations","lvl3":""}},
 {"objectID":"183568ccdb77340136a3026e2df12e9e82c5722ba3ddbf3b5749ba6c62de231b","title":"OTLP acknowledgement boundaries","url":"/docs/development/proxy-updates-and-token-budgets#otlp-acknowledgement-boundaries","content":"Both metadata and body queues serialize through OpenTelemetry's official JSON\nserializer. A response-aware HTTP sender validates the complete, bounded response\nbefore reporting transport acknowledgement. HTTP 200 with {} or a zero-rejection\npartialSuccess warning is acknowledged. A known partial rejection leaves the\nwhole batch unconfirmed because the response does not identify the rejected\nrecords; that batch is not replayed. Empty, malformed, interrupted, oversized,\nunexpected-shape or ambiguous-alias success responses are also unconfirmed and\nare not retried. Empty JSON is not {}; the zero-byte protobuf convention does\nnot apply to this JSON sender. Canonical and proto snake_case response names are\naccepted, but duplicate aliases are conservatively rejected.\n\nTransient HTTP 429/502/503/504 and transport failures before a response may retry\nwithin the existing 30-second total export deadline, with at most five attempts\nand exponential backoff with jitter even when Retry-After is zero. Retries retain the same\nserialized event IDs and bytes, enabling query-side deduplication. Retry-After\ncannot extend the deadline. Response reads are capped at 64 KiB. The exporter\npreserves merged generic/log-specific OTLP headers, gzip request compression,\nand configured CA/client certificate/key files; invalid configuration fails\nexplicitly. It requests uncompressed JSON responses and treats unsupported\nresponse encodings as unconfirmed. Diagnostics omit collector response bodies\nand credentials. Transport acknowledgement remains distinct from backend\npersistence; query reconciliation is still needed to confirm ingestion.\n\nA staged update may finish after its original supervisor/updater has been\nreplaced. Before publishing, validation rollback, or activation, the updater\nrechecks that its recorded supervisor and updater PIDs still own the service\nand that the original parent is running. Unknown ownership defers mutation.\nStale update jobs cannot overwrite or roll back a replacemen","hierarchy":{"lvl0":"Development","lvl1":"Proxy package updates and token budgets","lvl2":"OTLP acknowledgement boundaries","lvl3":""}},
 {"objectID":"3d5db69fb501ec2b11df1700773d0e7648ef30c85f643c3b54975e4f45a3a05b","title":"🧪 COMPREHENSIVE TESTING & VERIFICATION PLAN","url":"/docs/development/testing-plan","content":"🧪 COMPREHENSIVE TESTING & VERIFICATION PLAN\nTest Results Documentation:\nUpdated Documentation:\n\nLighthouse Integration Testing Strategy\nDate: 2025-07-06 02:55 AM\nEstimated Duration: 3 hours total\n\n📋 TESTING OVERVIEW\n\nWhat We're Testing:\n✅ Real-time WebSocket Infrastructure - New streaming services, WebSocket server, enhanced chat\n✅ Advanced Telemetry Integration - OpenTelemetry stack (15+ dependencies, optional by default)\n✅ Voice AI Removal - Complete cleanup of voice dependencies and code\n✅ Backward Compatibility - All existing functionality preserved\n✅ New API Surface - Factory methods, exports, TypeScript interfaces\n\nCritical Success Criteria:\n✅ Zero Breaking Changes: All existing code works unchanged\n✅ Build Success: TypeScript compilation with 0 errors\n✅ Performance: \\<5% overhead when new features disabled\n✅ Optional Features: Telemetry disabled by default, WebSocket services optional\n✅ Complete Integration: New features work with existing AI providers and MCP tools\n\n🔄 PHASE A: IMMEDIATE VERIFICATION (30 minutes)\n\nPriority: CRITICAL | Blocking: Must pass before proceeding\n\nA.1 File System Verification (10 minutes)\n\nSuccess Criteria:\n✅ WebSocket infrastructure files exist\n✅ Streaming services files exist\n✅ Telemetry files exist\n✅ NO voice-related files remain\n✅ Enhanced chat files exist\n\nA.2 Build Validation (15 minutes)\n\nSuccess Criteria:\n✅ TypeScript compilation: 0 errors\n✅ Vite build: successful\n✅ CLI build: successful\n✅ publint: \"All good!\"\n✅ Package integrity: pnpm pack succeeds\n\nA.3 Dependency Verification (5 minutes)\n\nSuccess Criteria:\n✅ Voice AI dependencies: 0 found\n✅ OpenTelemetry dependencies: 15+ installed\n✅ No dependency conflicts\n✅ Package.json reflects changes\n\n🔧 PHASE B: CORE TESTING (1 hour)\n\nPriority: HIGH | Focus: New feature functionality\n\nB.1 WebSocket Infrastructure Testing (20 minutes)\n\nTests to Create:\ntest/websocket-server.test.ts\ntest/streaming-manager.test.ts\ntest/websocket-chat-handler.test.ts\n\nSuccess Criteria:\n✅ WebSocket server starts on specified port\n✅ Connection management works\n✅ Room creation/joining functional\n✅ Streaming channels operational\n✅ Error handling graceful\n\nB.2 Telemetry Integration Testing (20 minutes)\n\nTests to Create:\ntest/telemetryService.test.ts\ntest/ai-instrumentation.test.ts\ntest/mcp-instrumentation.test.ts\n\nSuccess Criteria:\n✅ Telemetry disabled by default\n✅ Telemetry enables when configured\n✅ AI operation tracking works\n✅ MCP tool instrumentation functional\n✅ Zero overhead when disabled\n\nB.3 Enhanced Chat Testing (20 minutes)\n\nTests to Create:\ntest/enhanced-chat.test.ts\ntest/chat-integration.test.ts\n\nSuccess Criteria:\n✅ Enhanced chat service creates successfully\n✅ SSE mode works\n✅ WebSocket mode works\n✅ Dual mode integration functional\n✅ Backward compatibility with existing chat\n\n🚀 PHASE C: COMPREHENSIVE VALIDATION (1 hour)\n\nPriority: HIGH | Focus: Integration and performance\n\nC.1 Existing Functionality Regression Testing (20 minutes)\n\nSuccess Criteria:\n✅ All existing tests pass\n✅ CLI commands work unchanged\n✅ SDK methods work unchanged\n✅ AI providers function correctly\n✅ MCP tools continue working\n\nC.2 Performance Impact Testing (20 minutes)\n\nSuccess Criteria:\n✅ Default performance unchanged\n✅ Performance overhead \\<5% when features enabled\n✅ Memory usage remains stable\n✅ No performance regressions\n\nC.3 Real-World Scenario Testing (20 minutes)\n\nSuccess Criteria:\n✅ WebSocket chat works end-to-end\n✅ Telemetry collects accurate data\n✅ Multi-provider scenarios work\n✅ Streaming integrations functional\n\n✅ PHASE D: FINAL VALIDATION (30 minutes)\n\nPriority: CRITICAL | Focus: Production readiness\n\nD.1 API Surface Validation (10 minutes)\n\nSuccess Criteria:\n✅ All new exports importable\n✅ TypeScript types correct\n✅ No missing dependencies\n✅ API surface consistent\n\nD.2 Documentation Synchronization (10 minutes)\n\nSuccess Criteria:\n✅ Documentation reflects actual implementation\n✅ Voice references removed/minimal\n✅ New features documented\n✅ Examples are accurate\n\nD.3 Production Deployment Readiness (10 minutes)\n\nSuccess Criteria:\n✅ Package builds correctly\n✅ Installation works\n✅ Imports work after installation\n✅ No missing files\n✅ Ready for npm publish\n\n📊 SUCCESS CRITERIA SUMMARY\n\nCritical (Must Pass):\n✅ Build Success: 0 TypeScript errors, successful compilation\n✅ Backward Compatibility: All existing functionality works unchanged\n✅ Performance: \\<5% overhead when new features disabled\n✅ Voice AI Removal: No voice dependencies or code remaining\n\nImportant (Should Pass):\n✅ WebSocket Infrastructure: Real-time services operational\n✅ Telemetry Integration: Optional monitoring works when enabled\n✅ Enhanced Chat: Dual-mode chat capabilities functional\n✅ API Consistency: New exports and types work correctly\n\nNice to Have (Can Be Fixed):\n✅ Documentation Completeness: All features documented\n✅ Example Applications: Working demos available\n✅ Performance Optimization: Further optimization opportunities\n\n🎯 EXECUTION ORDER\n\nSequential Execution Required:\nPhase A → Mu","hierarchy":{"lvl0":"Development","lvl1":"🧪 COMPREHENSIVE TESTING & VERIFICATION PLAN","lvl2":"","lvl3":""}},
@@ -2907,7 +2908,7 @@
 {"objectID":"8ea0d60b8e33eeebfb825eb12ad9fcd0cdad610ee262ac5486db5d7fa3b8406b","title":"5xx / Transient Server Error","url":"/docs/features/claude-proxy#5xx-transient-server-error","content":"Transient errors (408, 500, 502, 503, 504, and Cloudflare 520-526/529).\nAlso matches 400 responses with api_error or overloaded_error types that wrap transient HTML content (e.g., Cloudflare error pages).\nApply bounded same-account retries, then rotate to the next account.","hierarchy":{"lvl0":"Features","lvl1":"Claude Proxy","lvl2":"5xx / Transient Server Error","lvl3":""}},
 {"objectID":"195dae3c0ea28fdcfeb0fbf39c456fd580652b07fa5f2ce81b341d4279621cf8","title":"All Accounts Exhausted","url":"/docs/features/claude-proxy#all-accounts-exhausted","content":"When every account is in a cooling state:\nWalk the fallback chain (if configured).\nEach fallback uses NeuroLink's stream() pipeline with the specified provider/model.\nIf all fallbacks also fail, return a 429 with Retry-After set to the earliest account recovery time.","hierarchy":{"lvl0":"Features","lvl1":"Claude Proxy","lvl2":"All Accounts Exhausted","lvl3":""}},
 {"objectID":"a9d69b153d2a12e50877017c5bfbcdb2ba932f1223183c8c311614898ae4a910","title":"Bootstrap Retry (Streaming)","url":"/docs/features/claude-proxy#bootstrap-retry-streaming","content":"For streaming requests, the proxy reads the first chunk from the upstream response before forwarding it to the client. If the first chunk is empty (indicating a failed stream), the proxy retries with the next account. This prevents Claude Code from receiving an empty SSE stream.","hierarchy":{"lvl0":"Features","lvl1":"Claude Proxy","lvl2":"Bootstrap Retry (Streaming)","lvl3":""}},
-{"objectID":"98c795c3e6eec8f50fcb68adae0d6c62387d0ce83d06775eb4c32ff0698c7e7e","title":"Claude Code integration","url":"/docs/features/claude-proxy#claude-code-integration","content":"When the proxy starts, it automatically updates ~/.claude/settings.json:\n\nWhen the proxy stops (Ctrl+C or SIGTERM), it removes these entries from the settings file. This means Claude Code automatically routes through the proxy when it is running and goes direct when it is not.\n\nNote: You must restart Claude Code after starting or stopping the proxy for the settings change to take effect.","hierarchy":{"lvl0":"Features","lvl1":"Claude Proxy","lvl2":"Claude Code integration","lvl3":""}},
+{"objectID":"98c795c3e6eec8f50fcb68adae0d6c62387d0ce83d06775eb4c32ff0698c7e7e","title":"Claude Code integration","url":"/docs/features/claude-proxy#claude-code-integration","content":"Foreground proxy start and explicit proxy setup configure ~/.claude/settings.json:\n\nWhen the proxy stops (Ctrl+C or SIGTERM), it removes these entries from the settings file. This means Claude Code automatically routes through the proxy when it is running and goes direct when it is not.\n\nNote: You must restart Claude Code after starting or stopping the proxy for the settings change to take effect.\n\nManaged service restarts and rolling upgrades preserve existing client settings.\nThey do not reapply routing or replace user edits. Run neurolink proxy setup\nwhen you want to configure clients explicitly, including after a standalone\nservice installation.","hierarchy":{"lvl0":"Features","lvl1":"Claude Proxy","lvl2":"Claude Code integration","lvl3":""}},
 {"objectID":"228facfde8c5dd950496365bfc28e6470b20eee6543317f0c3cc9b5e239a972e","title":"Proxy state file","url":"/docs/features/claude-proxy#proxy-state-file","content":"The proxy persists its running state to ~/.neurolink/proxy-state.json so that neurolink proxy status can report on it and neurolink proxy start can detect an already-running instance. The state includes PID, port, host, strategy, start time, fallback chain, enforced account allowlist, and the optional foreground fail-open guard PID.","hierarchy":{"lvl0":"Features","lvl1":"Claude Proxy","lvl2":"Proxy state file","lvl3":""}},
 {"objectID":"08047056092173a6d64c0fa57508b677157b3da499411f5a0783681010239ce9","title":"Fail-open guard","url":"/docs/features/claude-proxy#fail-open-guard","content":"A foreground proxy spawns one detached neurolink proxy guard that removes stale Claude Code settings after confirming its parent process has died. A launchd-managed proxy keeps restart ownership in launchd and starts a separate updater-only worker. Automatic package updates are enabled by default and can be disabled with NEUROLINK_PROXY_AUTO_UPDATE=off (also accepts 0 or false). The worker validates the global package root and executable directory and requires the package manager that owns the running installation. Rolling installations activate and health-check the new serving worker first. If the parent supervisor still reports the older version, the updater waits for a two-minute idle window, applies a bounded admission drain, and asks launchd to refresh the supervisor. Success requires both worker and supervisor to report the new version from a new parent process. The drain automatically expires if the updater disappears, and refresh failures retain the installed version for retry instead of repeatedly reinstalling it. Legacy services wait for every request and stream before their direct launchd restart. Post-install executable validation uses bounded retries, and the proxy supervises and replaces an updater worker that exits unexpectedly. Installed-but-not-running versions and stage-specific update failures remain persisted in ~/.neurolink/update-state.json. Updater diagnostics are sent through the configured proxy log sink and exposed in neurolink proxy status.","hierarchy":{"lvl0":"Features","lvl1":"Claude Proxy","lvl2":"Fail-open guard","lvl3":""}},
 {"objectID":"778246a1bbbc0afc1258a50c9117e61d795099421fbd7f634d960f73aa6d3fc4","title":"Endpoints","url":"/docs/features/claude-proxy#endpoints","content":"| Method | Path                        | Description                             |\n| ------ | --------------------------- | --------------------------------------- |\n| POST   | /v1/messages              | Claude Messages API (main endpoint)     |\n| GET    | /v1/models                | List available Claude models            |\n| POST   | /v1/messages/count_tokens | Token counting                          |\n| GET    | /health                   | Health check (status, strategy, uptime) |\n| GET    | /status                   | Detailed proxy status                   |","hierarchy":{"lvl0":"Features","lvl1":"Claude Proxy","lvl2":"Endpoints","lvl3":""}},
@@ -3200,7 +3201,7 @@
 {"objectID":"8f00ff46e651a81fa28b61fd20f66b0a93b72d2024b4da2f2e8fe661b32c4d9e","title":"<<< neurolink-proxy (managed) <<<","url":"/docs/features/codex-proxy-support#-neurolink-proxy-managed--1","content":"Your original model_provider value is snapshotted to ~/.neurolink/codex-proxy-snapshot.json and restored on shutdown, so the edit is fully reversible even if the proxy crashes. The managed block is delimited by markers and removed cleanly on clear. If ~/.codex/config.toml` doesn't exist, the step is skipped silently.\n\nRestart Codex after starting the proxy for it to pick up the new provider.","hierarchy":{"lvl0":"Features","lvl1":"Codex (ChatGPT) Support for NeuroLink Proxy","lvl2":"<<< neurolink-proxy (managed) <<<","lvl3":""}},
 {"objectID":"404cd8f6d8542fc84651326cf0b252e7c3c3098678409fecaf8c2ff1559906fd","title":"4. Quota and routing","url":"/docs/features/codex-proxy-support#4-quota-and-routing","content":"Codex reports two rate-limit windows — primary (short) and secondary (weekly) — which map onto the shared AccountQuota model as the session and weekly fields respectively. That means Codex reuses the existing cooldown, persistence, and display code rather than duplicating it.\n\nAccount ordering is fill-first and quota-aware:\nAccounts on cooldown sort last.\nWithin the same cooldown state, accounts with a rejected unified quota sort after accounts without known rejection, even when their session usage is low or unknown.\nWithin each group, accounts with no session quota measurement sort first — they get probed so they become comparable, rather than being starved.\nOtherwise, least session utilization first. Rejected accounts remain eligible after preferred accounts so stale rejection evidence cannot permanently prevent a recovery probe.\n\nCooldown reasons map to the shared vocabulary: a rejected weekly window cools until its real reset (weekly), a rejected primary window until its reset (session), and a plain burst limit gets a bounded transient cooldown (60 s floor, 15 min ceiling).\n\nQuota and cooldown state are keyed by the full codex: account key, so a Codex account and an Anthropic account that share a bare label never collide.","hierarchy":{"lvl0":"Features","lvl1":"Codex (ChatGPT) Support for NeuroLink Proxy","lvl2":"4. Quota and routing","lvl3":""}},
 {"objectID":"acb592d28fcb90659fa175ac4f0d1e73cfb535d0aac2b63a101f0722e538eff7","title":"5. Response headers","url":"/docs/features/codex-proxy-support#5-response-headers","content":"A response served by the Codex pool carries these attribution headers. A\nresponse served by the outbound fallback\ncarries only x-neurolink-served-by: the account, attempt and quota headers\ndescribe a Codex account, and none served that turn.\n\n| Header                               | Meaning                                                                                                                                                                            |\n| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| x-neurolink-account                | Which pooled account served the request                                                                                                                                            |\n| x-neurolink-account-type           | Always codex-oauth                                                                                                                                                               |\n| x-neurolink-served-by              | codex, or codex-outbound-fallback:anthropic / codex-outbound-fallback:vertex when the outbound fallback served the turn |\n| x-neurolink-attempt                | Which attempt succeeded (1 = first account tried)                                                                                                                                  |\n| x-neurolink-quota-source           | live when the backend reported quota, else none                                                                                                                                |\n| x-neurolink-quota-session-left-pct | Remaining primary-window headroom                                                                                                                                                  |\n| x-neurolink-quota-weekly-left-pct  | Canonical remaining","hierarchy":{"lvl0":"Features","lvl1":"Codex (ChatGPT) Support for NeuroLink Proxy","lvl2":"5. Response headers","lvl3":""}},
-{"objectID":"2b17d62c4d9cb65067100d6a90003bee2dce2bc06ede425f25f0b761aade359a","title":"6. Error handling","url":"/docs/features/codex-proxy-support#6-error-handling","content":"| Condition                    | Behaviour                                                                                                                                                                        |\n| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| No Codex accounts configured | 401 with a message pointing at neurolink auth login codex                                                                                                                    |\n| All accounts cooling         | Terminal response.failed SSE event (200, retry-after computed from the soonest recovery) instead of a bare 429, so the CLI shows a real error instead of \"Reconnecting...\" |\n| 401 / 403 from upstream  | One forced token refresh, then rotate; a failed refresh disables the account until re-login                                                                                      |\n| 429                        | Cool the account per its reported window, then rotate                                                                                                                            |\n| 5xx / network              | Rotate to the next account                                                                                                                                                       |\n\nAccess tokens are refreshed proactively when within 5 minutes of expiry, and the rotated refresh token is written back to the store.","hierarchy":{"lvl0":"Features","lvl1":"Codex (ChatGPT) Support for NeuroLink Proxy","lvl2":"6. Error handling","lvl3":""}},
+{"objectID":"2b17d62c4d9cb65067100d6a90003bee2dce2bc06ede425f25f0b761aade359a","title":"6. Error handling","url":"/docs/features/codex-proxy-support#6-error-handling","content":"| Condition                    | Behaviour                                                                                                                                                                        |\n| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| No Codex accounts configured | 401 with a message pointing at neurolink auth login codex                                                                                                                    |\n| All accounts cooling         | Terminal response.failed SSE event (200, retry-after computed from the soonest recovery) instead of a bare 429, so the CLI shows a real error instead of \"Reconnecting...\" |\n| All accounts auth-cooling    | The same terminal event with code server_error instead of insufficient_quota (every account is parked by an auth failure), so it is not reported as spent quota              |\n| 401 / 403 from upstream  | One forced token refresh, then rotate; a failed refresh disables the account until re-login                                                                                      |\n| 429                        | Cool the account per its reported window, then rotate                                                                                                                            |\n| 5xx / network              | Rotate to the next account                                                                                                                                                       |\n\nAccess tokens are refreshed proactively when within 5 minutes of expiry, and the rotated refresh token is written back to the store.","hierarchy":{"lvl0":"Features","lvl1":"Codex (ChatGPT) Support for NeuroLink Proxy","lvl2":"6. Error handling","lvl3":""}},
 {"objectID":"9b1627d0fcff6a9e292b7f794fb47e62eb3da6b9c633e308da2b1de08a83368d","title":"7. Implementation map","url":"/docs/features/codex-proxy-support#7-implementation-map","content":"| File                                        | Role                                                                                      |\n| ------------------------------------------- | ----------------------------------------------------------------------------------------- |\n| src/lib/types/codex.ts                    | Codex auth-file, token, and rate-limit types                                              |\n| src/lib/auth/codexOAuth.ts                | Endpoints/constants, auth.json import, token refresh, JWT decode, account-id resolution |\n| src/lib/proxy/codexAccountUsage.ts        | Account enumeration, usage fetch, quota normalisation, header parsing                     |\n| src/lib/server/routes/codexProxyRoutes.ts | The pool engine: load → order → forward → rotate                                          |\n| src/cli/commands/auth.ts                  | auth login codex, Codex rows in auth list --refresh                                   |\n| src/cli/commands/proxy.ts                 | Route registration, /backend-api/* request tracking, ~/.codex/config.toml management  |\n\nThe Anthropic engine in claudeProxyRoutes.ts is untouched. The Codex engine is deliberately leaner: it does pre-commit rotation but not the full transient-retry-budget or admission-lease machinery.","hierarchy":{"lvl0":"Features","lvl1":"Codex (ChatGPT) Support for NeuroLink Proxy","lvl2":"7. Implementation map","lvl3":""}},
 {"objectID":"c90a5222434bc717385c13b9e9f9cb865d3ce71ed7a58c077a7b5241def7d086","title":"8. Caveats","url":"/docs/features/codex-proxy-support#8-caveats","content":"Model ids matter. The ChatGPT backend rejects models that aren't available to Codex-with-a-ChatGPT-account (e.g. gpt-5-codex returns a 400). Use the model your Codex config already uses.\nTerms of service. Pooling multiple personal ChatGPT subscriptions through one client fingerprint is the kind of pattern subscription anti-abuse systems are built to detect. The originator, installation_id, user-agent, and turn-metadata headers are all correlatable. Pooling your own accounts is materially different from sharing across people — weigh the account-ban risk accordingly.\nNative browser login is not implemented. The verified path is importing an existing codex login credential. The OAuth constants (authorize URL, PKCE, scopes) are present in codexOAuth.ts for a future native flow.\nQuota-aware ordering is unverified against the live backend. The usage endpoint and the rate-limit header shape were reconstructed from a capture, not confirmed end to end. If either is wrong, fetchCodexAccountUsage returns no quota, x-neurolink-quota-source reads none, and ordering degenerates to insertion order while every 429 falls back to the 15-minute transient cooldown. Rotation still works; it is simply not quota-aware. Verify with neurolink auth list --refresh — a codex usage … error line per account means the quota path is not live.\nSSE usage-limit signals are not acted on. Only an HTTP 429 triggers a cooldown and rotation. A 200 response whose SSE stream carries usage_limit_reached (or the workspace-credit variants) is relayed to the client untouched, so the account is neither cooled nor rotated away from. HTTP-level exhaustion is handled; in-stream exhaustion is not.\nClient fingerprint is forwarded verbatim. The proxy replaces the caller's credentials but does not regenerate originator, installation_id, session-id, or turn metadata per account, so every pooled account shares the client's fingerprint. This is what makes the terms-of-service point above concrete.","hierarchy":{"lvl0":"Features","lvl1":"Codex (ChatGPT) Support for NeuroLink Proxy","lvl2":"8. Caveats","lvl3":""}},
 {"objectID":"607b92eb2c3b89a57438267a92b6212e616ad0dd106cb1c1a6bd0514c3446cd2","title":"Model discovery","url":"/docs/features/codex-proxy-support#model-discovery","content":"The Codex CLI refreshes its model list on every invocation:\n\nThe proxy relays that upstream to chatgpt.com/backend-api/codex/models using a\npooled account, forwarding the CLI's own query parameters.\n\nIt relays rather than synthesises, unlike the Claude and OpenAI /v1/models\nroutes, which build their lists locally from the model router. Which Codex\nmodels an account can reach is a property of that account — plan tier, rollout\nstate — not something this proxy knows, so a locally-built list would be a guess\nthat reads as authoritative.\n\nTwo details matter to anyone touching it:\nclient_version is required upstream. Omit it and ChatGPT answers 400\n  with a pydantic Field required on ('query', 'client_version'). The query\n  is rebuilt from ctx.query; ctx.path carries no query string, and reading it\n  from there drops the parameter silently.\nDiscovery is side-effect free. No cooldown is recorded and no quota is\n  consumed, so the once-per-invocation refresh cannot influence routing for real\n  traffic. A cooling account is still allowed to answer it — being rate-limited\n  for completions does not make an account unable to say which models exist.\n\nBefore this route existed the request 404'd, and the CLI printed\nfailed to refresh available models: unexpected status 404 Not Found on every\nrun before silently falling back to a default model — quietly ignoring the model\nthe user had configured.","hierarchy":{"lvl0":"Features","lvl1":"Codex (ChatGPT) Support for NeuroLink Proxy","lvl2":"Model discovery","lvl3":""}},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "12.44.5",
+  "version": "12.44.7",
   "packageManager": "pnpm@10.15.1",
   "description": "The pipe layer of an AI nervous system: one interface connecting provider neurons to your application, across three inference types — generate, stream and decide. `decide` returns typed, calibrated judgements from a non-generative model (~400ms, ~$0.00002/call) for routing, tool selection and context budgeting. MCP-native (4 transports), voice TTS/STT/realtime, RAG, agents, memory, compaction, 9 observability exporters. OpenAI · Anthropic · Gemini · Bedrock · Azure · Ollama · TypeSafe Jev and more.",
   "author": {
@@ -188,6 +188,7 @@
     "test:tool-routing-cli": "pnpm exec tsx test/continuous-test-suite-tool-routing-cli.ts",
     "test:tool-dedup": "pnpm exec tsx test/continuous-test-suite-tool-dedup.ts",
     "test:tools-manager-truncation": "pnpm exec tsx test/continuous-test-suite-tools-manager-truncation.ts",
+    "test:tooling-scripts": "pnpm exec tsx test/continuous-test-suite-tooling-scripts.ts",
     "test:model-not-found-retryable": "pnpm exec tsx test/continuous-test-suite-model-not-found-retryable.ts",
     "test:reasoning-parity-live": "pnpm exec tsx test/continuous-test-suite-reasoning-parity-live.ts",
     "test:ci": "pnpm run test && pnpm run test:client && pnpm run test:hitl",
@@ -286,7 +287,8 @@
     "test:native-failure-events": "pnpm exec tsx test/continuous-test-suite-native-failure-events.ts",
     "test:native-audio-model-aware": "pnpm exec tsx test/continuous-test-suite-native-audio-model-aware.ts",
     "test:cli-json-output": "pnpm exec tsx test/continuous-test-suite-cli-json-output.ts",
-    "test:logging-guidelines": "pnpm exec tsx test/continuous-test-suite-logging-guidelines.ts"
+    "test:logging-guidelines": "pnpm exec tsx test/continuous-test-suite-logging-guidelines.ts",
+    "test:proxy-polyfills": "pnpm exec tsx test/continuous-test-suite-proxy-polyfills.ts"
   },
   "files": [
     "dist",
@@ -444,6 +446,7 @@
     "chardet": "2.1.1",
     "croner": "^9.1.0",
     "csv-parser": "^3.2.0",
+    "diff": "^9.0.0",
     "dotenv": "^17.3.1",
     "eventsource-parser": "^3.0.8",
     "fast-xml-parser": "^5.7.0",
@@ -565,7 +568,6 @@
     "@vercel/ncc": "^0.38.4",
     "concurrently": "^9.2.1",
     "conventional-changelog-conventionalcommits": "^9.1.0",
-    "diff": "^9.0.0",
     "esbuild": "^0.28.1",
     "eslint": "^10.0.2",
     "glob": "^13.0.6",