faces-cli 1.7.0 → 1.7.2

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

@@ -1,9 +1,11 @@
 import { BaseCommand } from '../../base.js';
 export default class ChatChat extends BaseCommand {
     static description: string;
+    static examples: string[];
     static flags: {
         message: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
         llm: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        formula: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         system: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         stream: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'max-tokens': import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
@@ -16,7 +18,7 @@ export default class ChatChat extends BaseCommand {
         'api-key': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     static args: {
-        face_username: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+        face_username: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
     };
     run(): Promise<unknown>;
     private oauthHint;

package/dist/commands/chat/chat.js

@@ -3,13 +3,19 @@ import fs from 'node:fs';
 import { BaseCommand } from '../../base.js';
 import { FacesAPIError } from '../../client.js';
 import { extractStreamDelta } from '../../utils.js';
-import { resolveEndpoint, MESSAGES_ENDPOINT, RESPONSES_ENDPOINT } from '../../routing.js';
+import { resolveEndpoint, MESSAGES_ENDPOINT, RESPONSES_ENDPOINT, isCompositeFormula, faceSpecOf, llmFromArg } from '../../routing.js';
 export default class ChatChat extends BaseCommand {
     static description = 'Chat via a face. Auto-routes to the correct API endpoint based on the model catalog.';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> socrates -m "What is virtue?"',
+        '<%= config.bin %> <%= command.id %> "(socrates | nietzsche)@claude-sonnet-4-6" -m "What is virtue?"',
+        '<%= config.bin %> <%= command.id %> --formula "socrates | nietzsche" --llm claude-sonnet-4-6 -m "What is virtue?"',
+    ];
     static flags = {
         ...BaseCommand.baseFlags,
         message: Flags.string({ char: 'm', description: 'User message (repeatable)', multiple: true, required: false }),
         llm: Flags.string({ description: 'LLM override (e.g. gpt-4o-mini, claude-sonnet-4-6)' }),
+        formula: Flags.string({ description: 'Compose a run-time composite from your own faces, e.g. "socrates | nietzsche" (operators: | & ^ -). Requires --llm.' }),
         system: Flags.string({ description: 'System prompt / instructions' }),
         stream: Flags.boolean({ description: 'Stream the response', default: false }),
         'max-tokens': Flags.integer({ description: 'Max tokens' }),
@@ -19,20 +25,39 @@ export default class ChatChat extends BaseCommand {
         '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, owner:alias@model for a published face, or a composite formula like "(a | b)@model"). Omit when using --formula.',
+            required: false,
+        }),
     };
     async run() {
         const { args, flags } = await this.parse(ChatChat);
         const client = this.makeClient(flags);
         // Build model string
         let model;
-        if (flags.llm) {
-            const base = args.face_username.split('@')[0];
+        if (flags.formula) {
+            if (args.face_username)
+                this.error('Pass either a face argument or --formula, not both.');
+            if (!flags.llm)
+                this.error('--formula needs a model. Add --llm <model>, e.g. --llm claude-sonnet-4-6.');
+            model = `(${flags.formula.trim()})@${flags.llm}`;
+        }
+        else if (!args.face_username) {
+            this.error('Provide a face (alias, owner:alias, or a composite formula), or use --formula.');
+        }
+        else if (flags.llm) {
+            const base = faceSpecOf(args.face_username);
             model = `${base}@${flags.llm}`;
         }
         else {
             model = args.face_username;
         }
+        // A run-time composite has no stored default_model — require an explicit @model (rule #1).
+        if (isCompositeFormula(model) && !llmFromArg(model)) {
+            const spec = faceSpecOf(model);
+            this.error(`Composite face '${spec}' has no default model. Specify one explicitly, ` +
+                `e.g. '${spec}@claude-sonnet-4-6', or pass --llm <model>.`);
+        }
         // Collect user messages
         const userMessages = [];
         if (flags.file) {

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.js

@@ -98,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,
         }),
     };

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}`);
                 }
             }
         }

package/dist/routing.d.ts

@@ -11,6 +11,15 @@ export interface RouteInfo {
 }
 /** Split `alias@llm` → llm; bare `alias` → undefined. */
 export declare function llmFromArg(modelArg: string): string | undefined;
+/** The face-spec (everything left of the trailing `@model`), e.g. `(a | b)@x` → `(a | b)`. */
+export declare function faceSpecOf(modelArg: string): string;
+/**
+ * True when a model arg's face-spec is a run-time composite formula, i.e. it
+ * contains a set operator (`| & ^`), grouping parens, or a space-delimited `-`
+ * difference. None of these characters are legal in an alias (`^[a-z0-9-]+$`) or
+ * in `owner:alias`, so detection is unambiguous. Mirrors the backend's check.
+ */
+export declare function isCompositeFormula(modelArg: string): boolean;
 /**
  * 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

package/dist/routing.js

@@ -88,6 +88,21 @@ export function llmFromArg(modelArg) {
     const i = modelArg.lastIndexOf('@');
     return i >= 0 ? modelArg.slice(i + 1) : undefined;
 }
+/** The face-spec (everything left of the trailing `@model`), e.g. `(a | b)@x` → `(a | b)`. */
+export function faceSpecOf(modelArg) {
+    const i = modelArg.lastIndexOf('@');
+    return i >= 0 ? modelArg.slice(0, i) : modelArg;
+}
+/**
+ * True when a model arg's face-spec is a run-time composite formula, i.e. it
+ * contains a set operator (`| & ^`), grouping parens, or a space-delimited `-`
+ * difference. None of these characters are legal in an alias (`^[a-z0-9-]+$`) or
+ * in `owner:alias`, so detection is unambiguous. Mirrors the backend's check.
+ */
+export function isCompositeFormula(modelArg) {
+    const spec = faceSpecOf(modelArg).trim();
+    return /[|&^()]/.test(spec) || /\S\s+\S/.test(spec);
+}
 /**
  * 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
@@ -95,7 +110,9 @@ export function llmFromArg(modelArg) {
  */
 export async function resolveEndpoint(client, modelArg) {
     let llm = llmFromArg(modelArg);
-    if (!llm) {
+    // A composite formula has no stored default_model and isn't a catalog face, so
+    // never attempt an alias lookup — route purely off the explicit `@model`.
+    if (!llm && !isCompositeFormula(modelArg)) {
         const alias = modelArg.split('@')[0];
         llm = defaultModelFromCatalog(alias);
         if (!llm) {