agent-accelerator 0.1.0 → 0.2.0

package/src/agent/loop.ts

@@ -7,8 +7,9 @@ import { AssistantMessageEventStream } from "../streaming/event-stream.ts";
 import { AgentContext } from "./context.ts";
 import { toStandardToolDeclarations } from "../tools/tool.ts";
 import { executeToolCalls } from "../tools/executor.ts";
-import { getModelFromCatalog, ensureModelCatalogFresh } from "../models/catalog.ts";
-import { countTokens } from "../tokens/counter.ts";
+import { getModelFromCatalog, ensureModelCatalogFresh, validateModelThinking } from "../models/catalog.ts";
+import { preprocessFilePartsForBypass } from "../utils/documents.ts";
+import { noteProviderTurn } from "../providers.ts";
 
 export interface AgentLoopConfig {
   agentName?: string;
@@ -19,6 +20,8 @@ export interface AgentLoopConfig {
   options?: ProviderRequestOptions;
   runOptions?: AgentRunOptions;
   maxTurns?: number;
+  /** Convert `file` parts client-side for pdf-incapable models (see Agent flag). */
+  bypassInputFileModality?: boolean;
 }
 
 export function computeCostFromPricing(usage: TokenUsage, spec?: ModelSpec): TokenUsage["cost"] {
@@ -67,6 +70,13 @@ function accumulateUsage(target: TokenUsage, source: TokenUsage, spec?: ModelSpe
   target.cacheWriteTokens = (target.cacheWriteTokens ?? 0) + (source.cacheWriteTokens ?? 0);
   target.thinkingTokens = (target.thinkingTokens ?? 0) + (source.thinkingTokens ?? 0);
 
+  // Canonical invariant (provider-agnostic): cache hits are a subset of
+  // input. Some providers occasionally report cached > input on long chained
+  // runs, which surfaces as >100% hit rates downstream. Clamp the aggregate
+  // so no consumer can observe an impossible ratio.
+  target.cachedTokens = Math.min(target.cachedTokens ?? 0, target.inputTokens);
+  target.cacheReadTokens = Math.min(target.cacheReadTokens ?? 0, target.inputTokens);
+
   const sourceCost = computeCostFromPricing(source, spec);
   if (sourceCost) {
     source.cost = sourceCost;
@@ -155,12 +165,26 @@ async function executeToolCallsWithRepeatGuard(options: {
         sessionId: options.sessionId,
       })
     : [];
-  const byId = new Map<string, ToolResultRecord>();
-  for (const result of executed) byId.set(result.id, result);
-  for (const [id, result] of blocked) byId.set(id, result);
+  const byId = new Map<string, ToolResultRecord[]>();
+  for (const result of executed) {
+    const queue = byId.get(result.id) ?? [];
+    queue.push(result);
+    byId.set(result.id, queue);
+  }
+  for (const [id, result] of blocked) {
+    const queue = byId.get(id) ?? [];
+    queue.push(result);
+    byId.set(id, queue);
+  }
 
   return {
-    results: toolCalls.map((call) => byId.get(call.id)!).filter(Boolean),
+    // Consume per-id queues in call order: some open-weights models reuse one
+    // id for several distinct calls in a turn, and a plain id->result map
+    // would hand every call the last result. Queues keep each result aligned
+    // with its own call.
+    results: toolCalls
+      .map((call) => byId.get(call.id)?.shift())
+      .filter((r): r is ToolResultRecord => Boolean(r)),
     fingerprints: currentFingerprints,
   };
 }
@@ -181,6 +205,14 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
     maxTurns = 10,
   } = config;
 
+  if (config.bypassInputFileModality) {
+    await preprocessFilePartsForBypass(config.context.messages, {
+      providerId: provider.id,
+      modelId,
+      signal: runOptions?.signal,
+    });
+  }
+
   const standardTools = toStandardToolDeclarations(tools);
   const startTime = Date.now();
 
@@ -204,30 +236,7 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
   while (turns < maxTurns) {
     turns++;
 
-    // Battle-tested context window check — trim oldest history if needed, keep cached prefix (system+tools)
     const spec = getModelFromCatalog(provider.id, modelId);
-    const contextWindow = spec?.limit?.context ?? spec?.contextWindow ?? 128000;
-    const maxOutput = spec?.limit?.output ?? spec?.maxOutputTokens ?? 8192;
-    // Reserve for output + 10% headroom, ensure first turn already cache-friendly
-    const budgetForInput = Math.floor(contextWindow * 0.9) - maxOutput;
-    let estimated = 0;
-    try {
-      estimated = countTokens({ systemPrompt: context.systemPrompt, messages: context.messages, tools: standardTools as any });
-    } catch {}
-    if (estimated > budgetForInput && context.messages.length > 2) {
-      // Keep system + last 70% of history, drop oldest middle (preserve cached prefix stability)
-      const keepCount = Math.max(2, Math.floor(context.messages.length * 0.7));
-      const toKeep = context.messages.slice(-keepCount);
-      // Preserve at least system and first user if possible
-      const firstUserIdx = context.messages.findIndex((m) => m.role === "user");
-      if (firstUserIdx >= 0 && firstUserIdx < context.messages.length - keepCount) {
-        // Drop middle, keep head + tail for cache stability
-        const head = context.messages.slice(0, 1);
-        context.messages = [...head, ...toKeep];
-      } else {
-        context.messages = toKeep;
-      }
-    }
 
     const providerOptions: ProviderRequestOptions = {
       ...options,
@@ -250,6 +259,12 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
 
     finalResult = genResult;
 
+    // Canonical session routing: lets adapters detect provider switches.
+    noteProviderTurn(
+      runOptions?.sessionId || options?.sessionId || options?.cache?.sessionId,
+      provider.id
+    );
+
     // Safety fallback: if no tool calls and text is empty, rescue answer from thinking
     if ((!genResult.text || genResult.text.trim() === "") && (!genResult.toolCalls || genResult.toolCalls.length === 0) && genResult.thinking) {
       if (genResult.thinking.includes("</think>")) {
@@ -340,7 +355,7 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
   const startTime = Date.now();
 
   // Cancellation: merge user signal + outer cancel() into one linked controller.
-  // Vercel doStream honors abortSignal for all providers, so aborting this
+  // Native fetch honors abortSignal on every provider, so aborting this
   // stops the HTTP request; we also cancel the active inner provider stream.
   const linked = new AbortController();
   const userSignal = config.runOptions?.signal;
@@ -365,6 +380,27 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
   (async () => {
     try {
       await ensureModelCatalogFresh();
+      // Re-validate after refresh: Agent.stream() validates before the catalog
+      // is guaranteed fresh, so a cold cache validates permissively. A mismatch
+      // discovered here fails the stream instead of reaching the provider.
+      {
+        const lvl = config.runOptions?.thinkingLevel ?? config.options?.thinking?.level;
+        if (lvl) {
+          try {
+            validateModelThinking(config.provider.id, config.modelId, lvl);
+          } catch (err) {
+            outerStream.fail(err instanceof Error ? err : new Error(String(err)));
+            return;
+          }
+        }
+      }
+      if (config.bypassInputFileModality) {
+        await preprocessFilePartsForBypass(config.context.messages, {
+          providerId: config.provider.id,
+          modelId: config.modelId,
+          signal: config.runOptions?.signal,
+        });
+      }
       const {
         agentName,
         provider,
@@ -399,25 +435,7 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
         throwIfCancelled();
         turns++;
 
-        // Same context-window trim as non-stream (ensure cache prefix stable)
         const spec2 = getModelFromCatalog(provider.id, modelId);
-        const cw2 = spec2?.limit?.context ?? spec2?.contextWindow ?? 128000;
-        const mo2 = spec2?.limit?.output ?? spec2?.maxOutputTokens ?? 8192;
-        const budget2 = Math.floor(cw2 * 0.9) - mo2;
-        try {
-          const est2 = countTokens({ systemPrompt: context.systemPrompt, messages: context.messages, tools: standardTools as any });
-          if (est2 > budget2 && context.messages.length > 2) {
-            const keep2 = Math.max(2, Math.floor(context.messages.length * 0.7));
-            const toKeep = context.messages.slice(-keep2);
-            const firstUserIdx = context.messages.findIndex((m) => m.role === "user");
-            if (firstUserIdx >= 0 && firstUserIdx < context.messages.length - keep2) {
-              const head = context.messages.slice(0, 1);
-              context.messages = [...head, ...toKeep];
-            } else {
-              context.messages = toKeep;
-            }
-          }
-        } catch {}
 
         const providerOptions: ProviderRequestOptions = {
           ...options,
@@ -449,6 +467,11 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
         currentInner = null;
         throwIfCancelled();
         lastResponse = turnResponse;
+        // Canonical session routing: lets adapters detect provider switches.
+        noteProviderTurn(
+          runOptions?.sessionId || options?.sessionId || options?.cache?.sessionId,
+          provider.id
+        );
 
         // Safety fallback: if no tool calls and text is empty, rescue answer from thinking
         if ((!turnResponse.text || turnResponse.text.trim() === "") && (!turnResponse.toolCalls || turnResponse.toolCalls.length === 0) && turnResponse.thinking) {

package/src/data/README.md

@@ -11,13 +11,13 @@ Agent Accelerator references a catalog of **7,500+ models across 200+ providers*
 To keep the repository and published npm/Bun package lightweight and blazing fast:
 
 1. **Excluded from Production Package & Git**:
-   * The ~4.5 MB full catalog snapshot (`models-cache.json` / `models.dev.json`) is **never** committed to git and is **excluded** from the npm/Bun distribution bundle.
-   * Both files are tracked in `.gitignore` and `.npmignore`.
+   * The ~4.5 MB full catalog snapshot (`models.dev.json`) is **never** committed to git and is **excluded** from the npm/Bun distribution bundle.
+   * The file is tracked in `.gitignore` and `.npmignore`.
 
 2. **Dynamic 12-Hour Automated TTL Cache**:
-   * On agent execution (`runAgentLoop` / `streamAgentLoop`), Agent Accelerator checks the status of `src/data/models-cache.json`.
+   * On agent execution (`runAgentLoop` / `streamAgentLoop`), Agent Accelerator checks the status of `src/data/models.dev.json`.
    * **Cache Hit (< 12h)**: Instant memory/disk load with zero network overhead.
-   * **Cache Miss / Expired (≥ 12h)**: Automatically downloads the latest catalog directly from `https://models.dev/api.json`, caches it to `src/data/models-cache.json`, and loads the catalog into memory.
+   * **Cache Miss / Expired (≥ 12h)**: Automatically downloads the latest catalog directly from `https://models.dev/api.json`, caches it to `src/data/models.dev.json`, and loads the catalog into memory.
    * **Resilience**: If an existing cache exists on disk, temporary upstream network issues will safely continue using the local cached copy.
 
 ---
@@ -36,7 +36,7 @@ bun run update-models
 bun run update-models --force
 
 # Custom TTL (e.g., 24 hours)
-bun scripts/update-models.ts --ttl=24h
+bun src/update-models.ts --ttl=24h
 ```
 
 ---
@@ -80,5 +80,5 @@ setCatalogTTL(6 * 60 * 60 * 1000);
 ```text
 src/data/
 ├── README.md               # This documentation
-└── models-cache.json       # Auto-generated on first run (gitignored, excluded from bundle)
+└── models.dev.json         # Auto-generated on first run (gitignored, excluded from bundle)
 ```

package/src/index.ts

@@ -9,21 +9,43 @@ export type { CreateToolOptions } from "./tools/tool.ts";
 export { zodToJsonSchema, cleanJsonSchema } from "./tools/schema.ts";
 export { executeToolCalls } from "./tools/executor.ts";
 
+// Client-side document conversion (optional anydoc peer — see utils/documents.ts)
+export {
+  convertDocumentToMarkdown,
+  convertDocumentInput,
+  convert_document_to_markdown,
+  isAnydocAvailable,
+  resolveDocumentFormat,
+  truncateMarkdown,
+  buildDocumentXml,
+  modelSupportsFileInput,
+  preprocessFilePartsForBypass,
+  DocumentConversionError,
+  DEFAULT_DOCUMENT_MAX_CHARS,
+  MAX_DOCUMENT_FETCH_BYTES,
+} from "./utils/documents.ts";
+export type { ConvertDocumentOptions, ConvertedDocument } from "./utils/documents.ts";
+
 // Multi-Agent Delegation & Tools
 export {
   buildAgentTools,
+  agentToTool,
   createSubagentSpawnTool,
 } from "./agent/delegation.ts";
-export type { DynamicSubagentTask } from "./agent/delegation.ts";
+export type { DynamicSubagentTask, AgentAsToolTarget } from "./agent/delegation.ts";
 
-// Providers & Registry — unified multi-provider layer powered by Vercel AI SDK
+// Providers & Registry — unified multi-provider layer, all native REST
 export {
   getProvider,
   resolveModel,
   ModelProvider,
   ensureCustomProvider,
   normalizeProviderPrefix,
-} from "./ai-sdk/registry.ts";
+} from "./providers/registry.ts";
+export type {
+  ModelProviderInstance,
+  ModelProviderConfig,
+} from "./providers/registry.ts";
 export {
   getModelFromCatalog,
   getModelThinkingInfo,
@@ -37,48 +59,78 @@ export {
   getCatalogTTL,
   getCacheDir,
   getCacheFilePath,
+  isValidCatalogPayload,
+  createGenericModelSpec,
   DEFAULT_CATALOG_TTL_MS,
   type CatalogStatus,
   type RefreshCatalogOptions,
 } from "./models/catalog.ts";
-export { AiSdkBaseProvider as BaseProvider } from "./ai-sdk/model-provider.ts";
-export {
-  mapThinkingToReasoning,
-  resolveEffectiveThinking,
-  mapToolChoice,
-  mapThinkingToProviderOptions,
-  mapServiceTierToProviderOptions,
-  mapCacheToProviderOptions,
-  buildAiSdkCallOptions,
-  withAiSdkRetries,
-  isTransientAiSdkError,
-} from "./ai-sdk/options.ts";
-export { toConciseProviderError, assertModalitiesSupported } from "./ai-sdk/errors.ts";
-
-// Provider Implementations powered by Vercel AI SDK
+export { resolveEffectiveThinking } from "./agent/agent.ts";
+export { withRetries, isTransientError } from "./utils/retry.ts";
+export { toConciseProviderError, assertModalitiesSupported, assertNoVideoPartsOnResponses } from "./utils/errors.ts";
+// Native provider implementations. `openrouter-responses.ts` (discontinued
+// beta-Responses transport) stays importable directly but is wired nowhere.
 export {
-  GoogleAIStudioProvider,
-  GoogleAiSdkProvider,
-  OpenCodeProvider,
-  OpenCodeAiSdkProvider,
-  OpenRouterProvider,
-  OpenRouterAiSdkProvider,
-  OpenAIProvider,
-  OpenAiAiSdkProvider,
-  OpenAICompatibleProvider,
-  CustomAiSdkProvider,
-  AiSdkBaseProvider,
+  OpenAICompatibleChatProvider,
+  OpenAICompatibleChatProvider as OpenAICompatibleProvider,
   createOpenAICompatibleProvider,
   createCustomProvider,
   CustomProvider,
-  createGenericModelSpec,
-} from "./ai-sdk/model-provider.ts";
-export type { CustomProviderOptions } from "./ai-sdk/model-provider.ts";
+} from "./providers/openai-compat.ts";
+export type { CustomProviderOptions } from "./providers/openai-compat.ts";
+
+// Canonical provider contract (provider-agnostic) + native adapters.
+export {
+  GoogleInteractionsProvider,
+  GoogleInteractionsProvider as GoogleAIStudioProvider,
+  clearInteractionChains,
+} from "./providers/google.ts";
+export {
+  OpenRouterChatCompletionsProvider,
+  OpenRouterChatCompletionsProvider as OpenRouterProvider,
+} from "./providers/openrouter.ts";
+// Discontinued beta-Responses transport, retained frozen as migration
+// evidence (importable via `./providers/openrouter-responses.ts`, not wired
+// anywhere): OpenRouterResponsesProvider.
+export {
+  OpenAIResponsesProvider,
+  OpenAIResponsesProvider as OpenAIProvider,
+} from "./providers/openai.ts";
+export {
+  emitProviderWarning,
+  clearEmittedWarnings,
+  noteProviderTurn,
+  lastProviderFor,
+  isMixedProviderSession,
+  clearSessionRouting,
+  mapThinkingLevelToGoogle,
+  mapServiceTierToGoogle,
+  applyCacheForGoogle,
+  mapThinkingLevelToOpenRouter,
+  mapServiceTierToOpenRouter,
+  applyCacheForOpenRouter,
+  mapToolChoiceToOpenRouter,
+  mapThinkingLevelToOpenRouterChat,
+  mapToolChoiceToOpenRouterChat,
+  mapThinkingLevelToOpenAI,
+  mapServiceTierToOpenAI,
+  applyCacheForOpenAI,
+  applyCacheForCustom,
+  mapToolChoiceToOpenAI,
+  normalizeToolChoice,
+  parseStreamedToolArguments,
+} from "./providers.ts";
+export type {
+  ProviderCapabilityStatus,
+  CanonicalToolChoiceMode,
+  OpenRouterToolChoice,
+  OpenRouterChatToolChoice,
+  OpenAIToolChoice,
+} from "./providers.ts";
 
 export {
   GOOGLE_MODELS,
   OPENAI_MODELS,
-  OPENCODE_MODELS,
   OPENROUTER_MODELS,
 } from "./models/catalog.ts";
 
@@ -101,14 +153,6 @@ export type {
   CachedContentMetadata,
 } from "./utils/cache.ts";
 
-
-export {
-  countTokens,
-  estimateTokensFromText,
-  estimateTokensFromMessage,
-  estimateTokensFromPart,
-} from "./tokens/counter.ts";
-
 // Streaming & Events
 export { AssistantMessageEventStream } from "./streaming/event-stream.ts";
 export { SSEParser } from "./streaming/sse-parser.ts";
@@ -122,7 +166,7 @@ export { getApiKey, getEnv } from "./utils/env.ts";
 export { buildSessionHeaders } from "./utils/headers.ts";
 export { normalizeMediaInput, inferMimeType } from "./utils/media.ts";
 export { base64ToBytes, bytesToBase64 } from "./utils/base64.ts";
-export { toJsonSafe, safeStringify } from "./utils/serialization.ts";
+export { toJsonSafe, safeStringify, escapeXml } from "./utils/serialization.ts";
 
 // Re-export Zod
 export { z };
@@ -184,7 +228,48 @@ export type {
   DynamicSubagentsConfig,
 } from "./types/agent.ts";
 
+ // Provider wire payload types (back-compat inspection of raw requests/responses,
+// e.g. `res.raw.request.body as OpenAIChatCompletionRequest`).
+// NOTE: wire `OpenAIToolChoice` intentionally omitted — it duplicates the
+// canonical `OpenAIToolChoice` exported above (same shape); use that one.
 export type {
-  ModelProviderInstance,
-  ModelProviderConfig,
-} from "./ai-sdk/registry.ts";
+  GoogleThinkingLevel,
+  GoogleThinkingConfig,
+  GoogleFunctionCallingMode,
+  GoogleFunctionCallingConfig,
+  GoogleToolConfig,
+  GoogleFunctionDeclaration,
+  GoogleTool,
+  GoogleBlob,
+  GooglePart,
+  GoogleContent,
+  GoogleGenerationConfig,
+  GoogleCandidate,
+  GoogleUsageMetadata,
+  GoogleGenerateContentRequest,
+  GoogleGenerateContentResponse,
+  OpenRouterProviderRouting,
+  OpenRouterReasoning,
+  OpenRouterParameters,
+  OpenRouterUsage,
+  OpenRouterChatRequest,
+  OpenRouterResponse,
+  OpenAIMessageRole,
+  OpenAIReasoningEffort,
+  OpenAIServiceTier,
+  OpenAITextPart,
+  OpenAIImageUrlPart,
+  OpenAIInputAudioPart,
+  OpenAIVideoUrlPart,
+  OpenAIContentPart,
+  OpenAIToolCall,
+  OpenAIMessage,
+  OpenAITool,
+  OpenAIUsage,
+  OpenAIChoice,
+  OpenAIDelta,
+  OpenAIChunkChoice,
+  OpenAIChatCompletionRequest,
+  OpenAIChatCompletionResponse,
+  OpenAIChatCompletionChunk,
+} from "./types/provider-payloads.ts";

package/src/models/catalog-cache.ts

@@ -1,5 +1,6 @@
 import * as path from "node:path";
 import * as fs from "node:fs";
+import { getEnv } from "../utils/env.ts";
 
 /** Default TTL: 12 Hours (in milliseconds). */
 export const DEFAULT_CATALOG_TTL_MS = 12 * 60 * 60 * 1000;
@@ -65,14 +66,20 @@ function notifyUpdateListeners(): void {
   }
 }
 
-/** Non-configurable cache directory: src/data */
+/**
+ * Catalog cache directory. Defaults to `src/data` (repo convention); override
+ * with `AGENT_CACHE_DIR` when embedding as a package or running on a
+ * read-only filesystem (serverless/containers).
+ */
 export function getCacheDir(): string {
+  const override = getEnv("AGENT_CACHE_DIR");
+  if (override && override.trim()) return path.resolve(override.trim());
   return path.resolve(process.cwd(), "src/data");
 }
 
-/** Non-configurable cache file path: src/data/models-cache.json */
+/** Non-configurable cache file path: src/data/models.dev.json */
 export function getCacheFilePath(): string {
-  return path.resolve(process.cwd(), "src/data/models-cache.json");
+  return path.resolve(process.cwd(), "src/data/models.dev.json");
 }
 
 function readJsonFileSync(filePath: string): any {
@@ -99,7 +106,7 @@ let activeFetchedAt: number | undefined = undefined;
 let activeTtlMs: number = globalCatalogTtlMs;
 let activeFromCache = false;
 
-// Synchronous bootstrap: load from src/data/models-cache.json if present
+// Synchronous bootstrap: load from src/data/models.dev.json if present
 function initializeCatalogSync(): void {
   const cachePath = getCacheFilePath();
   const cached = readJsonFileSync(cachePath);
@@ -165,9 +172,30 @@ export function getCatalogStatus(): CatalogStatus {
   };
 }
 
+/**
+ * Structural check for a models.dev catalog payload: a map of provider ids
+ * to entries that each carry a `models` map. Rejects chat-completion
+ * payloads, error envelopes, and other non-catalog JSON (e.g. from mocked
+ * `fetch` in tests) BEFORE they can overwrite the good on-disk cache.
+ */
+export function isValidCatalogPayload(data: unknown): data is Record<string, any> {
+  if (!data || typeof data !== "object" || Array.isArray(data)) return false;
+  const entries = Object.entries(data as Record<string, unknown>);
+  if (entries.length < 3) return false;
+  let providersWithModels = 0;
+  for (const [, value] of entries) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+    const models = (value as Record<string, unknown>).models;
+    if (!models || typeof models !== "object" || Array.isArray(models)) return false;
+    if (Object.keys(models).length > 0) providersWithModels++;
+  }
+  // Guard against degenerate-but-shaped payloads (e.g. `{a:{models:{}}}`).
+  return providersWithModels >= 3;
+}
+
 /**
  * Refreshes the model catalog by downloading from models.dev
- * directly into src/data/models-cache.json with a 12-hour TTL.
+ * directly into src/data/models.dev.json with a 12-hour TTL.
  */
 export async function refreshModelCatalog(options: RefreshCatalogOptions = {}): Promise<CatalogStatus> {
   const effectiveTtl = options.ttlMs ?? globalCatalogTtlMs;
@@ -211,6 +239,21 @@ export async function refreshModelCatalog(options: RefreshCatalogOptions = {}):
     }
 
     freshData = (await res.json()) as Record<string, any>;
+
+    // Never let a non-catalog payload (mocked fetch, proxy error page,
+    // chat-completion stub) overwrite the good on-disk cache.
+    if (!isValidCatalogPayload(freshData)) {
+      clearTimeout(timer);
+      const existing = readJsonFileSync(cachePath);
+      if (existing && existing.data) {
+        activeCatalog = existing.data;
+        activeFetchedAt = existing.fetchedAt;
+        activeTtlMs = existing.ttlMs || effectiveTtl;
+        activeFromCache = true;
+        notifyUpdateListeners();
+      }
+      return getCatalogStatus();
+    }
   } catch (err: any) {
     clearTimeout(timer);
     // If download fails, retain disk cache if available
@@ -236,15 +279,23 @@ export async function refreshModelCatalog(options: RefreshCatalogOptions = {}):
     data: freshData,
   };
 
-  // Save to src/data/models-cache.json
-  writeJsonFileSync(cachePath, cachePayload);
-
-  // Update in-memory state
+  // Update in-memory state FIRST so a read-only filesystem still serves the
+  // fresh catalog for this process; disk persistence below is best-effort.
   activeCatalog = freshData;
   activeFetchedAt = fetchedAt;
   activeTtlMs = effectiveTtl;
   activeFromCache = true;
 
+  // Save to src/data/models.dev.json (or the AGENT_CACHE_DIR override)
+  try {
+    writeJsonFileSync(cachePath, cachePayload);
+  } catch (err) {
+    activeFromCache = false;
+    console.warn(
+      `[Agent Accelerator] Could not write model catalog cache to ${cachePath} (${err instanceof Error ? err.message : String(err)}). Continuing with the in-memory catalog.`
+    );
+  }
+
   notifyUpdateListeners();
   return getCatalogStatus();
 }