agent-accelerator 0.4.5 → 0.5.0

package/src/models/catalog-cache.ts

@@ -2,6 +2,8 @@ import * as path from "node:path";
 import * as fs from "node:fs";
 import { createHash } from "node:crypto";
 import { getEnv } from "../utils/env.ts";
+import { telemetryBus } from "../telemetry.ts";
+import { onHomeChange, resolveHome } from "../utils/home.ts";
 
 /** Default TTL: 12 Hours (in milliseconds). */
 export const DEFAULT_CATALOG_TTL_MS = 12 * 60 * 60 * 1000;
@@ -75,14 +77,14 @@ function notifyUpdateListeners(): void {
 }
 
 /**
- * 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).
+ * Catalog cache directory: `<home>/catalog` (the single Agent Accelerator home,
+ * see `resolveHome`), or `AGENT_CACHE_DIR` when set (read-only or serverless
+ * filesystems).
  */
 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");
+  return path.join(resolveHome(), "catalog");
 }
 
 /** Cache file path: `<cacheDir>/models.dev.json`, honoring AGENT_CACHE_DIR (Q-16a/Q-34). */
@@ -121,13 +123,22 @@ export function verifyCatalogSha256(text: string): boolean {
   return hex === pin;
 }
 
+/** Wall-clock of the last failed network refresh (0 = none); drives the retry backoff. */
+let lastRefreshFailureAt = 0;
+/** After a failed refresh, `ensureModelCatalogFresh` stays quiet this long (10 min). */
+export const REFRESH_FAILURE_BACKOFF_MS = 10 * 60 * 1000;
+/** Network timeout for a background refresh when a usable catalog is already loaded. */
+const BACKGROUND_REFRESH_TIMEOUT_MS = 8_000;
+
+let inFlightRefresh: Promise<CatalogStatus> | null = null;
+
 // In-memory catalog state
 let activeCatalog: Record<string, any> = {};
 let activeFetchedAt: number | undefined = undefined;
 let activeTtlMs: number = globalCatalogTtlMs;
 let activeFromCache = false;
 
