faces-cli 1.7.1 → 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 (alias@model, or owner:alias@model for a published face)', 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/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) {