@zergai/ztc 0.4.0-beta.1 → 0.4.1-dev.36919234045

package/dist/utils/model_cache.js

@@ -0,0 +1,143 @@
+/**
+ * Persistent model-catalog cache.
+ *
+ * Discovery needs the network, but the picker should not go empty when the
+ * network is down. This stores the last successful listing per provider so a
+ * restart — or an offline session — can still show what the provider offered
+ * last time.
+ *
+ * Deliberately boring: a single JSON file in the profile config dir, written
+ * atomically, capped at a fixed entry count. It is a cache, so every read path
+ * tolerates a missing, truncated, or corrupt file by returning nothing.
+ */
+import { mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { dirname, join } from 'node:path';
+import { profileConfigDir } from '../config/profiles.js';
+const CACHE_VERSION = 1;
+/** Bounded so a wide catalog (Modal, self-hosted) cannot grow the file without limit. */
+const MAX_MODELS_PER_PROVIDER = 512;
+const MAX_PROVIDERS = 64;
+function cacheFilePath() {
+    return join(profileConfigDir(), 'model-catalog-cache.json');
+}
+function sanitizeModels(models) {
+    const cleaned = [];
+    const seen = new Set();
+    for (const value of models) {
+        if (typeof value !== 'string')
+            continue;
+        const trimmed = value.trim();
+        // Model ids never legitimately carry control characters; drop anything that
+        // would corrupt a rendered row if a remote body were ever echoed here.
+        if (!trimmed || trimmed.length > 256 || /[\r\n\0]/.test(trimmed))
+            continue;
+        if (seen.has(trimmed))
+            continue;
+        seen.add(trimmed);
+        cleaned.push(trimmed);
+        if (cleaned.length >= MAX_MODELS_PER_PROVIDER)
+            break;
+    }
+    return cleaned;
+}
+/**
+ * The cached model list for a provider, or an empty array when absent.
+ * Empty means "nothing usable cached", never an error to surface.
+ */
+export async function readCachedModels(provider) {
+    const cache = await readModelCatalogCache();
+    return cache.providers[provider]?.models ?? [];
+}
+/** Epoch ms of the cached listing, or undefined when there is none. */
+export async function readCachedModelsFetchedAt(provider) {
+    const cache = await readModelCatalogCache();
+    return cache.providers[provider]?.fetchedAt;
+}
+/**
+ * Record a successful listing for a provider. A no-op for an empty list: a
+ * provider that legitimately returns zero models should not erase a good
+ * earlier cache, which is the case an offline restart needs most.
+ */
+export async function writeCachedModels(provider, models) {
+    const sanitized = sanitizeModels(models);
+    if (sanitized.length === 0)
+        return;
+    const file = cacheFilePath();
+    await updateCache(file, current => {
+        const providers = { ...current.providers, [provider]: { models: sanitized, fetchedAt: Date.now() } };
+        const names = Object.keys(providers);
+        for (const name of names.sort((a, b) => providers[a].fetchedAt - providers[b].fetchedAt)
+            .slice(0, Math.max(0, names.length - MAX_PROVIDERS)))
+            delete providers[name];
+        return { version: CACHE_VERSION, providers };
+    });
+}
+/** Drop one provider's cache without discarding concurrent catalog updates. */
+export async function clearCachedModels(provider) {
+    await updateCache(cacheFilePath(), current => {
+        if (!current.providers[provider])
+            return undefined;
+        delete current.providers[provider];
+        return current;
+    });
+}
+const pendingWrites = new Map();
+/** One in-process writer per profile owns read/modify/rename and its cleanup. */
+async function updateCache(file, update) {
+    const work = (pendingWrites.get(file) ?? Promise.resolve()).then(async () => {
+        const temp = `${file}.${process.pid}.${randomUUID()}.tmp`;
+        try {
+            const payload = update(await readModelCatalogCache(file));
+            if (payload === undefined)
+                return;
+            await mkdir(dirname(file), { recursive: true });
+            await writeFile(temp, JSON.stringify(payload, null, 2), { encoding: 'utf-8', mode: 0o600, flag: 'wx' });
+            await rename(temp, file);
+        }
+        catch {
+            // Catalog persistence is optional; discovery must survive unwritable profiles.
+        }
+        finally {
+            await unlink(temp).catch(() => { });
+        }
+    });
+    pendingWrites.set(file, work);
+    try {
+        await work;
+    }
+    finally {
+        if (pendingWrites.get(file) === work)
+            pendingWrites.delete(file);
+    }
+}
+async function readModelCatalogCache(file = cacheFilePath()) {
+    const empty = { version: CACHE_VERSION, providers: {} };
+    let raw;
+    try {
+        raw = await readFile(file, 'utf-8');
+    }
+    catch {
+        return empty;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object' || typeof parsed.providers !== 'object' || parsed.providers === null) {
+            return empty;
+        }
+        const providers = Object.create(null);
+        for (const [name, entry] of Object.entries(parsed.providers)) {
+            if (!entry || typeof entry !== 'object')
+                continue;
+            const models = sanitizeModels(Array.isArray(entry.models) ? entry.models : []);
+            if (models.length === 0)
+                continue;
+            providers[name] = { models, fetchedAt: Number.isFinite(entry.fetchedAt) ? entry.fetchedAt : 0 };
+        }
+        return { version: CACHE_VERSION, providers };
+    }
+    catch {
+        // Corrupt or truncated file: treat as absent rather than throwing.
+        return empty;
+    }
+}

