faces-cli 1.6.18 → 1.7.0

package/dist/commands/catalog/doctor.js

@@ -6,6 +6,7 @@ import { FacesAPIError } from '../../client.js';
 import { loadConfig } from '../../config.js';
 import { CatalogService, CATALOG_DIR } from '../../catalog.js';
 import { TeamCatalogService } from '../../team-catalog.js';
+import { resolveEndpoint, MESSAGES_ENDPOINT, RESPONSES_ENDPOINT } from '../../routing.js';
 export default class CatalogDoctor extends BaseCommand {
     static description = 'Diagnose and repair the local face and team catalog';
     static flags = {
@@ -203,6 +204,8 @@ export default class CatalogDoctor extends BaseCommand {
             const cfg = loadConfig();
             const catalogModel = cfg.catalog_model ?? 'gpt-5-nano';
             this.log(`Generating descriptions for ${noDescription.length} face(s) via ${catalogModel}...`);
+            // Route the description LLM the same way chat does — off the catalog.
+            const { endpoint: descEndpoint } = await resolveEndpoint(client, `_@${catalogModel}`);
             let generated = 0;
             for (const alias of noDescription) {
                 const remote = remoteByAlias.get(alias);
@@ -211,14 +214,26 @@ export default class CatalogDoctor extends BaseCommand {
                 try {
                     const prompt = 'Describe yourself in one paragraph. Who are you, what do you care about, and what kind of questions are you best suited to answer?';
                     const faceModel = `${alias}@${catalogModel}`;
-                    const isAnthropic = catalogModel.startsWith('claude');
                     let text;
-                    if (isAnthropic) {
+                    if (descEndpoint === MESSAGES_ENDPOINT) {
                         const resp = await client.post('/v1/messages', {
                             body: { model: faceModel, messages: [{ role: 'user', content: prompt }], max_tokens: 256 },
                         });
                         text = resp.content?.find((b) => b.type === 'text')?.text;
                     }
+                    else if (descEndpoint === RESPONSES_ENDPOINT) {
+                        const resp = await client.post('/v1/responses', {
+                            body: { model: faceModel, input: [{ role: 'user', content: prompt }], max_output_tokens: 256 },
+                        });
+                        let out = '';
+                        for (const item of resp.output ?? []) {
+                            for (const block of item.content ?? []) {
+                                if (block.type === 'output_text')
+                                    out += block.text ?? '';
+                            }
+                        }
+                        text = out || undefined;
+                    }
                     else {
                         const resp = await client.post('/v1/chat/completions', {
                             body: { model: faceModel, messages: [{ role: 'user', content: prompt }], max_tokens: 256 },

package/dist/commands/chat/chat.d.ts

@@ -19,8 +19,10 @@ export default class ChatChat extends BaseCommand {
         face_username: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
     };
     run(): Promise<unknown>;
+    private oauthHint;
+    private metaFor;
+    private streamDeltas;
     private runChatCompletions;
     private runMessages;
     private runResponses;
-    private extractText;
 }

package/dist/commands/chat/chat.js

@@ -3,14 +3,9 @@ import fs from 'node:fs';
 import { BaseCommand } from '../../base.js';
 import { FacesAPIError } from '../../client.js';
 import { extractStreamDelta } from '../../utils.js';
-function isAnthropicModel(model) {
-    // Extract model name from face@model format
-    const parts = model.split('@');
-    const llm = parts.length > 1 ? parts[parts.length - 1] : '';
-    return llm.startsWith('claude');
-}
+import { resolveEndpoint, MESSAGES_ENDPOINT, RESPONSES_ENDPOINT } from '../../routing.js';
 export default class ChatChat extends BaseCommand {
-    static description = 'Chat via a face. Auto-routes to the correct API endpoint based on model provider.';
+    static description = 'Chat via a face. Auto-routes to the correct API endpoint based on the model catalog.';
     static flags = {
         ...BaseCommand.baseFlags,
         message: Flags.string({ char: 'm', description: 'User message (repeatable)', multiple: true, required: false }),
@@ -20,7 +15,7 @@ export default class ChatChat extends BaseCommand {
         'max-tokens': Flags.integer({ description: 'Max tokens' }),
         temperature: Flags.string({ description: 'Temperature (0.0-2.0)' }),
         file: Flags.string({ description: 'Read message from file' }),
-        responses: Flags.boolean({ description: 'Use OpenAI Responses API instead of Chat Completions', default: false }),
+        responses: Flags.boolean({ description: 'Force the OpenAI Responses API endpoint (escape hatch; routing is automatic otherwise)', default: false }),
         'oauth-only': Flags.boolean({ description: 'Prevent fallback to paid system key (use OAuth only)', default: false }),
     };
     static args = {
@@ -51,15 +46,15 @@ export default class ChatChat extends BaseCommand {
         else {
             this.error('Provide at least one --message/-m or --file');
         }
-        // Route based on model provider
-        const anthropic = isAnthropicModel(model);
-        const useResponses = flags.responses && !anthropic;
+        // Route off the model catalog; --responses forces the Responses endpoint.
+        const route = await resolveEndpoint(client, model);
+        const endpoint = flags.responses ? RESPONSES_ENDPOINT : route.endpoint;
         try {
-            if (anthropic) {
+            if (endpoint === MESSAGES_ENDPOINT) {
                 return await this.runMessages(client, model, userMessages, flags);
             }
-            else if (useResponses) {
-                return await this.runResponses(client, model, userMessages[0], flags);
+            else if (endpoint === RESPONSES_ENDPOINT) {
+                return await this.runResponses(client, model, userMessages, flags);
             }
             else {
                 return await this.runChatCompletions(client, model, userMessages, flags);
@@ -67,17 +62,48 @@ export default class ChatChat extends BaseCommand {
         }
         catch (err) {
             if (err instanceof FacesAPIError) {
-                if (err.errorCode === 'oauth_rejected') {
-                    const hint = err.fallbackAvailable
-                        ? 'Run `faces account:preferences api_fallback true` to allow paid fallback.'
-                        : 'Run `faces billing:topup` to add credits, then enable fallback with `faces account:preferences api_fallback true`.';
-                    this.error(`OAuth failed: ${err.message}\n${hint}`);
-                }
+                if (err.errorCode === 'oauth_rejected')
+                    this.error(`OAuth failed: ${err.message}\n${this.oauthHint(err, { ...route, endpoint })}`);
                 this.error(`Error (${err.statusCode}): ${err.message}`);
             }
             throw err;
         }
     }
+    oauthHint(err, route) {
+        const hints = [];
+        if (route.endpoint === RESPONSES_ENDPOINT && route.freeWhenConnected) {
+            hints.push('This model is free when you link your ChatGPT account: faces auth:connect openai');
+        }
+        hints.push(err.fallbackAvailable
+            ? 'Run `faces account:preferences api_fallback true` to allow paid fallback.'
+            : 'Run `faces billing:topup` to add credits, then enable fallback with `faces account:preferences api_fallback true`.');
+        return hints.join('\n');
+    }
+    metaFor(headers, endpoint) {
+        const meta = {};
+        if (headers['x-faces-provider'])
+            meta.provider = headers['x-faces-provider'];
+        if (headers['x-faces-cost-usd'])
+            meta.cost_usd = headers['x-faces-cost-usd'];
+        meta.endpoint = endpoint;
+        return meta;
+    }
+    async streamDeltas(client, endpoint, payload) {
+        for await (const line of client.stream(endpoint, payload)) {
+            if (!line.startsWith('data: '))
+                continue;
+            const chunk = line.slice(6);
+            if (chunk.trim() === '[DONE]' || chunk.trim() === '')
+                continue;
+            try {
+                const delta = extractStreamDelta(JSON.parse(chunk));
+                if (delta)
+                    process.stdout.write(delta);
+            }
+            catch { /* ignore parse errors */ }
+        }
+        process.stdout.write('\n');
+    }
     async runChatCompletions(client, model, userMessages, flags) {
         const messages = [];
         if (flags.system)
@@ -92,39 +118,15 @@ export default class ChatChat extends BaseCommand {
         if (flags['oauth-only'])
             payload.oauth_only = true;
         if (flags.stream) {
-            // The backend may re-route /v1/chat/completions to /v1/messages or
-            // /v1/responses, so handle all three SSE event shapes.
-            for await (const line of client.stream('/v1/chat/completions', payload)) {
-                if (!line.startsWith('data: '))
-                    continue;
-                const chunk = line.slice(6);
-                if (chunk.trim() === '[DONE]' || chunk.trim() === '')
-                    continue;
-                try {
-                    const delta = extractStreamDelta(JSON.parse(chunk));
-                    if (delta)
-                        process.stdout.write(delta);
-                }
-                catch { /* ignore parse errors */ }
-            }
-            process.stdout.write('\n');
+            await this.streamDeltas(client, '/v1/chat/completions', payload);
             return {};
         }
         const { data, headers } = await client.postWithHeaders('/v1/chat/completions', { body: payload });
         const body = data;
-        const routedEndpoint = headers['x-faces-routed-endpoint'];
-        // Extract text based on which format the backend used
-        const text = this.extractText(body, routedEndpoint);
+        const choices = body.choices;
+        const text = String(choices?.[0]?.message?.content ?? '');
         if (this.jsonEnabled()) {
-            const meta = {};
-            if (headers['x-faces-provider'])
-                meta.provider = headers['x-faces-provider'];
-            if (headers['x-faces-cost-usd'])
-                meta.cost_usd = headers['x-faces-cost-usd'];
-            if (routedEndpoint)
-                meta.routed_endpoint = routedEndpoint;
-            if (Object.keys(meta).length > 0)
-                body._meta = meta;
+            body._meta = this.metaFor(headers, '/v1/chat/completions');
             return body;
         }
         this.log(text);
@@ -143,32 +145,13 @@ export default class ChatChat extends BaseCommand {
         if (flags['oauth-only'])
             payload.oauth_only = true;
         if (flags.stream) {
-            for await (const line of client.stream('/v1/messages', payload)) {
-                if (!line.startsWith('data: '))
-                    continue;
-                const chunk = line.slice(6);
-                if (chunk.trim() === '[DONE]' || chunk.trim() === '')
-                    continue;
-                try {
-                    const delta = extractStreamDelta(JSON.parse(chunk));
-                    if (delta)
-                        process.stdout.write(delta);
-                }
-                catch { /* ignore */ }
-            }
-            process.stdout.write('\n');
+            await this.streamDeltas(client, '/v1/messages', payload);
             return {};
         }
         const { data, headers } = await client.postWithHeaders('/v1/messages', { body: payload });
         const body = data;
         if (this.jsonEnabled()) {
-            const meta = {};
-            if (headers['x-faces-provider'])
-                meta.provider = headers['x-faces-provider'];
-            if (headers['x-faces-cost-usd'])
-                meta.cost_usd = headers['x-faces-cost-usd'];
-            if (Object.keys(meta).length > 0)
-                body._meta = meta;
+            body._meta = this.metaFor(headers, '/v1/messages');
             return body;
         }
         let content = '';
@@ -179,39 +162,24 @@ export default class ChatChat extends BaseCommand {
         this.log(content);
         return body;
     }
-    async runResponses(client, model, input, flags) {
-        const payload = { model, input, stream: flags.stream };
+    async runResponses(client, model, userMessages, flags) {
+        const payload = {
+            model,
+            input: userMessages.map((m) => ({ role: 'user', content: m })),
+            stream: flags.stream,
+        };
         if (flags.system)
             payload.instructions = flags.system;
         if (flags['oauth-only'])
             payload.oauth_only = true;
         if (flags.stream) {
-            for await (const line of client.stream('/v1/responses', payload)) {
-                if (!line.startsWith('data: '))
-                    continue;
-                const chunk = line.slice(6);
-                if (chunk.trim() === '[DONE]' || chunk.trim() === '')
-                    continue;
-                try {
-                    const delta = extractStreamDelta(JSON.parse(chunk));
-                    if (delta)
-                        process.stdout.write(delta);
-                }
-                catch { /* ignore */ }
-            }
-            process.stdout.write('\n');
+            await this.streamDeltas(client, '/v1/responses', payload);
             return {};
         }
         const { data, headers } = await client.postWithHeaders('/v1/responses', { body: payload });
         const body = data;
         if (this.jsonEnabled()) {
-            const meta = {};
-            if (headers['x-faces-provider'])
-                meta.provider = headers['x-faces-provider'];
-            if (headers['x-faces-cost-usd'])
-                meta.cost_usd = headers['x-faces-cost-usd'];
-            if (Object.keys(meta).length > 0)
-                body._meta = meta;
+            body._meta = this.metaFor(headers, '/v1/responses');
             return body;
         }
         let outputText = '';
@@ -224,30 +192,4 @@ export default class ChatChat extends BaseCommand {
         this.log(outputText);
         return body;
     }
-    extractText(body, routedEndpoint) {
-        if (routedEndpoint === '/v1/responses') {
-            // OpenAI Responses format
-            let text = '';
-            for (const item of body.output ?? []) {
-                for (const block of item.content ?? []) {
-                    if (block.type === 'output_text')
-                        text += String(block.text ?? '');
-                }
-            }
-            return text;
-        }
-        if (routedEndpoint === '/v1/messages') {
-            // Anthropic Messages format
-            let text = '';
-            for (const block of body.content ?? []) {
-                if (block.type === 'text')
-                    text += String(block.text ?? '');
-            }
-            return text;
-        }
-        // Standard chat/completions format (default)
-        const choices = body.choices;
-        const message = choices?.[0]?.message;
-        return String(message?.content ?? '');
-    }
 }

package/dist/commands/chat/thread.d.ts

@@ -27,12 +27,13 @@ export default class ChatThread extends BaseCommand {
     private handleDelete;
     private handleShow;
     private handleMessage;
-    private sendOpenAI;
+    private sendChatCompletions;
+    private sendResponses;
     private sendAnthropic;
     /**
      * Stream an SSE response, printing deltas to stdout as they arrive while
-     * accumulating the full text to persist on the thread. Handles any of the
-     * three event shapes, so a re-routed stream still renders correctly.
+     * accumulating the full text to persist on the thread. extractStreamDelta
+     * dispatches on event type, so it renders whichever endpoint we posted to.
      */
     private streamAndAccumulate;
 }

package/dist/commands/chat/thread.js

@@ -6,32 +6,23 @@ import path from 'node:path';
 import { BaseCommand } from '../../base.js';
 import { FacesAPIError } from '../../client.js';
 import { extractStreamDelta } from '../../utils.js';
+import { resolveEndpoint, MESSAGES_ENDPOINT, RESPONSES_ENDPOINT, CHAT_COMPLETIONS_ENDPOINT } from '../../routing.js';
 const THREADS_DIR = path.join(os.homedir(), '.faces', 'threads');
-function isAnthropicModel(model) {
-    const parts = model.split('@');
-    const llm = parts.length > 1 ? parts[parts.length - 1] : '';
-    return llm.startsWith('claude');
-}
 /**
- * Extract assistant text from any response body shape. The backend may serve a
- * request at the endpoint we hit, or re-route it (signalled by the
- * x-faces-routed-endpoint header) — so handle all three families regardless of
- * which endpoint we posted to: Anthropic Messages, OpenAI Responses, and Chat
+ * Extract assistant text for a known endpoint. Routing is deterministic, so we
+ * parse exactly one shape: Anthropic Messages, OpenAI Responses, or Chat
  * Completions.
  */
-function extractAssistantText(body, routedEndpoint) {
-    // Anthropic Messages shape: { type: 'message', content: [{type:'text', text}] }
-    if (routedEndpoint === '/v1/messages' || (Array.isArray(body.content) && body.type === 'message')) {
+function extractAssistantText(body, endpoint) {
+    if (endpoint === MESSAGES_ENDPOINT) {
         let text = '';
         for (const block of body.content ?? []) {
             if (block.type === 'text')
                 text += String(block.text ?? '');
         }
-        if (text)
-            return text;
+        return text;
     }
-    // OpenAI Responses shape: { output: [{content: [{type:'output_text', text}]}] }
-    if (routedEndpoint === '/v1/responses' || Array.isArray(body.output)) {
+    if (endpoint === RESPONSES_ENDPOINT) {
         let text = '';
         for (const item of body.output ?? []) {
             for (const block of item.content ?? []) {
@@ -39,13 +30,11 @@ function extractAssistantText(body, routedEndpoint) {
                     text += String(block.text ?? '');
             }
         }
-        if (text)
-            return text;
+        return text;
     }
-    // Standard Chat Completions shape: { choices: [{message: {content}}] }
+    // Chat Completions: { choices: [{message: {content}}] }
     const choices = body.choices;
-    const message = choices?.[0]?.message;
-    return String(message?.content ?? '');
+    return String(choices?.[0]?.message?.content ?? '');
 }
 function newThreadId() {
     return 't_' + crypto.randomBytes(6).toString('hex');
@@ -219,7 +208,7 @@ export default class ChatThread extends BaseCommand {
                 id: newThreadId(),
                 face_username: baseAlias,
                 model,
-                provider: isAnthropicModel(model) ? 'anthropic' : 'openai',
+                provider: 'openai', // refined from the resolved endpoint before sending
                 system: flags.system,
                 created_at: now,
                 updated_at: now,
@@ -227,10 +216,25 @@ export default class ChatThread extends BaseCommand {
             };
         }
         thread.messages.push({ role: 'user', content: userMessage, ts: new Date().toISOString() });
+        // Route off the model catalog; cache the endpoint on the thread so resumes
+        // (including legacy threads saved before `endpoint` existed) stay consistent.
+        let endpoint = thread.endpoint;
+        if (!endpoint) {
+            endpoint = (await resolveEndpoint(client, thread.model)).endpoint;
+            thread.endpoint = endpoint;
+            thread.provider = endpoint === MESSAGES_ENDPOINT ? 'anthropic' : 'openai';
+        }
         try {
-            const assistantText = thread.provider === 'anthropic'
-                ? await this.sendAnthropic(client, thread, flags)
-                : await this.sendOpenAI(client, thread, flags);
+            let assistantText;
+            if (endpoint === MESSAGES_ENDPOINT) {
+                assistantText = await this.sendAnthropic(client, thread, flags);
+            }
+            else if (endpoint === RESPONSES_ENDPOINT) {
+                assistantText = await this.sendResponses(client, thread, flags);
+            }
+            else {
+                assistantText = await this.sendChatCompletions(client, thread, flags);
+            }
             thread.messages.push({ role: 'assistant', content: assistantText, ts: new Date().toISOString() });
             saveThread(thread);
             if (this.jsonEnabled()) {
@@ -250,17 +254,21 @@ export default class ChatThread extends BaseCommand {
         catch (err) {
             if (err instanceof FacesAPIError) {
                 if (err.errorCode === 'oauth_rejected') {
-                    const hint = err.fallbackAvailable
+                    const hints = [];
+                    if (endpoint === RESPONSES_ENDPOINT) {
+                        hints.push('This model is free when you link your ChatGPT account: faces auth:connect openai');
+                    }
+                    hints.push(err.fallbackAvailable
                         ? 'Run `faces account:preferences api_fallback true` to allow paid fallback.'
-                        : 'Run `faces billing:topup` to add credits, then enable fallback with `faces account:preferences api_fallback true`.';
-                    this.error(`OAuth failed: ${err.message}\n${hint}`);
+                        : 'Run `faces billing:topup` to add credits, then enable fallback with `faces account:preferences api_fallback true`.');
+                    this.error(`OAuth failed: ${err.message}\n${hints.join('\n')}`);
                 }
                 this.error(`Error (${err.statusCode}): ${err.message}`);
             }
             throw err;
         }
     }
-    async sendOpenAI(client, thread, flags) {
+    async sendChatCompletions(client, thread, flags) {
         const messages = [];
         if (thread.system)
             messages.push({ role: 'system', content: thread.system });
@@ -274,10 +282,27 @@ export default class ChatThread extends BaseCommand {
         if (flags['oauth-only'])
             payload.oauth_only = true;
         if (flags.stream) {
-            return this.streamAndAccumulate(client, '/v1/chat/completions', payload);
+            return this.streamAndAccumulate(client, CHAT_COMPLETIONS_ENDPOINT, payload);
+        }
+        const { data } = await client.postWithHeaders(CHAT_COMPLETIONS_ENDPOINT, { body: payload });
+        return extractAssistantText(data, CHAT_COMPLETIONS_ENDPOINT);
+    }
+    async sendResponses(client, thread, flags) {
+        // The Responses API is stateless here: replay the full history as the input
+        // array each turn, with the system prompt carried in `instructions`.
+        const input = thread.messages.map((m) => ({ role: m.role, content: m.content }));
+        const payload = { model: thread.model, input, stream: flags.stream };
+        if (thread.system)
+            payload.instructions = thread.system;
+        if (flags['max-tokens'])
+            payload.max_output_tokens = flags['max-tokens'];
+        if (flags['oauth-only'])
+            payload.oauth_only = true;
+        if (flags.stream) {
+            return this.streamAndAccumulate(client, RESPONSES_ENDPOINT, payload);
         }
-        const { data, headers } = await client.postWithHeaders('/v1/chat/completions', { body: payload });
-        return extractAssistantText(data, headers['x-faces-routed-endpoint']);
+        const { data } = await client.postWithHeaders(RESPONSES_ENDPOINT, { body: payload });
+        return extractAssistantText(data, RESPONSES_ENDPOINT);
     }
     async sendAnthropic(client, thread, flags) {
         const msgs = thread.messages.map((m) => ({ role: m.role, content: m.content }));
@@ -292,15 +317,15 @@ export default class ChatThread extends BaseCommand {
         if (flags['oauth-only'])
             payload.oauth_only = true;
         if (flags.stream) {
-            return this.streamAndAccumulate(client, '/v1/messages', payload);
+            return this.streamAndAccumulate(client, MESSAGES_ENDPOINT, payload);
         }
-        const { data, headers } = await client.postWithHeaders('/v1/messages', { body: payload });
-        return extractAssistantText(data, headers['x-faces-routed-endpoint']);
+        const { data } = await client.postWithHeaders(MESSAGES_ENDPOINT, { body: payload });
+        return extractAssistantText(data, MESSAGES_ENDPOINT);
     }
     /**
      * Stream an SSE response, printing deltas to stdout as they arrive while
-     * accumulating the full text to persist on the thread. Handles any of the
-     * three event shapes, so a re-routed stream still renders correctly.
+     * accumulating the full text to persist on the thread. extractStreamDelta
+     * dispatches on event type, so it renders whichever endpoint we posted to.
      */
     async streamAndAccumulate(client, endpoint, payload) {
         let accum = '';

package/dist/routing.d.ts

@@ -0,0 +1,19 @@
+import { FacesClient } from './client.js';
+export declare const MESSAGES_ENDPOINT = "/v1/messages";
+export declare const RESPONSES_ENDPOINT = "/v1/responses";
+export declare const CHAT_COMPLETIONS_ENDPOINT = "/v1/chat/completions";
+export interface RouteInfo {
+    endpoint: string;
+    /** The resolved LLM id we routed on (undefined if it couldn't be determined). */
+    llm?: string;
+    /** True when a free (OAuth-subscription) variant of this model exists in the catalog. */
+    freeWhenConnected: boolean;
+}
+/** Split `alias@llm` → llm; bare `alias` → undefined. */
+export declare function llmFromArg(modelArg: string): string | undefined;
+/**
+ * Decide which API endpoint a chat request should be posted to, driven entirely
+ * by the model catalog (GET /v1/models). For a bare alias we resolve the face's
+ * default model from the local catalog, falling back to GET /v1/faces/{alias}.
+ */
+export declare function resolveEndpoint(client: FacesClient, modelArg: string): Promise<RouteInfo>;

package/dist/routing.js

@@ -0,0 +1,116 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { CATALOG_INDEX } from './catalog.js';
+export const MESSAGES_ENDPOINT = '/v1/messages';
+export const RESPONSES_ENDPOINT = '/v1/responses';
+export const CHAT_COMPLETIONS_ENDPOINT = '/v1/chat/completions';
+const CACHE_PATH = path.join(os.homedir(), '.faces', 'models-cache.json');
+const TTL_MS = 60 * 60 * 1000; // 1 hour
+/** Last-resort routing when the catalog can't tell us where a model lives. */
+function fallbackEndpoint(llm) {
+    if (llm && llm.startsWith('claude'))
+        return MESSAGES_ENDPOINT;
+    return CHAT_COMPLETIONS_ENDPOINT;
+}
+function readCache() {
+    try {
+        return JSON.parse(fs.readFileSync(CACHE_PATH, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function writeCache(models) {
+    try {
+        const dir = path.dirname(CACHE_PATH);
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+        fs.writeFileSync(CACHE_PATH, JSON.stringify({ fetched_at: Date.now(), models }), { mode: 0o600 });
+    }
+    catch {
+        // a cache write failure is non-fatal
+    }
+}
+async function fetchModels(client) {
+    const raw = (await client.get('/v1/models'));
+    const data = Array.isArray(raw) ? raw : (raw.data ?? raw.models ?? []);
+    return data;
+}
+/**
+ * Return the list of catalog models, served from a short-lived on-disk cache.
+ * Falls back to a stale cache if the network fetch fails, and to an empty list
+ * if there's nothing cached — callers degrade to {@link fallbackEndpoint}.
+ */
+async function getModels(client) {
+    const cache = readCache();
+    if (cache && Date.now() - cache.fetched_at < TTL_MS)
+        return cache.models;
+    try {
+        const models = await fetchModels(client);
+        writeCache(models);
+        return models;
+    }
+    catch {
+        return cache?.models ?? [];
+    }
+}
+/** Build an id → {endpoint, freeWhenConnected} map, deduping paid/oauth twins. */
+function buildMap(models) {
+    const map = new Map();
+    for (const m of models) {
+        if (!m.id || !m.endpoint)
+            continue;
+        const existing = map.get(m.id);
+        const isOauth = m.provider === 'openai_oauth';
+        if (existing) {
+            existing.freeWhenConnected = existing.freeWhenConnected || isOauth;
+        }
+        else {
+            map.set(m.id, { endpoint: m.endpoint, freeWhenConnected: isOauth });
+        }
+    }
+    return map;
+}
+/** Read a face's default_model from the local catalog index without a network call. */
+function defaultModelFromCatalog(alias) {
+    try {
+        const entries = JSON.parse(fs.readFileSync(CATALOG_INDEX, 'utf8'));
+        const hit = entries.find((e) => e.alias === alias);
+        return hit?.default_model || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Split `alias@llm` → llm; bare `alias` → undefined. */
+export function llmFromArg(modelArg) {
+    const i = modelArg.lastIndexOf('@');
+    return i >= 0 ? modelArg.slice(i + 1) : undefined;
+}
+/**
+ * Decide which API endpoint a chat request should be posted to, driven entirely
+ * by the model catalog (GET /v1/models). For a bare alias we resolve the face's
+ * default model from the local catalog, falling back to GET /v1/faces/{alias}.
+ */
+export async function resolveEndpoint(client, modelArg) {
+    let llm = llmFromArg(modelArg);
+    if (!llm) {
+        const alias = modelArg.split('@')[0];
+        llm = defaultModelFromCatalog(alias);
+        if (!llm) {
+            try {
+                const face = (await client.get(`/v1/faces/${encodeURIComponent(alias)}`));
+                llm = face.default_model || undefined;
+            }
+            catch {
+                // fall through to heuristic
+            }
+        }
+    }
+    const map = buildMap(await getModels(client));
+    const hit = llm ? map.get(llm) : undefined;
+    if (hit)
+        return { endpoint: hit.endpoint, llm, freeWhenConnected: hit.freeWhenConnected };
+    return { endpoint: fallbackEndpoint(llm), llm, freeWhenConnected: false };
+}