perf: cache the CLI catalog with validated startup fallback

Ports #6 with optional-field validation, conversion before cache writes, an upstream-specific cache directory, and startup regression tests.

Co-authored-by: dualface <dualface@gmail.com>

extensions/index.ts

@@ -2,6 +2,13 @@ import type { ExtensionAPI, ProviderModelConfig } from "@earendil-works/pi-codin
 import type { Api, Model, OAuthCredentials, OAuthLoginCallbacks } from "@earendil-works/pi-ai";
 import { authStatus, loginWithCli, readCredentials } from "../src/credentials.js";
 import { whichDevin, devinVersion } from "../src/cli.js";
+import {
+  type CachedDevinCatalog,
+  isUsableCatalog,
+  isCatalogCacheFresh,
+  readCatalogCache,
+  writeCatalogCache,
+} from "../src/catalog-cache.js";
 import { FALLBACK_MODELS, loadCliCatalog, modelsFromCatalog } from "../src/models.js";
 import { CLIENT_IDE, CLIENT_VERSION } from "../src/metadata.js";
 import { streamDevin } from "../src/stream.js";
@@ -10,6 +17,37 @@ const PROVIDER_ID = "devin";
 const PLACEHOLDER_BASE_URL = "https://server.codeium.com";
 
 let _pi: ExtensionAPI | null = null;
+let catalogRequest: Promise<ProviderModelConfig[]> | null = null;
+
+function isOffline(): boolean {
+  const value = process.env.PI_OFFLINE?.toLowerCase();
+  return value === "1" || value === "true" || value === "yes";
+}
+
+function refreshCatalog(pi: ExtensionAPI): Promise<ProviderModelConfig[]> {
+  if (!catalogRequest) {
+    const pending = loadCliCatalog().then((catalog) => {
+      if (!isUsableCatalog(catalog)) {
+        throw new Error("Devin CLI returned no usable model families");
+      }
+      const models = modelsFromCatalog(catalog);
+      try {
+        writeCatalogCache(catalog);
+      } catch (error) {
+        console.warn(`Devin: failed to cache model catalog: ${error instanceof Error ? error.message : String(error)}`);
+      }
+      return models;
+    });
+    catalogRequest = pending;
+    void pending.finally(() => {
+      if (catalogRequest === pending) catalogRequest = null;
+    }).catch(() => {});
+  }
+  return catalogRequest.then((models) => {
+    if (_pi === pi) registerDevinProvider(pi, models);
+    return models;
+  });
+}
 
 function registerDevinProvider(pi: ExtensionAPI, models: ProviderModelConfig[]): void {
   pi.registerProvider(PROVIDER_ID, {
@@ -23,8 +61,7 @@ function registerDevinProvider(pi: ExtensionAPI, models: ProviderModelConfig[]):
         const creds = await loginWithCli();
         if (_pi) {
           try {
-            const catalog = await loadCliCatalog();
-            registerDevinProvider(_pi, modelsFromCatalog(catalog));
+            await refreshCatalog(_pi);
           } catch {
             // keep current models
           }
@@ -57,26 +94,32 @@ function registerDevinProvider(pi: ExtensionAPI, models: ProviderModelConfig[]):
 
 export default async function (pi: ExtensionAPI): Promise<void> {
   _pi = pi;
-  registerDevinProvider(pi, FALLBACK_MODELS);
-
+  let cached: CachedDevinCatalog | null | undefined;
+  let initialModels = FALLBACK_MODELS;
   try {
-    if (readCredentials()) {
-      const catalog = await loadCliCatalog();
-      registerDevinProvider(pi, modelsFromCatalog(catalog));
-    }
-  } catch {
-    // fallback models already registered
+    cached = readCatalogCache();
+    if (cached) initialModels = modelsFromCatalog(cached.catalog);
+  } catch (error) {
+    cached = null;
+    console.warn(`Devin: failed to read model catalog cache: ${error instanceof Error ? error.message : String(error)}`);
   }
+  registerDevinProvider(pi, initialModels);
 
-  pi.on("session_start", async () => {
+  if (!isOffline()) {
     try {
-      if (!_pi || !readCredentials()) return;
-      const catalog = await loadCliCatalog();
-      registerDevinProvider(_pi, modelsFromCatalog(catalog));
+      if (readCredentials()) {
+        if (!cached) {
+          await refreshCatalog(pi);
+        } else if (!isCatalogCacheFresh(cached)) {
+          void refreshCatalog(pi).catch((error) => {
+            console.warn(`Devin: background model catalog refresh failed: ${error instanceof Error ? error.message : String(error)}`);
+          });
+        }
+      }
     } catch {
-      // keep current models
+      // Cached or fallback models stay registered when credential discovery or a cold refresh fails.
     }
-  });
+  }
 
   pi.registerCommand("devin-status", {
     description: "Show Devin CLI auth + binary status",
@@ -100,9 +143,7 @@ export default async function (pi: ExtensionAPI): Promise<void> {
     description: "Refresh Devin Local model catalog from `devin models list`",
     handler: async (_args, ctx) => {
       try {
-        const catalog = await loadCliCatalog();
-        const models = modelsFromCatalog(catalog);
-        registerDevinProvider(pi, models);
+        const models = await refreshCatalog(pi);
         ctx.ui.notify(`Devin: loaded ${models.length} families from the local CLI.`, "info");
       } catch (error) {
         ctx.ui.notify(
@@ -114,6 +155,6 @@ export default async function (pi: ExtensionAPI): Promise<void> {
   });
 
   pi.on("session_shutdown", async () => {
-    _pi = null;
+    if (_pi === pi) _pi = null;
   });
 }