@fudrouter/fsrouter 0.6.64 → 0.6.65

package/open-sse/services/comboConfig.js

@@ -0,0 +1,153 @@
+import { MAX_TIMER_TIMEOUT_MS } from '../../dist/shared/utils/runtimeTimeouts.ts.js';
+const PRE_SCREEN_CONCURRENCY = 5;
+const DEFAULT_COMBO_TARGET_TIMEOUT_MS = 12e4;
+const DEFAULT_COMBO_QUEUE_DEPTH = 20;
+const MAX_COMBO_QUEUE_DEPTH = 100;
+const DEFAULT_COMBO_CONFIG = {
+  strategy: "priority",
+  maxRetries: 1,
+  retryDelayMs: 2e3,
+  fallbackDelayMs: 0,
+  concurrencyPerModel: 3,
+  // max simultaneous requests per model (round-robin)
+  queueTimeoutMs: 3e4,
+  // max wait time in semaphore queue (round-robin)
+  queueDepth: DEFAULT_COMBO_QUEUE_DEPTH,
+  // pre-cascade semaphore queue depth (round-robin, #3872)
+  handoffThreshold: 0.85,
+  handoffModel: "",
+  handoffProviders: ["codex"],
+  maxMessagesForSummary: 30,
+  maxComboDepth: 3,
+  nestedComboMode: "flatten",
+  trackMetrics: true,
+  reasoningTokenBufferEnabled: true,
+  manifestRouting: false,
+  // Complexity-aware auto routing (2026): when on, the auto router scores
+  // candidates by how well their tier matches the request's classified
+  // difficulty (feeds tierAffinity/specificityMatch). Opt-in — off by default.
+  complexityAwareRouting: false,
+  resetAwareSessionWeight: 0.35,
+  resetAwareWeeklyWeight: 0.65,
+  resetAwareTieBandPercent: 5,
+  resetAwareExhaustionGuardPercent: 10,
+  failoverBeforeRetry: true,
+  // Feature 4985: configurable response-body validation predicate (per-combo). When set,
+  // a 200 OK whose body fails the predicate fails over to the next target.
+  responseValidation: void 0,
+  maxSetRetries: 0,
+  setRetryDelayMs: 2e3,
+  // Zero-latency optimizations are opt-in because some modes can race targets or
+  // mutate fallback request bodies for lower tail latency.
+  zeroLatencyOptimizationsEnabled: false,
+  // Hedging (Speculative Execution) defaults
+  hedging: false,
+  hedgeDelayMs: 500,
+  // Mid-Stream Fallback Compression defaults
+  fallbackCompressionMode: "lite",
+  fallbackCompressionThreshold: 1e3,
+  // Predictive TTFT Circuit Breaker defaults
+  predictiveTtftMs: 0,
+  // Pipeline defaults
+  pipeline_enabled: false,
+  task_detection: "pattern",
+  max_reflection_loops: 1,
+  skip_pipeline_for_tokens_under: 50,
+  pipeline_fallback: "single-provider",
+  resetAwareQuotaCacheTtlMs: 0,
+  resetAwareQuotaCacheMaxStaleMs: 0,
+  shadowRouting: {
+    enabled: false,
+    targets: [],
+    sampleRate: 1,
+    maxTargets: 2,
+    timeoutMs: 3e4
+  },
+  evalRouting: {
+    enabled: false,
+    suiteIds: [],
+    maxAgeHours: 720,
+    minCases: 1,
+    qualityWeight: 0.85,
+    latencyWeight: 0.15,
+    cacheTtlMs: 6e4
+  }
+};
+const LEGACY_COMBO_RESILIENCE_KEYS = /* @__PURE__ */ new Set([
+  "timeoutMs",
+  "healthCheckEnabled",
+  "healthCheckTimeoutMs"
+]);
+function isRecord(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function normalizePositiveTimeoutMs(value) {
+  const numericValue = Number(value);
+  if (!Number.isFinite(numericValue) || numericValue <= 0) return 0;
+  return Math.min(Math.floor(numericValue), MAX_TIMER_TIMEOUT_MS);
+}
+function resolveComboTargetTimeoutMs(config, upstreamTimeoutMs, defaultTimeoutMs = 0) {
+  const ceilingTimeoutMs = normalizePositiveTimeoutMs(upstreamTimeoutMs);
+  const configuredTimeoutMs = isRecord(config) ? normalizePositiveTimeoutMs(config.targetTimeoutMs) : 0;
+  if (configuredTimeoutMs > 0) {
+    if (ceilingTimeoutMs <= 0) return configuredTimeoutMs;
+    return Math.min(configuredTimeoutMs, ceilingTimeoutMs);
+  }
+  const fallbackDefaultMs = normalizePositiveTimeoutMs(defaultTimeoutMs);
+  if (ceilingTimeoutMs <= 0) return ceilingTimeoutMs;
+  if (fallbackDefaultMs <= 0) return ceilingTimeoutMs;
+  return Math.min(fallbackDefaultMs, ceilingTimeoutMs);
+}
+function resolveComboQueueDepth(config) {
+  const raw = isRecord(config) ? Number(config.queueDepth) : Number.NaN;
+  if (!Number.isFinite(raw) || raw < 0) return DEFAULT_COMBO_QUEUE_DEPTH;
+  return Math.min(Math.floor(raw), MAX_COMBO_QUEUE_DEPTH);
+}
+function resolveComboConfig(combo, settings, provider) {
+  const global = settings?.comboDefaults || {};
+  const providerOverride = provider ? settings?.providerOverrides?.[provider] || {} : {};
+  const comboConfig = combo?.config || {};
+  const clean = (obj) => Object.fromEntries(
+    Object.entries(obj).filter(
+      ([key, value]) => value !== void 0 && value !== null && !LEGACY_COMBO_RESILIENCE_KEYS.has(key)
+    )
+  );
+  const merged = {
+    ...DEFAULT_COMBO_CONFIG,
+    ...clean(global),
+    ...clean(providerOverride),
+    ...clean(comboConfig)
+  };
+  return {
+    ...merged,
+    shadowRouting: {
+      ...DEFAULT_COMBO_CONFIG.shadowRouting,
+      ...isRecord(global.shadowRouting) ? clean(global.shadowRouting) : {},
+      ...isRecord(providerOverride.shadowRouting) ? clean(providerOverride.shadowRouting) : {},
+      ...isRecord(comboConfig.shadowRouting) ? clean(comboConfig.shadowRouting) : {}
+    },
+    evalRouting: {
+      ...DEFAULT_COMBO_CONFIG.evalRouting,
+      ...isRecord(global.evalRouting) ? clean(global.evalRouting) : {},
+      ...isRecord(providerOverride.evalRouting) ? clean(providerOverride.evalRouting) : {},
+      ...isRecord(comboConfig.evalRouting) ? clean(comboConfig.evalRouting) : {}
+    }
+  };
+}
+function getDefaultComboConfig() {
+  return { ...DEFAULT_COMBO_CONFIG };
+}
+function resolveComboSetupConfig(combo, settings) {
+  return settings ? resolveComboConfig(combo, settings) : { ...getDefaultComboConfig(), ...combo?.config || {} };
+}
+export {
+  DEFAULT_COMBO_QUEUE_DEPTH,
+  DEFAULT_COMBO_TARGET_TIMEOUT_MS,
+  MAX_COMBO_QUEUE_DEPTH,
+  PRE_SCREEN_CONCURRENCY,
+  getDefaultComboConfig,
+  resolveComboConfig,
+  resolveComboQueueDepth,
+  resolveComboSetupConfig,
+  resolveComboTargetTimeoutMs
+};

package/open-sse/services/comboManifestMetrics.js

@@ -0,0 +1,10 @@
+import { getLogger } from "log-wrapper";
+function recordComboIntentWithSpecificity(comboName, specificityScore, specificityLevel, strategyModifier) {
+  getLogger().info(
+    { comboName, specificityScore, specificityLevel, strategyModifier },
+    "combo manifest routing applied"
+  );
+}
+export {
+  recordComboIntentWithSpecificity
+};

package/open-sse/services/comboMetrics.js

@@ -0,0 +1,278 @@
+import { recordProviderUsage } from "./autoCombo/providerDiversity";
+function toNonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+function inferProvider(modelStr) {
+  const model = toNonEmptyString(modelStr);
+  if (!model) return null;
+  const [provider] = model.split("/");
+  return toNonEmptyString(provider);
+}
+function createModelMetrics() {
+  return {
+    requests: 0,
+    successes: 0,
+    failures: 0,
+    totalLatencyMs: 0,
+    lastStatus: null,
+    lastUsedAt: null
+  };
+}
+function createComboEntry(strategy) {
+  return {
+    totalRequests: 0,
+    totalSuccesses: 0,
+    totalFailures: 0,
+    totalFallbacks: 0,
+    totalLatencyMs: 0,
+    strategy,
+    lastUsedAt: null,
+    intentCounts: {},
+    byModel: {},
+    byTarget: {}
+  };
+}
+function createShadowEntry() {
+  return {
+    totalRequests: 0,
+    totalSuccesses: 0,
+    totalFailures: 0,
+    totalLatencyMs: 0,
+    lastUsedAt: null,
+    byModel: {},
+    byTarget: {}
+  };
+}
+function applyMetricOutcome(metric, success, latencyMs, usedAt) {
+  metric.requests++;
+  metric.totalLatencyMs += latencyMs;
+  metric.lastUsedAt = usedAt;
+  if (success) {
+    metric.successes++;
+    metric.lastStatus = "ok";
+    return;
+  }
+  metric.failures++;
+  metric.lastStatus = "error";
+}
+function buildTargetMetric(modelStr, target) {
+  const executionKey = toNonEmptyString(target.executionKey) || toNonEmptyString(modelStr);
+  const model = toNonEmptyString(modelStr);
+  if (!executionKey || !model) return null;
+  return {
+    executionKey,
+    stepId: toNonEmptyString(target.stepId),
+    model,
+    provider: toNonEmptyString(target.provider) || inferProvider(model),
+    providerId: toNonEmptyString(target.providerId),
+    connectionId: target.connectionId === null ? null : toNonEmptyString(target.connectionId) ?? null,
+    label: target.label === null ? null : toNonEmptyString(target.label) ?? null,
+    ...createModelMetrics()
+  };
+}
+function toMetricView(metric) {
+  return {
+    ...metric,
+    avgLatencyMs: metric.requests > 0 ? Math.round(metric.totalLatencyMs / metric.requests) : 0,
+    successRate: metric.requests > 0 ? Math.round(metric.successes / metric.requests * 100) : 0
+  };
+}
+const metrics = /* @__PURE__ */ new Map();
+const shadowMetrics = /* @__PURE__ */ new Map();
+const MAX_METRICS_ENTRIES = 500;
+const METRICS_TTL_MS = 60 * 60 * 1e3;
+function evictOldestMetric(targetMap, options = {}) {
+  let oldest = null;
+  let oldestTime = Infinity;
+  for (const [name, entry] of targetMap) {
+    const t = entry.lastUsedAt ? new Date(entry.lastUsedAt).getTime() : Date.now();
+    if (t < oldestTime) {
+      oldestTime = t;
+      oldest = name;
+    }
+  }
+  if (oldest) {
+    targetMap.delete(oldest);
+    if (options.deletePairedShadow) {
+      shadowMetrics.delete(oldest);
+    }
+  }
+}
+const _metricsCleanupTimer = setInterval(() => {
+  const now = Date.now();
+  for (const [name, entry] of metrics) {
+    const lastUsed = entry.lastUsedAt ? new Date(entry.lastUsedAt).getTime() : now;
+    if (now - lastUsed > METRICS_TTL_MS) {
+      metrics.delete(name);
+      shadowMetrics.delete(name);
+    }
+  }
+  for (const [name, entry] of shadowMetrics) {
+    const lastUsed = entry.lastUsedAt ? new Date(entry.lastUsedAt).getTime() : now;
+    if (now - lastUsed > METRICS_TTL_MS) {
+      metrics.delete(name);
+      shadowMetrics.delete(name);
+    }
+  }
+}, 5 * 60 * 1e3);
+_metricsCleanupTimer.unref?.();
+function recordComboRequest(comboName, modelStr, {
+  success,
+  latencyMs,
+  fallbackCount = 0,
+  strategy = "priority",
+  target
+}) {
+  if (!metrics.has(comboName) && metrics.size >= MAX_METRICS_ENTRIES) {
+    evictOldestMetric(metrics, { deletePairedShadow: true });
+  }
+  if (!metrics.has(comboName)) {
+    metrics.set(comboName, createComboEntry(strategy));
+  }
+  const combo = metrics.get(comboName);
+  if (!combo) return;
+  const usedAt = (/* @__PURE__ */ new Date()).toISOString();
+  combo.totalRequests++;
+  combo.totalLatencyMs += latencyMs;
+  combo.totalFallbacks += fallbackCount;
+  combo.lastUsedAt = usedAt;
+  combo.strategy = strategy;
+  if (success) {
+    combo.totalSuccesses++;
+    const usedProvider = toNonEmptyString(target?.provider);
+    if (usedProvider) recordProviderUsage(usedProvider);
+  } else {
+    combo.totalFailures++;
+  }
+  if (!modelStr) return;
+  if (!combo.byModel[modelStr]) {
+    combo.byModel[modelStr] = createModelMetrics();
+  }
+  applyMetricOutcome(combo.byModel[modelStr], success, latencyMs, usedAt);
+  const targetMetric = buildTargetMetric(modelStr, target || {});
+  if (!targetMetric) return;
+  if (!combo.byTarget[targetMetric.executionKey]) {
+    combo.byTarget[targetMetric.executionKey] = targetMetric;
+  }
+  const existingTargetMetric = combo.byTarget[targetMetric.executionKey];
+  existingTargetMetric.stepId = targetMetric.stepId || existingTargetMetric.stepId;
+  existingTargetMetric.provider = targetMetric.provider || existingTargetMetric.provider;
+  existingTargetMetric.providerId = targetMetric.providerId || existingTargetMetric.providerId;
+  existingTargetMetric.connectionId = target?.connectionId === null ? null : targetMetric.connectionId ?? existingTargetMetric.connectionId;
+  existingTargetMetric.label = target?.label === null ? null : targetMetric.label ?? existingTargetMetric.label;
+  applyMetricOutcome(existingTargetMetric, success, latencyMs, usedAt);
+}
+function recordComboShadowRequest(comboName, modelStr, {
+  success,
+  latencyMs,
+  target
+}) {
+  if (!shadowMetrics.has(comboName) && shadowMetrics.size >= MAX_METRICS_ENTRIES) {
+    evictOldestMetric(shadowMetrics);
+  }
+  if (!shadowMetrics.has(comboName)) {
+    shadowMetrics.set(comboName, createShadowEntry());
+  }
+  const combo = shadowMetrics.get(comboName);
+  if (!combo) return;
+  const usedAt = (/* @__PURE__ */ new Date()).toISOString();
+  combo.totalRequests++;
+  combo.totalLatencyMs += latencyMs;
+  combo.lastUsedAt = usedAt;
+  if (success) combo.totalSuccesses++;
+  else combo.totalFailures++;
+  if (!modelStr) return;
+  if (!combo.byModel[modelStr]) {
+    combo.byModel[modelStr] = createModelMetrics();
+  }
+  applyMetricOutcome(combo.byModel[modelStr], success, latencyMs, usedAt);
+  const targetMetric = buildTargetMetric(modelStr, target || {});
+  if (!targetMetric) return;
+  if (!combo.byTarget[targetMetric.executionKey]) {
+    combo.byTarget[targetMetric.executionKey] = targetMetric;
+  }
+  const existingTargetMetric = combo.byTarget[targetMetric.executionKey];
+  existingTargetMetric.stepId = targetMetric.stepId || existingTargetMetric.stepId;
+  existingTargetMetric.provider = targetMetric.provider || existingTargetMetric.provider;
+  existingTargetMetric.providerId = targetMetric.providerId || existingTargetMetric.providerId;
+  existingTargetMetric.connectionId = target?.connectionId === null ? null : targetMetric.connectionId ?? existingTargetMetric.connectionId;
+  existingTargetMetric.label = target?.label === null ? null : targetMetric.label ?? existingTargetMetric.label;
+  applyMetricOutcome(existingTargetMetric, success, latencyMs, usedAt);
+}
+function getComboShadowMetrics(comboName) {
+  const combo = shadowMetrics.get(comboName) || createShadowEntry();
+  return {
+    ...combo,
+    avgLatencyMs: combo.totalRequests > 0 ? Math.round(combo.totalLatencyMs / combo.totalRequests) : 0,
+    successRate: combo.totalRequests > 0 ? Math.round(combo.totalSuccesses / combo.totalRequests * 100) : 0,
+    byModel: Object.fromEntries(
+      Object.entries(combo.byModel).map(([model, metric]) => [model, toMetricView(metric)])
+    ),
+    byTarget: Object.fromEntries(
+      Object.entries(combo.byTarget).map(([executionKey, metric]) => [
+        executionKey,
+        toMetricView(metric)
+      ])
+    )
+  };
+}
+function getComboMetrics(comboName) {
+  const productionCombo = metrics.get(comboName);
+  const combo = productionCombo || (shadowMetrics.has(comboName) ? createComboEntry("priority") : null);
+  if (!combo) return null;
+  return {
+    ...combo,
+    productionTraffic: !!productionCombo && productionCombo.totalRequests > 0,
+    avgLatencyMs: combo.totalRequests > 0 ? Math.round(combo.totalLatencyMs / combo.totalRequests) : 0,
+    successRate: combo.totalRequests > 0 ? Math.round(combo.totalSuccesses / combo.totalRequests * 100) : 0,
+    fallbackRate: combo.totalRequests > 0 ? Math.round(combo.totalFallbacks / combo.totalRequests * 100) : 0,
+    intentCounts: { ...combo.intentCounts },
+    byModel: Object.fromEntries(
+      Object.entries(combo.byModel).map(([model, metric]) => [model, toMetricView(metric)])
+    ),
+    byTarget: Object.fromEntries(
+      Object.entries(combo.byTarget).map(([executionKey, metric]) => [
+        executionKey,
+        toMetricView(metric)
+      ])
+    ),
+    shadow: getComboShadowMetrics(comboName)
+  };
+}
+function getAllComboMetrics() {
+  const result = {};
+  for (const name of /* @__PURE__ */ new Set([...metrics.keys(), ...shadowMetrics.keys()])) {
+    result[name] = getComboMetrics(name);
+  }
+  return result;
+}
+function recordComboIntent(comboName, intent) {
+  if (!metrics.has(comboName) && metrics.size >= MAX_METRICS_ENTRIES) {
+    evictOldestMetric(metrics, { deletePairedShadow: true });
+  }
+  if (!metrics.has(comboName)) {
+    metrics.set(comboName, createComboEntry("priority"));
+  }
+  const combo = metrics.get(comboName);
+  if (!combo) return;
+  const key = String(intent || "unknown");
+  combo.intentCounts[key] = (combo.intentCounts[key] || 0) + 1;
+}
+function resetComboMetrics(comboName) {
+  metrics.delete(comboName);
+  shadowMetrics.delete(comboName);
+}
+function resetAllComboMetrics() {
+  clearInterval(_metricsCleanupTimer);
+  metrics.clear();
+  shadowMetrics.clear();
+}
+export {
+  getAllComboMetrics,
+  getComboMetrics,
+  recordComboIntent,
+  recordComboRequest,
+  recordComboShadowRequest,
+  resetAllComboMetrics,
+  resetComboMetrics
+};

package/open-sse/services/compact.js

@@ -0,0 +1,71 @@
+/**
+ * Shared combo (model combo) handling with fallback support
+ */
+
+/**
+ * Get combo models from combos data
+ * @param {string} modelStr - Model string to check
+ * @param {Array|Object} combosData - Array of combos or object with combos
+ * @returns {string[]|null} Array of models or null if not a combo
+ */
+export function getComboModelsFromData(modelStr, combosData) {
+  // Don't check if it's in provider/model format
+  if (modelStr.includes("/")) return null;
+  
+  // Handle both array and object formats
+  const combos = Array.isArray(combosData) ? combosData : (combosData?.combos || []);
+  
+  const combo = combos.find(c => c.name === modelStr);
+  if (combo && combo.models && combo.models.length > 0) {
+    return combo.models;
+  }
+  return null;
+}
+
+/**
+ * Handle combo chat with fallback
+ * @param {Object} options
+ * @param {Object} options.body - Request body
+ * @param {string[]} options.models - Array of model strings to try
+ * @param {Function} options.handleSingleModel - Function to handle single model: (body, modelStr) => Promise<Response>
+ * @param {Object} options.log - Logger object
+ * @returns {Promise<Response>}
+ */
+export async function handleComboChat({ body, models, handleSingleModel, log }) {
+  let lastError = null;
+
+  for (let i = 0; i < models.length; i++) {
+    const modelStr = models[i];
+    log.info("COMBO", `Trying model ${i + 1}/${models.length}: ${modelStr}`);
+
+    let result;
+    try {
+      result = await handleSingleModel(body, modelStr);
+    } catch (e) {
+      lastError = `${modelStr}: ${e.message}`;
+      log.warn("COMBO", `Model threw exception, trying next`, { model: modelStr, error: e.message });
+      continue;
+    }
+
+    // Success or client error - return response
+    if (result.ok || result.status < 500) {
+      return result;
+    }
+
+    // 5xx error - try next model
+    lastError = `${modelStr}: ${result.statusText || result.status}`;
+    log.warn("COMBO", `Model failed, trying next`, { model: modelStr, status: result.status });
+  }
+
+  log.warn("COMBO", "All models failed");
+  
+  // Return 503 with last error
+  return new Response(
+    JSON.stringify({ error: lastError || "All combo models unavailable" }),
+    { 
+      status: 503, 
+      headers: { "Content-Type": "application/json" }
+    }
+  );
+}
+

package/open-sse/services/copilotModels.js

@@ -0,0 +1,155 @@
+/**
+ * GitHub Copilot model catalog fetcher.
+ *
+ * Calls Copilot's `GET /models` endpoint to get the live catalog for an
+ * authenticated account, so `/v1/models` reflects what the account can
+ * actually use (e.g. newly shipped `claude-opus-4.8`, `gpt-5.5`) instead of
+ * the hand-maintained static registry, which inevitably lags behind.
+ *
+ * Returns chat-capable models the account's policy allows. Embeddings and
+ * disabled models are filtered out.
+ */
+
+import { proxyAwareFetch } from "../utils/proxyFetch.js";
+import { GITHUB_COPILOT } from "../config/appConstants.js";
+import { refreshCopilotToken } from "./tokenRefresh.js";
+
+const MODELS_URL = "https://api.githubcopilot.com/models";
+const FETCH_TIMEOUT_MS = 10_000;
+const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes per credential
+
+/** @type {Map<string, { expiresAt: number, models: any[] }>} */
+const catalogCache = new Map();
+
+function cacheKey(credentials) {
+  return credentials?.providerSpecificData?.copilotToken
+    || credentials?.accessToken
+    || "copilot-anonymous";
+}
+
+function buildHeaders(token) {
+  return {
+    "Authorization": `Bearer ${token}`,
+    "Content-Type": "application/json",
+    "Copilot-Integration-Id": "vscode-chat",
+    "editor-version": `vscode/${GITHUB_COPILOT.VSCODE_VERSION}`,
+    "editor-plugin-version": `copilot-chat/${GITHUB_COPILOT.COPILOT_CHAT_VERSION}`,
+    "user-agent": GITHUB_COPILOT.USER_AGENT,
+    "x-github-api-version": GITHUB_COPILOT.API_VERSION,
+  };
+}
+
+async function fetchCatalogRaw(token, signal) {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+  try {
+    const response = await proxyAwareFetch(MODELS_URL, {
+      method: "GET",
+      headers: buildHeaders(token),
+      cache: "no-store",
+      signal: signal || controller.signal,
+    });
+    if (!response.ok) {
+      const err = new Error(`Copilot /models returned ${response.status}`);
+      err.status = response.status;
+      throw err;
+    }
+    const data = await response.json();
+    return Array.isArray(data?.data) ? data.data : [];
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+
+// Keep only chat models the account is allowed to use. The static registry
+// surfaced disabled/embedding entries inconsistently; here we trust upstream.
+function expandCatalog(raw) {
+  const seen = new Set();
+  const models = [];
+  for (const m of raw) {
+    if (!m || typeof m !== "object") continue;
+    if (m.capabilities?.type !== "chat") continue;
+    if (m.policy && m.policy.state !== "enabled") continue;
+    const id = m.id;
+    if (!id || seen.has(id)) continue;
+    seen.add(id);
+    models.push({ id, name: m.name || id });
+  }
+  return models;
+}
+
+/**
+ * Resolve the live Copilot model catalog for a connection.
+ *
+ * @param {object} credentials Connection record (accessToken, refreshToken,
+ *   providerSpecificData {copilotToken, copilotTokenExpiresAt}).
+ * @param {object} [options]
+ * @param {boolean} [options.forceRefresh] Bypass the per-credential cache.
+ * @param {object}  [options.log] Logger.
+ * @param {function} [options.onCredentialsRefreshed] Persist a refreshed
+ *   Copilot token back to your store. Called with `{ copilotToken,
+ *   copilotTokenExpiresAt }` whenever a 401 triggers a refresh.
+ * @returns {Promise<{ models: object[] } | null>}
+ */
+export async function resolveCopilotModels(credentials, options = {}) {
+  const token = credentials?.providerSpecificData?.copilotToken || credentials?.accessToken;
+  if (!token) {
+    options.log?.debug?.("COPILOT_MODELS", "No copilotToken/accessToken; skipping live fetch");
+    return null;
+  }
+
+  const key = cacheKey(credentials);
+  const now = Date.now();
+  if (!options.forceRefresh) {
+    const cached = catalogCache.get(key);
+    if (cached && cached.expiresAt > now) {
+      return { models: cached.models };
+    }
+  }
+
+  let raw;
+  try {
+    raw = await fetchCatalogRaw(token, options.signal);
+  } catch (err) {
+    // A 401/403 means the Copilot token is stale — refresh from the GitHub
+    // access token and retry once.
+    if (err && (err.status === 401 || err.status === 403) && credentials.accessToken) {
+      options.log?.info?.("COPILOT_MODELS", `Got ${err.status}; refreshing Copilot token`);
+      const refreshed = await refreshCopilotToken(credentials.accessToken);
+      if (refreshed?.token) {
+        if (typeof options.onCredentialsRefreshed === "function") {
+          try {
+            await options.onCredentialsRefreshed({
+              copilotToken: refreshed.token,
+              copilotTokenExpiresAt: refreshed.expiresAt,
+            });
+          } catch (e) {
+            options.log?.warn?.("COPILOT_MODELS", `onCredentialsRefreshed failed: ${e?.message || e}`);
+          }
+        }
+        try {
+          raw = await fetchCatalogRaw(refreshed.token, options.signal);
+        } catch (err2) {
+          options.log?.warn?.("COPILOT_MODELS", `Retry after refresh failed: ${err2?.message || err2}`);
+          return null;
+        }
+      } else {
+        options.log?.warn?.("COPILOT_MODELS", "Token refresh did not return a token");
+        return null;
+      }
+    } else {
+      options.log?.warn?.("COPILOT_MODELS", `Live model fetch failed: ${err?.message || err}`);
+      return null;
+    }
+  }
+
+  const models = expandCatalog(raw);
+  if (!models.length) return null;
+
+  catalogCache.set(key, { expiresAt: now + CACHE_TTL_MS, models });
+  return { models };
+}
+
+export function clearCopilotModelCache() {
+  catalogCache.clear();
+}