package/dist/utils/models.d.ts

@@ -1,3 +1,4 @@
+import { type ReasoningWireSurface } from '@zerg/model-contracts';
 import type { CodexReasoningEffort } from '../config/types.js';
 export declare const OFFICIAL_CODEX_MODEL_IDS: readonly ["gpt-6-sol", "gpt-6-luna", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", "gpt-5.5", "gpt-5.4", "gpt-5.4-mini", "gpt-5.3-codex", "gpt-5.2"];
 export interface OfficialCodexModelInfo {
@@ -66,9 +67,9 @@ export declare const CLAUDE_REASONING_EFFORTS: readonly CodexReasoningEffort[];
  * on a Haiku pane must be rejected, not persisted and then 400'd every turn.
  */
 export declare function getSupportedClaudeReasoningEfforts(model: string | undefined): readonly CodexReasoningEffort[] | undefined;
-export declare function getSupportedCodexReasoningEfforts(model: string | undefined, provider?: string): readonly CodexReasoningEffort[] | undefined;
+export declare function getSupportedCodexReasoningEfforts(model: string | undefined, provider?: string, surface?: ReasoningWireSurface): readonly CodexReasoningEffort[] | undefined;
 /** Unknown/dynamic models stay permissive; known models must honor their advertised contract. */
-export declare function isCodexReasoningEffortSupported(provider: string | undefined, model: string | undefined, effort: CodexReasoningEffort): boolean;
+export declare function isCodexReasoningEffortSupported(provider: string | undefined, model: string | undefined, effort: CodexReasoningEffort, surface?: ReasoningWireSurface): boolean;
 /**
  * Message shown when a model rejects a chosen reasoning effort. Handles the
  * empty-supported-list case (e.g. Kimi K2.6, whose depth is a `thinking` object
@@ -79,6 +80,7 @@ export declare function unsupportedEffortMessage(model: string | undefined, leve
 export declare const CODEX_MODELS_CLIENT_VERSION = "0.144.0";
 export declare function getDefaultModel(provider: string, tier?: 'full' | 'cheap'): string;
 interface ListModelsOptions {
+    workspaceId?: string;
     signal?: AbortSignal;
     provider: string;
     apiKey?: string;

package/dist/utils/models.js

@@ -1,3 +1,5 @@
+import { CONTRACT_PROVIDERS, modelContract, normalizeContractProvider } from '@zerg/model-contracts';
+import { fetchRouterCatalog, routerModelIds } from './router_catalog.js';
 /**
  * Get the default model for a provider by tier.
  * Single source of truth — replaces duplicated switch statements in sim/llm.ts,
@@ -202,7 +204,10 @@ export function getSupportedClaudeReasoningEfforts(model) {
     // Unrecognized Claude id (e.g. a future family): stay permissive.
     return undefined;
 }
-export function getSupportedCodexReasoningEfforts(model, provider) {
+export function getSupportedCodexReasoningEfforts(model, provider, surface = provider === 'openai_compatible' ? 'chat_tools' : 'native_api') {
+    if (provider && model && CONTRACT_PROVIDERS.includes(normalizeContractProvider(provider))) {
+        return modelContract(provider, model, surface)?.reasoningEfforts ?? [];
+    }
     if (isModalDeepSeekFlashModel(model))
         return MODAL_DEEPSEEK_FLASH_EFFORTS;
     if (isDeepSeekFlashModel(model))
@@ -235,8 +240,8 @@ export function getSupportedCodexReasoningEfforts(model, provider) {
     return appServerEfforts;
 }
 /** Unknown/dynamic models stay permissive; known models must honor their advertised contract. */
-export function isCodexReasoningEffortSupported(provider, model, effort) {
-    const supported = getSupportedCodexReasoningEfforts(model, provider);
+export function isCodexReasoningEffortSupported(provider, model, effort, surface) {
+    const supported = getSupportedCodexReasoningEfforts(model, provider, surface);
     return supported === undefined || supported.includes(effort);
 }
 /**
@@ -423,17 +428,7 @@ export async function listModels(options) {
     }
     // Token-authenticated zrouter model listing (container/default cloud path).
     if (proxyUrl && authToken) {
-        const url = `${proxyUrl}/v1/models?provider=${encodeURIComponent(provider)}`;
-        const res = await fetch(url, {
-            signal,
-            headers: {
-                Authorization: `Bearer ${authToken}`,
-            }
-        });
-        if (!res.ok) {
-            throw new Error(`ZRouter error (${res.status})`);
-        }
-        return parseList(res, provider === 'moonshot' ? 'kimi' : provider);
+        return routerModelIds(await fetchRouterCatalog({ origin: proxyUrl, token: authToken, workspaceId: options.workspaceId }, signal, provider === 'zergrouter' ? undefined : provider === 'moonshot' ? 'kimi' : provider), provider === 'moonshot' ? 'kimi' : provider);
     }
     if (provider === 'claude_code' || provider === 'claude-code') {
         const { ClaudeCodeAuthManager } = await import('../agent/backends/claude_code_auth.js');
@@ -470,8 +465,9 @@ export async function listModels(options) {
         }
         return parseList(res);
     }
-    if (provider === 'openai' || provider === 'deepseek') {
-        const endpoint = provider === 'deepseek' ? 'https://api.deepseek.com/v1/models' : 'https://api.openai.com/v1/models';
+    if (provider === 'openai' || provider === 'deepseek' || provider === 'fireworks') {
+        const endpoint = provider === 'fireworks' ? `${(options.baseUrl || 'https://api.fireworks.ai/inference/v1').replace(/\/$/, '')}/models`
+            : provider === 'deepseek' ? 'https://api.deepseek.com/v1/models' : 'https://api.openai.com/v1/models';
         const res = await fetch(endpoint, {
             signal,
             headers: {

package/dist/utils/reasoning.d.ts

@@ -1,9 +1,16 @@
+import type { ReasoningWireSurface } from '@zerg/model-contracts';
 import { type CodexReasoningEffort } from '../config/types.js';
+export type ReasoningContract = ReasoningWireSurface | readonly string[] | {
+    choices: readonly string[];
+    default?: string;
+};
+/** Suggestions and command validation share the same model contract. */
+export declare function reasoningCommandChoices(kind: 'effort' | 'thinking', provider: string, model: string, contract?: ReasoningContract): string[];
 /** One policy for slash commands and startup flags. null clears the model override. */
 export declare function parseReasoningSelection(provider: string, model: string, current: CodexReasoningEffort | undefined, selection: {
     effort?: string;
     thinking?: string;
-}): CodexReasoningEffort | null;
+}, contract?: ReasoningContract): CodexReasoningEffort | null;
 /**
  * How a resolved effort reads in command output.
  *

package/dist/utils/reasoning.js

@@ -1,22 +1,37 @@
 import { CODEX_REASONING_EFFORTS } from '../config/types.js';
 import { getSupportedCodexReasoningEfforts, unsupportedEffortMessage } from './models.js';
+function reasoningChoices(provider, model, contract) {
+    return contract === undefined || typeof contract === 'string'
+        ? getSupportedCodexReasoningEfforts(model, provider, contract)
+        : 'choices' in contract ? contract.choices : contract;
+}
+/** Suggestions and command validation share the same model contract. */
+export function reasoningCommandChoices(kind, provider, model, contract) {
+    const choices = reasoningChoices(provider, model, contract);
+    if (kind === 'effort')
+        return [...(choices ?? []), 'default'];
+    return [choices?.some(value => value.toLowerCase() !== 'none') ? 'on' : '', choices?.some(value => value.toLowerCase() === 'none') ? 'off' : ''].filter(Boolean);
+}
 /** One policy for slash commands and startup flags. null clears the model override. */
-export function parseReasoningSelection(provider, model, current, selection) {
-    const supported = getSupportedCodexReasoningEfforts(model, provider);
-    const effort = selection.effort?.toLowerCase();
+export function parseReasoningSelection(provider, model, current, selection, contract) {
+    const supported = reasoningChoices(provider, model, contract);
+    const advertisedChoices = typeof contract === 'string' || contract === undefined ? undefined : supported;
+    const canonical = (value) => supported?.find(choice => choice.toLowerCase() === value.toLowerCase()) ?? value;
+    const effortInput = selection.effort?.toLowerCase();
+    const effort = effortInput === undefined ? undefined : canonical(effortInput);
     const thinking = selection.thinking?.toLowerCase();
     if (thinking !== undefined && thinking !== 'on' && thinking !== 'off') {
         throw new Error('Invalid thinking setting. Choose on or off.');
     }
-    if (effort !== undefined && ['default', 'clear', 'reset', 'unset'].includes(effort)) {
+    if (effortInput !== undefined && ['default', 'clear', 'reset', 'unset'].includes(effortInput)) {
         if (thinking !== undefined)
             throw new Error('Default effort conflicts with an explicit thinking setting.');
         return null;
     }
-    if (effort !== undefined && !CODEX_REASONING_EFFORTS.includes(effort)) {
+    if (effort !== undefined && !(advertisedChoices ?? CODEX_REASONING_EFFORTS).includes(effort)) {
         throw new Error(`Invalid effort "${effort}". Choose: ${(supported ?? CODEX_REASONING_EFFORTS).join(', ')} (or default).`);
     }
-    if (effort !== undefined && ((thinking === 'off' && effort !== 'none') || (thinking === 'on' && effort === 'none'))) {
+    if (effort !== undefined && ((thinking === 'off' && effort.toLowerCase() !== 'none') || (thinking === 'on' && effort.toLowerCase() === 'none'))) {
         throw new Error(`Effort "${effort}" conflicts with thinking ${thinking}.`);
     }
     // A toggle requires a known model contract. Unknown endpoints can still
@@ -24,9 +39,14 @@ export function parseReasoningSelection(provider, model, current, selection) {
     if (thinking !== undefined && supported === undefined) {
         throw new Error(`Thinking controls are unknown for model "${model}". Use /effort only if your endpoint supports it.`);
     }
-    const level = effort ?? (thinking === 'off' ? 'none'
-        : current && current !== 'none' ? current
-            : 'high');
+    const defaultLevel = contract && typeof contract !== 'string' && 'choices' in contract ? contract.default : undefined;
+    const enabled = supported?.filter(value => value.toLowerCase() !== 'none');
+    const currentLevel = current === undefined ? undefined : canonical(current);
+    const preferred = defaultLevel === undefined ? undefined : canonical(defaultLevel);
+    const level = effort ?? (thinking === 'off' ? canonical('none')
+        : currentLevel && currentLevel.toLowerCase() !== 'none' && (supported === undefined || supported.includes(currentLevel)) ? currentLevel
+            : preferred && enabled?.includes(preferred) ? preferred
+                : enabled?.find(value => value.toLowerCase() === 'high') ?? enabled?.[0] ?? 'high');
     if (!level || (supported !== undefined && !supported.includes(level))) {
         throw new Error(unsupportedEffortMessage(model, level ?? 'on', supported ?? []));
     }
@@ -43,7 +63,7 @@ export function parseReasoningSelection(provider, model, current, selection) {
 export function formatReasoningEffort(level) {
     if (level === undefined)
         return 'provider default';
-    return level === 'none' ? 'thinking off' : `${level} thinking`;
+    return level.toLowerCase() === 'none' ? 'thinking off' : `${level} thinking`;
 }
 /**
  * The thinking switch on its own, for readouts that show it without the level.
@@ -52,5 +72,5 @@ export function formatReasoningEffort(level) {
  * claim either state then.
  */
 export function reasoningEnabled(level) {
-    return level === undefined ? undefined : level !== 'none';
+    return level === undefined ? undefined : level.toLowerCase() !== 'none';
 }

package/dist/utils/router_catalog.d.ts

@@ -0,0 +1,47 @@
+export interface RouterModelCapabilities {
+    chat: boolean;
+    tools?: boolean;
+    images?: boolean;
+    reasoning?: {
+        choices: string[];
+        default?: string;
+    };
+    context_window?: number;
+    max_output_tokens?: number;
+}
+export interface RouterModelDescriptor {
+    id: string;
+    owned_by: string;
+    object?: 'model';
+    display_name?: string;
+    provider_display_name?: string;
+    aliases?: string[];
+    is_default?: boolean;
+    available?: boolean;
+    capabilities?: RouterModelCapabilities;
+}
+export interface RouterCatalog {
+    version: 0 | 1;
+    models: RouterModelDescriptor[];
+    cached: boolean;
+    fetchedAt: number;
+    authRequired?: boolean;
+}
+export interface RouterCatalogConnection {
+    origin: string;
+    token: string;
+    workspaceId?: string;
+}
+export declare function resolveRouterModel(catalog: RouterCatalog, provider: string, model: string): RouterModelDescriptor | undefined;
+/** Opaque identity shared by cache readers and account-scoped completion state. */
+export declare function routerCatalogScope(connection: RouterCatalogConnection): string;
+export declare function readRouterCatalog(connection: RouterCatalogConnection): RouterCatalog | undefined;
+export declare class RouterCatalogAuthenticationError extends Error {
+    readonly status: number;
+    constructor(status: number);
+}
+/** Fresh HTTP discovery, shared by the catalog and provider-list cache owners. */
+export declare function fetchRouterCatalog(connection: RouterCatalogConnection, signal?: AbortSignal, provider?: string): Promise<RouterCatalog>;
+export declare function discoverRouterCatalog(connection: RouterCatalogConnection, signal?: AbortSignal): Promise<RouterCatalog>;
+export declare function routerModelsForProvider(catalog: RouterCatalog, provider: string): RouterModelDescriptor[];
+export declare function routerModelIds(catalog: RouterCatalog, provider: string): string[];

package/dist/utils/router_catalog.js

@@ -0,0 +1,222 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { statSync, readFileSync } from 'node:fs';
+import { mkdir, readdir, rename, stat, unlink, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { profileConfigDir } from '../config/profiles.js';
+function record(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function identifier(value) {
+    return typeof value === 'string' && value.length > 0 && value.length <= 512 && !/[\x00-\x1f\x7f]/.test(value);
+}
+function identifiers(value, max) {
+    return Array.isArray(value) && value.length <= max && value.every(identifier);
+}
+function descriptor(value, legacy) {
+    if (!record(value))
+        return undefined;
+    const id = value.id ?? (legacy ? value.name : undefined);
+    if (!identifier(id) || !identifier(value.owned_by))
+        return undefined;
+    const result = { id, owned_by: value.owned_by };
+    if (value.object !== undefined && value.object !== 'model')
+        return undefined;
+    if (value.object === 'model')
+        result.object = 'model';
+    for (const key of ['display_name', 'provider_display_name']) {
+        if (value[key] !== undefined) {
+            if (!identifier(value[key]))
+                return undefined;
+            result[key] = value[key];
+        }
+    }
+    for (const key of ['is_default', 'available']) {
+        if (value[key] !== undefined) {
+            if (typeof value[key] !== 'boolean')
+                return undefined;
+            result[key] = value[key];
+        }
+    }
+    if (value.aliases !== undefined) {
+        if (!identifiers(value.aliases, 32))
+            return undefined;
+        result.aliases = value.aliases;
+    }
+    if (value.capabilities !== undefined) {
+        const caps = value.capabilities;
+        if (!record(caps) || typeof caps.chat !== 'boolean')
+            return undefined;
+        const capabilities = { chat: caps.chat };
+        for (const key of ['tools', 'images']) {
+            if (caps[key] !== undefined) {
+                if (typeof caps[key] !== 'boolean')
+                    return undefined;
+                capabilities[key] = caps[key];
+            }
+        }
+        for (const key of ['context_window', 'max_output_tokens']) {
+            if (caps[key] !== undefined) {
+                if (typeof caps[key] !== 'number' || !Number.isSafeInteger(caps[key]) || caps[key] <= 0)
+                    return undefined;
+                capabilities[key] = caps[key];
+            }
+        }
+        if (caps.reasoning !== undefined) {
+            const reasoning = caps.reasoning;
+            if (!record(reasoning) || !identifiers(reasoning.choices, 32)
+                || (reasoning.default !== undefined && !identifier(reasoning.default)))
+                return undefined;
+            capabilities.reasoning = { choices: reasoning.choices, ...(reasoning.default === undefined ? {} : { default: reasoning.default }) };
+        }
+        result.capabilities = capabilities;
+    }
+    return result;
+}
+// Resolve only exact IDs or advertised/legacy aliases within the selected provider.
+// Opaque IDs win; duplicate aliases remain ambiguous instead of selecting another model.
+export function resolveRouterModel(catalog, provider, model) {
+    const owner = provider === 'moonshot' ? 'kimi' : provider;
+    const rows = catalog.models.filter(row => row.owned_by === owner);
+    const exact = rows.find(row => row.id === model);
+    if (exact)
+        return exact;
+    const matches = rows.filter(row => row.id === `${owner}/${model}` || row.aliases?.includes(model));
+    return matches.length === 1 ? matches[0] : undefined;
+}
+// The token digest is a conservative account partition, including opaque tokens.
+// Never persist a credential, or share a catalog between profiles or origins.
+/** Opaque identity shared by cache readers and account-scoped completion state. */
+export function routerCatalogScope(connection) {
+    const key = createHash('sha256').update(JSON.stringify([connection.origin.replace(/\/+$/, ''), connection.token, connection.workspaceId ?? ''])).digest('hex');
+    return join(profileConfigDir(), `router-models-${key}.json`);
+}
+function parseCatalog(value) {
+    if (!record(value))
+        throw new Error('Invalid Router catalog');
+    if (value.model_contract_version !== undefined && value.model_contract_version !== 1)
+        throw new Error('Unsupported Router model contract');
+    const data = value.data ?? value.models ?? value.items ?? [];
+    if (!Array.isArray(data) || data.length > 4096)
+        throw new Error('Invalid Router catalog');
+    const version = value.model_contract_version === 1 ? 1 : 0;
+    return { version, models: data.flatMap(value => { const row = descriptor(value, version === 0); return row ? [row] : []; }) };
+}
+const memo = new Map();
+export function readRouterCatalog(connection) {
+    const file = routerCatalogScope(connection);
+    try {
+        const stat = statSync(file, { bigint: true });
+        const stamp = `${stat.mtimeNs}:${stat.size}:${stat.ino}`;
+        const previous = memo.get(file);
+        if (previous?.stamp === stamp)
+            return previous.catalog;
+        const saved = JSON.parse(readFileSync(file, 'utf8'));
+        const parsed = parseCatalog(saved);
+        const catalog = { ...parsed, cached: true, fetchedAt: Number(saved.fetchedAt) || 0 };
+        if (memo.size >= 32)
+            memo.delete(memo.keys().next().value);
+        memo.set(file, { stamp, catalog });
+        return catalog;
+    }
+    catch {
+        memo.delete(file);
+        return undefined;
+    }
+}
+export class RouterCatalogAuthenticationError extends Error {
+    status;
+    constructor(status) {
+        super(`ZRouter error (${status}): authentication rejected. Run ztc auth login again.`);
+        this.status = status;
+    }
+}
+/** Fresh HTTP discovery, shared by the catalog and provider-list cache owners. */
+export async function fetchRouterCatalog(connection, signal, provider) {
+    const file = routerCatalogScope(connection);
+    const timeout = AbortSignal.timeout(8000);
+    const suffix = provider === undefined ? '' : `?provider=${encodeURIComponent(provider)}`;
+    const response = await fetch(`${connection.origin.replace(/\/+$/, '')}/v1/models${suffix}`, {
+        headers: { Authorization: `Bearer ${connection.token}`, ...(connection.workspaceId ? { 'X-Zerg-Workspace-ID': connection.workspaceId } : {}) },
+        signal: signal ? AbortSignal.any([signal, timeout]) : timeout,
+    });
+    if (response.status === 401 || response.status === 403) {
+        const cached = memo.get(file);
+        if (cached)
+            cached.catalog.authRequired = true;
+        throw new RouterCatalogAuthenticationError(response.status);
+    }
+    if (!response.ok)
+        throw new Error(`ZRouter error (${response.status})`);
+    return { ...parseCatalog(await response.json()), cached: false, fetchedAt: Date.now() };
+}
+async function pruneCatalogFiles(file) {
+    const directory = dirname(file);
+    const now = Date.now();
+    const caches = [];
+    for (const name of await readdir(directory)) {
+        const cache = /^router-models-[a-f0-9]{64}\.json$/.test(name);
+        const temporary = /^router-models-[a-f0-9]{64}\.json\.[a-f0-9-]{36}\.tmp$/.test(name);
+        if (!cache && !temporary)
+            continue;
+        const path = join(directory, name);
+        try {
+            const info = await stat(path);
+            if (!info.isFile())
+                continue;
+            if (temporary && now - info.mtimeMs > 3_600_000)
+                await unlink(path);
+            if (cache)
+                caches.push({ file: path, modified: info.mtimeMs });
+        }
+        catch { /* Another process may have completed or pruned this entry. */ }
+    }
+    // Keep this publication even when another process writes during the scan.
+    caches.sort((a, b) => Number(b.file === file) - Number(a.file === file) || b.modified - a.modified || a.file.localeCompare(b.file));
+    for (const entry of caches.slice(32)) {
+        await unlink(entry.file).catch(() => { });
+        memo.delete(entry.file);
+    }
+}
+export async function discoverRouterCatalog(connection, signal) {
+    const file = routerCatalogScope(connection); // Capture the profile before awaiting HTTP.
+    const previous = readRouterCatalog(connection);
+    let result;
+    try {
+        result = await fetchRouterCatalog(connection, signal);
+    }
+    catch (error) {
+        if (error instanceof RouterCatalogAuthenticationError) {
+            if (previous) {
+                previous.authRequired = true;
+                return previous;
+            }
+            throw error;
+        }
+        if (!signal?.aborted && previous)
+            return previous;
+        throw error;
+    }
+    const temp = `${file}.${randomUUID()}.tmp`;
+    try {
+        await mkdir(dirname(file), { recursive: true });
+        await writeFile(temp, JSON.stringify({ model_contract_version: result.version || undefined, data: result.models, fetchedAt: result.fetchedAt }), { mode: 0o600, flag: 'wx' });
+        await rename(temp, file);
+        await pruneCatalogFiles(file);
+    }
+    catch { /* Discovery still works when optional persistence is unavailable. */ }
+    finally {
+        await unlink(temp).catch(() => { });
+    }
+    return result;
+}
+export function routerModelsForProvider(catalog, provider) {
+    return catalog.models.filter(model => model.owned_by === provider && (catalog.version === 0 || model.capabilities?.chat === true));
+}
+export function routerModelIds(catalog, provider) {
+    if (provider === 'zergrouter')
+        return [...new Set(catalog.models.filter(m => catalog.version === 0 || m.capabilities?.chat).map(m => m.owned_by))];
+    const ids = routerModelsForProvider(catalog, provider).map(model => model.id);
+    if (catalog.version === 1)
+        return ids;
+    return provider === 'modal' ? ids.map(id => id.replace(/^modal\//, '')).filter(id => !/\.modal\.(?:direct|run)(?:[/:?#]|$)/i.test(id)) : ids;
+}