-// Synchronous bootstrap: load from src/data/models.dev.json if present
+// Synchronous bootstrap: load <home>/catalog/models.dev.json if present
 function initializeCatalogSync(): void {
   const cachePath = getCacheFilePath();
   const cached = readJsonFileSync(cachePath);
@@ -155,6 +166,11 @@ function initializeCatalogSync(): void {
 }
 
 initializeCatalogSync();
+// `setHome()` moves the cache folder: reload from the new place.
+onHomeChange(() => {
+  initializeCatalogSync();
+  notifyUpdateListeners();
+});
 
 /** Returns the active in-memory catalog data. */
 export function getActiveCatalog(): Record<string, any> {
@@ -216,7 +232,7 @@ export function isValidCatalogPayload(data: unknown): data is Record<string, any
 
 /**
  * Refreshes the model catalog by downloading from models.dev
- * directly into src/data/models.dev.json with a 12-hour TTL.
+ * into `<home>/catalog/models.dev.json` with a 12-hour TTL.
  */
 export async function refreshModelCatalog(options: RefreshCatalogOptions = {}): Promise<CatalogStatus> {
   const effectiveTtl = options.ttlMs ?? globalCatalogTtlMs;
@@ -247,6 +263,7 @@ export async function refreshModelCatalog(options: RefreshCatalogOptions = {}):
   let freshData: Record<string, any>;
 
   const fallbackToDiskCache = (): void => {
+    lastRefreshFailureAt = Date.now();
     const existing = readJsonFileSync(cachePath);
     if (existing && existing.data) {
       activeCatalog = existing.data;
@@ -309,6 +326,7 @@ export async function refreshModelCatalog(options: RefreshCatalogOptions = {}):
     clearTimeout(timer);
   }
 
+  lastRefreshFailureAt = 0;
   const fetchedAt = Date.now();
   const cachePayload: CatalogCacheFile = {
     fetchedAt,
@@ -326,42 +344,64 @@ export async function refreshModelCatalog(options: RefreshCatalogOptions = {}):
   activeTtlMs = effectiveTtl;
   activeFromCache = false;
 
-  // Save to src/data/models.dev.json (or the AGENT_CACHE_DIR override)
+  // Save to <home>/catalog/models.dev.json (or the AGENT_CACHE_DIR override)
   try {
     writeJsonFileSync(cachePath, cachePayload);
   } catch (err) {
     activeFromCache = false;
-    try {
-      (globalThis as any).__agentAccelTelemetry?.emitWarning?.({
-        code: "catalog_cache_write_failed",
-        message: `[Agent Accelerator] Could not write model catalog cache (${err instanceof Error ? err.message : String(err)}). Continuing with the in-memory catalog.`,
-      });
-    } catch {}
+    telemetryBus.emitWarning(
+      "catalog_cache_write_failed",
+      `[Agent Accelerator] Could not write model catalog cache (${err instanceof Error ? err.message : String(err)}). Continuing with the in-memory catalog.`,
+      { path: cachePath }
+    );
   }
 
   notifyUpdateListeners();
   return getCatalogStatus();
 }
 
-let inFlightRefresh: Promise<CatalogStatus> | null = null;
+
+/** True when `AGENT_CATALOG_REFRESH` is `off`/`0`/`false`: never touch the network automatically. */
+function automaticRefreshDisabled(): boolean {
+  const v = getEnv("AGENT_CATALOG_REFRESH")?.trim().toLowerCase();
+  return v === "off" || v === "0" || v === "false";
+}
 
 /**
- * Ensures that the model catalog is loaded and fresh.
- * Called automatically before Agent runs. If the cache is expired, triggers a refresh.
+ * Ensures that the model catalog is loaded and fresh. Called automatically
+ * before Agent runs.
+ *
+ * - Fresh and loaded: returns immediately.
+ * - Expired but loaded (stale-while-revalidate): returns the stale catalog at
+ *   once and refreshes in the background with a short timeout, so a run is
+ *   never delayed by models.dev being slow or unreachable.
+ * - Nothing loaded yet (cold start): waits for the download.
+ * - A failed refresh is not retried automatically for 10 minutes.
+ * - `AGENT_CATALOG_REFRESH=off` disables automatic refreshes entirely
+ *   (air-gapped hosts, hermetic tests); `force` and `refreshModelCatalog`
+ *   still work.
  */
 export async function ensureModelCatalogFresh(options: RefreshCatalogOptions = {}): Promise<CatalogStatus> {
   const current = getCatalogStatus();
-  if (!current.isExpired && current.loaded && !options.force) {
-    return current;
+  if (!options.force) {
+    if (!current.isExpired && current.loaded) return current;
+    if (automaticRefreshDisabled()) return current;
+    if (Date.now() - lastRefreshFailureAt < REFRESH_FAILURE_BACKOFF_MS) return current;
   }
 
-  if (inFlightRefresh) {
+  const start = (): Promise<CatalogStatus> => {
+    if (!inFlightRefresh) {
+      const timeoutMs = options.timeoutMs ?? (current.loaded ? BACKGROUND_REFRESH_TIMEOUT_MS : undefined);
+      inFlightRefresh = refreshModelCatalog({ ...options, ...(timeoutMs !== undefined ? { timeoutMs } : {}) }).finally(() => {
+        inFlightRefresh = null;
+      });
+    }
     return inFlightRefresh;
-  }
-
-  inFlightRefresh = refreshModelCatalog(options).finally(() => {
-    inFlightRefresh = null;
-  });
+  };
 
-  return inFlightRefresh;
+  if (current.loaded && !options.force) {
+    start().catch(() => {}); // background revalidation; failures are non-fatal
+    return current;
+  }
+  return start();
 }

package/src/models/catalog.ts

@@ -52,6 +52,19 @@ function applyModalityOverrides(provider: string, modelId: string, base: ModelMo
   };
 }
 
+/**
+ * Whether a lookup may fall back to the GLOBAL model index (any provider's
+ * entry with that id). Allowed for first-class providers and for explicit
+ * bare-id searches (`getModelFromCatalog(id, id)`). Denied for custom
+ * prefixes (`ollama/gpt-oss-20b`): a self-hosted model must not inherit the
+ * price, modalities or reasoning flags of an unrelated hosted model that
+ * happens to share its id: unknown stays unknown.
+ */
+function allowsGlobalFallback(providerInput: string, modelIdInput: string): boolean {
+  const p = providerInput.toLowerCase();
+  return p in PROVIDER_ALIASES || p === "gemini" || p === modelIdInput.trim().toLowerCase();
+}
+
 function normalizeModelIdForLookup(modelId: string): string {
   if (modelId.includes("/")) {
     const parts = modelId.split("/");
@@ -280,7 +293,11 @@ export function getModelFromCatalog(providerInput: string, modelIdInput: string)
     }
   }
 
-  // Global O(1) fallback via indexed catalog
+  // Global O(1) fallback via indexed catalog (first-class providers / bare ids only)
+  if (!allowsGlobalFallback(providerInput, modelId)) {
+    setLookupCache(cacheKey, undefined);
+    return undefined;
+  }
   const index = getGlobalIndex();
   const lowerModelId = modelId.toLowerCase();
   const strippedLower = normalizeModelIdForLookup(modelId).toLowerCase();
@@ -310,7 +327,9 @@ export interface ModelThinkingInfo {
  * @example `const info = getModelThinkingInfo("google", "gemini-3.5-flash-lite");`
  */
 export function getModelThinkingInfo(provider: string, modelId: string): ModelThinkingInfo {
-  const spec = getModelFromCatalog(provider, modelId) || getModelFromCatalog(modelId, modelId);
+  const spec =
+    getModelFromCatalog(provider, modelId) ||
+    (allowsGlobalFallback(provider, modelId) ? getModelFromCatalog(modelId, modelId) : undefined);
   if (!spec) {
     return {
       supportsThinking: true,