fix: allow extension to load when offline

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+- Allow pi to start when model discovery is unavailable. The provider now caches the last successfully fetched model catalog so previously discovered Command Code models remain selectable offline; a first offline start without a cache keeps Command Code unavailable until `/reload` succeeds.
+
+### Contributors
+
+- @k3-2o — reported that the model-list fetch blocked pi startup when offline.
+
 ## 0.4.2 - 2026-07-05
 
 - Fix Oh My Pi extension validation by avoiding the missing `calculateCost` export from OMP's legacy `pi-ai` shim.

README.md

@@ -134,7 +134,9 @@ On startup, the provider fetches:
 https://api.commandcode.ai/provider/v1/models
 ```
 
-For tests or local mocks, override it with `COMMANDCODE_MODELS_URL`.
+The last successfully fetched catalog is cached at `<agent-dir>/commandcode-models.json` (`~/.pi/agent/commandcode-models.json` by default). The agent directory follows pi's `PI_CODING_AGENT_DIR` setting, so compatible hosts such as OMP keep the cache in their own agent directory. If model discovery is temporarily unavailable, the provider uses this cached catalog so previously discovered Command Code models remain selectable. On a first offline start without a cache, pi still loads, but Command Code models remain unavailable until the connection is restored and `/reload` succeeds.
+
+For tests or local mocks, override the endpoint with `COMMANDCODE_MODELS_URL` and the cache file with `COMMANDCODE_MODELS_CACHE`.
 
 ## Pricing
 

index.ts

@@ -13,15 +13,18 @@
  */
 
 import { AssistantMessageEventStream } from "@earendil-works/pi-ai"
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"
+import { getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent"
+import { join } from "node:path"
 
 import { COMMAND_CODE_CLI_VERSION, createStreamCommandCode, DEFAULT_API_BASE } from "./src/core.ts"
 import { calculateCommandCodeCost } from "./src/cost.ts"
-import { DEFAULT_MODELS_URL, fetchCommandCodeModels } from "./src/models.ts"
+import { DEFAULT_MODELS_URL, loadCommandCodeModels } from "./src/models.ts"
 import { getApiKey, login, refreshToken } from "./src/oauth.ts"
 
 const API_BASE = process.env.COMMANDCODE_API_BASE ?? DEFAULT_API_BASE
 const MODELS_URL = process.env.COMMANDCODE_MODELS_URL ?? DEFAULT_MODELS_URL
+const MODELS_CACHE_PATH =
+  process.env.COMMANDCODE_MODELS_CACHE ?? join(getAgentDir(), "commandcode-models.json")
 
 type CommandCodeModelCost = {
   input: number
@@ -79,7 +82,12 @@ const streamCommandCode = createStreamCommandCode({
 // ---------------------------------------------------------------------------
 
 export default async function (pi: ExtensionAPI) {
-  const models = await fetchCommandCodeModels({ url: MODELS_URL })
+  const { models, warning } = await loadCommandCodeModels({
+    url: MODELS_URL,
+    cachePath: MODELS_CACHE_PATH,
+  })
+
+  if (warning) console.warn(`[commandcode] ${warning}`)
 
   pi.registerProvider("commandcode", {
     name: "Command Code",

src/models.ts

@@ -1,6 +1,10 @@
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises"
+import { dirname } from "node:path"
+
 export const DEFAULT_MODELS_URL = "https://api.commandcode.ai/provider/v1/models"
 
 const DEFAULT_MAX_OUTPUT_TOKENS = 65_536
+const MODEL_CACHE_VERSION = 1
 
 interface ApiModel {
   id: string
@@ -21,19 +25,39 @@ interface FetchCommandCodeModelsOptions {
   fetchImpl?: typeof fetch
 }
 
+interface LoadCommandCodeModelsOptions extends FetchCommandCodeModelsOptions {
+  cachePath: string
+}
+
+export interface LoadCommandCodeModelsResult {
+  models: readonly CommandCodeModel[]
+  source: "live" | "cache" | "empty"
+  warning?: string
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null
+  return typeof value === "object" && value !== null && !Array.isArray(value)
 }
 
 function stringField(record: Record<string, unknown>, key: string): string {
   const value = record[key]
-  if (typeof value !== "string") throw new Error(`Expected ${key} to be a string`)
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`Expected ${key} to be a non-empty string`)
+  }
   return value
 }
 
-function numberField(record: Record<string, unknown>, key: string): number {
+function booleanField(record: Record<string, unknown>, key: string): boolean {
   const value = record[key]
-  if (typeof value !== "number") throw new Error(`Expected ${key} to be a number`)
+  if (typeof value !== "boolean") throw new Error(`Expected ${key} to be a boolean`)
+  return value
+}
+
+function positiveNumberField(record: Record<string, unknown>, key: string): number {
+  const value = record[key]
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    throw new Error(`Expected ${key} to be a positive number`)
+  }
   return value
 }
 
@@ -43,10 +67,31 @@ function parseApiModel(value: unknown): ApiModel {
   return {
     id: stringField(value, "id"),
     name: stringField(value, "name"),
-    contextLength: numberField(value, "context_length"),
+    contextLength: positiveNumberField(value, "context_length"),
   }
 }
 
+function parseCachedModel(value: unknown): CommandCodeModel {
+  if (!isRecord(value)) throw new Error("Expected cached model entry to be an object")
+
+  return {
+    id: stringField(value, "id"),
+    name: stringField(value, "name"),
+    reasoning: booleanField(value, "reasoning"),
+    contextWindow: positiveNumberField(value, "contextWindow"),
+    maxTokens: positiveNumberField(value, "maxTokens"),
+  }
+}
+
+function requireModels(models: readonly CommandCodeModel[]): readonly CommandCodeModel[] {
+  if (models.length === 0) throw new Error("Command Code returned an empty model catalog")
+  return models
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
 export function commandCodeModelsFromApiResponse(value: unknown): readonly CommandCodeModel[] {
   if (!isRecord(value)) throw new Error("Expected models response to be an object")
   if (value.object !== "list") throw new Error("Expected models response object to be 'list'")
@@ -63,6 +108,16 @@ export function commandCodeModelsFromApiResponse(value: unknown): readonly Comma
   }))
 }
 
+export function commandCodeModelsFromCache(value: unknown): readonly CommandCodeModel[] {
+  if (!isRecord(value)) throw new Error("Expected model cache to be an object")
+  if (value.version !== MODEL_CACHE_VERSION) {
+    throw new Error(`Expected model cache version ${MODEL_CACHE_VERSION}`)
+  }
+  if (!Array.isArray(value.models)) throw new Error("Expected cached models to be an array")
+
+  return requireModels(value.models.map(parseCachedModel))
+}
+
 export async function fetchCommandCodeModels(
   options: FetchCommandCodeModelsOptions = {},
 ): Promise<readonly CommandCodeModel[]> {
@@ -81,5 +136,70 @@ export async function fetchCommandCodeModels(
   }
 
   const body: unknown = await response.json()
-  return commandCodeModelsFromApiResponse(body)
+  return requireModels(commandCodeModelsFromApiResponse(body))
+}
+
+async function readCommandCodeModelsCache(cachePath: string): Promise<readonly CommandCodeModel[]> {
+  const contents = await readFile(cachePath, "utf-8")
+  const parsed: unknown = JSON.parse(contents)
+  return commandCodeModelsFromCache(parsed)
+}
+
+async function writeCommandCodeModelsCache(
+  cachePath: string,
+  models: readonly CommandCodeModel[],
+): Promise<void> {
+  await mkdir(dirname(cachePath), { recursive: true })
+  const temporaryPath = `${cachePath}.${process.pid}.tmp`
+
+  try {
+    await writeFile(
+      temporaryPath,
+      `${JSON.stringify({ version: MODEL_CACHE_VERSION, models }, null, 2)}\n`,
+      { encoding: "utf-8", mode: 0o600 },
+    )
+    await rename(temporaryPath, cachePath)
+  } finally {
+    try {
+      await rm(temporaryPath, { force: true })
+    } catch {
+      // Best-effort cleanup must not hide the original cache write error.
+    }
+  }
+}
+
+export async function loadCommandCodeModels(
+  options: LoadCommandCodeModelsOptions,
+): Promise<LoadCommandCodeModelsResult> {
+  const cachePath = options.cachePath
+
+  try {
+    const models = await fetchCommandCodeModels(options)
+
+    try {
+      await writeCommandCodeModelsCache(cachePath, models)
+      return { models, source: "live" }
+    } catch (error) {
+      return {
+        models,
+        source: "live",
+        warning: `Loaded the live Command Code model catalog but could not update ${cachePath}: ${errorMessage(error)}`,
+      }
+    }
+  } catch (liveError) {
+    try {
+      const models = await readCommandCodeModelsCache(cachePath)
+      return {
+        models,
+        source: "cache",
+        warning: `Could not refresh the Command Code model catalog (${errorMessage(liveError)}). Using the cached catalog from ${cachePath}.`,
+      }
+    } catch (cacheError) {
+      return {
+        models: [],
+        source: "empty",
+        warning: `Could not refresh the Command Code model catalog (${errorMessage(liveError)}), and no valid cached catalog is available at ${cachePath} (${errorMessage(cacheError)}). Command Code models will remain unavailable until /reload succeeds.`,
+      }
+    }
+  }
 }