faces-cli 1.6.18 → 1.7.1

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,11 +15,11 @@ 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 = {
-        face_username: Args.string({ description: 'Face alias (or alias@model)', required: true }),
+        face_username: Args.string({ description: 'Face alias (alias@model, or owner:alias@model for a published face)', required: true }),
     };
     async run() {
         const { args, flags } = await this.parse(ChatChat);
@@ -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/messages.js

@@ -12,7 +12,7 @@ export default class ChatMessages extends BaseCommand {
         'oauth-only': Flags.boolean({ description: 'Prevent fallback to paid system key (use OAuth only)', default: false }),
     };
     static args = {
-        face_model: Args.string({ description: 'Face model (e.g. myface or myface@claude-sonnet-4-6)', required: true }),
+        face_model: Args.string({ description: 'Face model (e.g. myface, myface@claude-sonnet-4-6, or head:judge@claude-sonnet-4-6)', required: true }),
     };
     async run() {
         const { args, flags } = await this.parse(ChatMessages);

package/dist/commands/chat/responses.js

@@ -11,7 +11,7 @@ export default class ChatResponses extends BaseCommand {
         'oauth-only': Flags.boolean({ description: 'Prevent fallback to paid system key (use OAuth only)', default: false }),
     };
     static args = {
-        face_model: Args.string({ description: 'Face model (e.g. myface or myface@gpt-4o)', required: true }),
+        face_model: Args.string({ description: 'Face model (e.g. myface, myface@gpt-4o, or head:logician@gpt-5.4)', required: true }),
     };
     async run() {
         const { args, flags } = await this.parse(ChatResponses);

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');
@@ -109,7 +98,7 @@ export default class ChatThread extends BaseCommand {
     };
     static args = {
         face_username: Args.string({
-            description: 'Face alias (or alias@model) — required when starting a new thread',
+            description: 'Face alias (alias@model, or owner:alias@model for a published face) — required when starting a new thread',
             required: false,
         }),
     };
@@ -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/commands/face/list.d.ts

@@ -5,6 +5,10 @@ export default class FaceList extends BaseCommand {
         tag: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
         team: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
         include: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        public: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        system: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'from-users': import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'not-from-users': import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'base-url': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         token: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'api-key': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;

package/dist/commands/face/list.js

@@ -2,17 +2,34 @@ import { Flags } from '@oclif/core';
 import { BaseCommand } from '../../base.js';
 import { FacesAPIError } from '../../client.js';
 import { renameFaceFields } from '../../utils.js';
+/** Curated system faces are served under this owner account. */
+const SYSTEM_OWNER = 'head';
 export default class FaceList extends BaseCommand {
-    static description = 'List all owned faces';
+    static description = 'List faces. By default lists owned faces; use --public to include published faces from other accounts.';
     static flags = {
         ...BaseCommand.baseFlags,
         tag: Flags.string({ description: 'Filter by tag (repeatable, AND logic)', multiple: true }),
         team: Flags.string({ description: 'Filter by team ID (repeatable, OR logic)', multiple: true }),
         include: Flags.string({ description: 'Include extra fields: tags, teams (comma-separated)' }),
+        public: Flags.boolean({ description: 'Include published faces from other accounts' }),
+        system: Flags.boolean({ description: `Show only the curated system faces (published faces owned by '${SYSTEM_OWNER}')` }),
+        'from-users': Flags.string({ description: 'Only published faces from these owners (repeatable/comma-separated)', multiple: true }),
+        'not-from-users': Flags.string({ description: 'Exclude published faces from these owners (repeatable/comma-separated)', multiple: true }),
     };
     async run() {
         const { flags } = await this.parse(FaceList);
         const client = this.makeClient(flags);
+        // Split comma-separated owner lists into individual values.
+        const split = (vals) => (vals ?? []).flatMap(v => v.split(',')).map(v => v.trim()).filter(Boolean);
+        const fromUsers = split(flags['from-users']);
+        if (flags.system)
+            fromUsers.push(SYSTEM_OWNER);
+        const notFromUsers = split(flags['not-from-users']);
+        if (fromUsers.length > 0 && notFromUsers.length > 0) {
+            this.error('--from-users and --not-from-users are mutually exclusive');
+        }
+        // Any cross-account owner filter implies we want published faces.
+        const includePublished = flags.public || flags.system || fromUsers.length > 0 || notFromUsers.length > 0;
         // Build query string manually for repeated params
         const parts = [];
         if (flags.tag && flags.tag.length > 0) {
@@ -25,6 +42,12 @@ export default class FaceList extends BaseCommand {
         }
         if (flags.include)
             parts.push(`include=${encodeURIComponent(flags.include)}`);
+        if (includePublished)
+            parts.push('include_published=true');
+        for (const u of fromUsers)
+            parts.push(`from_users=${encodeURIComponent(u)}`);
+        for (const u of notFromUsers)
+            parts.push(`not_from_users=${encodeURIComponent(u)}`);
         let data;
         try {
             const path = parts.length > 0 ? `/v1/faces?${parts.join('&')}` : '/v1/faces';
@@ -40,13 +63,31 @@ export default class FaceList extends BaseCommand {
         for (const f of raw) {
             renameFaceFields(f);
         }
+        // The API's from_users/not_from_users only constrain the *appended published*
+        // set — the caller's own faces always come back. Filter client-side so
+        // --system / --from-users / --not-from-users actually mean "from these owners".
+        let faces = raw;
+        if (fromUsers.length > 0) {
+            const allow = new Set(fromUsers);
+            faces = faces.filter(f => f.owned_by != null && allow.has(f.owned_by));
+        }
+        else if (notFromUsers.length > 0) {
+            const block = new Set(notFromUsers);
+            faces = faces.filter(f => f.owned_by == null || !block.has(f.owned_by));
+        }
+        // Keep --json output consistent with what we display.
+        if (data.data !== undefined)
+            data.data = faces;
+        else
+            data = faces;
         if (!this.jsonEnabled()) {
-            const faces = raw;
+            // Published faces are chatted as `owner:alias`; own faces stay bare.
+            const handle = (f) => f.published && f.owned_by ? `${f.owned_by}:${f.alias}` : f.alias;
             if (faces.length === 0) {
                 this.log('(no faces)');
             }
             else {
-                const aliasWidth = Math.max(...faces.map(f => f.alias.length));
+                const handleWidth = Math.max(...faces.map(f => handle(f).length));
                 const nameWidth = Math.max(...faces.map(f => f.name.length));
                 for (const f of faces) {
                     let suffix = '';
@@ -59,7 +100,9 @@ export default class FaceList extends BaseCommand {
                         const profile = f.profile_token_count ?? 0;
                         suffix = `  [profile: ${profile} tok, components: ${total}]`;
                     }
-                    this.log(`${f.alias.padEnd(aliasWidth)}  ${f.name.padEnd(nameWidth)}${suffix}`);
+                    if (f.published)
+                        suffix += '  [public · requires @model]';
+                    this.log(`${handle(f).padEnd(handleWidth)}  ${f.name.padEnd(nameWidth)}${suffix}`);
                 }
             }
         }