@wolfx/opencode-magic-context 0.21.8-patch.1

package/src/shared/models-dev-cache.ts

@@ -0,0 +1,337 @@
+/**
+ * Resolve per-model context limits to match whatever OpenCode itself sees.
+ *
+ * Two layers:
+ *
+ *   1. API cache (primary): populated asynchronously via
+ *      `client.config.providers()`. OpenCode's own provider service merges
+ *      the live models.dev cache file, its compiled-in snapshot fallback,
+ *      opencode.json custom provider overrides, and derived experimental
+ *      modes. Whatever OpenCode reports is the source of truth.
+ *
+ *   2. File cache (fallback): read-from-disk parse of OpenCode's
+ *      `models.json` plus `opencode.json(c)` custom provider entries.
+ *      Used during cold starts before the API cache warms up and in any
+ *      code path that cannot reach the SDK client.
+ *
+ * The public getter (`getModelsDevContextLimit()`) is synchronous: it checks
+ * the API cache first, then the file cache. The plugin warms the API cache
+ * once from `src/index.ts` at startup. Runtime retries are reserved for the
+ * issue #77 cache-regression recovery path.
+ */
+
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir, platform } from "node:os";
+import { join } from "node:path";
+import { getCacheDir } from "./data-path";
+import { parseJsonc } from "./jsonc-parser";
+import { sessionLog } from "./logger";
+
+interface OpencodeClientLike {
+    config: {
+        providers: () => Promise<{ data?: { providers?: unknown } }>;
+    };
+}
+
+// File-cache fallback only. The primary API refresh is one-shot at startup;
+// this 5-minute interval governs the on-disk-cache fallback path when the API
+// loader hasn't run yet (e.g. during plugin warmup).
+const RELOAD_INTERVAL_MS = 5 * 60 * 1000;
+
+interface CachedModelMetadata {
+    limit?: number;
+}
+
+/** Populated async from OpenCode SDK. Primary source of truth when available. */
+let apiCache: Map<string, CachedModelMetadata> | null = null;
+let apiLoadedAt = 0;
+
+/** Populated sync from disk as fallback. */
+let fileCache: Map<string, CachedModelMetadata> | null = null;
+let fileLastAttempt = 0;
+
+function hashFast(input: string): string {
+    // Matches OpenCode's Hash.fast() (packages/shared/src/util/hash.ts).
+    return createHash("sha1").update(input).digest("hex");
+}
+
+function getModelsJsonPath(): string {
+    // 1. Explicit path override (OpenCode's OPENCODE_MODELS_PATH takes highest priority).
+    const explicit = process.env.OPENCODE_MODELS_PATH?.trim();
+    if (explicit) return explicit;
+
+    // OpenCode uses `xdg-basedir`, which falls back to `<homedir>/.cache` on
+    // every platform (including Windows) when XDG_CACHE_HOME is unset. See
+    // shared/data-path.ts#getCacheDir for the shared helper.
+    const cacheBase = getCacheDir();
+
+    // 2. Custom models source → hashed filename (matches OpenCode).
+    //    source === "https://models.dev" ? "models.json" : `models-${Hash.fast(source)}.json`
+    const source = process.env.OPENCODE_MODELS_URL?.trim();
+    const filename =
+        source && source !== "https://models.dev"
+            ? `models-${hashFast(source)}.json`
+            : "models.json";
+
+    return join(cacheBase, "opencode", filename);
+}
+
+function getOpencodeConfigPath(): string | null {
+    const envDir = process.env.OPENCODE_CONFIG_DIR?.trim();
+    const configDir = envDir
+        ? envDir
+        : platform() === "win32"
+          ? join(homedir(), ".config", "opencode")
+          : join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "opencode");
+
+    // Check jsonc first, then json (matches OpenCode's own lookup order).
+    const jsonc = join(configDir, "opencode.jsonc");
+    if (existsSync(jsonc)) return jsonc;
+    const json = join(configDir, "opencode.json");
+    if (existsSync(json)) return json;
+    return null;
+}
+
+/**
+ * Resolve the effective pressure limit for a model's `limit` object.
+ *
+ * Prefers `limit.input` (max prompt tokens the provider will accept) over
+ * `limit.context` (total window including output). For GitHub Copilot and
+ * several proxy providers, `context` is the marketing number (input + output
+ * combined), and sending a prompt sized against `context` gets rejected.
+ * OpenCode's own `session/overflow.ts` uses `input ?? context` for the same
+ * reason — the denominator that drives overflow/pressure must be the number
+ * the provider actually enforces on input.
+ */
+function resolveLimit(limit: { context?: number; input?: number } | undefined): number | undefined {
+    if (!limit) return undefined;
+    if (typeof limit.input === "number" && limit.input > 0) return limit.input;
+    if (typeof limit.context === "number" && limit.context > 0) return limit.context;
+    return undefined;
+}
+
+function setCachedModelMetadata(
+    cache: Map<string, CachedModelMetadata>,
+    key: string,
+    model:
+        | {
+              limit?: { context?: number; input?: number };
+              experimental?: { modes?: Record<string, unknown> };
+          }
+        | undefined,
+): void {
+    const limit = resolveLimit(model?.limit);
+
+    if (limit === undefined) {
+        return;
+    }
+
+    const value: CachedModelMetadata = { limit };
+    cache.set(key, value);
+
+    // OpenCode creates derived model IDs from experimental.modes
+    // e.g. gpt-5.4 + modes.fast → gpt-5.4-fast. These inherit the same
+    // context limit as the parent model.
+    const modes = model?.experimental?.modes;
+    if (modes && typeof modes === "object") {
+        for (const mode of Object.keys(modes)) {
+            cache.set(`${key}-${mode}`, value);
+        }
+    }
+}
+
+function loadModelsDevMetadataFromFile(): Map<string, CachedModelMetadata> {
+    const metadata = new Map<string, CachedModelMetadata>();
+
+    // 1. Read OpenCode's models.dev cache file (base layer).
+    const modelsJsonPath = getModelsJsonPath();
+    let fileFound = false;
+    try {
+        if (existsSync(modelsJsonPath)) {
+            fileFound = true;
+            const raw = readFileSync(modelsJsonPath, "utf-8");
+            const data = JSON.parse(raw) as Record<
+                string,
+                {
+                    models?: Record<
+                        string,
+                        {
+                            limit?: { context?: number; input?: number };
+                            experimental?: { modes?: Record<string, unknown> };
+                        }
+                    >;
+                }
+            >;
+
+            for (const [providerId, provider] of Object.entries(data)) {
+                if (!provider?.models || typeof provider.models !== "object") continue;
+                for (const [modelId, model] of Object.entries(provider.models)) {
+                    setCachedModelMetadata(metadata, `${providerId}/${modelId}`, model);
+                }
+            }
+        }
+    } catch (error) {
+        sessionLog(
+            "global",
+            `models-dev-cache: failed to read models.json at ${modelsJsonPath}:`,
+            error instanceof Error ? error.message : String(error),
+        );
+    }
+
+    // 2. Overlay custom provider models from OpenCode config (higher priority).
+    // Users define custom/proxy models via provider.<id>.models.<name>.limit.{input,context}
+    // in opencode.json(c). These override models.dev entries for the same key.
+    try {
+        const configPath = getOpencodeConfigPath();
+        if (configPath && existsSync(configPath)) {
+            // Use the shared JSONC parser — handles `//` comments AND trailing commas.
+            // The previous custom regex stripped comments only; OpenCode's `opencode.jsonc`
+            // frequently contains trailing commas (valid JSONC, invalid JSON), which broke
+            // custom provider model-limit resolution silently. See issue #14 follow-up.
+            const config = parseJsonc<{
+                provider?: Record<
+                    string,
+                    {
+                        models?: Record<string, { limit?: { context?: number; input?: number } }>;
+                    }
+                >;
+            }>(readFileSync(configPath, "utf-8"));
+
+            if (config.provider && typeof config.provider === "object") {
+                for (const [providerId, provider] of Object.entries(config.provider)) {
+                    if (!provider?.models || typeof provider.models !== "object") continue;
+                    for (const [modelId, model] of Object.entries(provider.models)) {
+                        setCachedModelMetadata(metadata, `${providerId}/${modelId}`, model);
+                    }
+                }
+            }
+        }
+    } catch (error) {
+        sessionLog(
+            "global",
+            "models-dev-cache: failed to read opencode config for custom models:",
+            error instanceof Error ? error.message : String(error),
+        );
+    }
+
+    sessionLog(
+        "global",
+        `models-dev-cache: file-layer loaded ${metadata.size} model metadata entries (modelsJsonPath=${modelsJsonPath}, found=${fileFound})`,
+    );
+
+    return metadata;
+}
+
+/**
+ * Asynchronously refresh the API-layer cache from OpenCode's SDK.
+ *
+ * Call this at plugin startup and from the issue #77 regression-recovery path.
+ * OpenCode's `/config/providers` endpoint returns every provider with full
+ * model metadata — including `limit.context` — resolved through the same path
+ * OpenCode itself uses (live cache + compiled-in snapshot + opencode.json
+ * overrides + derived experimental modes).
+ *
+ * Safe to call concurrently; only overwrites the cache on success.
+ */
+export async function refreshModelLimitsFromApi(client: OpencodeClientLike): Promise<void> {
+    try {
+        const result = await client.config.providers();
+        const data = (result as { data?: { providers?: Array<unknown> } }).data;
+        const providers = data?.providers;
+        if (!Array.isArray(providers)) {
+            sessionLog("global", "models-dev-cache: API refresh returned no providers payload");
+            return;
+        }
+
+        const map = new Map<string, CachedModelMetadata>();
+        for (const entry of providers) {
+            const p = entry as {
+                id?: string;
+                models?: Record<
+                    string,
+                    {
+                        limit?: { context?: number; input?: number };
+                        experimental?: { modes?: Record<string, unknown> };
+                    }
+                >;
+            };
+            if (!p?.id || !p.models || typeof p.models !== "object") continue;
+            for (const [modelId, model] of Object.entries(p.models)) {
+                setCachedModelMetadata(map, `${p.id}/${modelId}`, model);
+            }
+        }
+
+        const previousSize = apiCache?.size ?? null;
+        apiCache = map;
+        apiLoadedAt = Date.now();
+
+        if (previousSize === null) {
+            sessionLog(
+                "global",
+                `models-dev-cache: API layer loaded ${map.size} model metadata entries`,
+            );
+        } else if (previousSize !== map.size) {
+            sessionLog(
+                "global",
+                `models-dev-cache: API layer loaded ${map.size} model metadata entries (was ${previousSize})`,
+            );
+        }
+    } catch (error) {
+        sessionLog(
+            "global",
+            "models-dev-cache: API refresh failed:",
+            error instanceof Error ? error.message : String(error),
+        );
+    }
+}
+
+/**
+ * Returns the context limit for a provider/model.
+ *
+ * Lookup order:
+ *   1. API cache (populated by {@link refreshModelLimitsFromApi}). Matches
+ *      what OpenCode sees exactly, including snapshot-only models.
+ *   2. File cache (parsed from models.json + opencode.json overrides).
+ *      Used before the API cache warms and as a last resort.
+ *
+ * Returns `undefined` if neither layer knows the model.
+ */
+export function getModelsDevContextLimit(providerID: string, modelID: string): number | undefined {
+    const key = `${providerID}/${modelID}`;
+
+    if (apiCache) {
+        const fromApi = apiCache.get(key)?.limit;
+        if (typeof fromApi === "number") return fromApi;
+    }
+
+    const now = Date.now();
+    if (!fileCache || now - fileLastAttempt > RELOAD_INTERVAL_MS) {
+        fileLastAttempt = now;
+        fileCache = loadModelsDevMetadataFromFile();
+    }
+    return fileCache.get(key)?.limit;
+}
+
+/** Clear in-memory caches (for testing). */
+export function clearModelsDevCache(): void {
+    apiCache = null;
+    apiLoadedAt = 0;
+    fileCache = null;
+    fileLastAttempt = 0;
+}
+
+/** Inspection helpers (for logging / debugging). */
+export function getModelsDevCacheState(): {
+    apiLoaded: boolean;
+    apiCount: number;
+    apiAgeMs: number;
+    fileCount: number;
+} {
+    return {
+        apiLoaded: apiCache !== null,
+        apiCount: apiCache?.size ?? 0,
+        apiAgeMs: apiLoadedAt > 0 ? Date.now() - apiLoadedAt : -1,
+        fileCount: fileCache?.size ?? 0,
+    };
+}

