venice-video-harness 2.5.3 → 2.6.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 2.6.0 — 2026-07-31
+
+### Added
+
+- `venice-video shell` — a persistent interactive session. Commands run without
+  a process restart, so the Venice client's rate-limit pacing and caches stay
+  warm across a whole production instead of resetting on every invocation.
+- A selected project and part. `use <project> [part]` makes `-p` and `-e`
+  optional on every command; `unuse` clears it. The selection is stored in user
+  config, so it applies to one-shot commands and survives restarts.
+- Background commands: suffix any command with `&`, then `/jobs`,
+  `/jobs log <id>`, and `/jobs cancel <id>`. Output from a backgrounded render is
+  captured to its own buffer rather than sprayed over the prompt.
+- `venice-video status` — reports where a project sits in the pipeline and which
+  command to run next.
+- `venice-video queue` — lists Venice renders left in flight, with `prune` and
+  `clear` subcommands.
+- Shell conveniences: tab completion for commands, flags, and project slugs; a
+  persistent history file; a context-aware prompt; `!<cmd>` passthrough to the
+  system shell.
+
+### Fixed
+
+- **Interrupted renders no longer orphan paid work.** Each Venice `queue_id` is
+  now recorded to disk *before* polling starts. Re-running a command re-attaches
+  to the pending job instead of submitting and billing a second render. Previously
+  a Ctrl-C, crash, or dropped connection lost the id while Venice kept charging.
+- `Ctrl-C` now cancels the in-flight operation through an `AbortSignal` threaded
+  into every Venice request, poll loop, and retry backoff, rather than only
+  killing the process between requests.
+- Video polling gained an overall timeout and a consecutive-error ceiling, so a
+  wedged render fails instead of hanging indefinitely.
+- Tests no longer inherit an ambient `VENICE_VIDEO_WORKSPACE`, which could
+  silently redirect the projects they create.
+
 ## 2.5.3 — 2026-07-31
 
 - Workshop generation now writes a formatted, self-contained `WORKSHOP.html` alongside JSON and Markdown.

package/README.md

