faces-cli 1.6.15 → 1.6.17

package/dist/commands/chat/chat.js

@@ -2,6 +2,7 @@ import { Args, Flags } from '@oclif/core';
 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('@');
@@ -91,18 +92,18 @@ 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]')
-                    break;
+                if (chunk.trim() === '[DONE]' || chunk.trim() === '')
+                    continue;
                 try {
-                    const parsed = JSON.parse(chunk);
-                    const choices = parsed?.choices;
-                    const delta = choices?.[0]?.delta?.content ?? '';
+                    const delta = extractStreamDelta(JSON.parse(chunk));
                     if (delta)
-                        process.stdout.write(String(delta));
+                        process.stdout.write(delta);
                 }
                 catch { /* ignore parse errors */ }
             }
@@ -149,12 +150,9 @@ export default class ChatChat extends BaseCommand {
                 if (chunk.trim() === '[DONE]' || chunk.trim() === '')
                     continue;
                 try {
-                    const obj = JSON.parse(chunk);
-                    if (obj.type === 'content_block_delta') {
-                        const delta = obj.delta?.text ?? '';
-                        if (delta)
-                            process.stdout.write(String(delta));
-                    }
+                    const delta = extractStreamDelta(JSON.parse(chunk));
+                    if (delta)
+                        process.stdout.write(delta);
                 }
                 catch { /* ignore */ }
             }
@@ -195,12 +193,9 @@ export default class ChatChat extends BaseCommand {
                 if (chunk.trim() === '[DONE]' || chunk.trim() === '')
                     continue;
                 try {
-                    const obj = JSON.parse(chunk);
-                    if (obj.type === 'response.output_text.delta') {
-                        const delta = obj.delta ?? '';
-                        if (delta)
-                            process.stdout.write(String(delta));
-                    }
+                    const delta = extractStreamDelta(JSON.parse(chunk));
+                    if (delta)
+                        process.stdout.write(delta);
                 }
                 catch { /* ignore */ }
             }

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

@@ -0,0 +1,38 @@
+import { BaseCommand } from '../../base.js';
+export default class ChatThread extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        id: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        message: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        file: 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>;
+        system: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'max-tokens': import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        temperature: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        stream: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'oauth-only': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        list: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        show: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        delete: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        '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>;
+    };
+    static args: {
+        face_username: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
+    };
+    run(): Promise<unknown>;
+    private handleList;
+    private handleDelete;
+    private handleShow;
+    private handleMessage;
+    private sendOpenAI;
+    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.
+     */
+    private streamAndAccumulate;
+}

package/dist/commands/chat/thread.js

