agent-accelerator 0.4.0 → 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("/");
@@ -138,6 +151,7 @@ function mapCapabilities(raw: any, cost: ModelCost, reasoning: boolean, toolCall
     supportsExplicitCaching: cost.cache_read !== undefined,
     supportsParallelToolCalls: toolCall,
     supportsStreaming: true,
+    supportsStructuredOutput: raw.structured_output === undefined ? true : !!raw.structured_output,
     supportsReasoningToggle: Array.isArray(raw.reasoning_options) && raw.reasoning_options.some((o: any) => o.type === "toggle"),
     supportsReasoningEffort: Array.isArray(raw.reasoning_options) && raw.reasoning_options.some((o: any) => o.type === "effort"),
     modalities: [...(modalities.input || []), ...(modalities.output || [])].filter((v: any, i: any, a: any) => a.indexOf(v) === i),
@@ -279,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();
@@ -309,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,
@@ -588,6 +608,30 @@ export {
   type RefreshCatalogOptions,
 } from "./catalog-cache.ts";
 
+/**
+ * True when the model can enforce `response_format`/`text.format` natively.
+ * Unknown models (custom endpoints, dynamic routers) count as capable —
+ * the provider verdict stands, matching `assertModalitiesSupported`.
+ * Models with catalog `structured_output: false` return false so callers can
+ * emulate via prompt instruction + client validation instead of 400ing.
+ *
+ * @example `modelSupportsStructuredOutput("openrouter", "inclusionai/ling-3.0-flash-sante:free")`
+ */
+export function modelSupportsStructuredOutput(provider: string, modelId: string): boolean {
+  try {
+    const spec = getModelFromCatalog(provider, modelId);
+    if (!spec) return true;
+    if (typeof spec.capabilities?.supportsStructuredOutput === "boolean") {
+      return spec.capabilities.supportsStructuredOutput;
+    }
+    const raw = (spec as { raw?: { structured_output?: unknown } }).raw;
+    if (raw && typeof raw.structured_output === "boolean") return raw.structured_output;
+    return true;
+  } catch {
+    return true;
+  }
+}
+
 /**
  * Permissive placeholder so custom endpoints never fail preflight:
  * allows every ThinkingLevel (none -> max + dynamic).
@@ -622,6 +666,7 @@ export function createGenericModelSpec(provider: string, modelId: string): Model
       supportsLongCacheRetention: false,
       supportsParallelToolCalls: true,
       supportsStreaming: true,
+      supportsStructuredOutput: true,
       modalities: ["text"],
     },
     pricing: {},