@juspay/neurolink 12.30.0 → 12.30.2

package/CHANGELOG.md

@@ -1,8 +1,8 @@
-## [12.30.0](https://github.com/juspay/neurolink/compare/v12.29.2...v12.30.0) (2026-09-26)
+## [12.30.2](https://github.com/juspay/neurolink/compare/v12.30.1...v12.30.2) (2026-09-26)
 
-### Features
+### Bug Fixes
 
-- **(video):** honour videoOptions end to end, timestamp keyframes, transcribe speech ([ab037cc](https://github.com/juspay/neurolink/commit/ab037cc1ecce885c9a4bd64f6ca020021f24a038)), closes [#1720](https://github.com/juspay/neurolink/issues/1720) [#478](https://github.com/juspay/neurolink/issues/478) [#460](https://github.com/juspay/neurolink/issues/460) [#433](https://github.com/juspay/neurolink/issues/433) [#433](https://github.com/juspay/neurolink/issues/433) [#460](https://github.com/juspay/neurolink/issues/460)
+- **(ci):** read branch protection through read-access endpoints in the audit ([19e08e2](https://github.com/juspay/neurolink/commit/19e08e214cdd699c2a22cc0de45d781a163fc473))
 
 ## [11.2.3](https://github.com/juspay/neurolink/compare/v11.2.2...v11.2.3) (2026-08-19)
 

package/dist/cli/proxy-clients/codex.js

@@ -8,6 +8,7 @@ import { homedir } from "os";
 import { join } from "path";
 import { logger } from "../../utils/logger.js";
 import { writeFileAtomic } from "./snapshot.js";
+import { dottedTableIds, findDuplicateTable, ownedLineCount, readStringValue, splitTomlSections, } from "./tomlSections.js";
 //
 // Points the Codex CLI at the proxy by managing `~/.codex/config.toml`:
 //   - appends a marker-delimited `[model_providers.neurolink]` table
@@ -28,18 +29,67 @@ function getCodexSnapshotPath() {
 }
 const CODEX_BLOCK_BEGIN = "# >>> neurolink-proxy (managed) >>>";
 const CODEX_BLOCK_END = "# <<< neurolink-proxy (managed) <<<";
+const CODEX_MANAGED_COMMENT_LINES = new Set([
+    CODEX_BLOCK_BEGIN,
+    CODEX_BLOCK_END,
+]);
+const CODEX_PROVIDER_ID = "neurolink";
+const CODEX_PROVIDER_NAME = "NeuroLink Proxy";
 const CODEX_PROVIDER_LINE_RE = /^[ \t]*model_provider[ \t]*=.*$/m;
 const CODEX_MODEL_LINE_RE = /^[ \t]*model[ \t]*=.*$/m;
-/** Strip any previously-managed block + our injected provider line. */
-function stripCodexManagedConfig(text) {
-    const blockRe = new RegExp(`\\n?${escapeRegExp(CODEX_BLOCK_BEGIN)}[\\s\\S]*?${escapeRegExp(CODEX_BLOCK_END)}\\n?`, "g");
-    let out = text.replace(blockRe, "\n");
-    // Remove our injected selector line (only the exact "neurolink" one).
-    out = out.replace(/^[ \t]*model_provider[ \t]*=[ \t]*"neurolink"[ \t]*$\n?/m, "");
-    return out;
+const CODEX_MANAGED_SELECTOR_RE = /^[ \t]*model_provider[ \t]*=[ \t]*"neurolink"[ \t]*$\n?/m;
+/**
+ * What of a Codex config.toml the proxy owns, found by content rather than
+ * by the block markers. Codex's own saves keep comments (measured on
+ * codex-cli 0.155.1), but a hand edit or another tool need not, and a
+ * marker-only writer then appended a second `[model_providers.neurolink]`,
+ * which Codex cannot parse. The proxy's provider is that table carrying the
+ * name the proxy writes, with any sub-tables under it. `foreign` is set when
+ * a `neurolink` provider exists that the proxy did not write: another name, a
+ * dotted-key or array definition, or sub-tables with no provider table, which
+ * the proxy never writes. Writing ours beside it would declare the table twice
+ * or adopt the user's keys. `remainder` keeps every byte the proxy does not
+ * own, including comments the user wrote after its table.
+ */
+function inspectCodexConfig(text) {
+    const sections = splitTomlSections(text);
+    const isProvider = (section) => section.path !== null &&
+        section.path.length >= 2 &&
+        section.path[0] === "model_providers" &&
+        section.path[1] === CODEX_PROVIDER_ID;
+    const tables = sections.filter((section) => isProvider(section) && !section.arrayTable && section.path?.length === 2);
+    const ours = (section) => readStringValue(section, "name") === CODEX_PROVIDER_NAME;
+    const foreign = tables.some((table) => !ours(table)) ||
+        (tables.length === 0 && sections.some(isProvider)) ||
+        sections.some((section) => isProvider(section) && section.arrayTable) ||
+        dottedTableIds(sections, "model_providers").includes(CODEX_PROVIDER_ID);
+    const owned = sections.map((section) => isProvider(section) &&
+        !section.arrayTable &&
+        (section.path?.length === 2 ? ours(section) : !foreign));
+    const managedBaseUrls = [
+        ...new Set(sections.flatMap((section, index) => {
+            const url = owned[index]
+                ? readStringValue(section, "base_url")
+                : undefined;
+            return url === undefined ? [] : [url];
+        })),
+    ];
+    const remainder = sections
+        .flatMap((section, index) => owned[index]
+        ? section.lines.slice(ownedLineCount(section, CODEX_MANAGED_COMMENT_LINES))
+        : section.lines)
+        .filter((line) => !CODEX_MANAGED_COMMENT_LINES.has(line.trim()))
+        .join("");
+    return { remainder, managedBaseUrls, foreign };
 }
-function escapeRegExp(value) {
-    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/**
+ * Remove the selector the proxy injected. Only the preamble holds top-level
+ * keys: a profile's own `model_provider = "neurolink"` is the user's.
+ */
+function stripCodexSelector(text) {
+    return editTomlPreamble(text, (preamble) => CODEX_MANAGED_SELECTOR_RE.test(preamble)
+        ? preamble.replace(CODEX_MANAGED_SELECTOR_RE, "")
+        : null);
 }
 /**
  * Apply a top-level TOML key edit, confined to the document preamble.
@@ -60,8 +110,8 @@ function editTomlPreamble(text, edit) {
 function buildCodexProviderBlock(baseUrl) {
     return [
         CODEX_BLOCK_BEGIN,
-        "[model_providers.neurolink]",
-        'name = "NeuroLink Proxy"',
+        `[model_providers.${CODEX_PROVIDER_ID}]`,
+        `name = "${CODEX_PROVIDER_NAME}"`,
         `base_url = "${baseUrl}/backend-api/codex"`,
         'wire_api = "responses"',
         "requires_openai_auth = true",
@@ -77,6 +127,37 @@ export async function setCodexProxySettings(baseUrl) {
             return false;
         }
         const original = fs.readFileSync(getCodexConfigPath(), "utf8");
+        const inspected = inspectCodexConfig(original);
+        if (inspected.foreign) {
+            logger.warn("[proxy] Codex: config.toml already defines a neurolink provider the proxy did not write; leaving it untouched");
+            return false;
+        }
+        let text = stripCodexSelector(inspected.remainder);
+        // Set the selector: replace an existing top-level model_provider or insert
+        // one right after the top-level `model = ...` line (stays before any table).
+        let selectorPlaced = false;
+        text = editTomlPreamble(text, (preamble) => {
+            if (CODEX_PROVIDER_LINE_RE.test(preamble)) {
+                selectorPlaced = true;
+                return preamble.replace(CODEX_PROVIDER_LINE_RE, 'model_provider = "neurolink"');
+            }
+            if (CODEX_MODEL_LINE_RE.test(preamble)) {
+                selectorPlaced = true;
+                return preamble.replace(CODEX_MODEL_LINE_RE, (line) => `${line}\nmodel_provider = "neurolink"`);
+            }
+            return null;
+        });
+        if (!selectorPlaced) {
+            text = `model_provider = "neurolink"\n${text}`;
+        }
+        const next = `${text.replace(/\s*$/, "\n")}\n${buildCodexProviderBlock(baseUrl)}`;
+        // Codex will not load a config that declares a table twice. Writing into
+        // one would only bury the user's own error under ours.
+        const duplicate = findDuplicateTable(next);
+        if (duplicate !== undefined) {
+            logger.warn(`[proxy] Codex: config.toml declares [${duplicate}] more than once; leaving it untouched`);
+            return false;
+        }
         // Snapshot the user's original selector once (survives crashes/restarts).
         if (!fs.existsSync(getCodexSnapshotPath())) {
             // Same preamble boundary the edit paths use. Matching document-wide would
@@ -95,26 +176,11 @@ export async function setCodexProxySettings(baseUrl) {
             fs.mkdirSync(join(homedir(), ".neurolink"), { recursive: true });
             await writeFileAtomic(getCodexSnapshotPath(), JSON.stringify({ originalProviderLine }, null, 2), 0o600);
         }
-        let text = stripCodexManagedConfig(original);
-        // Set the selector: replace an existing top-level model_provider or insert
-        // one right after the top-level `model = ...` line (stays before any table).
-        let selectorPlaced = false;
-        text = editTomlPreamble(text, (preamble) => {
-            if (CODEX_PROVIDER_LINE_RE.test(preamble)) {
-                selectorPlaced = true;
-                return preamble.replace(CODEX_PROVIDER_LINE_RE, 'model_provider = "neurolink"');
-            }
-            if (CODEX_MODEL_LINE_RE.test(preamble)) {
-                selectorPlaced = true;
-                return preamble.replace(CODEX_MODEL_LINE_RE, (line) => `${line}\nmodel_provider = "neurolink"`);
-            }
-            return null;
-        });
-        if (!selectorPlaced) {
-            text = `model_provider = "neurolink"\n${text}`;
+        // Every proxy start applies. Rewriting a file that already matches only
+        // widens the window for racing Codex's own saves.
+        if (next !== original) {
+            await writeFileAtomic(getCodexConfigPath(), next);
         }
-        const trimmed = text.replace(/\s*$/, "\n");
-        await writeFileAtomic(getCodexConfigPath(), `${trimmed}\n${buildCodexProviderBlock(baseUrl)}`);
         return true;
     }
     catch (error) {
@@ -129,19 +195,23 @@ export async function clearCodexProxySettings(expectedBaseUrl) {
             return false;
         }
         const original = fs.readFileSync(getCodexConfigPath(), "utf8");
-        // The managed block records its owner in `base_url`. Without this check a
-        // second proxy shutting down on another port would strip the block that the
-        // still-running proxy installed, and restore the snapshot selector on top —
-        // silently taking Codex off the live proxy. Mirrors the Claude and OpenCode
-        // clear paths.
-        if (expectedBaseUrl) {
-            const ownerMatch = original.match(new RegExp(`${escapeRegExp(CODEX_BLOCK_BEGIN)}[\\s\\S]*?base_url\\s*=\\s*"([^"]*)"`));
-            if (ownerMatch &&
-                ownerMatch[1] !== `${expectedBaseUrl}/backend-api/codex`) {
-                return false;
-            }
+        const inspected = inspectCodexConfig(original);
+        // Apply refuses such a config, so the selector pointing at the user's own
+        // provider is theirs as well.
+        if (inspected.foreign) {
+            return false;
+        }
+        // The managed table records its owner in `base_url`. Without this check a
+        // second proxy shutting down on another port would strip the table that
+        // the still-running proxy installed, and restore the snapshot selector on
+        // top — silently taking Codex off the live proxy. Mirrors the Claude and
+        // OpenCode clear paths.
+        if (expectedBaseUrl &&
+            inspected.managedBaseUrls.length > 0 &&
+            !inspected.managedBaseUrls.includes(`${expectedBaseUrl}/backend-api/codex`)) {
+            return false;
         }
-        let text = stripCodexManagedConfig(original);
+        let text = stripCodexSelector(inspected.remainder);
         // Restore the user's original selector line if we snapshotted one.
         let restored = null;
         if (fs.existsSync(getCodexSnapshotPath())) {

package/dist/cli/proxy-clients/grok.d.ts

@@ -18,6 +18,16 @@
  * Adaptive thinking: Grok's global `default_reasoning_effort = "xhigh"`
  * becomes Anthropic `thinking.type = "adaptive"`. Haiku 4.5 rejects that
  * with 400. Only Claude Opus/Sonnet 4.6 and 5.x keep reasoning enabled.
+ *
+ * Ownership is decided by content, never by the block markers alone. Grok
+ * rewrites config.toml on its own saves (`/settings`, `grok mcp add`, ...)
+ * through a serializer that drops every comment, the markers included, and
+ * splits the inline `extra_headers` into a `[model.<id>.extra_headers]`
+ * sub-table (measured on Grok Build 1.0.40). A marker-only writer then kept
+ * the unmarked tables and appended a second copy of every id on the next
+ * proxy start, and TOML rejects a table declared twice, so Grok would not
+ * start. What marks an entry as ours is the placeholder key, a credential
+ * only the proxy accepts, and that survives Grok's rewrite.
  */
 import type { CliGrokProxyModelSpec, CliProxyClientApplyOptions, CliProxyClientConfigurator, ModelMapping } from "../../types/index.js";
 declare function getGrokConfigDir(): string;
@@ -26,7 +36,11 @@ declare function getGrokSnapshotPath(): string;
 declare function classifyGrokProxyModel(id: string, mapping?: ModelMapping): CliGrokProxyModelSpec;
 declare function loadRoutedModelIds(configPath?: string): Promise<string[]>;
 declare function catalogModelIds(configPath?: string): Promise<string[]>;
-declare function buildGrokManagedBlock(baseUrl: string, configPath?: string): Promise<string>;
+/**
+ * `userModelIds` are ids the user defines themselves. Writing the proxy's
+ * entry beside theirs would declare the table twice, so theirs wins.
+ */
+declare function buildGrokManagedBlock(baseUrl: string, configPath?: string, userModelIds?: ReadonlySet<string>): Promise<string>;
 export declare function setGrokProxySettings(baseUrl: string, options?: CliProxyClientApplyOptions): Promise<boolean>;
 export declare function clearGrokProxySettings(expectedBaseUrl?: string): Promise<boolean>;
 export declare const grokConfigurator: CliProxyClientConfigurator;

package/dist/cli/proxy-clients/grok.js

@@ -18,6 +18,16 @@
  * Adaptive thinking: Grok's global `default_reasoning_effort = "xhigh"`
  * becomes Anthropic `thinking.type = "adaptive"`. Haiku 4.5 rejects that
  * with 400. Only Claude Opus/Sonnet 4.6 and 5.x keep reasoning enabled.
+ *
+ * Ownership is decided by content, never by the block markers alone. Grok
+ * rewrites config.toml on its own saves (`/settings`, `grok mcp add`, ...)
+ * through a serializer that drops every comment, the markers included, and
+ * splits the inline `extra_headers` into a `[model.<id>.extra_headers]`
+ * sub-table (measured on Grok Build 1.0.40). A marker-only writer then kept
+ * the unmarked tables and appended a second copy of every id on the next
+ * proxy start, and TOML rejects a table declared twice, so Grok would not
+ * start. What marks an entry as ours is the placeholder key, a credential
+ * only the proxy accepts, and that survives Grok's rewrite.
  */
 import { readFileSync } from "fs";
 import { homedir } from "os";
@@ -26,9 +36,19 @@ import { logger } from "../../utils/logger.js";
 import { getContextWindowSize } from "../../constants/contextWindows.js";
 import { DEFAULT_PROXY_MODEL_IDS } from "../../constants/proxyModels.js";
 import { defaultProxyConfigPath, parseProxyConfigString, } from "../../proxy/proxyConfig.js";
-import { isUsableSnapshot, shouldCaptureSnapshot, writeFileAtomic, } from "./snapshot.js";
+import { isUsableSnapshot, resolveSymlinkTarget, shouldCaptureSnapshot, writeFileAtomic, } from "./snapshot.js";
+import { dottedTableIds, findDuplicateTable, inlineTablePairs, maskTomlStrings, maskedStringValue, ownedLineCount, parseMaskedAssignment, readStringValue, splitTomlSections, tomlCodeLines, } from "./tomlSections.js";
 const GROK_BLOCK_BEGIN = "# >>> neurolink-proxy (managed) >>>";
 const GROK_BLOCK_END = "# <<< neurolink-proxy (managed) <<<";
+const GROK_BLOCK_NOTES = [
+    "# Proxy catalog. Built-in grok-4.6 / grok-4.5 stay on xAI.",
+    "# context_window is Grok's compaction limit and must be <= upstream.",
+];
+const GROK_MANAGED_COMMENT_LINES = new Set([
+    GROK_BLOCK_BEGIN,
+    GROK_BLOCK_END,
+    ...GROK_BLOCK_NOTES,
+]);
 const PLACEHOLDER_KEY = "neurolink-proxy";
 const ANTHROPIC_VERSION = "2023-06-01";
 function getGrokConfigDir() {
@@ -43,9 +63,6 @@ function getGrokConfigPath() {
 function getGrokSnapshotPath() {
     return join(homedir(), ".neurolink", "grok-proxy-snapshot.json");
 }
-function escapeRegExp(value) {
-    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
 function tomlKey(id) {
     return /^[A-Za-z0-9_-]+$/.test(id) ? id : JSON.stringify(id);
 }
@@ -172,28 +189,148 @@ function buildGrokModelBlock(spec, baseUrl) {
     }
     return lines.join("\n");
 }
-async function buildGrokManagedBlock(baseUrl, configPath) {
-    const specs = await catalogGrokSpecs(configPath);
-    const body = specs
+/**
+ * `userModelIds` are ids the user defines themselves. Writing the proxy's
+ * entry beside theirs would declare the table twice, so theirs wins.
+ */
+async function buildGrokManagedBlock(baseUrl, configPath, userModelIds = new Set()) {
+    const catalog = await catalogGrokSpecs(configPath);
+    for (const spec of catalog) {
+        if (userModelIds.has(spec.id)) {
+            logger.debug(`[proxy] Grok: config.toml already defines [model.${tomlKey(spec.id)}]; keeping it and skipping the proxy's entry`);
+        }
+    }
+    const body = catalog
+        .filter((spec) => !userModelIds.has(spec.id))
         .map((spec) => buildGrokModelBlock(spec, baseUrl))
         .join("\n\n");
     return [
         GROK_BLOCK_BEGIN,
-        "# Proxy catalog. Built-in grok-4.6 / grok-4.5 stay on xAI.",
-        "# context_window is Grok's compaction limit and must be <= upstream.",
+        ...GROK_BLOCK_NOTES,
         "",
         body,
         GROK_BLOCK_END,
         "",
     ].join("\n");
 }
-function stripGrokManagedBlock(text) {
-    const blockRe = new RegExp(`\\n?${escapeRegExp(GROK_BLOCK_BEGIN)}[\\s\\S]*?${escapeRegExp(GROK_BLOCK_END)}\\n?`, "g");
-    return text.replace(blockRe, "\n");
+function modelEntryId(section) {
+    return section.path !== null &&
+        section.path.length >= 2 &&
+        section.path[0] === "model"
+        ? section.path[1]
+        : null;
+}
+/** Where a model entry carries the placeholder key, as a path within it. */
+const PLACEHOLDER_KEY_PATHS = [
+    ["api_key"],
+    ["extra_headers", "x-api-key"],
+];
+function isPlaceholderKey(path, value) {
+    return (value === PLACEHOLDER_KEY &&
+        PLACEHOLDER_KEY_PATHS.some((keyPath) => keyPath.length === path.length &&
+            keyPath.every((part, index) => path[index] === part)));
+}
+/**
+ * Whether a section of a model entry sends the placeholder key: `api_key` on
+ * the model, or `x-api-key` in its `extra_headers`, spelled as a plain key, a
+ * dotted key, an inline table or the sub-table Grok's own save writes. The
+ * full key path must match, so a user's `legacy.api_key` is not the proxy's.
+ */
+function sectionSendsPlaceholderKey(section) {
+    const prefix = section.path?.slice(2) ?? [];
+    return tomlCodeLines(section).some(({ line, statement }) => {
+        if (!statement) {
+            return false;
+        }
+        const { masked, strings } = maskTomlStrings(line);
+        const assignment = parseMaskedAssignment(masked, strings);
+        if (!assignment) {
+            return false;
+        }
+        const path = [...prefix, ...assignment.path];
+        return (isPlaceholderKey(path, maskedStringValue(assignment.value, strings)) ||
+            inlineTablePairs(assignment.value, strings).some((pair) => isPlaceholderKey([...path, ...pair.path], maskedStringValue(pair.value, strings))));
+    });
 }
-function extractManagedBaseUrl(text) {
-    const match = text.match(new RegExp(`${escapeRegExp(GROK_BLOCK_BEGIN)}[\\s\\S]*?base_url\\s*=\\s*"([^"]*)"`));
-    return match?.[1];
+/**
+ * Which parts of a Grok config.toml the proxy owns.
+ *
+ * A model entry is a `[model.<id>]` table plus its `[model.<id>.*]`
+ * sub-tables, wherever they sit: Grok's save keeps them together, hand edits
+ * need not. It is the proxy's when it sends the placeholder key and is either
+ * in the current catalog or still carries the exact name the proxy gave it,
+ * which covers entries a later catalog dropped. A user's own model behind the
+ * proxy, under their own name, is theirs. Keys and values are read as TOML,
+ * never as raw text, so a string that merely mentions the placeholder cannot
+ * make a user's table look like the proxy's. `remainder` is the text with
+ * owned entries and the managed comment lines removed and every other byte
+ * kept, so a missing, orphaned or doubled marker cannot make an apply delete
+ * the user's content or leave an old copy of the catalog behind.
+ */
+function inspectGrokConfig(text, catalogIds) {
+    const sections = splitTomlSections(text);
+    // Models the user defines without a [model.<id>] table of their own.
+    const definedElsewhere = new Set([
+        ...dottedTableIds(sections, "model"),
+        ...sections.flatMap((section) => {
+            const id = section.arrayTable ? modelEntryId(section) : null;
+            return id !== null && section.path?.length === 2 ? [id] : [];
+        }),
+    ]);
+    const ids = sections.map((section) => section.arrayTable ? null : modelEntryId(section));
+    const isModelTable = (index) => ids[index] !== null && sections[index].path?.length === 2;
+    const tableFor = (index) => {
+        if (ids[index] === null || isModelTable(index)) {
+            return index;
+        }
+        const sameModel = (candidate) => isModelTable(candidate) && ids[candidate] === ids[index];
+        const before = sections.findLastIndex((_, candidate) => candidate < index && sameModel(candidate));
+        const after = sections.findIndex((_, candidate) => candidate > index && sameModel(candidate));
+        return before !== -1 ? before : after !== -1 ? after : index;
+    };
+    const entryOf = sections.map((_, index) => tableFor(index));
+    const ownedEntries = new Set(entryOf.filter((entry) => {
+        const id = ids[entry];
+        if (id === null) {
+            return false;
+        }
+        const sendsPlaceholder = sections.some((section, index) => entryOf[index] === entry &&
+            ids[index] !== null &&
+            sectionSendsPlaceholderKey(section));
+        if (!sendsPlaceholder) {
+            return false;
+        }
+        // A sub-table left without its table carries no name to check; it is
+        // the proxy's unless the model is defined some other way.
+        if (!isModelTable(entry)) {
+            return !definedElsewhere.has(id);
+        }
+        return (catalogIds.has(id) ||
+            readStringValue(sections[entry], "name") === displayNameFor(id));
+    }));
+    const owned = sections.map((_, index) => ids[index] !== null && ownedEntries.has(entryOf[index]));
+    const userModelIds = new Set([
+        ...definedElsewhere,
+        ...sections.flatMap((section, index) => {
+            const id = modelEntryId(section);
+            return id !== null && !owned[index] ? [id] : [];
+        }),
+    ]);
+    const managedBaseUrls = [
+        ...new Set(sections.flatMap((section, index) => {
+            const url = owned[index]
+                ? readStringValue(section, "base_url")
+                : undefined;
+            return url === undefined ? [] : [url];
+        })),
+    ];
+    const remainder = sections
+        .flatMap((section, index) => owned[index]
+        ? section.lines.slice(ownedLineCount(section, GROK_MANAGED_COMMENT_LINES))
+        : section.lines)
+        .filter((line) => !GROK_MANAGED_COMMENT_LINES.has(line.trim()))
+        .join("");
+    return { remainder, managedBaseUrls, userModelIds };
 }
 async function readGrokSnapshot() {
     const fs = await import("fs");
@@ -250,11 +387,26 @@ export async function setGrokProxySettings(baseUrl, options) {
                 : original.indexOf(GROK_BLOCK_END) + GROK_BLOCK_END.length)
             : undefined
         : undefined;
+    const inspected = original === null
+        ? null
+        : inspectGrokConfig(original, new Set(await catalogModelIds(options?.configPath)));
+    const block = await buildGrokManagedBlock(baseUrl, options?.configPath, inspected?.userModelIds);
+    const remainder = inspected?.remainder ?? "";
+    const next = remainder.trim().length === 0
+        ? block
+        : `${remainder.replace(/\s*$/, "\n")}\n${block}`;
+    // Grok refuses to load or save a config it cannot parse. Writing into one
+    // would only bury the user's own error under ours.
+    const duplicate = findDuplicateTable(next);
+    if (duplicate !== undefined) {
+        logger.warn(`[proxy] Grok: config.toml declares [${duplicate}] more than once; leaving it untouched`);
+        return false;
+    }
     if (existingSnapshot === null ||
         shouldCaptureSnapshot({
             hasSnapshot: existingSnapshot !== null,
             written: existingSnapshot?.writtenBaseUrl,
-            current: extractManagedBaseUrl(original ?? "") ?? currentBlock,
+            current: inspected?.managedBaseUrls[0] ?? currentBlock,
         })) {
         fs.mkdirSync(join(homedir(), ".neurolink"), { recursive: true });
         await writeFileAtomic(getGrokSnapshotPath(), JSON.stringify({
@@ -262,12 +414,11 @@ export async function setGrokProxySettings(baseUrl, options) {
             writtenBaseUrl: baseUrl,
         }, null, 2), 0o600);
     }
-    const withoutBlock = original ? stripGrokManagedBlock(original) : "";
-    const trimmed = withoutBlock.replace(/\s*$/, "\n");
-    const next = `${trimmed}\n${await buildGrokManagedBlock(baseUrl, options?.configPath)}`;
-    await writeFileAtomic(getGrokConfigPath(), next.startsWith("\n") && original === null
-        ? next.replace(/^\n+/, "")
-        : next, original === null ? 0o600 : undefined);
+    // Every proxy start applies; an update starts one. Rewriting a file that
+    // already matches only widens the window for racing Grok's own saves.
+    if (next !== original) {
+        await writeFileAtomic(getGrokConfigPath(), next, original === null ? 0o600 : undefined);
+    }
     return true;
 }
 export async function clearGrokProxySettings(expectedBaseUrl) {
@@ -279,13 +430,16 @@ export async function clearGrokProxySettings(expectedBaseUrl) {
     catch {
         return false;
     }
-    if (!current.includes(GROK_BLOCK_BEGIN)) {
+    const inspected = inspectGrokConfig(current, new Set(await catalogModelIds()));
+    if (inspected.remainder === current) {
         return false;
     }
-    const configuredUrl = extractManagedBaseUrl(current);
+    // Another proxy's block is left alone. One entry the user repointed does
+    // not make the rest foreign, whichever entry happens to come first.
+    const configuredUrls = inspected.managedBaseUrls;
     if (expectedBaseUrl &&
-        configuredUrl !== undefined &&
-        configuredUrl !== expectedBaseUrl) {
+        configuredUrls.length > 0 &&
+        !configuredUrls.includes(expectedBaseUrl)) {
         logger.debug("[proxy] Grok clear: base URL is not the one we wrote, leaving it intact");
         return false;
     }
@@ -294,9 +448,13 @@ export async function clearGrokProxySettings(expectedBaseUrl) {
         logger.warn("[proxy] Grok clear: no usable snapshot, leaving config.toml untouched rather than stripping a block we cannot prove we own");
         return false;
     }
-    const remainder = stripGrokManagedBlock(current).replace(/\s*$/, "\n");
+    const remainder = inspected.remainder.replace(/\s*$/, "\n");
     if (!snapshot.originalExisted && remainder.trim().length === 0) {
-        fs.rmSync(getGrokConfigPath(), { force: true });
+        // Apply wrote through a symlink the user already had, so the link stays
+        // and the file apply created behind it goes.
+        fs.rmSync(await resolveSymlinkTarget(getGrokConfigPath()), {
+            force: true,
+        });
     }
     else {
         await writeFileAtomic(getGrokConfigPath(), remainder);

package/dist/cli/proxy-clients/snapshot.d.ts

@@ -63,6 +63,11 @@ export declare function isProxyOwnedValue(args: {
     written: unknown;
     current: unknown;
 }): boolean;
+/**
+ * The path a chain of symlinks finally names, which need not exist. A path
+ * that is not a link comes back unchanged.
+ */
+export declare function resolveSymlinkTarget(filePath: string): Promise<string>;
 /**
  * Replace a file's contents without ever exposing a partial one.
  *
@@ -112,5 +117,12 @@ export declare function isProxyOwnedValue(args: {
  * is NOT atomic. Moving the temp file to `os.tmpdir()` would look like a
  * tidy-up and would quietly restore the exact window this function exists to
  * close, on Windows only, where nobody here would see it.
+ *
+ * A config kept in a dotfiles repository is often a symlink into it, a setup
+ * Grok documents and its own writer honours. A rename over the link would
+ * replace the link with a regular file and leave the repository's copy stale,
+ * so the write lands on the end of the link chain instead, which need not
+ * exist yet. The temp file is that target's sibling, so the rename stays
+ * atomic.
  */
 export declare function writeFileAtomic(filePath: string, contents: string, mode?: number): Promise<void>;

package/dist/cli/proxy-clients/snapshot.js

@@ -113,6 +113,31 @@ export function isProxyOwnedValue(args) {
     }
     return valuesMatch(args.current, args.written);
 }
+/**
+ * The path a chain of symlinks finally names, which need not exist. A path
+ * that is not a link comes back unchanged.
+ */
+export async function resolveSymlinkTarget(filePath) {
+    const fs = await import("fs");
+    const { dirname, resolve } = await import("path");
+    let target = filePath;
+    for (let hops = 0;; hops += 1) {
+        let isLink;
+        try {
+            isLink = fs.lstatSync(target).isSymbolicLink();
+        }
+        catch {
+            isLink = false;
+        }
+        if (!isLink) {
+            return target;
+        }
+        if (hops === 40) {
+            throw new Error(`${filePath}: too many levels of symbolic links`);
+        }
+        target = resolve(dirname(target), fs.readlinkSync(target));
+    }
+}
 /** Distinguishes concurrent writers within one process. */
 let atomicWriteCounter = 0;
 /**
@@ -164,12 +189,20 @@ let atomicWriteCounter = 0;
  * is NOT atomic. Moving the temp file to `os.tmpdir()` would look like a
  * tidy-up and would quietly restore the exact window this function exists to
  * close, on Windows only, where nobody here would see it.
+ *
+ * A config kept in a dotfiles repository is often a symlink into it, a setup
+ * Grok documents and its own writer honours. A rename over the link would
+ * replace the link with a regular file and leave the repository's copy stale,
+ * so the write lands on the end of the link chain instead, which need not
+ * exist yet. The temp file is that target's sibling, so the rename stays
+ * atomic.
  */
 export async function writeFileAtomic(filePath, contents, mode) {
     const fs = await import("fs");
     const { dirname, join, basename } = await import("path");
+    const target = await resolveSymlinkTarget(filePath);
     atomicWriteCounter += 1;
-    const tempPath = join(dirname(filePath), `.${basename(filePath)}.neurolink-${process.pid}-${atomicWriteCounter}.tmp`);
+    const tempPath = join(dirname(target), `.${basename(target)}.neurolink-${process.pid}-${atomicWriteCounter}.tmp`);
     // Which step failed changes what the user should do about it: a failed write
     // is usually a missing directory or a full disk and the config is untouched,
     // while a failed rename is a locked destination and the config is intact but
@@ -180,7 +213,7 @@ export async function writeFileAtomic(filePath, contents, mode) {
     let effectiveMode = mode;
     if (effectiveMode === undefined) {
         try {
-            effectiveMode = fs.statSync(filePath).mode & 0o777;
+            effectiveMode = fs.statSync(target).mode & 0o777;
         }
         catch {
             effectiveMode = 0o600;
@@ -192,12 +225,12 @@ export async function writeFileAtomic(filePath, contents, mode) {
         // caller sees an ENOENT naming a path it never asked to write. Creating
         // the directory first makes a first-run write behave like the plain
         // writeFileSync it replaced.
-        fs.mkdirSync(dirname(filePath), { recursive: true });
+        fs.mkdirSync(dirname(target), { recursive: true });
         fs.writeFileSync(tempPath, contents, { mode: effectiveMode });
         stage = "chmod";
         fs.chmodSync(tempPath, effectiveMode);
         stage = "rename";
-        fs.renameSync(tempPath, filePath);
+        fs.renameSync(tempPath, target);
     }
     catch (error) {
         // Never leave scratch in the user's config directory.

package/dist/cli/proxy-clients/tomlSections.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Line-level TOML reading for the proxy's client-config writers.
+ *
+ * Grok and Codex keep their settings in TOML files the user and the CLI
+ * itself also edit, and the writers must find what the proxy wrote there
+ * without trusting its comment markers: Grok's own save drops every comment.
+ * No TOML parser is a dependency, and a parse-and-serialize round trip would
+ * reformat the user's file anyway, so this reads just enough structure to
+ * edit text in place: table headers, strings, keys and assignments. Every
+ * line keeps its own terminator, so text a writer does not own round-trips
+ * byte for byte.
+ */
+import type { CliTomlSection } from "../../types/index.js";
+export declare function splitTomlSections(text: string): CliTomlSection[];
+/**
+ * A line of TOML with every string replaced by `@<n>@` and any comment
+ * dropped, so text inside a string can never read as a key or an assignment.
+ * `strings[n]` is the decoded value. `@` cannot occur outside a string in
+ * valid TOML.
+ */
+export declare function maskTomlStrings(line: string): {
+    masked: string;
+    strings: string[];
+};
+export declare function parseMaskedAssignment(masked: string, strings: readonly string[]): {
+    path: string[];
+    value: string;
+} | null;
+/**
+ * The string a masked value starts with. Only the start counts, so a value
+ * with damage after it (a literal `\n` left by a bad paste) is still read.
+ */
+export declare function maskedStringValue(value: string, strings: readonly string[]): string | undefined;
+/** The pairs directly inside a one-line inline table. */
+export declare function inlineTablePairs(value: string, strings: readonly string[]): {
+    path: string[];
+    value: string;
+}[];
+/** The dotted key a statement assigns, and its value when that is a string. */
+export declare function readTomlAssignment(line: string): {
+    path: string[];
+    value: string | undefined;
+} | null;
+/**
+ * The lines of a section that are TOML rather than the inside of a
+ * multi-line string; `statement` marks those that start a key/value pair
+ * rather than continue an array or inline table.
+ */
+export declare function tomlCodeLines(section: CliTomlSection): {
+    line: string;
+    statement: boolean;
+}[];
+export declare function readStringValue(section: CliTomlSection, key: string): string | undefined;
+/**
+ * Names of the `<parent>.<name>` tables defined by dotted keys instead of a
+ * `[<parent>.<name>]` header: `claude-opus-4-6.base_url = ...` under
+ * `[model]`, or `model.claude-opus-4-6.base_url = ...` before the first
+ * header.
+ */
+export declare function dottedTableIds(sections: readonly CliTomlSection[], parent: string): string[];
+/**
+ * How many of an owned section's lines are the writer's. Comments after its
+ * last key belong to what follows, so a note the user wrote above their own
+ * next table survives. `managedLines` are the writer's own comment lines,
+ * which are dropped wherever they sit.
+ */
+export declare function ownedLineCount(section: CliTomlSection, managedLines: ReadonlySet<string>): number;
+/**
+ * A table declared twice is a TOML error, and neither Grok nor Codex will
+ * start on one.
+ * Each `[[array]]` element opens a fresh scope for everything under it, so
+ * `[mcp_servers.env]` under two elements is not a repeat.
+ */
+export declare function findDuplicateTable(text: string): string | undefined;

package/dist/cli/proxy-clients/tomlSections.js

@@ -0,0 +1,365 @@
+/**
+ * Line-level TOML reading for the proxy's client-config writers.
+ *
+ * Grok and Codex keep their settings in TOML files the user and the CLI
+ * itself also edit, and the writers must find what the proxy wrote there
+ * without trusting its comment markers: Grok's own save drops every comment.
+ * No TOML parser is a dependency, and a parse-and-serialize round trip would
+ * reformat the user's file anyway, so this reads just enough structure to
+ * edit text in place: table headers, strings, keys and assignments. Every
+ * line keeps its own terminator, so text a writer does not own round-trips
+ * byte for byte.
+ */
+function splitLinesKeepingEnds(text) {
+    return text.match(/[^\n]*\n|[^\n]+$/g) ?? [];
+}
+function readTomlKey(text) {
+    const bare = text.match(/^[A-Za-z0-9_-]+/);
+    if (bare) {
+        return { value: bare[0], length: bare[0].length };
+    }
+    const basic = text.match(/^"(?:[^"\\]|\\.)*"/);
+    if (basic) {
+        let value;
+        try {
+            value = JSON.parse(basic[0]);
+        }
+        catch {
+            value = undefined;
+        }
+        return {
+            value: typeof value === "string" ? value : basic[0].slice(1, -1),
+            length: basic[0].length,
+        };
+    }
+    const literal = text.match(/^'[^']*'/);
+    if (literal) {
+        return { value: literal[0].slice(1, -1), length: literal[0].length };
+    }
+    return null;
+}
+function parseTomlTableHeader(line) {
+    const text = line.trim();
+    if (!text.startsWith("[")) {
+        return null;
+    }
+    const arrayTable = text.startsWith("[[");
+    const path = [];
+    let rest = text.slice(arrayTable ? 2 : 1);
+    for (;;) {
+        rest = rest.trimStart();
+        const key = readTomlKey(rest);
+        if (key === null) {
+            return null;
+        }
+        path.push(key.value);
+        rest = rest.slice(key.length).trimStart();
+        if (!rest.startsWith(".")) {
+            break;
+        }
+        rest = rest.slice(1);
+    }
+    const close = arrayTable ? "]]" : "]";
+    if (!rest.startsWith(close)) {
+        return null;
+    }
+    const tail = rest.slice(close.length).trim();
+    return tail.length === 0 || tail.startsWith("#")
+        ? { path, arrayTable }
+        : null;
+}
+function advanceTomlScan(line, state) {
+    let { multiline, depth } = state;
+    let i = 0;
+    while (i < line.length) {
+        if (multiline !== null) {
+            if (multiline === '"""' && line[i] === "\\") {
+                i += 2;
+            }
+            else if (line.startsWith(multiline, i)) {
+                // Up to two quotes of content may sit against the closing delimiter.
+                const quote = multiline[0];
+                i += 3;
+                while (line[i] === quote) {
+                    i += 1;
+                }
+                multiline = null;
+            }
+            else {
+                i += 1;
+            }
+            continue;
+        }
+        const ch = line[i];
+        if (ch === "#") {
+            break;
+        }
+        if (line.startsWith('"""', i) || line.startsWith("'''", i)) {
+            multiline = line.startsWith('"""', i) ? '"""' : "'''";
+            i += 3;
+        }
+        else if (ch === '"') {
+            i += 1;
+            while (i < line.length && line[i] !== '"') {
+                i += line[i] === "\\" ? 2 : 1;
+            }
+            i += 1;
+        }
+        else if (ch === "'") {
+            const end = line.indexOf("'", i + 1);
+            i = end === -1 ? line.length : end + 1;
+        }
+        else {
+            if (ch === "[" || ch === "{") {
+                depth += 1;
+            }
+            else if (ch === "]" || ch === "}") {
+                depth = Math.max(0, depth - 1);
+            }
+            i += 1;
+        }
+    }
+    return { multiline, depth };
+}
+export function splitTomlSections(text) {
+    const sections = [];
+    let current = { path: null, arrayTable: false, lines: [] };
+    let state = { multiline: null, depth: 0 };
+    for (const line of splitLinesKeepingEnds(text)) {
+        const header = state.multiline === null && state.depth === 0
+            ? parseTomlTableHeader(line)
+            : null;
+        if (header) {
+            sections.push(current);
+            current = { ...header, lines: [line] };
+            continue;
+        }
+        current.lines.push(line);
+        state = advanceTomlScan(line, state);
+    }
+    sections.push(current);
+    return sections;
+}
+function decodeBasicString(inner) {
+    try {
+        const value = JSON.parse(`"${inner}"`);
+        return typeof value === "string" ? value : inner;
+    }
+    catch {
+        return inner;
+    }
+}
+/**
+ * A line of TOML with every string replaced by `@<n>@` and any comment
+ * dropped, so text inside a string can never read as a key or an assignment.
+ * `strings[n]` is the decoded value. `@` cannot occur outside a string in
+ * valid TOML.
+ */
+export function maskTomlStrings(line) {
+    const strings = [];
+    let masked = "";
+    let i = 0;
+    while (i < line.length) {
+        const ch = line[i];
+        if (ch === "#") {
+            break;
+        }
+        const triple = line.startsWith('"""', i)
+            ? '"""'
+            : line.startsWith("'''", i)
+                ? "'''"
+                : null;
+        if (triple !== null || ch === '"' || ch === "'") {
+            const delimiter = triple ?? ch;
+            let end = i + delimiter.length;
+            while (end < line.length && !line.startsWith(delimiter, end)) {
+                end += delimiter.startsWith('"') && line[end] === "\\" ? 2 : 1;
+            }
+            // Up to two quotes of content may sit against a triple closer.
+            for (let extra = 0; triple !== null &&
+                extra < 2 &&
+                line[end + delimiter.length] === delimiter[0]; extra += 1) {
+                end += 1;
+            }
+            const inner = line.slice(i + delimiter.length, Math.min(end, line.length));
+            strings.push(delimiter.startsWith("'") ? inner : decodeBasicString(inner));
+            masked += `@${strings.length - 1}@`;
+            i = end + delimiter.length;
+            continue;
+        }
+        masked += ch;
+        i += 1;
+    }
+    return { masked, strings };
+}
+const TOML_KEY_PART = String.raw `(?:[A-Za-z0-9_-]+|@\d+@)`;
+const TOML_ASSIGNMENT = new RegExp(String.raw `^\s*(${TOML_KEY_PART}(?:\s*\.\s*${TOML_KEY_PART})*)\s*=\s*(.*?)\s*$`);
+function unmaskKeyPart(part, strings) {
+    const token = part.match(/^@(\d+)@$/);
+    return token ? strings[Number(token[1])] : part;
+}
+export function parseMaskedAssignment(masked, strings) {
+    const match = masked.match(TOML_ASSIGNMENT);
+    return match
+        ? {
+            path: match[1]
+                .split(".")
+                .map((part) => unmaskKeyPart(part.trim(), strings)),
+            value: match[2],
+        }
+        : null;
+}
+/**
+ * The string a masked value starts with. Only the start counts, so a value
+ * with damage after it (a literal `\n` left by a bad paste) is still read.
+ */
+export function maskedStringValue(value, strings) {
+    const token = value.match(/^@(\d+)@/);
+    return token ? strings[Number(token[1])] : undefined;
+}
+/** The pairs directly inside a one-line inline table. */
+export function inlineTablePairs(value, strings) {
+    if (!value.startsWith("{") || !value.endsWith("}")) {
+        return [];
+    }
+    const parts = [];
+    let depth = 0;
+    let start = 1;
+    for (let i = 1; i < value.length - 1; i += 1) {
+        if (value[i] === "{" || value[i] === "[") {
+            depth += 1;
+        }
+        else if (value[i] === "}" || value[i] === "]") {
+            depth -= 1;
+        }
+        else if (value[i] === "," && depth === 0) {
+            parts.push(value.slice(start, i));
+            start = i + 1;
+        }
+    }
+    parts.push(value.slice(start, value.length - 1));
+    return parts.flatMap((part) => {
+        const pair = parseMaskedAssignment(part, strings);
+        return pair ? [pair] : [];
+    });
+}
+/** The dotted key a statement assigns, and its value when that is a string. */
+export function readTomlAssignment(line) {
+    const { masked, strings } = maskTomlStrings(line);
+    const assignment = parseMaskedAssignment(masked, strings);
+    return assignment
+        ? {
+            path: assignment.path,
+            value: maskedStringValue(assignment.value, strings),
+        }
+        : null;
+}
+function isTomlContentLine(line) {
+    const text = line.trim();
+    return text.length > 0 && !text.startsWith("#");
+}
+/**
+ * The lines of a section that are TOML rather than the inside of a
+ * multi-line string; `statement` marks those that start a key/value pair
+ * rather than continue an array or inline table.
+ */
+export function tomlCodeLines(section) {
+    const code = [];
+    let state = { multiline: null, depth: 0 };
+    section.lines.forEach((line, index) => {
+        const isHeader = index === 0 && section.path !== null;
+        if (!isHeader && state.multiline === null) {
+            code.push({ line, statement: state.depth === 0 });
+        }
+        if (!isHeader) {
+            state = advanceTomlScan(line, state);
+        }
+    });
+    return code;
+}
+export function readStringValue(section, key) {
+    for (const { line, statement } of tomlCodeLines(section)) {
+        const assignment = statement ? readTomlAssignment(line) : null;
+        if (assignment?.path.length === 1 && assignment.path[0] === key) {
+            return assignment.value;
+        }
+    }
+    return undefined;
+}
+/**
+ * Names of the `<parent>.<name>` tables defined by dotted keys instead of a
+ * `[<parent>.<name>]` header: `claude-opus-4-6.base_url = ...` under
+ * `[model]`, or `model.claude-opus-4-6.base_url = ...` before the first
+ * header.
+ */
+export function dottedTableIds(sections, parent) {
+    return sections.flatMap((section) => {
+        const underParent = !section.arrayTable &&
+            section.path?.length === 1 &&
+            section.path[0] === parent;
+        if (!underParent && section.path !== null) {
+            return [];
+        }
+        return tomlCodeLines(section).flatMap(({ line, statement }) => {
+            const path = statement ? readTomlAssignment(line)?.path : undefined;
+            if (!path) {
+                return [];
+            }
+            if (underParent) {
+                return [path[0]];
+            }
+            return path.length >= 2 && path[0] === parent ? [path[1]] : [];
+        });
+    });
+}
+/**
+ * How many of an owned section's lines are the writer's. Comments after its
+ * last key belong to what follows, so a note the user wrote above their own
+ * next table survives. `managedLines` are the writer's own comment lines,
+ * which are dropped wherever they sit.
+ */
+export function ownedLineCount(section, managedLines) {
+    const lastKey = section.lines.findLastIndex(isTomlContentLine);
+    const firstNote = section.lines.findIndex((line, index) => index > lastKey &&
+        line.trim().length > 0 &&
+        !managedLines.has(line.trim()));
+    return firstNote === -1 ? section.lines.length : firstNote;
+}
+/**
+ * A table declared twice is a TOML error, and neither Grok nor Codex will
+ * start on one.
+ * Each `[[array]]` element opens a fresh scope for everything under it, so
+ * `[mcp_servers.env]` under two elements is not a repeat.
+ */
+export function findDuplicateTable(text) {
+    const tables = new Map();
+    const arrays = new Map();
+    const isUnder = (candidate, prefix) => candidate.length > prefix.length &&
+        prefix.every((part, index) => candidate[index] === part);
+    for (const { path, arrayTable } of splitTomlSections(text)) {
+        if (path === null) {
+            continue;
+        }
+        const key = JSON.stringify(path);
+        if (arrayTable) {
+            if (tables.has(key)) {
+                return path.join(".");
+            }
+            for (const scope of [tables, arrays]) {
+                for (const [seenKey, seenPath] of scope) {
+                    if (isUnder(seenPath, path)) {
+                        scope.delete(seenKey);
+                    }
+                }
+            }
+            arrays.set(key, path);
+            continue;
+        }
+        if (tables.has(key) || arrays.has(key)) {
+            return path.join(".");
+        }
+        tables.set(key, path);
+    }
+    return undefined;
+}
+//# sourceMappingURL=tomlSections.js.map

package/dist/types/proxyClient.d.ts

@@ -29,8 +29,10 @@ export type CliProxyClientConfigurator = {
     /**
      * Point the CLI at the proxy. `proxyBaseUrl` is the bare proxy origin
      * (e.g. "http://127.0.0.1:55669"); the configurator appends whatever path
-     * suffix its CLI needs. Returns false when nothing was written, so callers
-     * never print a success message for work that did not happen.
+     * suffix its CLI needs. Returns false when the CLI is not left pointing at
+     * the proxy, so callers never print a success message for work that did
+     * not happen. A configurator whose file already matches may return true
+     * without rewriting it.
      */
     apply: (proxyBaseUrl: string, options?: CliProxyClientApplyOptions) => Promise<boolean>;
     /**
@@ -55,7 +57,10 @@ export type CliProxyClientConfigurator = {
 export type CliProxyClientApplyResult = {
     id: string;
     displayName: string;
-    /** True only when the configurator actually wrote configuration. */
+    /**
+     * True only when the CLI's configuration points at the proxy: written now,
+     * or already written and left as it was.
+     */
     applied: boolean;
     /**
      * Set when the write landed but is not yet in effect — see
@@ -110,6 +115,26 @@ export type CliGrokSnapshot = {
     originalExisted: boolean;
     writtenBaseUrl: string;
 };
+/**
+ * One header-delimited run of a client's TOML config. `path` is the parsed
+ * header key (`["model", "gemini-2.5-pro"]` for `[model."gemini-2.5-pro"]`),
+ * or null for the keys before the first header. `lines` keep their own
+ * terminators, so text the writer does not own round-trips byte for byte.
+ */
+export type CliTomlSection = {
+    path: readonly string[] | null;
+    arrayTable: boolean;
+    lines: readonly string[];
+};
+/**
+ * What a line of TOML leaves open for the next one: a multi-line string, or
+ * brackets of an array or inline table. A `[` that starts a line is a table
+ * header only when neither is open.
+ */
+export type CliTomlScanState = {
+    multiline: '"""' | "'''" | null;
+    depth: number;
+};
 /**
  * Snapshot of the user's pre-existing Gemini CLI `~/.gemini/.env`.
  *

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

@@ -2090,9 +2090,9 @@
 {"objectID":"b67926d8a755ad92e57bdd16c8f17d1f7f0a0ce03c42865cb1f341959b146e2e","title":"Post-Migration","url":"/docs/development/factory-migration#post-migration","content":"[ ] Verify all provider functionality\n[ ] Confirm performance improvements\n[ ] Validate error handling behavior\n[ ] Test failover scenarios\n[ ] Monitor production metrics\n[ ] Document new patterns for team\n[ ] Clean up legacy code","hierarchy":{"lvl0":"Development","lvl1":"Factory Pattern Migration Guide","lvl2":"Post-Migration","lvl3":""}},
 {"objectID":"70058ed2ee55a4afc9808da9da91ee30ac2e23f2ac1113720e9e2e60b1053f19","title":"Key Performance Indicators","url":"/docs/development/factory-migration#key-performance-indicators","content":"This comprehensive migration guide ensures a smooth transition to NeuroLink's factory pattern architecture, maximizing the benefits of standardized provider management while minimizing migration risks.","hierarchy":{"lvl0":"Development","lvl1":"Factory Pattern Migration Guide","lvl2":"Key Performance Indicators","lvl3":""}},
 {"objectID":"01352a99c713cd63d938c086b918f9cfaebdf1246aec71e0bd851c194caf370a","title":"📚 Related Documentation","url":"/docs/development/factory-migration#-related-documentation","content":"System Architecture - Overall system design\nTesting Strategy - Quality assurance approaches\nContributing Guide - Development workflow\nAdvanced Patterns - Factory implementation details","hierarchy":{"lvl0":"Development","lvl1":"Factory Pattern Migration Guide","lvl2":"📚 Related Documentation","lvl3":""}},
-{"objectID":"b5593a1a523fdc5889c9f1f0eff5b9644c34bade7dd677fda08dbbc87f023986","title":"Development","url":"/docs/development","content":"Development\n\nContributing to NeuroLink and extending its capabilities for your specific needs.\n\n🎯 Development Hub\n\nThis section covers everything needed for contributing to NeuroLink, understanding its architecture, and extending its functionality.\nContributing — How to contribute to NeuroLink, including setup, coding standards, and submission guidelines.\nTesting — Comprehensive testing strategies, test suite organization, and validation procedures.\nArchitecture — Deep dive into NeuroLink's architecture, design patterns, and system organization.\nFactory Pattern Migration — Guide for upgrading from older architectures to the new unified factory pattern system.\nDocumentation Versioning — Managing documentation versions across releases using mike for version control and deployment.\nAutomated Link Checking — Automated validation of documentation links with CI/CD integration to prevent broken references.\n\n🚀 Quick Development Setup\n\n🏗️ Architecture Overview\n\nNeuroLink uses a Factory Pattern architecture that provides:\n\nCore Components\n\nDesign Principles\nUnified Interface: All providers implement the same  interface\nType Safety: Full TypeScript support with strict typing\nExtensibility: Easy to add new providers and tools\nPerformance: Optimized for production use\nReliability: Comprehensive error handling and fallbacks\n\n🔧 Development Features\n\nEnterprise Automation (72+ Commands)\n\nNeuroLink includes comprehensive automation for development:\n\nSmart Testing System\nAdaptive test selection based on code changes\nProvider validation across all AI services\nPerformance benchmarking and regression detection\nComprehensive coverage reporting\n\nAutomated Content Generation\nScreenshot automation for documentation\nVideo generation for demonstrations\nDocumentation synchronization across files\nAsset optimization and management\n\n🧪 Testing Philosophy\n\nNeuroLink uses a multi-layered testing approach:\n\nTest Categories\nUnit Tests - Individual component testing\nIntegration Tests - Provider and tool interaction\nEnd-to-End Tests - Complete workflow validation\nPerformance Tests - Speed and resource usage\nRegression Tests - Prevent breaking changes\n\nTest Organization\n\nRunning Tests\n\n🎨 Code Style & Standards\n\nTypeScript Configuration\nStrict mode enabled for maximum type safety\nPath mapping for clean imports\nESLint and Prettier for consistent formatting\nDocumentation comments for all public APIs\n\nNaming Conventions\nPascalCase for classes and interfaces\ncamelCase for functions and variables\nkebab-case for file names\nUPPER_CASE for constants\n\nFile Organization\n\n🔄 Contribution Workflow\nSetup Development Environment\nCreate Feature Branch\nDevelopment Process\nCommit & Submit\n\n📚 Learning Resources\n\nArchitecture Deep Dive\nFactory Pattern Guide - Understanding the core architecture\nMCP Integration - Tool system implementation\nProvider Development - Adding new AI providers\n\nBest Practices\nError handling patterns and strategies\nPerformance optimization techniques\nTesting methodologies and coverage\nDocumentation standards and automation\n\nCommunity\nGitHub Discussions for questions and ideas\nIssue tracking for bugs and feature requests\nCode reviews for learning and improvement\nRelease notes for staying updated\n\n🔗 Related Resources\nCLI Guide - Understanding the command-line interface\nSDK Reference - API implementation details\nAdvanced Features - Enterprise capabilities\nExamples - Practical implementations","hierarchy":{"lvl0":"Development","lvl1":"Development","lvl2":"","lvl3":""}},
+{"objectID":"b5593a1a523fdc5889c9f1f0eff5b9644c34bade7dd677fda08dbbc87f023986","title":"Development","url":"/docs/development","content":"Development\n\nContributing to NeuroLink and extending its capabilities for your specific needs.\n\n🎯 Development Hub\n\nThis section covers everything needed for contributing to NeuroLink, understanding its architecture, and extending its functionality.\nContributing — How to contribute to NeuroLink, including setup, coding standards, and submission guidelines.\nTesting — Comprehensive testing strategies, test suite organization, and validation procedures.\nLogging Guidelines — Log levels, structured fields, redaction, and per-instance routing.\nArchitecture — Deep dive into NeuroLink's architecture, design patterns, and system organization.\nFactory Pattern Migration — Guide for upgrading from older architectures to the new unified factory pattern system.\nDocumentation Versioning — Managing documentation versions across releases using mike for version control and deployment.\nAutomated Link Checking — Automated validation of documentation links with CI/CD integration to prevent broken references.\n\n🚀 Quick Development Setup\n\n🏗️ Architecture Overview\n\nNeuroLink uses a Factory Pattern architecture that provides:\n\nCore Components\n\nDesign Principles\nUnified Interface: All providers implement the same  interface\nType Safety: Full TypeScript support with strict typing\nExtensibility: Easy to add new providers and tools\nPerformance: Optimized for production use\nReliability: Comprehensive error handling and fallbacks\n\n🔧 Development Features\n\nEnterprise Automation (72+ Commands)\n\nNeuroLink includes comprehensive automation for development:\n\nSmart Testing System\nAdaptive test selection based on code changes\nProvider validation across all AI services\nPerformance benchmarking and regression detection\nComprehensive coverage reporting\n\nAutomated Content Generation\nScreenshot automation for documentation\nVideo generation for demonstrations\nDocumentation synchronization across files\nAsset optimization and management\n\n🧪 Testing Philosophy\n\nNeuroLink uses a multi-layered testing approach:\n\nTest Categories\nUnit Tests - Individual component testing\nIntegration Tests - Provider and tool interaction\nEnd-to-End Tests - Complete workflow validation\nPerformance Tests - Speed and resource usage\nRegression Tests - Prevent breaking changes\n\nTest Organization\n\nRunning Tests\n\n🎨 Code Style & Standards\n\nTypeScript Configuration\nStrict mode enabled for maximum type safety\nPath mapping for clean imports\nESLint and Prettier for consistent formatting\nDocumentation comments for all public APIs\n\nNaming Conventions\nPascalCase for classes and interfaces\ncamelCase for functions and variables\nkebab-case for file names\nUPPER_CASE for constants\n\nFile Organization\n\n🔄 Contribution Workflow\nSetup Development Environment\nCreate Feature Branch\nDevelopment Process\nCommit & Submit\n\n📚 Learning Resources\n\nArchitecture Deep Dive\nFactory Pattern Guide - Understanding the core architecture\nMCP Integration - Tool system implementation\nProvider Development - Adding new AI providers\n\nBest Practices\nError handling patterns and strategies\nPerformance optimization techniques\nTesting methodologies and coverage\nDocumentation standards and automation\n\nCommunity\nGitHub Discussions for questions and ideas\nIssue tracking for bugs and feature requests\nCode reviews for learning and improvement\nRelease notes for staying updated\n\n🔗 Related Resources\nCLI Guide - Understanding the command-line interface\nSDK Reference - API implementation details\nAdvanced Features - Enterprise capabilities\nExamples - Practical implementations","hierarchy":{"lvl0":"Development","lvl1":"Development","lvl2":"","lvl3":""}},
 {"objectID":"7e615005bdec5429e8e613c0d3c0defeb45247422fadd40a4fac3649c5a3933b","title":"Development","url":"/docs/development#development","content":"Contributing to NeuroLink and extending its capabilities for your specific needs.","hierarchy":{"lvl0":"Development","lvl1":"Development","lvl2":"Development","lvl3":""}},
-{"objectID":"90a5298bb0c032d275a7a07b66e9795f8de3267dc17a2cb2981093354ad6ac16","title":"🎯 Development Hub","url":"/docs/development#-development-hub","content":"This section covers everything needed for contributing to NeuroLink, understanding its architecture, and extending its functionality.\nContributing — How to contribute to NeuroLink, including setup, coding standards, and submission guidelines.\nTesting — Comprehensive testing strategies, test suite organization, and validation procedures.\nArchitecture — Deep dive into NeuroLink's architecture, design patterns, and system organization.\nFactory Pattern Migration — Guide for upgrading from older architectures to the new unified factory pattern system.\nDocumentation Versioning — Managing documentation versions across releases using mike for version control and deployment.\nAutomated Link Checking — Automated validation of documentation links with CI/CD integration to prevent broken references.","hierarchy":{"lvl0":"Development","lvl1":"Development","lvl2":"🎯 Development Hub","lvl3":""}},
+{"objectID":"90a5298bb0c032d275a7a07b66e9795f8de3267dc17a2cb2981093354ad6ac16","title":"🎯 Development Hub","url":"/docs/development#-development-hub","content":"This section covers everything needed for contributing to NeuroLink, understanding its architecture, and extending its functionality.\nContributing — How to contribute to NeuroLink, including setup, coding standards, and submission guidelines.\nTesting — Comprehensive testing strategies, test suite organization, and validation procedures.\nLogging Guidelines — Log levels, structured fields, redaction, and per-instance routing.\nArchitecture — Deep dive into NeuroLink's architecture, design patterns, and system organization.\nFactory Pattern Migration — Guide for upgrading from older architectures to the new unified factory pattern system.\nDocumentation Versioning — Managing documentation versions across releases using mike for version control and deployment.\nAutomated Link Checking — Automated validation of documentation links with CI/CD integration to prevent broken references.","hierarchy":{"lvl0":"Development","lvl1":"Development","lvl2":"🎯 Development Hub","lvl3":""}},
 {"objectID":"5946aa015605c5d07b2c06eb361f2a408413b013014f8ea53c1121e099767678","title":"🚀 Quick Development Setup","url":"/docs/development#-quick-development-setup","content":"`bash","hierarchy":{"lvl0":"Development","lvl1":"Development","lvl2":"🚀 Quick Development Setup","lvl3":""}},
 {"objectID":"15a2f66b412fdff80552d6b65a8f2d4beea2bcb7be6be8118f6fcbf6e1cbc02c","title":"Clone the repository","url":"/docs/development#clone-the-repository","content":"git clone https://github.com/juspay/neurolink\ncd neurolink","hierarchy":{"lvl0":"Development","lvl1":"Development","lvl2":"Clone the repository","lvl3":""}},
 {"objectID":"8a73475040b7c11aeadadf82943d4c99d644301c0c5b978a029392fc2f7b7d6f","title":"Install dependencies","url":"/docs/development#install-dependencies","content":"pnpm install","hierarchy":{"lvl0":"Development","lvl1":"Development","lvl2":"Install dependencies","lvl3":""}},
@@ -2240,6 +2240,17 @@
 {"objectID":"8655bbc0db2d8853389936e04247ce18bf5f825c17810ab505c2212ae7ef88d1","title":"Build-time Link Checking","url":"/docs/development/link-checking#build-time-link-checking","content":"Add to :\n\nCreate :","hierarchy":{"lvl0":"Development","lvl1":"Automated Link Checking","lvl2":"Build-time Link Checking","lvl3":""}},
 {"objectID":"4677ec51bc0b0f13c2e326aabf374218f42cf9fd3e2809acda6a932217461adb","title":"Related Documentation","url":"/docs/development/link-checking#related-documentation","content":"Versioning - Documentation version management\nContributing - Contribution guidelines\nTesting - Testing strategies","hierarchy":{"lvl0":"Development","lvl1":"Automated Link Checking","lvl2":"Related Documentation","lvl3":""}},
 {"objectID":"44c7a422d2affcdb3f335b78d80b0958be5d760990185fb0d4505d45b8a9a325","title":"Additional Resources","url":"/docs/development/link-checking#additional-resources","content":"markdown-link-check - Link checker tool\nremark-validate-links - Alternative validator\nGitHub Actions - CI/CD automation","hierarchy":{"lvl0":"Development","lvl1":"Automated Link Checking","lvl2":"Additional Resources","lvl3":""}},
+{"objectID":"e111ff87d03c1f77a7d1932885150cd17c19ce903dce394a0514ed74e4bd0270","title":"Logging Guidelines","url":"/docs/development/logging-guidelines","content":"Logging Guidelines\n\nHow NeuroLink logs, and what a contributor has to get right. This documents the\nconvention the codebase already follows — it is not a proposal to change it.\n\nThe logger\n\nImport the shared logger. Never call  in : ESLint's\n rule fails the build for , and the exceptions for\n// exist for a handful of legacy call sites, not as an\ninvitation.\n\nThere is one logger for the whole process.  attaches\nthe process-wide sink; per-instance events reach a worker only through its\n bridge (see per-instance routing below).\n\nLevels\n\n| Level   | Use for                                                                                                                                    |\n| ------- | ------------------------------------------------------------------------------------------------------------------------------------------ |\n|  | Routine operation: request construction, cache hits, resolution steps, internal state. The default for anything that fires per request.    |\n|   | Events an operator would want in a quiet log: a server binding, a provider registering, an MCP server connecting. Not per-request chatter. |\n|   | Something recoverable happened and the code carried on: a retry, a fallback, a deprecated option, a degraded capability.                   |\n|  | An operation failed, or a failure was swallowed and the caller will not see it.                                                            |\n\n bypasses level filtering and writes to the console\nunconditionally. It is CLI output, not logging — user-facing text that must\nappear regardless of . Of ~2,260 call sites, ~2,150 are in .\nDo not reach for it in .\n\nNothing below  is visible by default\n\n suppresses every level except  unless debug mode is on\n(, or ).  then sets the\nfloor within debug mode. Two consequences worth internalising:\nA  log is not emitted in a normal run, but its arguments are still\n  evaluated. Prefer  over silence.\nA condition a user must act on cannot be reported at  alone — they will\n  never see it. Either raise it to  or surface it on the result object.\n\nChoosing between  and \n\nThe common mistake is logging an ordinary outcome at . If a branch is\nreached on a healthy request, it is , however unwelcome it looks locally.\n is the worked example: a detection that lands below the\nconfidence threshold is the normal case for most files, so it logs at \nand says so in a comment. A detection where no strategy identified a type at\nall is a genuine failure, and logs at .\n\nFormat\n\nPass a message and a structured data object. The message is a constant; the\nvariables go in the object, where a log consumer can index them.\n\nPrefix the message with the emitting component in brackets — ,\n, , . Grepping a debug run is how most of this\ngets read.\n\nTemplate literals are not banned, and a short one carrying a single value is\nfine. What matters is that a value a consumer would want to filter on ends up in\nthe data object rather than baked into the message string.\n\nGuard expensive serialization\n\n evaluates its arguments before  ever runs, so a\n of a large payload costs full price on every request even when\nnothing is logged. Guard it:\n\nThe guard is only needed for work that is expensive to produce. Passing an\nobject you already hold is free — the logger does not serialize it unless it\nemits.\n\nNever log secrets\n\nAPI keys, tokens, credentials, presigned URL query strings, user prompt content\nand absolute host paths must not reach a log or a thrown error message.\n has the helpers, and they are the reason several\npast leaks are closed:\n\n| Helper                      | Use for                                                                                    |\n| --------------------------- | ------------------------------------------------------------------------------------------ |\n|     | A URL in a log or error — strips query and fragment, so a presigned token cannot survive.  |\n|       | A URL that may carry .                                                     |\n|      | A filesystem path in a message.                                                            |\n|         | An error from Node/undici — these embed the full request URL or path in their own message. |\n|            | A header bag before logging it.                                                            |\n|             | An arbitrary object, with string truncation.                                               |\n|         | A large value in a debug log, length-capped.                                               |\n|  | Tool-call parameters before logging them (this one lives in ).     |\n\nThe rule for errors is the same as for logs: an error message is read by more\npeople than a log line, not fewer.\n\nPer-instance routing\n\nThe logger routes per instance, so a worker's  bridge\n() receives only that worker's own\nevents, not everything in the process. The SDK entry points — ,\n,  — run their bodies inside an \nscope carrying the instance's id, so a log call anywhere beneath them is\nattr","hierarchy":{"lvl0":"Development","lvl1":"Logging Guidelines","lvl2":"","lvl3":""}},
+{"objectID":"ec8f0114d488deec97f5a673a32bb2715f189d83292738c48c9fbc75b8344202","title":"Logging Guidelines","url":"/docs/development/logging-guidelines#logging-guidelines","content":"How NeuroLink logs, and what a contributor has to get right. This documents the\nconvention the codebase already follows — it is not a proposal to change it.","hierarchy":{"lvl0":"Development","lvl1":"Logging Guidelines","lvl2":"Logging Guidelines","lvl3":""}},
+{"objectID":"5d174f91c3ccb88a59544c066c3cbf3a2116b97ffacd2414a51f4d64f46fda14","title":"The logger","url":"/docs/development/logging-guidelines#the-logger","content":"Import the shared logger. Never call  in : ESLint's\n rule fails the build for , and the exceptions for\n// exist for a handful of legacy call sites, not as an\ninvitation.\n\nThere is one logger for the whole process.  attaches\nthe process-wide sink; per-instance events reach a worker only through its\n bridge (see per-instance routing below).","hierarchy":{"lvl0":"Development","lvl1":"Logging Guidelines","lvl2":"The logger","lvl3":""}},
+{"objectID":"73c3d51ed27bc5ea62bb86ab9dde6cc2b17cecce7a0452a5aa7593da612cf798","title":"Levels","url":"/docs/development/logging-guidelines#levels","content":"| Level   | Use for                                                                                                                                    |\n| ------- | ------------------------------------------------------------------------------------------------------------------------------------------ |\n|  | Routine operation: request construction, cache hits, resolution steps, internal state. The default for anything that fires per request.    |\n|   | Events an operator would want in a quiet log: a server binding, a provider registering, an MCP server connecting. Not per-request chatter. |\n|   | Something recoverable happened and the code carried on: a retry, a fallback, a deprecated option, a degraded capability.                   |\n|  | An operation failed, or a failure was swallowed and the caller will not see it.                                                            |\n\n bypasses level filtering and writes to the console\nunconditionally. It is CLI output, not logging — user-facing text that must\nappear regardless of . Of ~2,260 call sites, ~2,150 are in .\nDo not reach for it in .","hierarchy":{"lvl0":"Development","lvl1":"Logging Guidelines","lvl2":"Levels","lvl3":""}},
+{"objectID":"4dfd061a8a2bd9527c19e4f651358a6a1f9d1e6ecad7505f47dcc69e88ac5cd2","title":"Nothing below error is visible by default","url":"/docs/development/logging-guidelines#nothing-below-error-is-visible-by-default","content":"suppresses every level except  unless debug mode is on\n(, or ).  then sets the\nfloor within debug mode. Two consequences worth internalising:\nA  log is not emitted in a normal run, but its arguments are still\n  evaluated. Prefer  over silence.\nA condition a user must act on cannot be reported at  alone — they will\n  never see it. Either raise it to  or surface it on the result object.","hierarchy":{"lvl0":"Development","lvl1":"Logging Guidelines","lvl2":"Nothing below error is visible by default","lvl3":""}},
+{"objectID":"19e83441e80eb578fc3e13da08db3aecd6953418f59ea037e40d543ff6f1e812","title":"Choosing between warn and debug","url":"/docs/development/logging-guidelines#choosing-between-warn-and-debug","content":"The common mistake is logging an ordinary outcome at . If a branch is\nreached on a healthy request, it is , however unwelcome it looks locally.\n is the worked example: a detection that lands below the\nconfidence threshold is the normal case for most files, so it logs at \nand says so in a comment. A detection where no strategy identified a type at\nall is a genuine failure, and logs at .","hierarchy":{"lvl0":"Development","lvl1":"Logging Guidelines","lvl2":"Choosing between warn and debug","lvl3":""}},
+{"objectID":"5e7a37fe452805fbf06c4864c7c4bedb538788640158dd499a2de613d4c12cae","title":"Format","url":"/docs/development/logging-guidelines#format","content":"Pass a message and a structured data object. The message is a constant; the\nvariables go in the object, where a log consumer can index them.\n\nPrefix the message with the emitting component in brackets — ,\n, , . Grepping a debug run is how most of this\ngets read.\n\nTemplate literals are not banned, and a short one carrying a single value is\nfine. What matters is that a value a consumer would want to filter on ends up in\nthe data object rather than baked into the message string.","hierarchy":{"lvl0":"Development","lvl1":"Logging Guidelines","lvl2":"Format","lvl3":""}},
+{"objectID":"53c83ffa5114d21fc9998ca5d409a69d0c10feeedb061bc0f757ebd2d3a0d9eb","title":"Guard expensive serialization","url":"/docs/development/logging-guidelines#guard-expensive-serialization","content":"evaluates its arguments before  ever runs, so a\n of a large payload costs full price on every request even when\nnothing is logged. Guard it:\n\nThe guard is only needed for work that is expensive to produce. Passing an\nobject you already hold is free — the logger does not serialize it unless it\nemits.","hierarchy":{"lvl0":"Development","lvl1":"Logging Guidelines","lvl2":"Guard expensive serialization","lvl3":""}},
+{"objectID":"611da1cea62fd0b5bf313f3659615743913252c6ba487823808c87bee60efd00","title":"Never log secrets","url":"/docs/development/logging-guidelines#never-log-secrets","content":"API keys, tokens, credentials, presigned URL query strings, user prompt content\nand absolute host paths must not reach a log or a thrown error message.\n has the helpers, and they are the reason several\npast leaks are closed:\n\n| Helper                      | Use for                                                                                    |\n| --------------------------- | ------------------------------------------------------------------------------------------ |\n|     | A URL in a log or error — strips query and fragment, so a presigned token cannot survive.  |\n|       | A URL that may carry .                                                     |\n|      | A filesystem path in a message.                                                            |\n|         | An error from Node/undici — these embed the full request URL or path in their own message. |\n|            | A header bag before logging it.                                                            |\n|             | An arbitrary object, with string truncation.                                               |\n|         | A large value in a debug log, length-capped.                                               |\n|  | Tool-call parameters before logging them (this one lives in ).     |\n\nThe rule for errors is the same as for logs: an error message is read by more\npeople than a log line, not fewer.","hierarchy":{"lvl0":"Development","lvl1":"Logging Guidelines","lvl2":"Never log secrets","lvl3":""}},
+{"objectID":"c8bf38e894176c3436e15411303845f458ecf58f7bc7da0d105ecaf057adf7f4","title":"Per-instance routing","url":"/docs/development/logging-guidelines#per-instance-routing","content":"The logger routes per instance, so a worker's  bridge\n() receives only that worker's own\nevents, not everything in the process. The SDK entry points — ,\n,  — run their bodies inside an \nscope carrying the instance's id, so a log call anywhere beneath them is\nattributed without threading an instance through every call site. Two things\nsit outside the scope by construction: logs emitted while a consumer drains a\nreturned stream (iteration runs in the consumer's context), and logs emitted\noutside any call — construction, background MCP reconnects, module init —\nwhich stay unattributed rather than being charged to an arbitrary instance.\n\n's JSDoc () is\nthe authoritative description of this behaviour; check it before relying on\nthe routing in a new integration.\n\nA process-wide sink installed with  still receives\neverything either way.","hierarchy":{"lvl0":"Development","lvl1":"Logging Guidelines","lvl2":"Per-instance routing","lvl3":""}},
+{"objectID":"fcd10d804aaa898a37f6d1303fbf6b07499f6bcd5b7e90e8f727aedec7b3f8e8","title":"Checklist for a new log call","url":"/docs/development/logging-guidelines#checklist-for-a-new-log-call","content":"Level matches the table above, and a routine branch is .\nMessage is a constant with a  prefix; variables are in the data\n  object.\nAnything expensive to build is behind .\nNo key, token, credential, prompt body, presigned URL or absolute host path\n  in either the message or the data — run it through  if in\n  doubt.","hierarchy":{"lvl0":"Development","lvl1":"Logging Guidelines","lvl2":"Checklist for a new log call","lvl3":""}},
 {"objectID":"b7ea7ebd627e70d0c3debd74687c71a4ad7cb1a63a6b24e2a4818736e0129778","title":"Provider-Agnostic Testing Framework - January 2025 Snapshot","url":"/docs/development/provider-testing","content":"⚠️ HISTORICAL DOCUMENT (January 2025) — This is a snapshot of the provider-agnostic testing milestone when 9 providers were live. The current product ships 40 providers (incl. voice and the decision-only  type). For the up-to-date provider list and capability matrix, see the README and Provider Capabilities Audit.\n\nProvider-Agnostic Testing Framework - January 2025 Snapshot\n\nUpdated: January 20, 2025  \nStatus: COMPLETE SUCCESS — 9/9 providers verified working at the time of writing  \nObjective: Complete provider testing after resolving critical configuration bug\n\n🎯 MISSION ACCOMPLISHED\n\nProblem Solved\n\nThe previous testing framework was hardcoded to Google AI, making it impossible to validate other providers during migration. This has been completely fixed.\n\nSolution Implemented\n\n✅ Provider-agnostic test runner  \n✅ Configurable environment validation  \n✅ Dynamic provider switching  \n✅ Hugging Face implementation complete\n✅ Ready for comprehensive testing phase\n\n🔧 IMPLEMENTATION DETAILS\nEnhanced Test Runner ()\n\nProvider Configuration System\n\nUsage Examples\n\nEnvironment Validation\n✅ Automatic API key detection\n✅ Clear error messages for missing credentials\n✅ Provider-specific configuration validation\n✅ Dynamic environment variable setup\nProvider-Agnostic Test Files\n\nDynamic Provider Detection\n\nUpdated Test Files\n✅  - Provider-agnostic\n✅  - Provider-agnostic\n🔄 Additional test files can be updated using same pattern\n\n🧪 VALIDATION RESULTS\n\nGoogle AI Provider Testing\n\nOpenAI Provider Testing\n\nKey Observations\n✅ Both providers pass all tests\n✅ OpenAI is slightly faster (6.15s vs 9.08s)\n✅ Same test suite validates both providers\n✅ No code changes needed between providers\n\n🚀 STRATEGIC BENEFITS\nMigration Confidence\nBaseline Established: Google AI provider validated and working\nTarget Confirmed: OpenAI provider already operational\nTest Coverage: Universal test suite applies to all providers\nRegression Prevention: Any breaking changes immediately detected\nDevelopment Velocity\nParallel Testing: Can test multiple providers simultaneously\nQuick Validation: Individual provider testing in \\<10 seconds\nClear Feedback: Provider-specific error messages and success metrics\nAutomated Reports: JSON reports saved per provider\nQuality Assurance\nNo Manual Testing: Automated validation across all providers\nConsistent Coverage: Same test scenarios for all providers\nPerformance Monitoring: Response time tracking per provider\nEnvironment Validation: Automatic credential checking\n\n📋 NEXT STEPS FOR PHASE 3\n\n✅ Migration Complete - All Providers Operational\n\nWith the provider-agnostic testing framework and factory pattern complete:\n\n✅ Factory Pattern Implementation Complete\n✅ BaseProvider: All 9 providers (at the time of writing) extend BaseProvider (verified)\n✅ Custom Vercel AI SDK: Azure, HuggingFace, Ollama use custom implementations\n✅ Official Vercel AI SDK: OpenAI, Anthropic, Bedrock, Google AI, Mistral\n✅ 100% Success Rate: All 9 providers in this snapshot tested and operational\n\n✅ Architecture Achievements\n✅ No External Package Issues: Custom implementations solve compatibility problems\n✅ Universal Analytics: Analytics helper integrated across all providers\n✅ Unified Interface: Single parameter handling system operational\n✅ Enterprise Ready: Complete factory-first MCP architecture\n\nTesting Strategy for Phase 3\n\n🎯 SUCCESS CRITERIA MET\n\nOriginal Requirements\n✅ Fix testing script to be provider agnostic\n✅ Test with OpenAI first (already implemented)\n✅ Validate provider-agnostic functionality working\n\nAdditional Achievements\n✅ Support for 4 providers (Google AI, OpenAI, Anthropic, Bedrock)\n✅ Automatic environment validation\n✅ Clear error messaging\n✅ Performance benchmarking\n✅ JSON report generation\n\n🏆 CONCLUSION\n\nThe provider-agnostic testing framework is now complete and operational.\nProblem Solved: No longer bound to Google AI\nQuality Assured: Both existing providers validated\nFoundation Ready: Perfect infrastructure for Phase 3 migration\nDevelopment Ready: Can proceed with confidence\n\nWe can now begin Phase 3 migration knowing that every step can be validated immediately with comprehensive, provider-agnostic testing.","hierarchy":{"lvl0":"Development","lvl1":"Provider-Agnostic Testing Framework - January 2025 Snapshot","lvl2":"","lvl3":""}},
 {"objectID":"40155d0164fbc188b20eb8158f339edd47393bae047ec9d23dc1a22745059fa8","title":"Provider-Agnostic Testing Framework - January 2025 Snapshot","url":"/docs/development/provider-testing#provider-agnostic-testing-framework---january-2025-snapshot","content":"Updated: January 20, 2025  \nStatus: COMPLETE SUCCESS — 9/9 providers verified working at the time of writing  \nObjective: Complete provider testing after resolving critical configuration bug","hierarchy":{"lvl0":"Development","lvl1":"Provider-Agnostic Testing Framework - January 2025 Snapshot","lvl2":"Provider-Agnostic Testing Framework - January 2025 Snapshot","lvl3":""}},
 {"objectID":"3212634220f7620a7f5dd8d7ffa3a5fb8b359e4c6722504ae1d7881d0020a6da","title":"Problem Solved","url":"/docs/development/provider-testing#problem-solved","content":"The previous testing framework was hardcoded to Google AI, making it impossible to validate other providers during migration. This has been completely fixed.","hierarchy":{"lvl0":"Development","lvl1":"Provider-Agnostic Testing Framework - January 2025 Snapshot","lvl2":"Problem Solved","lvl3":""}},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "12.30.0",
+  "version": "12.30.2",
   "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": {
@@ -275,7 +275,8 @@
     "test:file-tool-roots": "pnpm exec tsx test/continuous-test-suite-file-tool-roots.ts",
     "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: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"
   },
   "files": [
     "dist",