@juspay/neurolink 12.3.0 → 12.4.0

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

@@ -3,11 +3,44 @@
  *
  * Moved verbatim out of `proxy.ts` so that adding a CLI means adding a file
  * here rather than editing a 5,000-line command module in seven places.
+ *
+ * Two defects made every config this writer produced unusable, and both are
+ * fixed here. They are recorded because each was invisible to the tests that
+ * were supposed to cover this file.
+ *
+ * 1. The snapshot lived in `opencode.json` itself, under two `__proxy_*` keys
+ *    at the top level. OpenCode validates its config against a closed schema
+ *    and rejects unknown top-level keys outright:
+ *
+ *      Error: Configuration is invalid at ~/.config/opencode/opencode.json
+ *      ↳ Unrecognized keys: "__proxy_original_neurolink", "__proxy_written_neurolink"
+ *
+ *    Every `opencode` invocation failed at startup — not just proxied ones —
+ *    so auto-configuration bricked the CLI it was meant to onboard. The
+ *    snapshot now lives beside Codex's, in `~/.neurolink/`, which is what
+ *    `codex.ts` has always done. Claude Code and Qwen embed a snapshot the
+ *    same way and survive it only because their schemas ignore unknown keys;
+ *    that is tolerance, not permission, and new writers should not rely on it.
+ *
+ * 2. `models` was written as `{}`. OpenCode resolves `--model provider/id`
+ *    against that map and never calls `/v1/models`, so an empty map meant
+ *    every id was unknown:
+ *
+ *      ProviderModelNotFoundError: providerID "neurolink", suggestions: []
+ *
+ *    Fixing only the keys exposed this one immediately underneath.
+ *
+ * Configs written by the previous version are repaired in place: both apply()
+ * and restore() adopt a legacy in-file snapshot before deleting the keys, so
+ * an existing broken config heals on the next `proxy start` without losing the
+ * user's original provider block.
  */
+import { createHash } from "crypto";
 import { homedir } from "os";
 import { join } from "path";
 import { logger } from "../../utils/logger.js";
