@hypersoniclabs/helix-cli 0.1.25-helix3.462 → 0.1.25-helix3.463

package/README.md

@@ -86,6 +86,9 @@ The token is stored in `~/.helix/credentials.json` (mode `600`). It's sent as
 | `helix assets start\|status\|generate\|resume` | Start or poll generation without duplicates. Props/characters use the Asset Generation job lane; standalone assets use the shared broker and report the auto-published `vaultAssetId`. `generate` and `resume` block waiting for the job (see `--timeout`/`--poll-interval` below). |
 | `helix assets voices [--search <text>] [--category premade\|professional] [--page-size <n>] [--page-token <token>] [--json]` | Discover safe text-to-speech voices through the authenticated HELIX catalog, including language, labels, preview, default/recommended selection, and pagination. |
 | `helix assets generate-image\|generate-material\|generate-audio\|generate-environment` | Run the supported standalone generation adapters. Material is a validated PBR bundle (1K default, explicit 2K); splats declare object/environment scope. Animation remains an explicit unavailable boundary. |
+| `helix assets start character "<prompt>" [--title t] [--visibility v] [--max-lix n]` | Starts a character on the server-side Asset Generation job driver (`POST /api/v1/asset-generation/jobs`, `mode: deterministic`) and returns at once; stdout is the driver job JSON (`id`). `--visibility` is sent only when you pass it; the server owns the default and every other policy (reference review, redraws, retries, visual QA wait, WARN/BLOCK, refunds). |
+| `helix assets resume <id> [--timeout <ms>] [--poll-interval <ms>]` (driver job) | Waits for `succeeded`, `held`, `failed` or `handoff` (default **80 min**, poll **3 s**), one progress line per change on stderr (stage, reference gate, scheduled retry, policy events, cost). Final stdout is the driver job JSON plus top-level `publishedItemId` (= `result.itemId`). Exit 0 for succeeded, held (the item exists but is not released; `result.qa` says why; `helix assets refund <id>` is offered) and handoff; exit 1 for `failed` (JSON on stdout, message with `escalate`/`retriable` on stderr) and for a client-side timeout (nothing on stdout). `--visibility` must match the job's (it is fixed at start) or the command exits 1. An id the driver does not know (props, older characters) resumes through the previous loop below. `helix assets generate character` is `start` + `resume`. |
+| `helix assets act <id> approve\|revise ["guidance"]`, `helix assets refund <id>`, `helix assets status <id> --pipeline driver` | Decide at the open reference gate, get the LIX back for a held avatar, or read the raw driver job. |
 | `helix assets start-reference\|generate-reference` | Start or fully drive a character job from a local four-view PNG/JPEG/WebP. The backend validates and reuses the exact sheet; it skips image generation while preserving mesh, texture, rig, LOD, thumbnail, billing, and Vault publication. `generate-reference` blocks waiting for the job (see `--timeout`/`--poll-interval` below). |
 | `helix assets generate\|generate-reference\|resume [--timeout <ms>] [--poll-interval <ms>]` | These three drive an Asset Generation prop/character job to completion (concept → mesh → texture → rig → publish) and block until it finishes. `--timeout` bounds how long the CLI process waits before giving up (default **1200000ms / 20min**, unchanged if omitted); `--poll-interval` sets how often it checks job status while waiting (default **2000ms**). A timeout is a CLIENT-SIDE giveup, not a job failure — the job keeps running server-side. The error prints the exact `helix assets resume <job-id>` command to check on or continue it; on a genuinely slow stage (e.g. mesh generation), rerun with a larger `--timeout`, or just poll separately with `helix assets status <job-id> --pipeline dreamer`. |
 | `helix assets materials [--resolution <res>] [--no-resolve] [--human]` | Discover the small built-in material palette. `--resolution` keeps only materials carrying that texture resolution. Each entry also carries the Scene v2 `vault` pin and the `continuum` package ref; `--no-resolve` skips those lookups. |