package/src/shared/native-binding.ts

@@ -0,0 +1,311 @@
+/**
+ * Native-binding resolver for Electron-runtime mismatches.
+ *
+ * Why this module exists
+ * ----------------------
+ * `better-sqlite3` uses raw v8/nan bindings, so its compiled `.node` file is
+ * locked to a specific NODE_MODULE_VERSION (Node-API ABI revision). When
+ * OpenCode Desktop (Electron 41 → ABI 145) loads a plugin whose `node_modules`
+ * was populated by `bun install` / `npm install` under a different runtime,
+ * the fetched prebuild is for `node-vNNN` (e.g. ABI 137 for Node 22) and
+ * Electron refuses to load it with:
+ *
+ *   The module '...better_sqlite3.node' was compiled against a different
+ *   Node.js version using NODE_MODULE_VERSION 137. This version of Node.js
+ *   requires NODE_MODULE_VERSION 145.
+ *
+ * `onnxruntime-node` (used by `@huggingface/transformers` for local
+ * embeddings) is N-API v3 and is ABI-stable across runtimes, so it does NOT
+ * have this problem. Only `better-sqlite3` is affected.
+ *
+ * What this does
+ * --------------
+ * On plugin load, before constructing any `Database`:
+ *
+ *  1. If we are NOT running under Electron (`process.versions.electron` is
+ *     unset), return null. Bun uses `bun:sqlite` and never reaches this code;
+ *     Pi/Node-CLI install matching Node-vNNN prebuilds via npm, which work
+ *     natively against the on-disk binary.
+ *
+ *  2. If we ARE on Electron, locate the `.node` file path that
+ *     `better-sqlite3`'s default `bindings()` lookup would try first. Probe
+ *     its ABI by attempting a sandboxed `process.dlopen`. If it succeeds
+ *     (Electron-compatible), return null — the default lookup will work.
+ *
+ *  3. Otherwise, look for a cached Electron prebuild at
+ *     `<XDG_CACHE_HOME>/cortexkit/native-bindings/better-sqlite3/v<version>/electron-v<abi>-<platform>-<arch>/better_sqlite3.node`.
+ *     Download it from the `WiseLibs/better-sqlite3` GitHub release if
+ *     missing, extract with `nanotar` (pure-JS, ~45 KB, zero deps), validate
+ *     the ABI, and return the absolute path.
+ *
+ * The caller (`sqlite.ts`) then passes this path through `better-sqlite3`'s
+ * documented `nativeBinding` constructor option:
+ *
+ *   new Database(filename, { nativeBinding: <our cached path> })
+ *
+ * `better-sqlite3` calls `require()` directly on that path, bypassing the
+ * normal `bindings()` lookup chain. This is a first-class API the maintainer
+ * added for exactly this kind of cross-runtime extension scenario — see
+ * `node_modules/better-sqlite3/lib/database.js` `nativeBinding` handling.
+ *
+ * Why we don't replace the on-disk binary
+ * ---------------------------------------
+ * An earlier iteration copied the cached Electron binary over the in-tree
+ * `node_modules/.../better_sqlite3.node`. That worked but mutates a shared
+ * resource: in monorepo dev setups (or any case where multiple runtimes
+ * share one `node_modules`), a Pi process opening the plugin from the same
+ * workspace would then load the Electron-ABI binary and fail. Returning a
+ * separate cached path keeps the on-disk file untouched so each runtime
+ * sees the binary it needs.
+ *
+ * Failure modes
+ * -------------
+ * If GitHub is unreachable (corporate firewall, offline laptop, rate limit)
+ * AND no cached binary exists, this throws. The caller (sqlite.ts →
+ * openDatabase) surfaces a `storage unavailable` error and Magic Context
+ * disables itself for the run. The user can connect to the network and
+ * restart, or wait for a cached binary from a previous successful launch.
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import * as path from "node:path";
+import { parseTarGzip } from "nanotar";
+import { getCacheDir } from "./data-path";
+import { log } from "./logger";
+
+const PREFIX = "[native-binding]";
+
+function logInfo(message: string): void {
+    log(`${PREFIX} ${message}`);
+}
+
+function logWarn(message: string): void {
+    log(`${PREFIX} WARN ${message}`);
+}
+
+/**
+ * Result of probing a `.node` file's ABI by attempting a sandboxed `dlopen`.
+ *
+ * - `ok: true` means the runtime accepted the binary; the on-disk file is
+ *   already Electron-compatible and we don't need to do anything.
+ * - `ok: false` carries the parsed `actual` ABI for diagnostics (or `null`
+ *   if the error message didn't match any known shape).
+ */
+type ProbeResult = { ok: true } | { ok: false; expected: string; actual: string | null };
+
+function probeAbi(binaryPath: string): ProbeResult {
+    const expected = process.versions.modules;
+    try {
+        // Throwaway sandbox: process.dlopen runs the module's init function
+        // against `sandbox.exports`. On ABI mismatch it throws BEFORE init
+        // runs, so the binary is NOT loaded into process memory in the
+        // failure case. On success the binary IS loaded (Node refcounts
+        // these, so a second dlopen by the real `require()` is cheap).
+        const sandbox = { exports: {} as Record<string, unknown> };
+        process.dlopen(sandbox, binaryPath);
+        return { ok: true };
+    } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const pair = message.match(/NODE_MODULE_VERSION (\d+).*NODE_MODULE_VERSION (\d+)/s);
+        if (pair?.[1] && pair[2]) {
+            return { ok: false, expected: pair[2], actual: pair[1] };
+        }
+        const single = message.match(/NODE_MODULE_VERSION[ =:]+(\d+)/);
+        if (single?.[1]) {
+            return { ok: false, expected, actual: single[1] };
+        }
+        // Couldn't parse — log raw message so we can refine the regex if a
+        // future runtime emits a different shape.
+        logWarn(`could not parse ABI from dlopen error: ${message}`);
+        return { ok: false, expected, actual: null };
+    }
+}
+
+/**
+ * Locate the on-disk path `better-sqlite3` ships its `.node` file at, plus
+ * the package version. Returns null if better-sqlite3 isn't resolvable —
+ * that's a broken install we let propagate naturally through the dynamic
+ * import in sqlite.ts.
+ */
+function resolveBetterSqlite3OnDisk(
+    requireFn: NodeRequire,
+): { binaryPath: string; pkgVersion: string } | null {
+    try {
+        const pkgJsonPath = requireFn.resolve("better-sqlite3/package.json");
+        const pkgDir = path.dirname(pkgJsonPath);
+        const pkgJson = requireFn(pkgJsonPath) as { version: string };
+        const binaryPath = path.join(pkgDir, "build", "Release", "better_sqlite3.node");
+        return { binaryPath, pkgVersion: pkgJson.version };
+    } catch (err) {
+        logWarn(
+            `could not resolve better-sqlite3 in node_modules: ${err instanceof Error ? err.message : String(err)}`,
+        );
+        return null;
+    }
+}
+
+/**
+ * Cache directory for downloaded native bindings. Keyed by
+ * `<pkgVersion>/electron-v<abi>-<platform>-<arch>` so a Magic Context update
+ * that bumps better-sqlite3 or an OpenCode update that bumps Electron both
+ * trigger a fresh download cleanly.
+ */
+function getCachedBinaryPath(pkgVersion: string, abi: string): string {
+    return path.join(
+        getCacheDir(),
+        "cortexkit",
+        "native-bindings",
+        "better-sqlite3",
+        `v${pkgVersion}`,
+        `electron-v${abi}-${process.platform}-${process.arch}`,
+        "better_sqlite3.node",
+    );
+}
+
+/**
+ * Download the Electron-targeted prebuild tarball from WiseLibs/better-sqlite3
+ * GitHub releases and extract the `.node` bytes. Throws on HTTP failure or
+ * if the tarball doesn't contain the expected file.
+ */
+async function downloadElectronPrebuild(pkgVersion: string, abi: string): Promise<Uint8Array> {
+    const filename = `better-sqlite3-v${pkgVersion}-electron-v${abi}-${process.platform}-${process.arch}.tar.gz`;
+    const url = `https://github.com/WiseLibs/better-sqlite3/releases/download/v${pkgVersion}/${filename}`;
+    logInfo(`downloading ${url}`);
+
+    const response = await fetch(url, {
+        redirect: "follow",
+        headers: { "User-Agent": "magic-context-plugin/native-binding" },
+    });
+    if (!response.ok) {
+        throw new Error(
+            `failed to download Electron prebuild (HTTP ${response.status} ${response.statusText}) from ${url}`,
+        );
+    }
+
+    const tarballBytes = new Uint8Array(await response.arrayBuffer());
+    logInfo(`downloaded ${(tarballBytes.length / 1024).toFixed(1)} KB; extracting`);
+
+    const files = await parseTarGzip(tarballBytes);
+    const nodeFile = files.find((f) => f.name.endsWith("better_sqlite3.node"));
+    if (!nodeFile?.data) {
+        const names = files.map((f) => f.name).join(", ");
+        throw new Error(
+            `Electron prebuild tarball did not contain better_sqlite3.node; got: [${names}]`,
+        );
+    }
+    return nodeFile.data instanceof Uint8Array ? nodeFile.data : new Uint8Array(nodeFile.data);
+}
+
+/**
+ * Singleton promise so concurrent callers (multiple plugin init paths in the
+ * same process) only do the check + download once. Reset to null after
+ * completion so a future call can retry on transient failures.
+ */
+let inFlight: Promise<string | null> | null = null;
+
+/**
+ * Resolve the absolute path to a `better-sqlite3` `.node` binary that the
+ * current runtime can load.
+ *
+ *   - Returns `null` outside Electron (Bun uses `bun:sqlite`; Pi/Node CLI
+ *     loads matching prebuilds from `node_modules` natively).
+ *   - Returns `null` on Electron when the on-disk binary already matches
+ *     the runtime's ABI (rare but possible — a future OpenCode build that
+ *     post-install-rebuilds for Electron would hit this fast path).
+ *   - Returns the cached/downloaded prebuild path on Electron when the
+ *     on-disk binary's ABI doesn't match.
+ *
+ * The returned path is suitable as the `nativeBinding` option to
+ * `new Database(filename, { nativeBinding })`. better-sqlite3 calls `require()`
+ * directly on it, bypassing the default `bindings()` lookup chain — this is
+ * a documented public API in better-sqlite3, not an internal hack.
+ */
+export async function resolveBetterSqliteNativeBinding(): Promise<string | null> {
+    if (!process.versions.electron) {
+        return null;
+    }
+
+    if (inFlight) {
+        return inFlight;
+    }
+
+    const promise = (async () => {
+        const expected = process.versions.modules;
+        logInfo(
+            `Electron detected (v${process.versions.electron}, NODE_MODULE_VERSION ${expected}); verifying better-sqlite3 binding`,
+        );
+
+        const requireFn = createRequire(import.meta.url);
+        const resolved = resolveBetterSqlite3OnDisk(requireFn);
+        if (!resolved) {
+            return null;
+        }
+        const { binaryPath: diskPath, pkgVersion } = resolved;
+
+        // Fast path: if the on-disk binary already matches the runtime's
+        // ABI, we don't need to override the lookup at all. This handles
+        // any future OpenCode build that rebuilds native modules for
+        // Electron at install time, plus the case where the user manually
+        // ran `prebuild-install --runtime=electron`.
+        if (existsSync(diskPath)) {
+            const diskProbe = probeAbi(diskPath);
+            if (diskProbe.ok) {
+                logInfo(
+                    `on-disk binary already matches Electron ABI v${expected}; using default bindings() lookup`,
+                );
+                return null;
+            }
+            logInfo(
+                `on-disk binary ABI ${diskProbe.actual ?? "unknown"} != required ${expected}; will use Electron prebuild`,
+            );
+        } else {
+            logWarn(
+                `expected better-sqlite3 binary not found at ${diskPath}; will fetch Electron prebuild anyway`,
+            );
+        }
+
+        // Look for a cached Electron prebuild from a previous launch.
+        const cachedPath = getCachedBinaryPath(pkgVersion, expected);
+        if (existsSync(cachedPath)) {
+            const cachedProbe = probeAbi(cachedPath);
+            if (cachedProbe.ok) {
+                logInfo(`using cached Electron prebuild at ${cachedPath}`);
+                return cachedPath;
+            }
+            logWarn(
+                `cached binary at ${cachedPath} has wrong ABI (${cachedProbe.actual ?? "unknown"} != ${expected}); refetching`,
+            );
+        }
+
+        // Download fresh.
+        mkdirSync(path.dirname(cachedPath), { recursive: true });
+        const nodeFileBytes = await downloadElectronPrebuild(pkgVersion, expected);
+        writeFileSync(cachedPath, nodeFileBytes);
+        logInfo(
+            `cached Electron prebuild at ${cachedPath} (${(nodeFileBytes.length / 1024).toFixed(1)} KB)`,
+        );
+
+        // Validate the freshly downloaded binary before returning it — if
+        // the upstream tarball was malformed or for the wrong ABI, fail
+        // loudly here rather than letting the better-sqlite3 constructor
+        // throw a less actionable error later.
+        const finalProbe = probeAbi(cachedPath);
+        if (!finalProbe.ok) {
+            throw new Error(
+                `downloaded Electron prebuild has wrong ABI (${finalProbe.actual ?? "unknown"} != ${expected}); refusing to use`,
+            );
+        }
+
+        return cachedPath;
+    })();
+
+    inFlight = promise;
+    try {
+        return await promise;
+    } finally {
+        if (inFlight === promise) {
+            inFlight = null;
+        }
+    }
+}

package/src/shared/normalize-sdk-response.ts

@@ -0,0 +1,40 @@
+export interface NormalizeSDKResponseOptions {
+    preferResponseOnMissingData?: boolean;
+}
+
+// Audit note: `as TData` casts are intentional at this boundary. The OpenCode plugin SDK types
+// external responses as `unknown`. Adding Zod validation here would require schema definitions
+// for every SDK response shape, which changes with each OpenCode release. The fallback parameter
+// provides safe degradation when shapes mismatch.
+export function normalizeSDKResponse<TData>(
+    response: unknown,
+    fallback: TData,
+    options?: NormalizeSDKResponseOptions,
+): TData {
+    if (response === null || response === undefined) {
+        return fallback;
+    }
+
+    if (Array.isArray(response)) {
+        return response as TData;
+    }
+
+    if (typeof response === "object" && "data" in response) {
+        const data = (response as { data?: unknown }).data;
+        if (data !== null && data !== undefined) {
+            return data as TData;
+        }
+
+        if (options?.preferResponseOnMissingData === true) {
+            return response as TData;
+        }
+
+        return fallback;
+    }
+
+    if (options?.preferResponseOnMissingData === true) {
+        return response as TData;
+    }
+
+    return fallback;
+}