faces-cli 1.7.3 → 1.7.5

package/dist/base.js

@@ -47,6 +47,12 @@ export class BaseCommand extends Command {
         }
         else if (data !== null && typeof data === 'object') {
             for (const [k, v] of Object.entries(data)) {
+                // read_only: only surface when set; render as a bare marker, never "read_only: false"
+                if (k === 'read_only') {
+                    if (v)
+                        this.log(`${prefix}read only`);
+                    continue;
+                }
                 if (v !== null && typeof v === 'object') {
                     this.log(`${prefix}${k}:`);
                     this.printHuman(v, indent + 1);

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

@@ -10,6 +10,8 @@ export default class FaceCreate extends BaseCommand {
         formula: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         attr: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
         tool: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'profile-addendum': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'profile-addendum-file': 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/create.js

@@ -2,7 +2,7 @@ import { Flags } from '@oclif/core';
 import { BaseCommand } from '../../base.js';
 import { FacesAPIError } from '../../client.js';
 import { CatalogService } from '../../catalog.js';
-import { renameFaceFields } from '../../utils.js';
+import { renameFaceFields, resolveProfileAddendum } from '../../utils.js';
 export default class FaceCreate extends BaseCommand {
     static description = 'Create a new face';
     static flags = {
@@ -15,6 +15,8 @@ export default class FaceCreate extends BaseCommand {
         formula: Flags.string({ description: 'Boolean formula over owned concrete face aliases (e.g. "a | b", "(a | b) - c"). Creates a composite face.' }),
         attr: Flags.string({ description: 'Attribute KEY=VALUE (repeatable)', multiple: true }),
         tool: Flags.string({ description: 'Tool name to enable (repeatable)', multiple: true }),
+        'profile-addendum': Flags.string({ description: 'Per-face system prompt, injected after the persona profile and before any per-request system prompt (max 100,000 chars).' }),
+        'profile-addendum-file': Flags.string({ description: 'Read the per-face system prompt from a file (alternative to --profile-addendum).', exclusive: ['profile-addendum'] }),
     };
     static args = {};
     async run() {
@@ -26,6 +28,15 @@ export default class FaceCreate extends BaseCommand {
         const payload = { name: flags.name, alias: flags.alias };
         if (flags.description)
             payload.description = flags.description;
+        let addendum;
+        try {
+            addendum = resolveProfileAddendum(flags['profile-addendum'], flags['profile-addendum-file']);
+        }
+        catch (err) {
+            this.error(err instanceof Error ? err.message : String(err));
+        }
+        if (addendum !== undefined)
+            payload.profile_addendum = addendum;
         if (flags.formula) {
             payload.formula = flags.formula;
             if (flags['default-model'])

package/dist/commands/face/edit.d.ts

@@ -9,6 +9,9 @@ export default class FaceEdit extends BaseCommand {
         formula: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         attr: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
         tool: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'profile-addendum': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'profile-addendum-file': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'clear-profile-addendum': 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/face/edit.js

@@ -2,7 +2,7 @@ import { Args, Flags } from '@oclif/core';
 import { BaseCommand } from '../../base.js';
 import { FacesAPIError } from '../../client.js';
 import { CatalogService } from '../../catalog.js';
-import { renameFaceFields } from '../../utils.js';
+import { renameFaceFields, resolveProfileAddendum } from '../../utils.js';
 export default class FaceEdit extends BaseCommand {
     static description = "Edit a face's metadata";
     static flags = {
@@ -14,6 +14,9 @@ export default class FaceEdit extends BaseCommand {
         formula: Flags.string({ description: 'New boolean formula (synthetic faces only)' }),
         attr: Flags.string({ description: 'Update attribute KEY=VALUE (repeatable)', multiple: true }),
         tool: Flags.string({ description: 'Tool names to set (replaces list, repeatable)', multiple: true }),
+        'profile-addendum': Flags.string({ description: 'Replace the per-face system prompt (max 100,000 chars).' }),
+        'profile-addendum-file': Flags.string({ description: 'Replace the per-face system prompt from a file.', exclusive: ['profile-addendum'] }),
+        'clear-profile-addendum': Flags.boolean({ description: 'Remove the per-face system prompt.', exclusive: ['profile-addendum', 'profile-addendum-file'] }),
     };
     static args = {
         face_id: Args.string({ description: 'Face alias', required: true }),
@@ -42,6 +45,20 @@ export default class FaceEdit extends BaseCommand {
             payload.default_model = flags['default-model'];
         if (flags.description !== undefined)
             payload.description = flags.description;
+        if (flags['clear-profile-addendum']) {
+            payload.profile_addendum = '';
+        }
+        else {
+            let addendum;
+            try {
+                addendum = resolveProfileAddendum(flags['profile-addendum'], flags['profile-addendum-file']);
+            }
+            catch (err) {
+                this.error(err instanceof Error ? err.message : String(err));
+            }
+            if (addendum !== undefined)
+                payload.profile_addendum = addendum;
+        }
         const hasTags = flags.tag && flags.tag.length > 0;
         if (Object.keys(payload).length === 0 && !hasTags)
             this.error('Provide at least one field to update.');

package/dist/commands/face/get.d.ts

@@ -3,6 +3,7 @@ export default class FaceGet extends BaseCommand {
     static description: string;
     static flags: {
         include: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        full: 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/face/get.js

@@ -7,6 +7,7 @@ export default class FaceGet extends BaseCommand {
     static flags = {
         ...BaseCommand.baseFlags,
         include: Flags.string({ description: 'Include extra fields: tags, teams (comma-separated)' }),
+        full: Flags.boolean({ description: 'Print the full profile_addendum instead of a truncated preview' }),
     };
     static args = {
         face_id: Args.string({ description: 'Face alias', required: true }),
@@ -55,6 +56,20 @@ export default class FaceGet extends BaseCommand {
                 if (f.default_model)
                     this.log(`default_model: ${f.default_model}`);
             }
+            if (f.profile_addendum) {
+                const text = f.profile_addendum;
+                if (flags.full) {
+                    this.log(`profile_addendum (${text.length} chars):`);
+                    this.log(text);
+                }
+                else {
+                    const oneLine = text.replace(/\s+/g, ' ').trim();
+                    const preview = oneLine.length > 160 ? `${oneLine.slice(0, 160)}…` : oneLine;
+                    this.log(`profile_addendum (${text.length} chars): ${preview}`);
+                    if (oneLine.length > 160)
+                        this.log('  (use --full to print the whole prompt)');
+                }
+            }
         }
         return data;
     }

package/dist/commands/voiceprint/build-status.d.ts

@@ -0,0 +1,14 @@
+import { BaseCommand } from '../../base.js';
+export default class VoiceprintBuildStatus extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        '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: {
+        job_id: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    run(): Promise<unknown>;
+}

package/dist/commands/voiceprint/build-status.js

@@ -0,0 +1,46 @@
+import { Args } from '@oclif/core';
+import { BaseCommand } from '../../base.js';
+import { FacesAPIError } from '../../client.js';
+import { jobFailureMessage } from '../../voiceprint.js';
+import { printBuildReport } from './build.js';
+export default class VoiceprintBuildStatus extends BaseCommand {
+    static description = 'Get the status/result of a voiceprint build job (from voiceprint:build without --wait)';
+    static examples = ['<%= config.bin %> <%= command.id %> 4e13bf03-fbc1-4ad0-92ae-16984e2f9a1d'];
+    static flags = { ...BaseCommand.baseFlags };
+    static args = {
+        job_id: Args.string({ description: 'Build job id', required: true }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(VoiceprintBuildStatus);
+        const client = this.makeClient(flags);
+        let data;
+        try {
+            data = (await client.get(`/v1/voiceprint/builds/${encodeURIComponent(args.job_id)}`));
+        }
+        catch (err) {
+            if (err instanceof FacesAPIError)
+                this.error(`Error (${err.statusCode}): ${err.message}`);
+            throw err;
+        }
+        if (this.jsonEnabled())
+            return data;
+        const status = String(data.status ?? 'unknown');
+        if (status === 'failed') {
+            this.log(`job:    ${args.job_id}`);
+            this.log(`status: failed`);
+            this.log(`error:  ${jobFailureMessage(data.error)}`);
+        }
+        else if (status === 'done') {
+            printBuildReport(this, args.job_id, data);
+        }
+        else {
+            const p = data.progress;
+            this.log(`job:    ${args.job_id}`);
+            this.log(`status: ${status}`);
+            if (p?.stage)
+                this.log(`stage:  ${p.stage}${p.total ? ` ${p.done}/${p.total}` : ''}`);
+            this.log(`(still running — poll again with: faces voiceprint:build-status ${args.job_id})`);
+        }
+        return data;
+    }
+}

package/dist/commands/voiceprint/build.d.ts

@@ -0,0 +1,23 @@
+import { BaseCommand } from '../../base.js';
+export default class VoiceprintBuild extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        model: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'holdout-count': import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'min-valid': import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'oauth-only': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        wait: 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: {
+        self_alias: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    run(): Promise<unknown>;
+}
+/** Shared build-report formatter (used by voiceprint:build --wait and voiceprint:build-status). */
+export declare function printBuildReport(cmd: {
+    log: (m: string) => void;
+}, jobId: string, data: Record<string, unknown>): void;

package/dist/commands/voiceprint/build.js

@@ -0,0 +1,109 @@
+import { Args, Flags } from '@oclif/core';
+import { BaseCommand } from '../../base.js';
+import { FacesAPIError } from '../../client.js';
+import { pollVoiceprintJob, jobFailureMessage } from '../../voiceprint.js';
+export default class VoiceprintBuild extends BaseCommand {
+    static description = "Build a self face's voice map from its uploaded corpus. Auto-creates the hidden <self>-voiceprint face and installs the map. Async — use --wait to block.";
+    static examples = [
+        '<%= config.bin %> <%= command.id %> alice --wait',
+        '<%= config.bin %> <%= command.id %> alice --holdout-count 120 --oauth-only --wait',
+    ];
+    static flags = {
+        ...BaseCommand.baseFlags,
+        model: Flags.string({ description: 'Model that forges the voice map (default: gpt-5.4)' }),
+        'holdout-count': Flags.integer({ description: 'Stratified scoring holdout size (default: 120)' }),
+        'min-valid': Flags.integer({ description: 'Corpus floor below which no holdout is split — train on all (default: 550)' }),
+        'oauth-only': Flags.boolean({ description: 'Only run on a free (OAuth) route; never fall back to billed inference', default: false }),
+        wait: Flags.boolean({ description: 'Block and poll until the build finishes (default: print the job_id and return)', default: false }),
+    };
+    static args = {
+        self_alias: Args.string({ description: 'Self face alias', required: true }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(VoiceprintBuild);
+        const client = this.makeClient(flags);
+        const json = this.jsonEnabled();
+        const payload = { self_face: args.self_alias };
+        if (flags.model)
+            payload.model = flags.model;
+        if (flags['holdout-count'] !== undefined)
+            payload.holdout_count = flags['holdout-count'];
+        if (flags['min-valid'] !== undefined)
+            payload.min_valid = flags['min-valid'];
+        if (flags['oauth-only'])
+            payload.oauth_only = true;
+        let started;
+        try {
+            started = (await client.post('/v1/voiceprint/builds', { body: payload }));
+        }
+        catch (err) {
+            if (err instanceof FacesAPIError)
+                this.error(`Error (${err.statusCode}): ${err.message}`);
+            throw err;
+        }
+        const jobId = String(started.job_id ?? '');
+        if (!jobId)
+            this.error('Server did not return a job_id');
+        if (!flags.wait) {
+            if (!json) {
+                this.log(`Build started: ${jobId}`);
+                this.log(`Poll with: faces voiceprint:build-status ${jobId}`);
+            }
+            return started;
+        }
+        if (!json)
+            process.stderr.write(`Building voice map for ${args.self_alias} (job ${jobId})...\n`);
+        let final;
+        let lastStage = '';
+        try {
+            final = await pollVoiceprintJob(client, '/v1/voiceprint/builds', jobId, {
+                timeoutMs: 3_600_000, // a large corpus fans lenses over many chunks — can take a while
+                onPoll: (data) => {
+                    if (json)
+                        return;
+                    const p = data.progress;
+                    const key = p ? `${p.stage}:${p.done}/${p.total}` : String(data.status);
+                    if (key !== lastStage) {
+                        lastStage = key;
+                        process.stderr.write(`  ${p?.stage ?? data.status}${p?.total ? ` ${p.done}/${p.total}` : ''}\n`);
+                    }
+                },
+            });
+        }
+        catch (err) {
+            if (err instanceof FacesAPIError)
+                this.error(`Error (${err.statusCode}): ${err.message}`);
+            this.error(err instanceof Error ? err.message : String(err));
+        }
+        if (final.status === 'failed')
+            this.error(`Build failed: ${jobFailureMessage(final.error)}`);
+        if (json)
+            return final;
+        printBuildReport(this, jobId, final);
+        return final;
+    }
+}
+/** Shared build-report formatter (used by voiceprint:build --wait and voiceprint:build-status). */
+export function printBuildReport(cmd, jobId, data) {
+    const report = (data.report ?? {});
+    cmd.log(`job:                ${jobId}`);
+    cmd.log(`status:             ${data.status}`);
+    if (data.voiceprint_face_id)
+        cmd.log(`voiceprint_face_id: ${data.voiceprint_face_id}`);
+    if (data.version_id)
+        cmd.log(`version_id:         ${data.version_id}`);
+    if (report.voice_map_chars !== undefined)
+        cmd.log(`voice_map_chars:    ${report.voice_map_chars}`);
+    const baseline = report.baseline;
+    if (baseline) {
+        if (baseline.skipped) {
+            cmd.log(`baseline:           skipped (${baseline.skipped})`);
+        }
+        else {
+            cmd.log(`baseline VCI:       ${baseline.VCI ?? 'n/a'}`);
+            cmd.log(`baseline VFI:       ${baseline.VFI ?? 'n/a'}`);
+            if (baseline.delta_ratio !== undefined)
+                cmd.log(`baseline delta:     ${baseline.delta_ratio}`);
+        }
+    }
+}

package/dist/commands/voiceprint/get.d.ts

@@ -0,0 +1,14 @@
+import { BaseCommand } from '../../base.js';
+export default class VoiceprintGet extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        '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: {
+        job_id: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    run(): Promise<unknown>;
+}

package/dist/commands/voiceprint/get.js

@@ -0,0 +1,47 @@
+import { Args } from '@oclif/core';
+import { BaseCommand } from '../../base.js';
+import { FacesAPIError } from '../../client.js';
+export default class VoiceprintGet extends BaseCommand {
+    static description = 'Get the status/result of a voiceprint scoring job started with voiceprint:score --no-wait';
+    static examples = ['<%= config.bin %> <%= command.id %> 4e13bf03-fbc1-4ad0-92ae-16984e2f9a1d'];
+    static flags = { ...BaseCommand.baseFlags };
+    static args = {
+        job_id: Args.string({ description: 'Scoring job id (from voiceprint:score --no-wait)', required: true }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(VoiceprintGet);
+        const client = this.makeClient(flags);
+        let data;
+        try {
+            data = (await client.get(`/v1/voiceprint/score/${encodeURIComponent(args.job_id)}`));
+        }
+        catch (err) {
+            if (err instanceof FacesAPIError)
+                this.error(`Error (${err.statusCode}): ${err.message}`);
+            throw err;
+        }
+        if (this.jsonEnabled())
+            return data;
+        const status = String(data.status ?? 'unknown');
+        this.log(`job:    ${args.job_id}`);
+        this.log(`status: ${status}`);
+        const progress = data.progress;
+        if (progress && typeof progress.pairs_done === 'number') {
+            this.log(`pairs:  ${progress.pairs_done}/${progress.pairs_total ?? '?'}`);
+        }
+        if (status === 'done') {
+            const report = (data.report ?? {});
+            this.log(`VCI:     ${report.VCI ?? 'n/a'}   (voice closeness — 100 = writes indistinguishably from the person)`);
+            this.log(`VFI:     ${report.VFI ?? 'n/a'}   (voice fidelity — how much of their voice is captured vs a generic baseline)`);
+            if (report.n_pairs !== undefined)
+                this.log(`n_pairs: ${report.n_pairs}`);
+        }
+        else if (status === 'failed') {
+            this.log(`error:  ${data.error ?? 'unknown error'}`);
+        }
+        else {
+            this.log(`(still running — poll again with: faces voiceprint:get ${args.job_id})`);
+        }
+        return data;
+    }
+}

package/dist/commands/voiceprint/refine-status.d.ts

@@ -0,0 +1,14 @@
+import { BaseCommand } from '../../base.js';
+export default class VoiceprintRefineStatus extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        '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: {
+        job_id: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    run(): Promise<unknown>;
+}

package/dist/commands/voiceprint/refine-status.js

@@ -0,0 +1,43 @@
+import { Args } from '@oclif/core';
+import { BaseCommand } from '../../base.js';
+import { FacesAPIError } from '../../client.js';
+import { jobFailureMessage } from '../../voiceprint.js';
+import { printRefineReport } from './refine.js';
+export default class VoiceprintRefineStatus extends BaseCommand {
+    static description = 'Get the status/result of a voiceprint refine job (from voiceprint:refine without --wait)';
+    static examples = ['<%= config.bin %> <%= command.id %> 4e13bf03-fbc1-4ad0-92ae-16984e2f9a1d'];
+    static flags = { ...BaseCommand.baseFlags };
+    static args = {
+        job_id: Args.string({ description: 'Refine job id', required: true }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(VoiceprintRefineStatus);
+        const client = this.makeClient(flags);
+        let data;
+        try {
+            data = (await client.get(`/v1/voiceprint/refines/${encodeURIComponent(args.job_id)}`));
+        }
+        catch (err) {
+            if (err instanceof FacesAPIError)
+                this.error(`Error (${err.statusCode}): ${err.message}`);
+            throw err;
+        }
+        if (this.jsonEnabled())
+            return data;
+        const status = String(data.status ?? 'unknown');
+        if (status === 'failed') {
+            this.log(`job:    ${args.job_id}`);
+            this.log(`status: failed`);
+            this.log(`error:  ${jobFailureMessage(data.error)}`);
+        }
+        else if (status === 'done') {
+            printRefineReport(this, args.job_id, (data.report ?? {}));
+        }
+        else {
+            this.log(`job:    ${args.job_id}`);
+            this.log(`status: ${status}`);
+            this.log(`(still running — poll again with: faces voiceprint:refine-status ${args.job_id})`);
+        }
+        return data;
+    }
+}

package/dist/commands/voiceprint/refine.d.ts

@@ -0,0 +1,23 @@
+import { BaseCommand } from '../../base.js';
+export default class VoiceprintRefine extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        model: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        temperature: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'n-samples': import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'oauth-only': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        wait: 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: {
+        self_alias: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    run(): Promise<unknown>;
+}
+/** Shared refine-report formatter (used by voiceprint:refine --wait and voiceprint:refine-status). */
+export declare function printRefineReport(cmd: {
+    log: (m: string) => void;
+}, jobId: string, report: Record<string, unknown>): void;

package/dist/commands/voiceprint/refine.js

@@ -0,0 +1,88 @@
+import { Args, Flags } from '@oclif/core';
+import { BaseCommand } from '../../base.js';
+import { FacesAPIError } from '../../client.js';
+import { pollVoiceprintJob, jobFailureMessage } from '../../voiceprint.js';
+export default class VoiceprintRefine extends BaseCommand {
+    static description = "Tune the active version's post-processing recipe and promote it only if it beats the current one. Requires an existing build with a holdout ≥ 20. Undo with voiceprint:revert.";
+    static examples = [
+        '<%= config.bin %> <%= command.id %> alice --wait',
+        '<%= config.bin %> <%= command.id %> alice --temperature 0.4 --n-samples 6 --wait',
+    ];
+    static flags = {
+        ...BaseCommand.baseFlags,
+        model: Flags.string({ description: "Model used to forge candidate drafts (default: the active version's build model)" }),
+        temperature: Flags.string({ description: 'Sampling temperature for candidate drafts (default: 0.4)' }),
+        'n-samples': Flags.integer({ description: 'Drafts forged per holdout pair (default: 6)' }),
+        'oauth-only': Flags.boolean({ description: 'Only run on a free (OAuth) route; never fall back to billed inference', default: false }),
+        wait: Flags.boolean({ description: 'Block and poll until refine finishes (default: print the job_id and return)', default: false }),
+    };
+    static args = {
+        self_alias: Args.string({ description: 'Self face alias', required: true }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(VoiceprintRefine);
+        const client = this.makeClient(flags);
+        const json = this.jsonEnabled();
+        const payload = { self_face: args.self_alias };
+        if (flags.model)
+            payload.model = flags.model;
+        if (flags.temperature !== undefined)
+            payload.temperature = Number.parseFloat(flags.temperature);
+        if (flags['n-samples'] !== undefined)
+            payload.n_samples = flags['n-samples'];
+        if (flags['oauth-only'])
+            payload.oauth_only = true;
+        let started;
+        try {
+            started = (await client.post('/v1/voiceprint/refines', { body: payload }));
+        }
+        catch (err) {
+            if (err instanceof FacesAPIError)
+                this.error(`Error (${err.statusCode}): ${err.message}`);
+            throw err;
+        }
+        const jobId = String(started.job_id ?? '');
+        if (!jobId)
+            this.error('Server did not return a job_id');
+        if (!flags.wait) {
+            if (!json) {
+                this.log(`Refine started: ${jobId}`);
+                this.log(`Poll with: faces voiceprint:refine-status ${jobId}`);
+            }
+            return started;
+        }
+        if (!json)
+            process.stderr.write(`Refining ${args.self_alias}'s recipe (job ${jobId})...\n`);
+        let final;
+        try {
+            final = await pollVoiceprintJob(client, '/v1/voiceprint/refines', jobId, { timeoutMs: 3_600_000 });
+        }
+        catch (err) {
+            if (err instanceof FacesAPIError)
+                this.error(`Error (${err.statusCode}): ${err.message}`);
+            this.error(err instanceof Error ? err.message : String(err));
+        }
+        if (final.status === 'failed')
+            this.error(`Refine failed: ${jobFailureMessage(final.error)}`);
+        if (json)
+            return final;
+        printRefineReport(this, jobId, (final.report ?? {}));
+        return final;
+    }
+}
+/** Shared refine-report formatter (used by voiceprint:refine --wait and voiceprint:refine-status). */
+export function printRefineReport(cmd, jobId, report) {
+    const decision = String(report.decision ?? 'unknown');
+    const baseline = (report.baseline ?? {});
+    cmd.log(`job:      ${jobId}`);
+    cmd.log(`decision: ${decision}${decision === 'promote' ? ' (a better recipe was promoted to a new active version)' : decision === 'keep' ? ' (nothing beat the current recipe; unchanged)' : ''}`);
+    if (baseline.VCI !== undefined || baseline.VFI !== undefined) {
+        cmd.log(`baseline: VCI ${baseline.VCI ?? 'n/a'} / VFI ${baseline.VFI ?? 'n/a'}`);
+    }
+    if (report.version_id)
+        cmd.log(`version:  ${report.version_id}`);
+    if (Array.isArray(report.promoted_recipe))
+        cmd.log(`recipe:   ${JSON.stringify(report.promoted_recipe)}`);
+    if (decision === 'promote')
+        cmd.log(`\nUndo with: faces voiceprint:revert <self_alias>`);
+}

package/dist/commands/voiceprint/revert.d.ts

@@ -0,0 +1,14 @@
+import { BaseCommand } from '../../base.js';
+export default class VoiceprintRevert extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        '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: {
+        self_alias: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    run(): Promise<unknown>;
+}

package/dist/commands/voiceprint/revert.js

@@ -0,0 +1,36 @@
+import { Args } from '@oclif/core';
+import { BaseCommand } from '../../base.js';
+import { FacesAPIError } from '../../client.js';
+export default class VoiceprintRevert extends BaseCommand {
+    static description = "Revert a self face's voice map to its prior version (one-deep undo; re-running toggles back). Only changes which stored recipe/baseline is active — the map text is frozen.";
+    static examples = ['<%= config.bin %> <%= command.id %> alice'];
+    static flags = { ...BaseCommand.baseFlags };
+    static args = {
+        self_alias: Args.string({ description: 'Self face alias', required: true }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(VoiceprintRevert);
+        const client = this.makeClient(flags);
+        let data;
+        try {
+            data = (await client.post('/v1/voiceprint/versions/revert', { body: { self_face: args.self_alias } }));
+        }
+        catch (err) {
+            if (err instanceof FacesAPIError) {
+                if (err.statusCode === 409)
+                    this.error(`Nothing to revert to — ${args.self_alias} has only one voice-map version.`);
+                this.error(`Error (${err.statusCode}): ${err.message}`);
+            }
+            throw err;
+        }
+        if (this.jsonEnabled())
+            return data;
+        this.log(`self_face:    ${data.self_face ?? args.self_alias}`);
+        this.log(`from_version: ${data.from_version ?? '?'}`);
+        this.log(`to_version:   ${data.to_version ?? '?'}`);
+        this.log(`VCI/VFI:      ${data.baseline_vci ?? 'n/a'} / ${data.baseline_vfi ?? 'n/a'}`);
+        if (data.recipe !== undefined)
+            this.log(`recipe:       ${JSON.stringify(data.recipe)}`);
+        return data;
+    }
+}