package/dist/assetGenerationDriver.d.ts

@@ -0,0 +1,109 @@
+export type DriverVisibility = 'public' | 'unlisted' | 'private';
+export type DriverStatus = 'queued' | 'running' | 'succeeded' | 'held' | 'failed' | 'handoff';
+export declare const DRIVER_TERMINAL: readonly DriverStatus[];
+export interface DriverFailure {
+    code: string;
+    message: string;
+    retriable: boolean;
+    escalate: boolean;
+}
+export interface DriverJobView {
+    id: string;
+    kind: string;
+    status: DriverStatus;
+    phase?: string;
+    visibility?: DriverVisibility;
+    stages?: Record<string, {
+        state: string;
+        note?: string;
+    }>;
+    gate?: {
+        state: string;
+        autoApproveAt?: string | null;
+        options?: string[];
+    } | null;
+    lix?: {
+        spentTotal?: number;
+        byStage?: Record<string, number>;
+        refunded?: number;
+    };
+    retry?: {
+        at: string;
+        message: string;
+    } | null;
+    result?: {
+        itemId?: string | null;
+        released?: string;
+        qa?: {
+            verdict?: string;
+            warnings?: unknown[];
+            blockers?: unknown[];
+            note?: string;
+        };
+    } | null;
+    failure?: DriverFailure | null;
+    actions?: string[];
+    lastEventSeq?: number;
+    [key: string]: unknown;
+}
+export interface DriverEvent {
+    seq: number;
+    type: string;
+    [key: string]: unknown;
+}
+/** The slice of HelixApi this client needs, so tests can pass a fake. */
+export interface DriverApi {
+    request<T>(method: string, path: string, body?: unknown): Promise<T>;
+}
+export declare const DRIVER_BASE = "/api/v1/asset-generation";
+/** The driver itself waits up to 75 minutes for visual QA; the client waits a little longer. */
+export declare const DRIVER_DEFAULT_TIMEOUT_MS: number;
+export declare const DRIVER_DEFAULT_POLL_MS = 3000;
+export interface StartDriverAvatarInput {
+    prompt: string;
+    title?: string;
+    /** Sent ONLY when the user chose one; the server owns the default. */
+    visibility?: DriverVisibility;
+}
+export declare function startDriverAvatarJob(api: DriverApi, input: StartDriverAvatarInput, newKey?: () => string): Promise<DriverJobView>;
+/** The driver job, or null when the id is not a driver job (a legacy generation job id, a prop). */
+export declare function getDriverJob(api: DriverApi, id: string): Promise<DriverJobView | null>;
+export declare class DriverVisibilityError extends Error {
+    constructor(requested: string, actual: string);
+}
+export declare class DriverTimeoutError extends Error {
+    readonly job: DriverJobView;
+    constructor(job: DriverJobView, timeoutMs: number);
+}
+/** One human line for an event, or null when it carries nothing a person needs. */
+export declare function describeDriverEvent(e: DriverEvent): string | null;
+export interface ResumeDriverOptions {
+    /** The user's --visibility, if any. Compared with the job's; never applied. */
+    visibility?: DriverVisibility;
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+    /** One human progress line (the caller sends it to stderr). */
+    progress?: (line: string) => void;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+}
+/**
+ * Wait for a driver job to reach a terminal status. Returns null when `id` is not a driver job (the caller falls
+ * back to the legacy loop). Throws DriverVisibilityError / DriverTimeoutError / the transport error; a `failed`
+ * job is RETURNED (the caller prints it and exits 1), not thrown.
+ */
+export declare function waitForDriverJob(api: DriverApi, id: string, options?: ResumeDriverOptions): Promise<DriverJobView | null>;
+export interface DriverIo {
+    stdout: (text: string) => void;
+    stderr: (text: string) => void;
+}
+/** The JSON a consumer reads: the backend's view plus `publishedItemId` once the item exists. */
+export declare function driverOutput(job: DriverJobView): DriverJobView & {
+    publishedItemId?: string;
+};
+export declare function renderDriverFailure(job: DriverJobView): string;
+/**
+ * Wait, print, and return the process exit code. Returns null when `id` is not a driver job.
+ * Never calls process.exit, so piped output is not cut.
+ */
+export declare function runDriverResume(api: DriverApi, id: string, options: ResumeDriverOptions, io: DriverIo): Promise<number | null>;