@@ -291,6 +291,58 @@ venice-video list-series
 venice-video --help
 ```
 
+### Interactive shell
+
+Every command above also runs inside a persistent session:
+
+```bash
+venice-video shell
+```
+
+The shell keeps one warm process for the whole production, which changes three
+things that matter over a long session:
+
+- **A selected project and part.** `use <project> [part]` sets them once; after
+  that `-p` and `-e` are optional on every command and the prompt shows what you
+  are pointed at. `unuse` clears the selection. The selection persists across
+  shell restarts and applies to one-shot commands too.
+- **Warm rate limiting and caches.** The Venice client's pacing state survives
+  between commands instead of resetting on every invocation, so back-to-back
+  generation stops tripping 429s.
+- **Background commands.** Suffix any command with `&` to detach it, then keep
+  working. `/jobs` lists them with elapsed time and current progress detail,
+  `/jobs log <id>` replays captured output, `/jobs cancel <id>` aborts one.
+
+```
+venice-video my-film · ep 01 › storyboard-episode
+venice-video my-film · ep 01 › generate-videos &
+  [1] started in the background. Check with /jobs.
+venice-video my-film · ep 01 › /jobs
+  [1] running    4m12s  generate-videos — shot 3/12 polling
+```
+
+Session extras: `Tab` completes commands, flags, and project slugs; `↑`/`↓` walk
+a persistent history file; `Ctrl-C` cancels the running command without killing
+the session (`Ctrl-D` or `/exit` leaves); `/help`, `/status`, `/jobs`, `/cd`, and
+`/pwd` are shell meta-commands; `!<cmd>` runs something in your system shell.
+
+### Interrupted renders are resumable
+
+The harness records each Venice `queue_id` to disk *before* it starts polling, so
+a cancelled command, a crash, or a closed laptop no longer orphans a render you
+have already paid for. Re-running the same command re-attaches to the pending job
+and keeps polling it instead of submitting and billing a second one.
+
+```bash
+venice-video queue              # renders Venice still has in flight
+venice-video queue prune        # forget records too old for Venice to still hold
+venice-video queue clear <id>   # forget one record (does not refund it)
+```
+
+The shell reports stranded renders in its banner on startup. Note the split:
+`queue` is Venice's side of the work (real money, survives restarts), while
+`/jobs` is only the background commands of the current session.
+
 For server environments, prefer `VENICE_API_KEY` instead of writing a user
 configuration file. Credential precedence is environment variable, then stored
 user configuration, then the repository `.env` compatibility path.

package/dist/mini-drama/cli.d.ts

@@ -1,3 +1,6 @@
 #!/usr/bin/env node
 import 'dotenv/config';
+import { Command } from 'commander';
+declare const program: Command;
+export { program };
 //# sourceMappingURL=cli.d.ts.map

package/dist/mini-drama/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/mini-drama/cli.ts"],"names":[],"mappings":";AAEA,OAAO,eAAe,CAAC"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/mini-drama/cli.ts"],"names":[],"mappings":";AAEA,OAAO,eAAe,CAAC;AACvB,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA2HpC,QAAA,MAAM,OAAO,SAAgB,CAAC;AAu5G9B,OAAO,EAAE,OAAO,EAAE,CAAC"}

package/dist/mini-drama/cli.js

@@ -2,10 +2,11 @@
 import 'dotenv/config';
 import { Command } from 'commander';
 import { resolve, join, basename } from 'node:path';
-import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from 'node:fs';
 import { mkdir, readFile, writeFile, copyFile } from 'node:fs/promises';
 import { spawnSync } from 'node:child_process';
 import { stdin } from 'node:process';
+import { fileURLToPath } from 'node:url';
 import { createSeries, saveSeries, loadSeries, listSeries, addCharacter, getCharacter, addEpisode, getEpisodeDir, getCharacterDir, getLocationDir, getLocation, addLocation, locationSlugify, saveEpisodeScript, loadEpisodeScript, } from '../series/manager.js';
 import { FEMALE_BASE_TRAITS, MALE_BASE_TRAITS, DEFAULT_CHARACTER_CONSISTENCY_MODEL, DEFAULT_IMAGE_GENERATION_MODEL, DEFAULT_IMAGE_EDIT_MODEL, } from '../series/types.js';
 import { VeniceClient } from '../venice/client.js';
@@ -17,6 +18,11 @@ import { getVeniceApiKey } from '../config.js';
 import { promptChoice, promptText } from '../interactive.js';
 import { getConfigPath, getDefaultSetupWorkspace, getWorkspaceDir, maskApiKey, readUserConfig, updateUserConfig, validateVeniceApiKey, } from '../user-config.js';
 import { listVoices, filterVoices, auditionVoices } from '../venice/voices.js';
+import { clearContext, MissingContextError, readContext, resolveProjectRef, setContext, } from '../session/context.js';
+import { OperationAbortedError } from '../venice/operation-context.js';
+import { applyContextDefaults } from '../session/program-context.js';
+import { collectProjectStatus, formatProjectStatus } from '../session/status.js';
+import { clearPendingJob, isStale, listPendingJobs, prunePendingJobs, } from '../venice/job-store.js';
 import { generateDialogueForShots, generateSoundEffect, generateMusic, generateSeedAudio, DEFAULT_VENICE_MUSIC_MODEL, DEFAULT_VENICE_SEED_AUDIO_MODEL, } from '../venice/audio.js';
 import { getMusicModel } from '../venice/models.js';
 import { buildImagePrompt, buildCharacterReferencePromptParts } from './prompt-builder.js';
@@ -32,11 +38,21 @@ import { buildGenerationPlan, saveGenerationPlan } from './generation-planner.js
 import { AUDIO_STRATEGY_CHOICES, VIDEO_FAMILY_CHOICES } from './choices.js';
 import { getProjectLanguage } from '../series/project-language.js';
 import { approveWorkshop, generateWorkshop, getWorkshopPath, inventoryReferencePath, loadWorkshop, saveWorkshop, } from './workshop.js';
+// Read from package.json rather than a literal, which drifts on every release.
+const packageVersion = (() => {
+    try {
+        const pkgPath = fileURLToPath(new URL('../../package.json', import.meta.url));
+        return JSON.parse(readFileSync(pkgPath, 'utf-8')).version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+})();
 const program = new Command();
 program
     .name('venice-video')
     .description('Standalone consistency-first video production with Venice AI')
-    .version('2.5.3')
+    .version(packageVersion)
     .option('--workspace <dir>', 'Workspace containing Venice Video projects');
 const VIDEO_FAMILIES = new Set(VIDEO_FAMILY_CHOICES.map(c => c.value));
 function openInDefaultBrowser(path) {
@@ -50,6 +66,33 @@ function openInDefaultBrowser(path) {
     const result = spawnSync(command.name, command.args, { stdio: 'ignore' });
     return result.status === 0;
 }
+/**
+ * True when this file is the process entry point. The program is only parsed in
+ * that case, so `shell` (and tests) can import the same command tree without
+ * argv being consumed at import time.
+ *
+ * `bin` points straight at this file, so the comparison is against argv[1] with
+ * symlinks resolved. The basename fallback covers the tsx dev path (.ts entry
+ * for a .js module specifier) -- getting this wrong would leave the CLI silently
+ * doing nothing, so it errs toward "yes, run".
+ */
+function isMainModule(moduleUrl) {
+    const entry = process.argv[1];
+    if (!entry)
+        return true;
+    const canonical = (path) => {
+        try {
+            return realpathSync(path);
+        }
+        catch {
+            return resolve(path);
+        }
+    };
+    const stripExtension = (path) => basename(path).replace(/\.[cm]?[jt]s$/, '');
+    const modulePath = canonical(fileURLToPath(moduleUrl));
+    const entryPath = canonical(entry);
+    return modulePath === entryPath || stripExtension(modulePath) === stripExtension(entryPath);
+}
 function runCommand(command, args) {
     const result = spawnSync(command, args, {
         encoding: 'utf-8',
@@ -3062,7 +3105,161 @@ program
     await program.parseAsync(['', '', 'assemble-episode', '-p', opts.project, '-e', String(opts.episode)]);
     console.log('\n=== Production Complete ===');
 });
-await program.parseAsync();
+// ── session: use / status / queue / shell ─────────────────────────────
+program
+    .command('use')
+    .description('Select the project (and episode) that -p / -e default to')
+    .argument('[project]', 'Project slug, name, or directory')
+    .option('-e, --episode <number>', 'Episode number to select', parseInt)
+    .option('--clear', 'Clear the current selection', false)
+    .action(async (projectRef, opts) => {
+    if (opts.clear) {
+        await clearContext();
+        console.log('Selection cleared. Commands now require -p / -e again.');
+        return;
+    }
+    if (!projectRef && opts.episode === undefined) {
+        const context = await readContext();
+        if (!context.project) {
+            console.log('Nothing selected. Usage: venice-video use <project> [-e <episode>]');
+            const workspace = await getWorkspaceDir(program.opts().workspace);
+            const available = await listSeries(workspace);
+            if (available.length > 0) {
+                console.log('\nAvailable projects:');
+                for (const entry of available)
+                    console.log(`  ${entry.slug.padEnd(28)} ${entry.name}`);
+            }
+            return;
+        }
+        console.log(`Project: ${context.project}`);
+        if (context.episode !== undefined)
+            console.log(`Episode: ${context.episode}`);
+        return;
+    }
+    const patch = {};
+    if (projectRef) {
+        const projectDir = await resolveProjectRef(projectRef, program.opts().workspace);
+        const series = await loadSeries(projectDir);
+        if (!series) {
+            console.error(`No series.json found at ${projectDir}.`);
+            console.error('Run `venice-video list-series` to see what is available.');
+            process.exit(1);
+        }
+        patch.project = projectDir;
+    }
+    if (opts.episode !== undefined)
+        patch.episode = opts.episode;
+    const next = await setContext(patch);
+    console.log(`Selected ${next.project}${next.episode !== undefined ? ` · episode ${next.episode}` : ''}`);
+});
+program
+    .command('unuse')
+    .description('Clear the selected project and episode')
+    .action(async () => {
+    await clearContext();
+    console.log('Selection cleared.');
+});
+program
+    .command('status')
+    .description('Show pipeline state for a project and the next command to run')
+    .option('-p, --project <dir>', 'Project directory (defaults to the selection)')
+    .action(async (opts) => {
+    const context = await readContext();
+    const projectRef = opts.project ?? context.project;
+    if (!projectRef) {
+        console.log('No project selected. Run `venice-video use <project>` or pass -p <dir>.');
+        return;
+    }
+    const projectDir = await resolveProjectRef(projectRef, program.opts().workspace);
+    const status = await collectProjectStatus(projectDir);
+    if (!status) {
+        console.error(`No series.json found at ${projectDir}.`);
+        process.exit(1);
+        return;
+    }
+    console.log(formatProjectStatus(status, context.episode));
+});
+program
+    .command('queue')
+    .description('List Venice renders left in flight by an interrupted run')
+    .argument('[action]', 'clear to drop a recorded job, prune to drop stale ones')
+    .argument('[target]', 'Output path or queue id to clear')
+    .action(async (action, target) => {
+    if (action === 'prune') {
+        const removed = await prunePendingJobs();
+        console.log(`Pruned ${removed} stale job record(s).`);
+        return;
+    }
+    if (action === 'clear') {
+        if (!target) {
+            console.error('Usage: venice-video queue clear <output-path|queue-id>');
+            process.exit(1);
+            return;
+        }
+        const pending = await listPendingJobs();
+        const match = pending.find(job => job.queueId === target)
+            ?? pending.find(job => job.outputPath === resolve(target))
+            ?? pending.find(job => job.outputPath.endsWith(target));
+        if (!match) {
+            console.error(`No recorded job matching "${target}".`);
+            process.exit(1);
+            return;
+        }
+        await clearPendingJob(match.outputPath);
+        console.log(`Dropped ${match.queueId} (${match.outputPath}).`);
+        console.log('Note: this only forgets the id locally. Venice already charged for the render.');
+        return;
+    }
+    const pending = await listPendingJobs();
+    if (pending.length === 0) {
+        console.log('No Venice jobs are recorded as in flight.');
+        return;
+    }
+    console.log(`${pending.length} job(s) recorded as in flight:\n`);
+    for (const job of pending) {
+        const ageMin = Math.round((Date.now() - Date.parse(job.updatedAt)) / 60_000);
+        console.log(`  ${job.kind}  ${job.model}`);
+        console.log(`    queue id   ${job.queueId}`);
+        console.log(`    output     ${job.outputPath}`);
+        console.log(`    last seen  ${ageMin} min ago${isStale(job) ? ' (stale — Venice has likely dropped it)' : ''}`);
+        if (job.prompt)
+            console.log(`    prompt     ${job.prompt.slice(0, 70)}…`);
+        console.log('');
+    }
+    console.log('Re-run the command that produced these to re-attach instead of re-billing.');
+});
+program
+    .command('shell')
+    .description('Start an interactive session that keeps the selected project and runs jobs in the background')
+    .action(async () => {
+    // Imported lazily so the shell (and its readline/job machinery) costs
+    // nothing for one-shot invocations, and to avoid an import cycle back
+    // into this module.
+    const { startShell } = await import('../session/shell.js');
+    await startShell(program);
+});
+applyContextDefaults(program);
+// Only parse when executed directly. The shell imports this module to reuse the
+// same command tree, and must not have argv consumed at import time.
+if (isMainModule(import.meta.url)) {
+    try {
+        await program.parseAsync();
+    }
+    catch (error) {
+        // A missing project/episode selection is ordinary user error, not a crash —
+        // report it the way Commander reports a missing required option.
+        if (error instanceof MissingContextError) {
+            console.error(`error: ${error.message}`);
+            process.exit(1);
+        }
+        if (error instanceof OperationAbortedError) {
+            console.error('Cancelled. Any in-flight Venice job is recorded — re-run to re-attach.');
+            process.exit(130);
+        }
+        throw error;
+    }
+}
+export { program };
 // ── Helpers ───────────────────────────────────────────────────────────
 function generateCompareHtml(styles, seriesName) {
     const cards = styles.map(s => `