-import { cloneForSnapshot, isProxyOwnedValue, shouldCaptureSnapshot, writeFileAtomic, } from "./snapshot.js";
+import { DEFAULT_PROXY_MODEL_IDS } from "../../constants/proxyModels.js";
+import { cloneForSnapshot, isProxyOwnedValue, isUsableSnapshot, shouldCaptureSnapshot, writeFileAtomic, } from "./snapshot.js";
 function getOpenCodeConfigDir() {
     // OpenCode resolves this with the unmodified `xdg-basedir` package —
     // `XDG_CONFIG_HOME || ~/.config` — on every platform, macOS included. There
@@ -21,19 +54,130 @@ function getOpenCodeConfigPath() {
     return join(getOpenCodeConfigDir(), "opencode.json");
 }
 /**
- * Key under which we persist the snapshot of the user's pre-existing
- * `provider.neurolink` config inside `opencode.json` itself. Persisting (rather
- * than relying on in-process state) means restoration still works even if the
- * proxy crashes or shutdown handlers run in a different process.
+ * Where the snapshot of the user's pre-existing `provider.neurolink` lives.
+ *
+ * Outside `opencode.json`, for the reason in the file header. Persisting it on
+ * disk (rather than in process memory) means restoration still works when the
+ * proxy crashes or shutdown runs in a different process — the property the
+ * in-file version was reaching for.
+ */
+function getOpenCodeSnapshotPath() {
+    // Scoped to the config directory, not just HOME. `getOpenCodeConfigPath()`
+    // resolves through XDG_CONFIG_HOME, so two XDG roots under one HOME are two
+    // independent OpenCode installs — and a single shared snapshot file made the
+    // second apply() overwrite the first's saved original. Clearing the first
+    // root then restored the second root's block onto it, or deleted a real
+    // provider entry outright. Measured before this fix: root A came back
+    // holding root B's block.
+    const slug = createHash("sha256")
+        .update(getOpenCodeConfigDir())
+        .digest("hex")
+        .slice(0, 12);
+    return join(homedir(), ".neurolink", `opencode-proxy-snapshot-${slug}.json`);
+}
+/**
+ * The unscoped path used before snapshots were scoped per config directory.
  *
- * Mirrors the Claude pattern (`__proxy_original_env` inside Claude's settings).
+ * Read-only, and only as a fallback: a real user has exactly one config dir, so
+ * adopting their existing snapshot is correct. Writes always go to the scoped
+ * path, so the ambiguity cannot be reintroduced.
  */
-const OPENCODE_ORIGINAL_KEY = "__proxy_original_neurolink";
+function getLegacyOpenCodeSnapshotPath() {
+    return join(homedir(), ".neurolink", "opencode-proxy-snapshot.json");
+}
+/**
+ * Top-level keys written by the pre-fix version of this writer. Present only
+ * in configs it already corrupted; removed on sight.
+ */
+const LEGACY_ORIGINAL_KEY = "__proxy_original_neurolink";
+const LEGACY_WRITTEN_KEY = "__proxy_written_neurolink";
 /**
- * What this writer last wrote into provider.neurolink. Lets apply() tell its
- * own block from one the user substituted while the proxy was not running.
+ * Remove the legacy in-file snapshot keys.
+ *
+ * @returns the legacy snapshot if one was found, so the caller can migrate it
+ * to the external file rather than discard the user's original provider block.
  */
-const OPENCODE_WRITTEN_KEY = "__proxy_written_neurolink";
+function takeLegacySnapshot(config) {
+    const hasOriginal = LEGACY_ORIGINAL_KEY in config;
+    const removed = hasOriginal || LEGACY_WRITTEN_KEY in config;
+    if (!removed) {
+        return { removed: false, snapshot: null };
+    }
+    // Both keys go, always — leaving either behind keeps OpenCode unstartable.
+    // But only a record that actually carries `original` may be restored from.
+    // A file with just the written key proves the proxy wrote something; it does
+    // NOT prove the user had no provider block, and treating it as `original:
+    // null` made restore delete a real one.
+    const snapshot = hasOriginal
+        ? {
+            original: config[LEGACY_ORIGINAL_KEY],
+            written: config[LEGACY_WRITTEN_KEY],
+        }
+        : null;
+    delete config[LEGACY_ORIGINAL_KEY];
+    delete config[LEGACY_WRITTEN_KEY];
+    logger.debug("[proxy] OpenCode: migrated in-file snapshot keys out of opencode.json");
+    return { removed, snapshot };
+}
+async function readSnapshotFile(filePath) {
+    const fs = await import("fs");
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
+    }
+    catch {
+        return null;
+    }
+    // A snapshot missing `original` is malformed, not a record of "the user had
+    // no provider block". Restore distinguishes those by deleting in the second
+    // case, so returning `{}` here would destroy a real provider.neurolink.
+    if (!isUsableSnapshot(parsed, "original")) {
+        logger.debug("[proxy] OpenCode: ignoring a malformed snapshot rather than treating it as empty");
+        return null;
+    }
+    return parsed;
+}
+/**
+ * Resolve the snapshot for the ACTIVE config directory, most specific first.
+ *
+ * The unscoped file is shared by every XDG root on the machine, so it must
+ * never outrank a record that belongs to this config in particular. Preferring
+ * it let one root adopt another root's `original` and restore the wrong
+ * provider block.
+ */
+async function resolveOpenCodeSnapshot(inFileLegacy) {
+    const scoped = await readSnapshotFile(getOpenCodeSnapshotPath());
+    if (scoped !== null) {
+        return { snapshot: scoped, source: "scoped" };
+    }
+    if (inFileLegacy !== null) {
+        return { snapshot: inFileLegacy, source: "in-file" };
+    }
+    const unscoped = await readSnapshotFile(getLegacyOpenCodeSnapshotPath());
+    return unscoped === null
+        ? { snapshot: null, source: null }
+        : { snapshot: unscoped, source: "unscoped" };
+}
+async function writeOpenCodeSnapshot(snap) {
+    const fs = await import("fs");
+    fs.mkdirSync(join(homedir(), ".neurolink"), { recursive: true });
+    // 0o600: the snapshot holds whatever the user's own provider block held,
+    // which for a custom endpoint includes its API key.
+    await writeFileAtomic(getOpenCodeSnapshotPath(), JSON.stringify(snap, null, 2), 0o600);
+}
+/**
+ * The models map written into `provider.neurolink`.
+ *
+ * OpenCode needs every selectable id present here; see DEFAULT_PROXY_MODEL_IDS
+ * for why an empty map is fatal rather than merely unhelpful.
+ */
+function buildModelsMap() {
+    const models = {};
+    for (const id of DEFAULT_PROXY_MODEL_IDS) {
+        models[id] = { name: id };
+    }
+    return models;
+}
 export async function setOpenCodeProxySettings(baseUrl, proxyKey) {
     const fs = await import("fs");
     const configDir = getOpenCodeConfigDir();
@@ -54,34 +198,43 @@ export async function setOpenCodeProxySettings(baseUrl, proxyKey) {
         // file missing/invalid — create fresh config object
         config = { provider: {} };
     }
+    // Repair a config written by the pre-fix version before doing anything else.
+    // The legacy snapshot is the only record of the user's original block, so it
+    // is adopted rather than dropped when no external snapshot exists yet.
+    const { snapshot: legacySnapshot } = takeLegacySnapshot(config);
     const provider = (config.provider ?? {});
     // Persist a snapshot of the user's pre-existing provider.neurolink. Repeat
     // apply() calls must not overwrite it with the proxy's own block — but a
     // block the user wrote while the proxy was gone must replace it. See
     // shouldCaptureSnapshot.
     const currentBlock = "neurolink" in provider ? provider.neurolink : undefined;
+    let { snapshot } = await resolveOpenCodeSnapshot(legacySnapshot);
     if (shouldCaptureSnapshot({
-        hasSnapshot: OPENCODE_ORIGINAL_KEY in config,
-        written: config[OPENCODE_WRITTEN_KEY],
+        hasSnapshot: snapshot !== null,
+        written: snapshot?.written,
         current: currentBlock,
     })) {
-        config[OPENCODE_ORIGINAL_KEY] =
-            currentBlock === undefined ? null : cloneForSnapshot(currentBlock);
+        snapshot = {
+            original: currentBlock === undefined ? null : cloneForSnapshot(currentBlock),
+        };
     }
     const block = {
         id: "neurolink",
         name: "NeuroLink Proxy",
         npm: "@ai-sdk/openai-compatible",
         env: [],
-        models: {},
+        models: buildModelsMap(),
         options: {
             baseURL: baseUrl,
             apiKey: proxyKey || "neurolink-proxy",
         },
     };
     provider.neurolink = block;
-    config[OPENCODE_WRITTEN_KEY] = cloneForSnapshot(block);
     config.provider = provider;
+    await writeOpenCodeSnapshot({
+        original: snapshot?.original ?? null,
+        written: cloneForSnapshot(block),
+    });
     await writeFileAtomic(getOpenCodeConfigPath(), JSON.stringify(config, null, 2));
     return true;
 }