@@ -0,0 +1,325 @@
+import { Args, Flags } from '@oclif/core';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { BaseCommand } from '../../base.js';
+import { FacesAPIError } from '../../client.js';
+import { extractStreamDelta } from '../../utils.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
+ * 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')) {
+        let text = '';
+        for (const block of body.content ?? []) {
+            if (block.type === 'text')
+                text += String(block.text ?? '');
+        }
+        if (text)
+            return text;
+    }
+    // OpenAI Responses shape: { output: [{content: [{type:'output_text', text}]}] }
+    if (routedEndpoint === '/v1/responses' || Array.isArray(body.output)) {
+        let text = '';
+        for (const item of body.output ?? []) {
+            for (const block of item.content ?? []) {
+                if (block.type === 'output_text')
+                    text += String(block.text ?? '');
+            }
+        }
+        if (text)
+            return text;
+    }
+    // Standard Chat Completions shape: { choices: [{message: {content}}] }
+    const choices = body.choices;
+    const message = choices?.[0]?.message;
+    return String(message?.content ?? '');
+}
+function newThreadId() {
+    return 't_' + crypto.randomBytes(6).toString('hex');
+}
+function threadPath(id) {
+    return path.join(THREADS_DIR, `${id}.json`);
+}
+function ensureThreadsDir() {
+    if (!fs.existsSync(THREADS_DIR))
+        fs.mkdirSync(THREADS_DIR, { recursive: true, mode: 0o700 });
+}
+function loadThread(id) {
+    const p = threadPath(id);
+    if (!fs.existsSync(p))
+        return null;
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+}
+function saveThread(t) {
+    ensureThreadsDir();
+    t.updated_at = new Date().toISOString();
+    fs.writeFileSync(threadPath(t.id), JSON.stringify(t, null, 2), { mode: 0o600 });
+}
+function listThreads() {
+    if (!fs.existsSync(THREADS_DIR))
+        return [];
+    const out = [];
+    for (const f of fs.readdirSync(THREADS_DIR)) {
+        if (!f.endsWith('.json'))
+            continue;
+        try {
+            out.push(JSON.parse(fs.readFileSync(path.join(THREADS_DIR, f), 'utf8')));
+        }
+        catch { /* skip corrupt */ }
+    }
+    out.sort((a, b) => (b.updated_at ?? '').localeCompare(a.updated_at ?? ''));
+    return out;
+}
+export default class ChatThread extends BaseCommand {
+    static description = 'Multi-turn chat thread. Conversation history is stored under ~/.faces/threads/<id>.json — resume any thread later with --id.';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> socrates -m "What is justice?"',
+        '<%= config.bin %> <%= command.id %> --id t_abc123 -m "Say more about that"',
+        '<%= config.bin %> <%= command.id %> --list',
+        '<%= config.bin %> <%= command.id %> --id t_abc123 --show',
+        '<%= config.bin %> <%= command.id %> --id t_abc123 --delete',
+    ];
+    static flags = {
+        ...BaseCommand.baseFlags,
+        id: Flags.string({ description: 'Resume an existing thread by id' }),
+        message: Flags.string({ char: 'm', description: 'User message' }),
+        file: Flags.string({ description: 'Read message from file' }),
+        llm: Flags.string({ description: 'LLM override (only honored when starting a new thread)' }),
+        system: Flags.string({ description: 'System prompt (only honored when starting a new thread)' }),
+        'max-tokens': Flags.integer({ description: 'Max tokens' }),
+        temperature: Flags.string({ description: 'Temperature (0.0-2.0, OpenAI/Chat Completions only)' }),
+        stream: Flags.boolean({ description: 'Stream the response', default: false }),
+        'oauth-only': Flags.boolean({ description: 'Prevent fallback to paid system key', default: false }),
+        list: Flags.boolean({ description: 'List saved threads', default: false }),
+        show: Flags.boolean({ description: 'Show the thread transcript (requires --id)', default: false }),
+        delete: Flags.boolean({ description: 'Delete the thread (requires --id)', default: false }),
+    };
+    static args = {
+        face_username: Args.string({
+            description: 'Face alias (or alias@model) — required when starting a new thread',
+            required: false,
+        }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(ChatThread);
+        if (flags.list)
+            return this.handleList();
+        if (flags.delete)
+            return this.handleDelete(flags.id);
+        if (flags.show)
+            return this.handleShow(flags.id);
+        return this.handleMessage(args.face_username, flags);
+    }
+    handleList() {
+        const threads = listThreads();
+        if (this.jsonEnabled()) {
+            return threads.map((t) => ({
+                id: t.id,
+                face: t.face_username,
+                model: t.model,
+                turns: t.messages.length,
+                created_at: t.created_at,
+                updated_at: t.updated_at,
+            }));
+        }
+        if (threads.length === 0) {
+            this.log('(no threads)');
+            return {};
+        }
+        for (const t of threads) {
+            const last = t.messages[t.messages.length - 1];
+            const preview = last
+                ? last.content.slice(0, 60).replace(/\s+/g, ' ') + (last.content.length > 60 ? '…' : '')
+                : '';
+            this.log(`${t.id}  ${t.model}  (${t.messages.length} turns, updated ${t.updated_at})`);
+            if (preview)
+                this.log(`  ${last.role}: ${preview}`);
+        }
+        return {};
+    }
+    handleDelete(id) {
+        if (!id)
+            this.error('--delete requires --id <thread-id>');
+        const p = threadPath(id);
+        if (!fs.existsSync(p))
+            this.error(`Thread not found: ${id}`);
+        fs.unlinkSync(p);
+        if (this.jsonEnabled())
+            return { deleted: id };
+        this.log(`Deleted thread ${id}`);
+        return { deleted: id };
+    }
+    handleShow(id) {
+        if (!id)
+            this.error('--show requires --id <thread-id>');
+        const t = loadThread(id);
+        if (!t)
+            this.error(`Thread not found: ${id}`);
+        if (this.jsonEnabled())
+            return t;
+        this.log(`Thread ${t.id}  (${t.model}, provider=${t.provider})`);
+        this.log(`Created: ${t.created_at}`);
+        this.log(`Updated: ${t.updated_at}`);
+        if (t.system) {
+            this.log('---');
+            this.log(`system: ${t.system}`);
+        }
+        for (const m of t.messages) {
+            this.log('---');
+            this.log(`${m.role} [${m.ts}]:`);
+            this.log(m.content);
+        }
+        return t;
+    }
+    async handleMessage(face_username, flags) {
+        let userMessage;
+        if (flags.file) {
+            if (!fs.existsSync(flags.file))
+                this.error(`File not found: ${flags.file}`);
+            userMessage = fs.readFileSync(flags.file, 'utf8');
+        }
+        else if (flags.message) {
+            userMessage = flags.message;
+        }
+        else {
+            this.error('Provide --message/-m or --file');
+        }
+        const client = this.makeClient(flags);
+        let thread;
+        if (flags.id) {
+            const existing = loadThread(flags.id);
+            if (!existing)
+                this.error(`Thread not found: ${flags.id}`);
+            thread = existing;
+            if (flags.llm || flags.system) {
+                this.warn('--llm and --system are ignored when resuming a thread; using values stored on the thread');
+            }
+        }
+        else {
+            if (!face_username) {
+                this.error('Provide a face (e.g. `faces chat:thread socrates -m "…"`) or --id <thread-id> to resume');
+            }
+            const baseAlias = face_username.split('@')[0];
+            const model = flags.llm ? `${baseAlias}@${flags.llm}` : face_username;
+            const now = new Date().toISOString();
+            thread = {
+                id: newThreadId(),
+                face_username: baseAlias,
+                model,
+                provider: isAnthropicModel(model) ? 'anthropic' : 'openai',
+                system: flags.system,
+                created_at: now,
+                updated_at: now,
+                messages: [],
+            };
+        }
+        thread.messages.push({ role: 'user', content: userMessage, ts: new Date().toISOString() });
+        try {
+            const assistantText = thread.provider === 'anthropic'
+                ? await this.sendAnthropic(client, thread, flags)
+                : await this.sendOpenAI(client, thread, flags);
+            thread.messages.push({ role: 'assistant', content: assistantText, ts: new Date().toISOString() });
+            saveThread(thread);
+            if (this.jsonEnabled()) {
+                return {
+                    thread_id: thread.id,
+                    model: thread.model,
+                    provider: thread.provider,
+                    assistant: assistantText,
+                    turns: thread.messages.length,
+                };
+            }
+            if (!flags.stream)
+                this.log(assistantText);
+            this.log(`\n[thread ${thread.id}  ·  ${thread.messages.length} turns]`);
+            return { thread_id: thread.id, assistant: assistantText };
+        }
+        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}`);
+                }
+                this.error(`Error (${err.statusCode}): ${err.message}`);
+            }
+            throw err;
+        }
+    }
+    async sendOpenAI(client, thread, flags) {
+        const messages = [];
+        if (thread.system)
+            messages.push({ role: 'system', content: thread.system });
+        for (const m of thread.messages)
+            messages.push({ role: m.role, content: m.content });
+        const payload = { model: thread.model, messages, stream: flags.stream };
+        if (flags['max-tokens'])
+            payload.max_tokens = flags['max-tokens'];
+        if (flags.temperature !== undefined)
+            payload.temperature = Number.parseFloat(flags.temperature);
+        if (flags['oauth-only'])
+            payload.oauth_only = true;
+        if (flags.stream) {
+            return this.streamAndAccumulate(client, '/v1/chat/completions', payload);
+        }
+        const { data, headers } = await client.postWithHeaders('/v1/chat/completions', { body: payload });
+        return extractAssistantText(data, headers['x-faces-routed-endpoint']);
+    }
+    async sendAnthropic(client, thread, flags) {
+        const msgs = thread.messages.map((m) => ({ role: m.role, content: m.content }));
+        const payload = {
+            model: thread.model,
+            messages: msgs,
+            max_tokens: flags['max-tokens'] ?? 1024,
+            stream: flags.stream,
+        };
+        if (thread.system)
+            payload.system = thread.system;
+        if (flags['oauth-only'])
+            payload.oauth_only = true;
+        if (flags.stream) {
+            return this.streamAndAccumulate(client, '/v1/messages', payload);
+        }
+        const { data, headers } = await client.postWithHeaders('/v1/messages', { body: payload });
+        return extractAssistantText(data, headers['x-faces-routed-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.
+     */
+    async streamAndAccumulate(client, endpoint, payload) {
+        let accum = '';
+        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) {
+                    accum += delta;
+                    process.stdout.write(delta);
+                }
+            }
+            catch { /* ignore parse errors */ }
+        }
+        process.stdout.write('\n');
+        return accum;
+    }
+}

package/dist/commands/keys/create.d.ts

@@ -7,6 +7,7 @@ export default class KeysCreate extends BaseCommand {
         budget: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         face: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
         model: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        save: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         '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/keys/create.js

@@ -1,8 +1,9 @@
 import { Flags } from '@oclif/core';
 import { BaseCommand } from '../../base.js';
 import { FacesAPIError } from '../../client.js';
+import { saveConfig } from '../../config.js';
 export default class KeysCreate extends BaseCommand {
-    static description = 'Create a new API key (JWT required)';
+    static description = 'Create a new API key (JWT required). The new key is saved to ~/.faces/config.json as api_key by default; pass --no-save to skip.';
     static flags = {
         ...BaseCommand.baseFlags,
         name: Flags.string({ description: 'Key name/label', required: true }),
@@ -10,6 +11,11 @@ export default class KeysCreate extends BaseCommand {
         budget: Flags.string({ description: 'Spend budget in USD' }),
         face: Flags.string({ description: 'Allowed face alias (repeatable)', multiple: true }),
         model: Flags.string({ description: 'Allowed model name (repeatable)', multiple: true }),
+        save: Flags.boolean({
+            description: 'Save the new key to ~/.faces/config.json as api_key (default: true; use --no-save to skip)',
+            default: true,
+            allowNo: true,
+        }),
     };
     async run() {
         const { flags } = await this.parse(KeysCreate);
@@ -25,15 +31,40 @@ export default class KeysCreate extends BaseCommand {
             payload.allowed_models = flags.model;
         let data;
         try {
-            data = await client.post('/v1/auth/api-keys', { requireJwt: true, body: payload });
+            data = (await client.post('/v1/auth/api-keys', {
+                requireJwt: true,
+                body: payload,
+            }));
         }
         catch (err) {
             if (err instanceof FacesAPIError)
                 this.error(`Error (${err.statusCode}): ${err.message}`);
             throw err;
         }
-        if (!this.jsonEnabled())
-            this.printHuman(data);
+        // The plaintext secret is returned exactly once — here. keys:list only ever
+        // returns it truncated, so it must be saved or copied now.
+        const apiKey = (data.key ?? data.api_key ?? data.secret);
+        let saved = false;
+        if (flags.save && apiKey) {
+            saveConfig({ api_key: apiKey });
+            saved = true;
+        }
+        if (this.jsonEnabled()) {
+            data._saved_to_config = saved;
+            return data;
+        }
+        this.printHuman(data);
+        this.log('');
+        this.log('⚠  The full key is shown only once — `faces keys:list` returns it truncated by design.');
+        if (saved) {
+            this.log('✓  Saved to ~/.faces/config.json as api_key — faces commands will use it automatically.');
+        }
+        else if (!flags.save) {
+            this.log('   Not saved (--no-save). Copy the key above now.');
+        }
+        else {
+            this.warn('Could not find the key in the response — nothing was saved. Copy it manually.');
+        }
         return data;
     }
 }

package/dist/utils.d.ts

@@ -10,3 +10,13 @@ export declare const flattenBasicFacts: typeof flattenAttributes;
  * Mutates the object in place and returns it.
  */
 export declare function renameFaceFields(face: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Extract a streamed text delta from a parsed SSE event, regardless of which
+ * API family produced it. A request posted to /v1/chat/completions may be
+ * re-routed by the backend to /v1/messages or /v1/responses, so a stream
+ * consumer must handle all three event shapes:
+ *   - Anthropic Messages:    { type: 'content_block_delta', delta: {text} }
+ *   - OpenAI Responses:      { type: 'response.output_text.delta', delta }
+ *   - OpenAI Chat Completions: { choices: [{delta: {content}}] }
+ */
+export declare function extractStreamDelta(parsed: Record<string, unknown>): string;

package/dist/utils.js

@@ -29,3 +29,22 @@ export function renameFaceFields(face) {
     }
     return face;
 }
+/**
+ * Extract a streamed text delta from a parsed SSE event, regardless of which
+ * API family produced it. A request posted to /v1/chat/completions may be
+ * re-routed by the backend to /v1/messages or /v1/responses, so a stream
+ * consumer must handle all three event shapes:
+ *   - Anthropic Messages:    { type: 'content_block_delta', delta: {text} }
+ *   - OpenAI Responses:      { type: 'response.output_text.delta', delta }
+ *   - OpenAI Chat Completions: { choices: [{delta: {content}}] }
+ */
+export function extractStreamDelta(parsed) {
+    if (parsed.type === 'content_block_delta') {
+        return String(parsed.delta?.text ?? '');
+    }
+    if (parsed.type === 'response.output_text.delta') {
+        return String(parsed.delta ?? '');
+    }
+    const choices = parsed.choices;
+    return String(choices?.[0]?.delta?.content ?? '');
+}