@cortexkit/opencode-magic-context 0.9.1 → 0.10.0

package/dist/plugin/hooks/create-session-hooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-session-hooks.d.ts","sourceRoot":"","sources":["../../../src/plugin/hooks/create-session-hooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAU7D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8CAA8C,CAAC;AACrF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE9C,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IACrC,GAAG,EAAE,aAAa,CAAC;IACnB,YAAY,EAAE,wBAAwB,CAAC;IACvC,gBAAgB,EAAE,gBAAgB,CAAC;CACtC;;;;;;qBA8CgrB,CAAC;;;;;;;;;;;;qBAR/pB,CAAC;mBAAiB,CAAC;iBACtB,CAAP;;;;;0BAOkza,CAAC;;;;;;EAD3za"}
+{"version":3,"file":"create-session-hooks.d.ts","sourceRoot":"","sources":["../../../src/plugin/hooks/create-session-hooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAU7D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8CAA8C,CAAC;AACrF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE9C,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IACrC,GAAG,EAAE,aAAa,CAAC;IACnB,YAAY,EAAE,wBAAwB,CAAC;IACvC,gBAAgB,EAAE,gBAAgB,CAAC;CACtC;;;;;;qBA8C8sB,CAAC;;;;;;;;;;;;qBAPhsB,CAAX;mBAAiB,CAAC;iBAAe,CAAC;;;;;0BAO60b,CAAC;;;;;;EADp3b"}

package/dist/plugin/rpc-handlers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rpc-handlers.d.ts","sourceRoot":"","sources":["../../src/plugin/rpc-handlers.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAIzE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2CAA2C,CAAC;AAGlF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAmZlE;;GAEG;AACH,wBAAgB,mBAAmB,CAC/B,SAAS,EAAE,qBAAqB,EAChC,IAAI,EAAE;IACF,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,MAAM,EAAE,OAAO,CAAC;IAChB,gBAAgB,EAAE,gBAAgB,CAAC;CACtC,GACF,IAAI,CA+FN"}
+{"version":3,"file":"rpc-handlers.d.ts","sourceRoot":"","sources":["../../src/plugin/rpc-handlers.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAIzE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2CAA2C,CAAC;AAGlF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAmZlE;;GAEG;AACH,wBAAgB,mBAAmB,CAC/B,SAAS,EAAE,qBAAqB,EAChC,IAAI,EAAE;IACF,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,MAAM,EAAE,OAAO,CAAC;IAChB,gBAAgB,EAAE,gBAAgB,CAAC;CACtC,GACF,IAAI,CAqGN"}

package/dist/plugin/tui-action-consumer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tui-action-consumer.d.ts","sourceRoot":"","sources":["../../src/plugin/tui-action-consumer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAKzE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2CAA2C,CAAC;AAGlF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAQ7C;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE;IACzC,MAAM,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,gBAAgB,EAAE,gBAAgB,CAAC;CACtC,GAAG,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CA2E3B"}
+{"version":3,"file":"tui-action-consumer.d.ts","sourceRoot":"","sources":["../../src/plugin/tui-action-consumer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AASzE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2CAA2C,CAAC;AAGlF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAO7C;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE;IACzC,MAAM,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,gBAAgB,EAAE,gBAAgB,CAAC;CACtC,GAAG,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAiF3B"}

package/dist/shared/models-dev-cache.d.ts

@@ -1,9 +1,57 @@
 /**
- * Get the context limit for a specific provider/model from OpenCode's models.dev cache.
- * Returns undefined if the model is not found or the cache is unavailable.
- * Results are cached in memory and refreshed every 5 minutes.
+ * 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 `getModelsDevContextLimit()` getter is synchronous: it checks
+ * the API cache first, then the file cache. The plugin warms and refreshes
+ * the API cache from `src/index.ts` at startup and on a timer.
+ */
+import type { createOpencodeClient } from "@opencode-ai/sdk";
+type OpencodeClient = ReturnType<typeof createOpencodeClient>;
+/**
+ * Asynchronously refresh the API-layer cache from OpenCode's SDK.
+ *
+ * Call this at plugin startup and periodically (e.g. every 5 minutes) from
+ * `src/index.ts`. 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 declare function refreshModelLimitsFromApi(client: OpencodeClient): Promise<void>;
+/**
+ * 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 declare function getModelsDevContextLimit(providerID: string, modelID: string): number | undefined;
-/** Clear the in-memory cache (for testing) */
+/** Clear in-memory caches (for testing). */
 export declare function clearModelsDevCache(): void;
+/** Inspection helpers (for logging / debugging). */
+export declare function getModelsDevCacheState(): {
+    apiLoaded: boolean;
+    apiCount: number;
+    apiAgeMs: number;
+    fileCount: number;
+};
+export {};
 //# sourceMappingURL=models-dev-cache.d.ts.map

package/dist/shared/models-dev-cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"models-dev-cache.d.ts","sourceRoot":"","sources":["../../src/shared/models-dev-cache.ts"],"names":[],"mappings":"AA6IA;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAShG;AAED,8CAA8C;AAC9C,wBAAgB,mBAAmB,IAAI,IAAI,CAG1C"}
+{"version":3,"file":"models-dev-cache.d.ts","sourceRoot":"","sources":["../../src/shared/models-dev-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAMH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAG7D,KAAK,cAAc,GAAG,UAAU,CAAC,OAAO,oBAAoB,CAAC,CAAC;AA2J9D;;;;;;;;;;GAUG;AACH,wBAAsB,yBAAyB,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAmCrF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAchG;AAED,4CAA4C;AAC5C,wBAAgB,mBAAmB,IAAI,IAAI,CAK1C;AAED,oDAAoD;AACpD,wBAAgB,sBAAsB,IAAI;IACtC,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACrB,CAOA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cortexkit/opencode-magic-context",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "type": "module",
   "description": "OpenCode plugin for Magic Context — cross-session memory and context management",
   "main": "dist/index.js",

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

@@ -0,0 +1,228 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+    clearModelsDevCache,
+    getModelsDevCacheState,
+    getModelsDevContextLimit,
+    refreshModelLimitsFromApi,
+} from "./models-dev-cache";
+
+describe("models-dev-cache", () => {
+    let tempDir: string;
+    let originalEnv: Record<string, string | undefined>;
+
+    beforeEach(() => {
+        tempDir = mkdtempSync(join(tmpdir(), "mc-models-dev-"));
+        originalEnv = {
+            OPENCODE_MODELS_PATH: process.env.OPENCODE_MODELS_PATH,
+            OPENCODE_MODELS_URL: process.env.OPENCODE_MODELS_URL,
+            XDG_CACHE_HOME: process.env.XDG_CACHE_HOME,
+        };
+        // Isolate from user environment.
+        delete process.env.OPENCODE_MODELS_PATH;
+        delete process.env.OPENCODE_MODELS_URL;
+        process.env.XDG_CACHE_HOME = tempDir;
+        clearModelsDevCache();
+    });
+
+    afterEach(() => {
+        // Restore env.
+        for (const [k, v] of Object.entries(originalEnv)) {
+            if (v === undefined) delete process.env[k];
+            else process.env[k] = v;
+        }
+        rmSync(tempDir, { recursive: true, force: true });
+        clearModelsDevCache();
+    });
+
+    test("reads context limits from models.json under XDG_CACHE_HOME", () => {
+        const opencodeDir = join(tempDir, "opencode");
+        mkdirSync(opencodeDir, { recursive: true });
+        writeFileSync(
+            join(opencodeDir, "models.json"),
+            JSON.stringify({
+                anthropic: {
+                    models: {
+                        "claude-sonnet-4-6": { limit: { context: 200000 } },
+                    },
+                },
+                "github-copilot": {
+                    models: {
+                        "gpt-5.3-codex": { limit: { context: 400000 } },
+                    },
+                },
+            }),
+        );
+
+        expect(getModelsDevContextLimit("anthropic", "claude-sonnet-4-6")).toBe(200000);
+        expect(getModelsDevContextLimit("github-copilot", "gpt-5.3-codex")).toBe(400000);
+        expect(getModelsDevContextLimit("unknown", "unknown")).toBeUndefined();
+    });
+
+    test("expands experimental.modes into derived model IDs with parent context", () => {
+        const opencodeDir = join(tempDir, "opencode");
+        mkdirSync(opencodeDir, { recursive: true });
+        writeFileSync(
+            join(opencodeDir, "models.json"),
+            JSON.stringify({
+                "github-copilot": {
+                    models: {
+                        "gpt-5.4": {
+                            limit: { context: 400000 },
+                            experimental: { modes: { fast: {}, high: {} } },
+                        },
+                    },
+                },
+            }),
+        );
+
+        // Parent ID works.
+        expect(getModelsDevContextLimit("github-copilot", "gpt-5.4")).toBe(400000);
+        // Derived mode IDs inherit parent context.
+        expect(getModelsDevContextLimit("github-copilot", "gpt-5.4-fast")).toBe(400000);
+        expect(getModelsDevContextLimit("github-copilot", "gpt-5.4-high")).toBe(400000);
+    });
+
+    test("OPENCODE_MODELS_PATH env overrides default path", () => {
+        // Write real file somewhere unexpected.
+        const customPath = join(tempDir, "elsewhere", "my-models.json");
+        mkdirSync(join(tempDir, "elsewhere"), { recursive: true });
+        writeFileSync(
+            customPath,
+            JSON.stringify({
+                anthropic: { models: { "claude-4": { limit: { context: 1000000 } } } },
+            }),
+        );
+        process.env.OPENCODE_MODELS_PATH = customPath;
+        clearModelsDevCache();
+
+        expect(getModelsDevContextLimit("anthropic", "claude-4")).toBe(1000000);
+    });
+
+    test("OPENCODE_MODELS_URL (non-default) selects hashed filename", () => {
+        // We can't easily verify the exact hash without duplicating the hash logic,
+        // but we can confirm that setting OPENCODE_MODELS_URL prevents reading
+        // the default models.json when that file exists with different data.
+        const opencodeDir = join(tempDir, "opencode");
+        mkdirSync(opencodeDir, { recursive: true });
+        writeFileSync(
+            join(opencodeDir, "models.json"),
+            JSON.stringify({
+                anthropic: { models: { "claude-4": { limit: { context: 500000 } } } },
+            }),
+        );
+
+        process.env.OPENCODE_MODELS_URL = "https://custom.example.com/models";
+        clearModelsDevCache();
+
+        // Should NOT find claude-4 because we're looking at a hashed filename now,
+        // not models.json.
+        expect(getModelsDevContextLimit("anthropic", "claude-4")).toBeUndefined();
+    });
+
+    test("API cache takes priority over file cache", async () => {
+        // Seed file layer with one value.
+        const opencodeDir = join(tempDir, "opencode");
+        mkdirSync(opencodeDir, { recursive: true });
+        writeFileSync(
+            join(opencodeDir, "models.json"),
+            JSON.stringify({
+                anthropic: { models: { "claude-4": { limit: { context: 100000 } } } },
+            }),
+        );
+
+        // Sanity: file layer returns 100000 before API refresh.
+        expect(getModelsDevContextLimit("anthropic", "claude-4")).toBe(100000);
+
+        // Mock client providing DIFFERENT value via API.
+        const mockClient = {
+            config: {
+                providers: async () => ({
+                    data: {
+                        providers: [
+                            {
+                                id: "anthropic",
+                                models: {
+                                    "claude-4": { limit: { context: 1000000 } },
+                                },
+                            },
+                        ],
+                    },
+                }),
+            },
+        };
+        // @ts-expect-error mock narrow shape
+        await refreshModelLimitsFromApi(mockClient);
+
+        // API value wins.
+        expect(getModelsDevContextLimit("anthropic", "claude-4")).toBe(1000000);
+
+        const state = getModelsDevCacheState();
+        expect(state.apiLoaded).toBe(true);
+        expect(state.apiCount).toBe(1);
+    });
+
+    test("refreshModelLimitsFromApi tolerates empty/malformed responses", async () => {
+        // Undefined data.
+        // @ts-expect-error mock narrow shape
+        await refreshModelLimitsFromApi({
+            config: { providers: async () => ({ data: undefined }) },
+        });
+        expect(getModelsDevCacheState().apiLoaded).toBe(false);
+
+        // Non-array providers.
+        // @ts-expect-error mock narrow shape
+        await refreshModelLimitsFromApi({
+            config: { providers: async () => ({ data: { providers: "not an array" } }) },
+        });
+        expect(getModelsDevCacheState().apiLoaded).toBe(false);
+
+        // Thrown error.
+        // @ts-expect-error mock narrow shape
+        await refreshModelLimitsFromApi({
+            config: {
+                providers: async () => {
+                    throw new Error("network error");
+                },
+            },
+        });
+        expect(getModelsDevCacheState().apiLoaded).toBe(false);
+    });
+
+    test("falls back to file layer when API provider/model key is missing", async () => {
+        const opencodeDir = join(tempDir, "opencode");
+        mkdirSync(opencodeDir, { recursive: true });
+        writeFileSync(
+            join(opencodeDir, "models.json"),
+            JSON.stringify({
+                anthropic: { models: { "claude-only-in-file": { limit: { context: 777777 } } } },
+            }),
+        );
+
+        const mockClient = {
+            config: {
+                providers: async () => ({
+                    data: {
+                        providers: [
+                            {
+                                id: "anthropic",
+                                models: {
+                                    "claude-only-in-api": { limit: { context: 888888 } },
+                                },
+                            },
+                        ],
+                    },
+                }),
+            },
+        };
+        // @ts-expect-error mock narrow shape
+        await refreshModelLimitsFromApi(mockClient);
+
+        // API-only key comes from API.
+        expect(getModelsDevContextLimit("anthropic", "claude-only-in-api")).toBe(888888);
+        // File-only key falls through to file layer.
+        expect(getModelsDevContextLimit("anthropic", "claude-only-in-file")).toBe(777777);
+    });
+});

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

@@ -1,27 +1,55 @@
 /**
- * Read model context limits from OpenCode's models.dev cache file.
+ * Resolve per-model context limits to match whatever OpenCode itself sees.
  *
- * OpenCode fetches model metadata from models.dev and caches it at:
- *   <xdg_cache>/opencode/models.json
+ * Two layers:
  *
- * This file contains per-provider, per-model data including `limit.context`.
- * We read it lazily and refresh periodically to get accurate context limits
- * without requiring user configuration.
+ *   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 `getModelsDevContextLimit()` getter is synchronous: it checks
+ * the API cache first, then the file cache. The plugin warms and refreshes
+ * the API cache from `src/index.ts` at startup and on a timer.
  */
+
+import { createHash } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import { homedir, platform } from "node:os";
 import { join } from "node:path";
+import type { createOpencodeClient } from "@opencode-ai/sdk";
 import { sessionLog } from "./logger";
 
-/** Resolved context limits keyed by "providerID/modelID" */
-let cachedLimits: Map<string, number> | null = null;
-let lastLoadAttempt = 0;
+type OpencodeClient = ReturnType<typeof createOpencodeClient>;
+
 const RELOAD_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes, matches OpenCode's TTL
 
+/** Populated async from OpenCode SDK. Primary source of truth when available. */
+let apiCache: Map<string, number> | null = null;
+let apiLoadedAt = 0;
+
+/** Populated sync from disk as fallback. */
+let fileCache: Map<string, number> | 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;
+
     const xdgCache = process.env.XDG_CACHE_HOME;
     const os = platform();
-
     let cacheBase: string;
     if (xdgCache) {
         cacheBase = xdgCache;
@@ -31,7 +59,15 @@ function getModelsJsonPath(): string {
         cacheBase = join(homedir(), ".cache");
     }
 
-    return join(cacheBase, "opencode", "models.json");
+    // 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 {
@@ -42,7 +78,7 @@ function getOpencodeConfigPath(): string | null {
           ? 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)
+    // 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");
@@ -50,13 +86,15 @@ function getOpencodeConfigPath(): string | null {
     return null;
 }
 
-function loadModelsDevLimits(): Map<string, number> {
+function loadModelsDevLimitsFromFile(): Map<string, number> {
     const limits = new Map<string, number>();
 
-    // 1. Load from OpenCode's models.dev cache (base layer — all known public models)
+    // 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,
@@ -78,7 +116,7 @@ function loadModelsDevLimits(): Map<string, number> {
                     if (typeof context === "number" && context > 0) {
                         limits.set(`${providerId}/${modelId}`, context);
                         // OpenCode creates derived model IDs from experimental.modes
-                        // e.g. gpt-5.4 + modes.fast → gpt-5.4-fast (inherits parent limit)
+                        // e.g. gpt-5.4 + modes.fast → gpt-5.4-fast (inherits parent limit).
                         const modes = model?.experimental?.modes;
                         if (modes && typeof modes === "object") {
                             for (const mode of Object.keys(modes)) {
@@ -92,7 +130,7 @@ function loadModelsDevLimits(): Map<string, number> {
     } catch (error) {
         sessionLog(
             "global",
-            "models-dev-cache: failed to read models.json:",
+            `models-dev-cache: failed to read models.json at ${modelsJsonPath}:`,
             error instanceof Error ? error.message : String(error),
         );
     }
@@ -105,7 +143,6 @@ function loadModelsDevLimits(): Map<string, number> {
         if (configPath && existsSync(configPath)) {
             let raw = readFileSync(configPath, "utf-8");
             // Strip JSONC single-line comments while preserving // inside strings.
-            // Match strings first (to skip them), then match comments outside strings.
             raw = raw.replace(/"(?:[^"\\]|\\.)*"|\/\/.*$/gm, (match) =>
                 match.startsWith('"') ? match : "",
             );
@@ -136,27 +173,108 @@ function loadModelsDevLimits(): Map<string, number> {
         );
     }
 
+    sessionLog(
+        "global",
+        `models-dev-cache: file-layer loaded ${limits.size} model limits (modelsJsonPath=${modelsJsonPath}, found=${fileFound})`,
+    );
+
     return limits;
 }
 
 /**
- * Get the context limit for a specific provider/model from OpenCode's models.dev cache.
- * Returns undefined if the model is not found or the cache is unavailable.
- * Results are cached in memory and refreshed every 5 minutes.
+ * Asynchronously refresh the API-layer cache from OpenCode's SDK.
+ *
+ * Call this at plugin startup and periodically (e.g. every 5 minutes) from
+ * `src/index.ts`. 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: OpencodeClient): 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, number>();
+        for (const entry of providers) {
+            const p = entry as {
+                id?: string;
+                models?: Record<string, { limit?: { context?: number } }>;
+            };
+            if (!p?.id || !p.models || typeof p.models !== "object") continue;
+            for (const [modelId, model] of Object.entries(p.models)) {
+                const context = model?.limit?.context;
+                if (typeof context === "number" && context > 0) {
+                    map.set(`${p.id}/${modelId}`, context);
+                }
+            }
+        }
+
+        apiCache = map;
+        apiLoadedAt = Date.now();
+        sessionLog("global", `models-dev-cache: API layer loaded ${map.size} model limits`);
+    } 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 now = Date.now();
+    const key = `${providerID}/${modelID}`;
 
-    if (!cachedLimits || now - lastLoadAttempt > RELOAD_INTERVAL_MS) {
-        lastLoadAttempt = now;
-        cachedLimits = loadModelsDevLimits();
+    if (apiCache) {
+        const fromApi = apiCache.get(key);
+        if (typeof fromApi === "number") return fromApi;
     }
 
-    return cachedLimits.get(`${providerID}/${modelID}`);
+    const now = Date.now();
+    if (!fileCache || now - fileLastAttempt > RELOAD_INTERVAL_MS) {
+        fileLastAttempt = now;
+        fileCache = loadModelsDevLimitsFromFile();
+    }
+    return fileCache.get(key);
 }
 
-/** Clear the in-memory cache (for testing) */
+/** Clear in-memory caches (for testing). */
 export function clearModelsDevCache(): void {
-    cachedLimits = null;
-    lastLoadAttempt = 0;
+    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,
+    };
 }