@@ -94,8 +247,18 @@ export async function clearOpenCodeProxySettings(expectedBaseUrl) {
     catch {
         return false;
     }
+    // Always strip legacy keys, even on a path that returns false below: leaving
+    // them behind keeps OpenCode unusable, which is the whole defect.
+    const { removed: legacyStripped, snapshot: legacySnapshot } = takeLegacySnapshot(config);
+    const flushLegacy = async () => {
+        if (legacyStripped) {
+            config.provider = config.provider ?? {};
+            await writeFileAtomic(getOpenCodeConfigPath(), JSON.stringify(config, null, 2));
+        }
+    };
     const provider = config.provider;
     if (!provider || !("neurolink" in provider)) {
+        await flushLegacy();
         return false;
     }
     // Check if our proxy URL matches before removing
@@ -105,6 +268,7 @@ export async function clearOpenCodeProxySettings(expectedBaseUrl) {
         if (options && typeof options.baseURL === "string") {
             if (options.baseURL !== expectedBaseUrl) {
                 // User configured a different URL; do not clobber
+                await flushLegacy();
                 return false;
             }
         }
@@ -112,41 +276,61 @@ export async function clearOpenCodeProxySettings(expectedBaseUrl) {
     const hadNeurolink = "neurolink" in provider;
     // Restore from the snapshot persisted at first set(), regardless of process
     // identity. Only delete provider.neurolink when the snapshot says the user
-    // explicitly had no entry before — never on an "undefined" snapshot, since
-    // that would mean the snapshot was lost and we cannot prove the entry is ours.
-    if (OPENCODE_ORIGINAL_KEY in config) {
+    // explicitly had no entry before — never on a missing snapshot, since that
+    // would mean the snapshot was lost and we cannot prove the entry is ours.
+    const { snapshot, source: snapshotSource } = await resolveOpenCodeSnapshot(legacySnapshot);
+    if (snapshot !== null) {
         // Only restore what we can prove is ours. The base-URL check above lets
         // through a block still pointing at the proxy that the user has edited
         // beside the URL; reverting that discards a deliberate change.
         if (isProxyOwnedValue({
-            written: config[OPENCODE_WRITTEN_KEY],
+            written: snapshot.written,
             current: existing,
         })) {
-            const snapshot = config[OPENCODE_ORIGINAL_KEY];
-            if (snapshot === null) {
+            if (snapshot.original === null || snapshot.original === undefined) {
                 // User had no provider.neurolink before the proxy started — safe to remove.
                 delete provider.neurolink;
             }
             else {
-                provider.neurolink = snapshot;
+                provider.neurolink = snapshot.original;
             }
         }
         else {
             logger.debug("[proxy] OpenCode clear: provider.neurolink was edited after the proxy wrote it, leaving it intact");
         }
-        delete config[OPENCODE_ORIGINAL_KEY];
-        delete config[OPENCODE_WRITTEN_KEY];
+        // Deletion is deferred until after the config write below. Removing the
+        // recovery data first means a failed write leaves opencode.json still
+        // pointing at the proxy with nothing left to restore from — the one
+        // ordering that turns a recoverable error into permanent loss.
     }
     else {
         // No snapshot present — refuse to delete to avoid destroying a config
         // the proxy may not own (e.g. a user wrote their own `neurolink` block
-        // before the snapshot key was introduced, or this is being cleared from
-        // a process that never ran set()).
+        // before the snapshot existed, or this is being cleared from a process
+        // that never ran set()).
         logger.debug("[proxy] OpenCode clear: no original-provider snapshot found, leaving provider.neurolink intact");
+        await flushLegacy();
         return false;
     }
     config.provider = provider;
     await writeFileAtomic(getOpenCodeConfigPath(), JSON.stringify(config, null, 2));
+    // Only now, and only the store we actually consumed. The unscoped file is
+    // shared by every XDG root on this machine: deleting it because *this* root
+    // restored from its own scoped snapshot would take away another root's only
+    // record of its original provider block.
+    try {
+        if (snapshotSource === "scoped") {
+            fs.rmSync(getOpenCodeSnapshotPath(), { force: true });
+        }
+        else if (snapshotSource === "unscoped") {
+            fs.rmSync(getLegacyOpenCodeSnapshotPath(), { force: true });
+        }
+        // "in-file" needs no deletion: takeLegacySnapshot already removed the keys
+        // and the config write above persisted their absence.
+    }
+    catch {
+        // A snapshot we cannot delete is harmless: the next apply() overwrites it.
+    }
     return hadNeurolink;
 }
 /**
@@ -159,6 +343,7 @@ export async function clearOpenCodeProxySettings(expectedBaseUrl) {
 export const __openCodeTestHooks = {
     getOpenCodeConfigDir,
     getOpenCodeConfigPath,
+    getOpenCodeSnapshotPath,
     setOpenCodeProxySettings,
     clearOpenCodeProxySettings,
 };

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

@@ -4,6 +4,7 @@ import { openCodeConfigurator } from "./openCode.js";
 import { codexConfigurator } from "./codex.js";
 import { qwenCodeConfigurator } from "./qwenCode.js";
 import { copilotConfigurator } from "./copilot.js";
+import { geminiConfigurator } from "./gemini.js";
 /**
  * Every CLI the proxy auto-configures, in apply order.
  *
@@ -16,6 +17,7 @@ export const PROXY_CLIENT_CONFIGURATORS = [
     codexConfigurator,
     qwenCodeConfigurator,
     copilotConfigurator,
+    geminiConfigurator,
 ];
 /**
  * Point every detected client at the proxy.

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

@@ -33,6 +33,19 @@ export declare function shouldCaptureSnapshot(args: {
     written: unknown;
     current: unknown;
 }): boolean;
+/**
+ * Whether a decoded snapshot file is structurally usable.
+ *
+ * A snapshot on disk is not necessarily one we wrote: it can be truncated by a
+ * full disk, hand-edited, or left over from another version. `JSON.parse` is
+ * happy with `{}`, `[]`, `null` and `"text"`, and every one of those then reads
+ * as "a snapshot whose recorded original is absent" — which restore paths treat
+ * as "the user had nothing here", and act on by deleting the user's real
+ * config. Requiring the discriminating key present makes a malformed file fall
+ * through to the caller's no-snapshot branch, which refuses to destroy
+ * anything, instead of impersonating an empty one.
+ */
+export declare function isUsableSnapshot<K extends string>(value: unknown, requiredKey: K): value is Record<K, unknown>;
 /** Deep copy through JSON, so a snapshot cannot alias the object it describes. */
 export declare function cloneForSnapshot<T>(value: T): T;
 /**

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

@@ -74,6 +74,24 @@ export function shouldCaptureSnapshot(args) {
     }
     return !valuesMatch(args.current, args.written);
 }
+/**
+ * Whether a decoded snapshot file is structurally usable.
+ *
+ * A snapshot on disk is not necessarily one we wrote: it can be truncated by a
+ * full disk, hand-edited, or left over from another version. `JSON.parse` is
+ * happy with `{}`, `[]`, `null` and `"text"`, and every one of those then reads
+ * as "a snapshot whose recorded original is absent" — which restore paths treat
+ * as "the user had nothing here", and act on by deleting the user's real
+ * config. Requiring the discriminating key present makes a malformed file fall
+ * through to the caller's no-snapshot branch, which refuses to destroy
+ * anything, instead of impersonating an empty one.
+ */
+export function isUsableSnapshot(value, requiredKey) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        Object.prototype.hasOwnProperty.call(value, requiredKey));
+}
 /** Deep copy through JSON, so a snapshot cannot alias the object it describes. */
 export function cloneForSnapshot(value) {
     return JSON.parse(JSON.stringify(value));

package/dist/constants/proxyModels.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Model IDs the proxy advertises when no routing config narrows the list.
+ *
+ * Two consumers need the same answer and must not drift apart:
+ *
+ *   - `proxyTranslationEngine` serves them from `GET /v1/models`.
+ *   - The OpenCode client configurator writes them into `provider.neurolink.
+ *     models`, because OpenCode resolves a `--model` against that map alone.
+ *     It does not call `/v1/models`, so an empty map means every model id is
+ *     unknown and `opencode run` fails with `ProviderModelNotFoundError`
+ *     before a request is ever made.
+ *
+ * Format matches the IDs used throughout `src/lib/models/` and
+ * `src/lib/constants/` (e.g. `claude-3-5-haiku-20241022`, not
+ * `claude-haiku-3.5-20241022`).
+ *
+ * This is the no-router default. A proxy configured with explicit
+ * `routing.model-mappings` serves those instead, and a config written from
+ * this list will not mention them — a limitation worth knowing, but strictly
+ * better than the empty map it replaces.
+ */
+export declare const DEFAULT_PROXY_MODEL_IDS: readonly string[];

package/dist/constants/proxyModels.js

@@ -0,0 +1,36 @@
+/**
+ * Model IDs the proxy advertises when no routing config narrows the list.
+ *
+ * Two consumers need the same answer and must not drift apart:
+ *
+ *   - `proxyTranslationEngine` serves them from `GET /v1/models`.
+ *   - The OpenCode client configurator writes them into `provider.neurolink.
+ *     models`, because OpenCode resolves a `--model` against that map alone.
+ *     It does not call `/v1/models`, so an empty map means every model id is
+ *     unknown and `opencode run` fails with `ProviderModelNotFoundError`
+ *     before a request is ever made.
+ *
+ * Format matches the IDs used throughout `src/lib/models/` and
+ * `src/lib/constants/` (e.g. `claude-3-5-haiku-20241022`, not
+ * `claude-haiku-3.5-20241022`).
+ *
+ * This is the no-router default. A proxy configured with explicit
+ * `routing.model-mappings` serves those instead, and a config written from
+ * this list will not mention them — a limitation worth knowing, but strictly
+ * better than the empty map it replaces.
+ */
+export const DEFAULT_PROXY_MODEL_IDS = [
+    // Claude 4-series (current generation, hyphen-suffix family)
+    "claude-opus-4-6",
+    "claude-sonnet-4-6",
+    "claude-haiku-4-5",
+    // Claude 4 dated variant
+    "claude-sonnet-4-20250514",
+    // Claude 3.5-series (canonical Anthropic form: claude-3-5-{variant}-{date})
+    "claude-3-5-sonnet-20241022",
+    "claude-3-5-haiku-20241022",
+    // OpenAI / Google for translated-fallback users
+    "gpt-4o",
+    "gemini-2.5-pro",
+    "gemini-2.5-flash",
+];

package/dist/proxy/proxyTranslationEngine.js

@@ -14,6 +14,7 @@
 import { ClaudeStreamSerializer, generateToolUseId, serializeClaudeResponse, } from "./claudeFormat.js";
 import { buildGeminiResponse, createGeminiSerializerAdapter, } from "./geminiFormat.js";
 import { generateOpenAIToolCallId, OpenAIStreamSerializer, serializeOpenAIResponse, } from "./openaiFormat.js";
+import { DEFAULT_PROXY_MODEL_IDS } from "../constants/proxyModels.js";
 import { logRequest } from "./requestLogger.js";
 import { recordAttempt, recordAttemptError, recordFinalError, recordFinalSuccess, } from "./usageStats.js";
 import { ErrorCategory, ErrorSeverity } from "../constants/enums.js";
@@ -677,7 +678,7 @@ export function buildModelsListResponse(modelRouter) {
     }
     // Always include a default entry if nothing else is configured
     if (models.length === 0) {
-        for (const id of DEFAULT_MODEL_IDS) {
+        for (const id of DEFAULT_PROXY_MODEL_IDS) {
             models.push({
                 id,
                 object: "model",
@@ -691,26 +692,6 @@ export function buildModelsListResponse(modelRouter) {
         data: models,
     };
 }
-/**
- * Canonical default model IDs surfaced when no router is configured. Format
- * matches the IDs used throughout `src/lib/models/` and `src/lib/constants/`
- * (e.g. `claude-3-5-haiku-20241022`, not `claude-haiku-3.5-20241022`).
- */
-const DEFAULT_MODEL_IDS = [
-    // Claude 4-series (current generation, hyphen-suffix family)
-    "claude-opus-4-6",
-    "claude-sonnet-4-6",
-    "claude-haiku-4-5",
-    // Claude 4 dated variant
-    "claude-sonnet-4-20250514",
-    // Claude 3.5-series (canonical Anthropic form: claude-3-5-{variant}-{date})
-    "claude-3-5-sonnet-20241022",
-    "claude-3-5-haiku-20241022",
-    // OpenAI / Google for translated-fallback users
-    "gpt-4o",
-    "gemini-2.5-pro",
-    "gemini-2.5-flash",
-];
 /**
  * Build an Anthropic-shaped `/v1/models` list response.
  *
@@ -736,7 +717,7 @@ export function buildAnthropicModelsListResponse(modelRouter) {
         }
     }
     if (ids.length === 0) {
-        ids.push(...DEFAULT_MODEL_IDS);
+        ids.push(...DEFAULT_PROXY_MODEL_IDS);
     }
     // Deduplicate while preserving order — multiple router sources can publish
     // the same id (e.g. both an explicit mapping and a passthrough entry).

package/dist/types/proxyClient.d.ts

@@ -47,6 +47,39 @@ export type CliProxyClientRestoreResult = {
     restored: boolean;
     error?: Error;
 };
+/**
+ * Snapshot of the user's pre-existing OpenCode `provider.neurolink`.
+ *
+ * Persisted to `~/.neurolink/opencode-proxy-snapshot.json`, never inside
+ * `opencode.json` — OpenCode validates against a closed schema and rejects
+ * unknown top-level keys, so an in-file snapshot made the CLI unstartable.
+ */
+export type CliOpenCodeSnapshot = {
+    /** The user's provider.neurolink before the proxy first touched it. */
+    original: unknown;
+    /** What the writer last wrote, so apply() can recognise its own block. */
+    written?: unknown;
+};
+/**
+ * Snapshot of the user's pre-existing Gemini CLI `~/.gemini/.env`.
+ *
+ * The whole file is kept rather than the managed keys alone: restoring must
+ * reproduce the user's comments, ordering and unrelated variables exactly.
+ */
+export type CliGeminiSnapshot = {
+    /** The whole prior `.env`, or null when the user had no such file. */
+    originalEnv: string | null;
+    /**
+     * What the writer last wrote for each managed variable. Compared against the
+     * file on disk to detect a snapshot that has gone stale — one left behind by
+     * a restore whose cleanup failed, or overtaken by a user edit. Reusing such a
+     * record would make the next restore replay outdated values.
+     */
+    written?: {
+        baseUrl: string;
+        apiKey: string;
+    };
+};
 /**
  * Raw contents of a Qwen Code `settings.json`. Deliberately open-ended: the
  * configurator rewrites only `security.auth` and must round-trip every other

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "12.3.0",
+  "version": "12.4.0",
   "packageManager": "pnpm@10.15.1",
   "description": "TypeScript AI SDK with 24+ LLM providers behind one consistent API. MCP-native (connect any MCP server), voice TTS/STT/realtime, RAG, agents, memory, context compaction. OpenAI · Anthropic · Gemini · Bedrock · Azure · Ollama · DeepSeek · NVIDIA NIM and more.",
   "author": {