package/dist/assetGenerationDriver.js

@@ -0,0 +1,216 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DriverTimeoutError = exports.DriverVisibilityError = exports.DRIVER_DEFAULT_POLL_MS = exports.DRIVER_DEFAULT_TIMEOUT_MS = exports.DRIVER_BASE = exports.DRIVER_TERMINAL = void 0;
+exports.startDriverAvatarJob = startDriverAvatarJob;
+exports.getDriverJob = getDriverJob;
+exports.describeDriverEvent = describeDriverEvent;
+exports.waitForDriverJob = waitForDriverJob;
+exports.driverOutput = driverOutput;
+exports.renderDriverFailure = renderDriverFailure;
+exports.runDriverResume = runDriverResume;
+// Thin client of the Asset Generation job driver (helix-backend-api
+// docs/architecture/asset-generation-driver.md). The server runs an avatar from prompt to released item under
+// ONE policy (reference review, redraws, retries, visual QA wait, WARN/BLOCK handling, refunds). This file only
+// starts a job, reads its status and events, and reports. It carries no policy: no approve call, no publish call,
+// no retry of a stage, no escalation decision.
+//
+// Output contract (also parsed by the HELIX MCP):
+//   stdout  the driver job view JSON as returned by the backend, plus a top-level `publishedItemId` (= result.itemId)
+//           once the item exists.
+//   stderr  one human progress line per change while waiting; the failure text on a failed job.
+//   exit    succeeded 0, held 0, handoff 0, failed 1, client timeout 1.
+const node_crypto_1 = require("node:crypto");
+const api_1 = require("./api");
+exports.DRIVER_TERMINAL = ['succeeded', 'held', 'failed', 'handoff'];
+exports.DRIVER_BASE = '/api/v1/asset-generation';
+/** The driver itself waits up to 75 minutes for visual QA; the client waits a little longer. */
+exports.DRIVER_DEFAULT_TIMEOUT_MS = 80 * 60_000;
+exports.DRIVER_DEFAULT_POLL_MS = 3_000;
+const MAX_CONSECUTIVE_POLL_ERRORS = 5;
+async function startDriverAvatarJob(api, input, newKey = node_crypto_1.randomUUID) {
+    return api.request('POST', `${exports.DRIVER_BASE}/jobs`, {
+        kind: 'avatar',
+        prompt: input.prompt,
+        ...(input.title ? { title: input.title } : {}),
+        mode: 'deterministic',
+        ...(input.visibility ? { visibility: input.visibility } : {}),
+        idempotencyKey: newKey(),
+    });
+}
+/** The driver job, or null when the id is not a driver job (a legacy generation job id, a prop). */
+async function getDriverJob(api, id) {
+    try {
+        return await api.request('GET', `${exports.DRIVER_BASE}/jobs/${encodeURIComponent(id)}`);
+    }
+    catch (err) {
+        if (err instanceof api_1.ApiError && err.status === 404)
+            return null;
+        throw err;
+    }
+}
+class DriverVisibilityError extends Error {
+    constructor(requested, actual) {
+        super(`Visibility is fixed when the job starts: this job was started as ${actual}, not ${requested}. ` +
+            `Re-run without --visibility to wait for it as it is.`);
+        this.name = 'DriverVisibilityError';
+    }
+}
+exports.DriverVisibilityError = DriverVisibilityError;
+class DriverTimeoutError extends Error {
+    job;
+    constructor(job, timeoutMs) {
+        super(`Gave up waiting for Asset Generation job ${job.id} after ${timeoutMs}ms ` +
+            `(still ${job.status}${job.phase ? `:${job.phase}` : ''}). ` +
+            `This is a CLIENT-SIDE wait giving up. The job itself keeps running on the server and needs nothing from you. ` +
+            `Check or continue waiting with:\n` +
+            `  helix assets resume ${job.id}\n` +
+            `To wait longer next time, pass --timeout <ms> (and optionally --poll-interval <ms>).`);
+        this.job = job;
+        this.name = 'DriverTimeoutError';
+    }
+}
+exports.DriverTimeoutError = DriverTimeoutError;
+/** One human line for an event, or null when it carries nothing a person needs. */
+function describeDriverEvent(e) {
+    switch (e.type) {
+        case 'stage': {
+            const note = typeof e.note === 'string' && e.note ? ` (${e.note})` : '';
+            return `stage ${String(e.stage)}: ${String(e.state)}${note}`;
+        }
+        case 'gate': {
+            if (e.state === 'open') {
+                const at = typeof e.autoApproveAt === 'number' ? new Date(e.autoApproveAt).toISOString() : null;
+                return `reference gate open${at ? `, auto-approves at ${at}` : ''}`;
+            }
+            return `reference gate closed${e.decision ? ` (${String(e.decision)})` : ''}`;
+        }
+        case 'retry_scheduled':
+            return `retry scheduled in ${String(e.inSeconds)}s (attempt ${String(e.attempt)} of ${String(e.of)}): ${String(e.message ?? '')}`.trim();
+        case 'policy':
+            return `policy ${String(e.rule)}: ${String(e.text ?? '')}`.trim();
+        case 'cost':
+            return `cost: ${String(e.spentTotal)} LIX spent`;
+        case 'step':
+            return typeof e.text === 'string' ? e.text : null;
+        case 'status':
+            return `status: ${String(e.status)}`;
+        case 'restart':
+            return `restart: ${String(e.note ?? '')}`.trim();
+        case 'failed':
+            return `failed: ${String(e.message ?? e.code)}`;
+        default:
+            return null;
+    }
+}
+/**
+ * Wait for a driver job to reach a terminal status. Returns null when `id` is not a driver job (the caller falls
+ * back to the legacy loop). Throws DriverVisibilityError / DriverTimeoutError / the transport error; a `failed`
+ * job is RETURNED (the caller prints it and exits 1), not thrown.
+ */
+async function waitForDriverJob(api, id, options = {}) {
+    const sleep = options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const now = options.now ?? Date.now;
+    const timeoutMs = options.timeoutMs ?? exports.DRIVER_DEFAULT_TIMEOUT_MS;
+    const pollMs = options.pollIntervalMs ?? exports.DRIVER_DEFAULT_POLL_MS;
+    const say = options.progress ?? (() => { });
+    let job = await getDriverJob(api, id);
+    if (!job)
+        return null;
+    if (options.visibility && job.visibility && options.visibility !== job.visibility) {
+        throw new DriverVisibilityError(options.visibility, job.visibility);
+    }
+    const deadline = now() + timeoutMs;
+    let seq = 0;
+    let lastLine = '';
+    let errors = 0;
+    const line = (text) => {
+        if (!text || text === lastLine)
+            return;
+        lastLine = text;
+        say(text);
+    };
+    line(`job ${job.id}: ${job.status}${job.phase ? ` (${job.phase})` : ''}`);
+    for (;;) {
+        // Events are progress only, never a decision input; a failed read costs a line, not the wait.
+        if ((job.lastEventSeq ?? 0) > seq) {
+            try {
+                const page = await api.request('GET', `${exports.DRIVER_BASE}/jobs/${encodeURIComponent(id)}/events?after=${seq}`);
+                for (const e of page.events) {
+                    line(describeDriverEvent(e));
+                    seq = Math.max(seq, e.seq);
+                }
+                seq = Math.max(seq, page.lastSeq ?? seq);
+            }
+            catch {
+                // best effort
+            }
+        }
+        if (exports.DRIVER_TERMINAL.includes(job.status))
+            return job;
+        if (now() >= deadline)
+            throw new DriverTimeoutError(job, timeoutMs);
+        await sleep(pollMs);
+        try {
+            const next = await getDriverJob(api, id);
+            if (next)
+                job = next;
+            errors = 0;
+        }
+        catch (err) {
+            // A transport blip on a poll is not a verdict about the job; a persistent one is real.
+            if (++errors >= MAX_CONSECUTIVE_POLL_ERRORS)
+                throw err;
+        }
+    }
+}
+/** The JSON a consumer reads: the backend's view plus `publishedItemId` once the item exists. */
+function driverOutput(job) {
+    const itemId = job.result?.itemId;
+    return itemId ? { ...job, publishedItemId: itemId } : { ...job };
+}
+function renderDriverFailure(job) {
+    const f = job.failure;
+    if (!f)
+        return `✖ Asset Generation job ${job.id} failed (no details).`;
+    return (`✖ Asset Generation job ${job.id} failed: ${f.message} ` +
+        `(code: ${f.code}, escalate: ${f.escalate}, retriable: ${f.retriable})`);
+}
+/**
+ * Wait, print, and return the process exit code. Returns null when `id` is not a driver job.
+ * Never calls process.exit, so piped output is not cut.
+ */
+async function runDriverResume(api, id, options, io) {
+    let job;
+    try {
+        job = await waitForDriverJob(api, id, { ...options, progress: options.progress ?? ((l) => io.stderr(`  ${l}`)) });
+    }
+    catch (err) {
+        if (err instanceof DriverTimeoutError) {
+            io.stderr(`✖ ${err.message}`);
+            return 1;
+        }
+        if (err instanceof DriverVisibilityError) {
+            io.stderr(`✖ ${err.message}`);
+            return 1;
+        }
+        throw err;
+    }
+    if (!job)
+        return null;
+    io.stdout(JSON.stringify(driverOutput(job), null, 2));
+    if (job.status === 'failed') {
+        io.stderr(renderDriverFailure(job));
+        return 1;
+    }
+    if (job.status === 'held') {
+        const qa = job.result?.qa;
+        io.stderr(`Held: the avatar exists${job.result?.itemId ? ` (item ${job.result.itemId})` : ''} but is not released` +
+            `${qa?.verdict ? ` (platform check: ${qa.verdict})` : ''}${qa?.note ? `. ${qa.note}` : ''}.` +
+            `${job.actions?.includes('refund') ? ` Get the LIX back with: helix assets refund ${job.id}` : ''}`);
+    }
+    else if (job.status === 'handoff') {
+        io.stderr('Handed off: this request is for an agent; the driver ran nothing and nothing was charged.');
+    }
+    return 0;
+}
+//# sourceMappingURL=assetGenerationDriver.js.map

package/dist/assetGenerationDriver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assetGenerationDriver.js","sourceRoot":"","sources":["../src/assetGenerationDriver.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -50,6 +50,7 @@ const node_path_1 = require("node:path");
 const node_os_1 = require("node:os");
 const scenePerformance_1 = require("./scenePerformance");
 const lib_1 = require("./lib");
+const assetGenerationDriver_1 = require("./assetGenerationDriver");
 const itemSearch_1 = require("./itemSearch");
 const vault_1 = require("./vault");
 const looks_1 = require("./looks");
@@ -3276,6 +3277,30 @@ function printJson(value) {
 function note(line) {
     process.stderr.write(`${line}\n`);
 }
+/** Validate `--visibility`; undefined stays undefined (the driver owns the default). */
+function parseDriverVisibility(value) {
+    if (value === undefined)
+        return undefined;
+    if (!['public', 'unlisted', 'private'].includes(value)) {
+        fail('✖ --visibility must be public, unlisted, or private');
+    }
+    return value;
+}
+/** The driver takes a prompt, a title and a visibility. Guidance folds into the prompt; a polycount is not its input. */
+function driverStartInput(prompt, opts) {
+    if (opts.targetPolycount !== undefined) {
+        note('• --target-polycount is ignored for characters: the Asset Generation job driver sets it.');
+    }
+    return {
+        prompt: opts.additionalPrompt ? `${prompt}\n${opts.additionalPrompt}` : prompt,
+        title: opts.title,
+        visibility: parseDriverVisibility(opts.visibility),
+    };
+}
+const driverIo = {
+    stdout: (text) => console.log(text),
+    stderr: (text) => note(text),
+};
 // Which flags the server accepts for which kind. The quote route REFUSES a field that does not
 // apply to the kind — `resolution`/`repeatPerMeter` are material-only, `splatScope` is
 // Gaussian-splat-only, `targetPolycount` is mesh-only. Commander gives `--resolution` and
@@ -3761,6 +3786,7 @@ const assetsStart = assets
     .option('--resolution <n>', 'material resolution: 1024 or 2048', '1024')
     .option('--repeat-per-meter <n>', 'material physical scale: tile repeats per metre')
     .option('--splat-scope <scope>', 'Gaussian-splat scope: object or environment', 'environment')
+    .option('--visibility <visibility>', 'character: public, unlisted, or private. Sent only when you pass it; otherwise the Asset Generation job driver applies its own default')
     .option('--max-lix <n>', 'refuse to start if the estimate exceeds this many LIX')
     .option('--no-estimate', 'skip the up-front cost estimate');
 // The audio surface, attached from the SAME definition `generate-audio` uses (minus the flags
@@ -3845,7 +3871,13 @@ const assetsStart = assets
     const generationInput = audioInput ?? buildQuoteInput(kind, promptText, opts);
     await showEstimateBeforeSpending(creds, generationInput, opts);
     try {
-        if (kind === 'prop' || kind === 'character') {
+        if (kind === 'character') {
+            // A character from a prompt is a thin client of the Asset Generation job driver: it owns every policy.
+            const input = driverStartInput(promptText, opts);
+            printJson(await (0, assetGenerationDriver_1.startDriverAvatarJob)(lib_1.HelixApi.forCredentials(creds), input));
+            return;
+        }
+        if (kind === 'prop') {
             printJson(await (0, lib_1.startDreamerAssetGeneration)(creds, {
                 kind,
                 prompt: promptText,
@@ -4051,13 +4083,20 @@ assets
     .command('status')
     .description('Poll one generation job without starting or advancing a duplicate')
     .argument('<job-id>', 'Asset Generation job id')
-    .requiredOption('--pipeline <pipeline>', 'dreamer = prop/character job lane (legacy name), asset = standalone lane')
+    .requiredOption('--pipeline <pipeline>', 'driver = a character driven by the Asset Generation job driver (`start character`), dreamer = prop/legacy character job lane (legacy name), asset = standalone lane')
     .action(async (jobId, opts) => {
-    if (!['dreamer', 'asset'].includes(opts.pipeline)) {
-        fail('✖ --pipeline must be dreamer or asset');
+    if (!['driver', 'dreamer', 'asset'].includes(opts.pipeline)) {
+        fail('✖ --pipeline must be driver, dreamer or asset');
     }
     const creds = requireAuth();
     try {
+        if (opts.pipeline === 'driver') {
+            const job = await (0, assetGenerationDriver_1.getDriverJob)(lib_1.HelixApi.forCredentials(creds), jobId);
+            if (!job)
+                fail(`✖ ${jobId} is not an Asset Generation driver job (try --pipeline dreamer)`);
+            printJson(job.result?.itemId ? { ...job, publishedItemId: job.result.itemId } : job);
+            return;
+        }
         const job = opts.pipeline === 'dreamer'
             ? await (0, lib_1.getDreamerAssetGenerationJob)(creds, jobId)
             : await (0, lib_1.getStandaloneAssetGenerationJob)(creds, jobId);
@@ -4116,22 +4155,33 @@ assets
     .option('--title <title>', 'asset title')
     .option('--additional-prompt <text>', 'additional generation guidance')
     .option('--target-polycount <n>', 'target triangle count')
-    .option('--visibility <visibility>', 'public, unlisted, or private', 'public')
-    .option('--timeout <ms>', 'how long to wait for the job to finish before giving up (client-side only — the job keeps running; default 1200000ms/20min)')
-    .option('--poll-interval <ms>', 'how often to poll job status while waiting (default 2000ms)')
+    .option('--visibility <visibility>', 'public, unlisted, or private (default public for a prop; a character uses the Asset Generation job driver default unless you pass it)')
+    .option('--timeout <ms>', 'how long to wait for the job to finish before giving up (client-side only — the job keeps running; default 20min for a prop, 80min for a character)')
+    .option('--poll-interval <ms>', 'how often to poll job status while waiting (default 2000ms prop, 3000ms character)')
     .option('--max-lix <n>', 'refuse to start if the estimate exceeds this many LIX')
     .option('--no-estimate', 'skip the up-front cost estimate')
     .action(async (kind, prompt, opts) => {
     if (kind !== 'prop' && kind !== 'character') {
         fail(`✖ kind must be prop or character, got '${kind}'`);
     }
-    if (!['public', 'unlisted', 'private'].includes(opts.visibility)) {
-        fail(`✖ --visibility must be public, unlisted, or private`);
-    }
+    const requestedVisibility = parseDriverVisibility(opts.visibility);
     const timeoutMs = optionalPositiveMs(opts.timeout, '--timeout');
     const pollIntervalMs = optionalPositiveMs(opts.pollInterval, '--poll-interval');
     const creds = requireAuth();
     await showEstimateBeforeSpending(creds, buildQuoteInput(kind, prompt, opts), opts);
+    if (kind === 'character') {
+        const api = lib_1.HelixApi.forCredentials(creds);
+        try {
+            const started = await (0, assetGenerationDriver_1.startDriverAvatarJob)(api, driverStartInput(prompt, opts));
+            note(`Started Asset Generation job ${started.id}. Waiting (resume later with: helix assets resume ${started.id})`);
+            const code = await (0, assetGenerationDriver_1.runDriverResume)(api, started.id, { timeoutMs, pollIntervalMs }, driverIo);
+            process.exitCode = code ?? 1;
+        }
+        catch (err) {
+            fail(`✖ ${err instanceof Error ? err.message : String(err)}`);
+        }
+        return;
+    }
     try {
         printJson(await (0, lib_1.generateAndPublishAsset)(creds, {
             kind,
@@ -4140,7 +4190,7 @@ assets
             additionalPrompt: opts.additionalPrompt,
             targetPolycount: optionalNumber(opts.targetPolycount, '--target-polycount'),
         }, {
-            visibility: opts.visibility,
+            visibility: requestedVisibility ?? 'public',
             timeoutMs,
             pollIntervalMs,
         }));
@@ -4186,11 +4236,11 @@ assets
 });
 assets
     .command('resume')
-    .description('Resume and publish an existing Asset Generation job')
+    .description('Wait for an Asset Generation job and print its result. A character started with `helix assets start character` is driven by the server: this only reads it (progress lines on stderr, the job JSON on stdout; exit 0 for succeeded/held/handoff, 1 for failed or a client timeout). Older job ids (props, legacy characters) resume and publish through the previous loop')
     .argument('<job-id>', 'Asset Generation job id')
-    .option('--visibility <visibility>', 'public, unlisted, or private (default: the visibility the job was generated with, else public)')
-    .option('--timeout <ms>', 'how long to wait for the job to finish before giving up (client-side only — the job keeps running; default 1200000ms/20min)')
-    .option('--poll-interval <ms>', 'how often to poll job status while waiting (default 2000ms)')
+    .option('--visibility <visibility>', 'public, unlisted, or private (legacy jobs: default is the visibility the job was generated with, else public). A driver job fixes its visibility when it starts: a different value here is an error')
+    .option('--timeout <ms>', 'how long to wait for the job to finish before giving up (client-side only — the job keeps running; default 80min for a driver job, 20min for a legacy job)')
+    .option('--poll-interval <ms>', 'how often to poll job status while waiting (default 3000ms driver job, 2000ms legacy job)')
     .action(async (jobId, opts) => {
     if (opts.visibility !== undefined &&
         !['public', 'unlisted', 'private'].includes(opts.visibility)) {
@@ -4200,6 +4250,16 @@ assets
     const pollIntervalMs = optionalPositiveMs(opts.pollInterval, '--poll-interval');
     const creds = requireAuth();
     try {
+        const code = await (0, assetGenerationDriver_1.runDriverResume)(lib_1.HelixApi.forCredentials(creds), jobId, {
+            visibility: opts.visibility,
+            timeoutMs,
+            pollIntervalMs,
+        }, driverIo);
+        if (code !== null) {
+            process.exitCode = code;
+            return;
+        }
+        // Not a driver job: the legacy loop, unchanged.
         const job = await (0, lib_1.resumeAndPublishAsset)(creds, jobId, {
             visibility: opts.visibility,
             timeoutMs,
@@ -4217,6 +4277,40 @@ assets
         fail(`✖ ${err instanceof Error ? err.message : String(err)}`);
     }
 });
+assets
+    .command('act')
+    .description('Decide at the open reference gate of an Asset Generation job driven by the server: approve it now, or revise it with guidance (a revise charges a regeneration)')
+    .argument('<job-id>', 'Asset Generation job id')
+    .argument('<action>', 'approve or revise')
+    .argument('[guidance]', 'revise: what to change')
+    .option('--prompt <text>', 'revise: what to change (same as the guidance argument)')
+    .action(async (jobId, action, guidance, opts) => {
+    if (action !== 'approve' && action !== 'revise')
+        fail('✖ action must be approve or revise');
+    const prompt = guidance ?? opts.prompt;
+    if (action === 'approve' && prompt)
+        fail('✖ approve takes no guidance; use revise');
+    const creds = requireAuth();
+    try {
+        printJson(await lib_1.HelixApi.forCredentials(creds).request('POST', `${assetGenerationDriver_1.DRIVER_BASE}/jobs/${encodeURIComponent(jobId)}/actions`, { action, ...(prompt ? { prompt } : {}) }));
+    }
+    catch (err) {
+        fail(err instanceof lib_1.ApiError ? err.render() : `✖ ${err instanceof Error ? err.message : String(err)}`);
+    }
+});
+assets
+    .command('refund')
+    .description('Get the LIX back for an avatar the platform check held (Asset Generation job driver; server-verified, idempotent)')
+    .argument('<job-id>', 'Asset Generation job id')
+    .action(async (jobId) => {
+    const creds = requireAuth();
+    try {
+        printJson(await lib_1.HelixApi.forCredentials(creds).request('POST', `${assetGenerationDriver_1.DRIVER_BASE}/jobs/${encodeURIComponent(jobId)}/refund`));
+    }
+    catch (err) {
+        fail(err instanceof lib_1.ApiError ? err.render() : `✖ ${err instanceof Error ? err.message : String(err)}`);
+    }
+});
 assets
     .command('generate-image')
     .description('Generate a standalone image with Asset Generation')