Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

12.5 KB
Raw Blame
/**
 * Pipeline — Episode Video stage handoff.
 *
 * The Pipeline's `episodeVideo` stage drives the full per-scene render +
 * stitch loop, but reuses the Creative Director machinery instead of
 * duplicating it. We create a CD project with `autoAcceptScenes: true` so
 * no LLM evaluator round-trip runs (the Pipeline already had the human
 * vetting the storyboard scenes), then ask CD to start the project. CD's own
 * completionHook / sceneRunner / stitchRunner take it from there.
 *
 * That start goes through `creativeDirector/projectStartSink.js` rather than a
 * direct import of the completion hook (#5920): a static edge pipeline → CD closed
 * a 22-module import cycle, because CD's tool registry starts a Series Autopilot in
 * the other direction. The sink is a leaf both halves can depend on; the hook
 * registers the concrete starter on it.
 *
 * The CD project id is persisted on the issue's `stages.episodeVideo` so
 * the UI can poll `/api/creative-director/:id` to render progress and
 * surface the final stitched video when complete.
 */
import { composeVisualPrompt } from './visualStages.js';
import { getIssue, updateStage, assertStageUnlocked } from './issues.js';
import { getSeries } from './series.js';
import { getSeriesCanon } from './seriesCanon.js';
import { createProject as createCDProject, setTreatment as setCDTreatment } from '../creativeDirector/local.js';
import { requestCreativeDirectorProjectStart } from '../creativeDirector/projectStartSink.js';
import { getDefaultVideoModelId, getVideoModels } from '../../lib/mediaModels.js';
import { buildPlaceByKey } from '../../lib/scenePrompt.js';
import { getSettings } from '../settings.js';
import { codedError } from '../../lib/codedError.js';

export const ERR_NO_STORYBOARDS = 'PIPELINE_EPISODE_NO_STORYBOARDS';

const DEFAULT_SCENE_DURATION = 3;
const MAX_SCENES = 30;
const CD_NEGATIVE_PROMPT = 'text, watermark, blur, motion blur, low quality';

// Single source of truth for the CD-scene shape. `order` is stamped at flatten
// time so callers don't carry a placeholder. Duration is clamped to [1,10] for
// CD pacing — narrower than the sanitizer's [1,30] storage envelope on purpose.
function buildCdScene({ sceneId, intent, prompt, durationSecondsRaw, useContinuationFromPrior }) {
  return {
    sceneId,
    intent: intent.slice(0, 1000),
    prompt: prompt.slice(0, 8000),
    negativePrompt: CD_NEGATIVE_PROMPT,
    durationSeconds: Number.isFinite(durationSecondsRaw)
      ? Math.min(10, Math.max(1, durationSecondsRaw))
      : DEFAULT_SCENE_DURATION,
    useContinuationFromPrior,
    sourceImageFile: null,
  };
}

// Map one storyboard scene's shots[] to N CD scenes. Within-scene shots chain
// by default (natural i2v continuation); the LLM can also flag an explicit
// continuity ref to chain across a scene boundary (deliberate match cut).
function expandShotsToCdScenes(scene, sceneIdx, shortIssueId, baselinePrompt) {
  const shots = Array.isArray(scene.shots) ? scene.shots : [];
  return shots.map((shot, sIdx) => {
    const description = (shot.description || '').trim() || scene.description;
    const chainsWithinScene = sIdx > 0;
    const explicitContinuity = !!shot.continuityFromShotId;
    return buildCdScene({
      sceneId: `iss-${shortIssueId}-s${sceneIdx + 1}-sh${sIdx + 1}`,
      intent: scene.slugline
        ? `${scene.slugline} — shot ${sIdx + 1}`
        : `Scene ${sceneIdx + 1} Shot ${sIdx + 1}`,
      prompt: baselinePrompt(description, scene.slugline),
      durationSecondsRaw: shot.durationSeconds,
      useContinuationFromPrior: chainsWithinScene || explicitContinuity,
    });
  });
}

/**
 * Build the CD treatment from a pipeline issue's storyboards stage. The
 * mapping rules:
 *   - Scene with shots[] → N CD scenes (one per shot); shots chain within
 *     the scene, the first shot of each scene starts a fresh angle.
 *   - Scene without shots[] → one CD scene (legacy behavior); subsequent
 *     legacy scenes chain via useContinuationFromPrior=true.
 *
 * MAX_SCENES caps the flattened CD scene count so an issue with deep shot
 * decomposition can't push the CD render queue past its single-issue budget.
 */
export function buildTreatmentFromStoryboards({ issue, series, canon = null }) {
  const storyboards = issue.stages?.storyboards;
  const rawScenes = Array.isArray(storyboards?.scenes) ? storyboards.scenes : [];
  const usable = rawScenes.filter((s) => (s?.description || '').trim().length > 0);
  if (!usable.length) {
    throw codedError(
      'Storyboards stage has no scenes with descriptions. Add scenes on the Storyboards stage first.',
      ERR_NO_STORYBOARDS,
    );
  }
  const shortIssueId = issue.id.slice(-8);
  // Canon places live on the linked universe (Phase B.4). Build the
  // placeByKey once and reuse across every scene's composeVisualPrompt
  // call rather than rebuilding per-call.
  const placeByKey = buildPlaceByKey(canon?.places);
  const baselinePrompt = (description, slugline) =>
    composeVisualPrompt({ series, description, slugline: slugline || '', placeByKey });

  const flattened = [];
  for (let idx = 0; idx < usable.length; idx += 1) {
    const scene = usable[idx];
    const expanded = (Array.isArray(scene.shots) && scene.shots.length > 0)
      ? expandShotsToCdScenes(scene, idx, shortIssueId, baselinePrompt)
      : [buildCdScene({
        sceneId: `iss-${shortIssueId}-s${idx + 1}`,
        intent: scene.slugline || `Scene ${idx + 1}`,
        prompt: baselinePrompt(scene.description, scene.slugline),
        durationSecondsRaw: scene.durationSeconds,
        // First entry overall is fresh; every legacy scene after it chains
        // from its predecessor — matches the pre-shots behavior exactly.
        useContinuationFromPrior: flattened.length > 0,
      })];
    const room = MAX_SCENES - flattened.length;
    if (room <= 0) break;
    flattened.push(...expanded.slice(0, room));
  }
  // Stamp final order indices after truncation so the CD project sees a
  // contiguous [0..N) sequence regardless of where the cap kicked in.
  const scenes = flattened.map((cd, i) => ({ ...cd, order: i }));
  const logline = (series?.logline || issue.title || 'Episode video').slice(0, 500);
  const synopsis = ((issue.stages?.idea?.output || issue.title || 'Pipeline episode') + '').slice(0, 5000);
  return { logline, synopsis, scenes };
}

/**
 * Create a CD project from a pipeline issue's storyboards stage and kick
 * off the render → stitch loop. Persists `cdProjectId` on the issue's
 * `stages.episodeVideo` so subsequent polls find the running CD project.
 *
 * Idempotent in spirit: if the stage already has a `cdProjectId` and
 * `options.force` is not set, returns the existing id instead of creating
 * a duplicate. The route layer can call this again to reuse an in-flight
 * run safely.
 */
export async function startEpisodeVideoForIssue(issueId, options = {}) {
  const [issue, settings] = await Promise.all([getIssue(issueId), getSettings()]);

  // Reuse path (existing cdProjectId) is still allowed when locked — locking
  // a stage freezes regeneration, not status reads. The fresh-start branch
  // below builds a new CD project + treatment, which IS regeneration; the
  // lock check gates that branch only.
  const existing = issue.stages?.episodeVideo?.cdProjectId;
  const series = await getSeries(issue.seriesId);
  // Canon (characters / places / objects) lives on the linked universe
  // — load it so the per-scene baseline prompt can inject place baseline
  // context (INT/EXT, timeOfDay, palette, recurring details) for matched
  // sluglines. Orphan series render with empty canon.
  const canon = await getSeriesCanon(series);
  const treatment = buildTreatmentFromStoryboards({ issue, series, canon });
  if (existing && !options.force) {
    // SSE / UI status messaging stays consistent between fresh-start and
    // reuse paths by reusing the treatment builder for the scene count —
    // shot expansion + MAX_SCENES truncation produce the same number both
    // times, so the user sees "N scenes" matching what was actually queued.
    return { cdProjectId: existing, reused: true, scenes: treatment.scenes.length };
  }
  // Fresh-start branch — gate on the per-stage lock now that we know we're
  // about to spin up a new CD project + render run.
  assertStageUnlocked(issue, 'episodeVideo');
  const aspectRatio = options.aspectRatio || '16:9';
  const quality = options.quality || 'standard';
  // The user's picker choice: `null` = "Default model". Unlike aspectRatio /
  // quality (whose defaults are fixed constants), the video default is a live
  // user setting (videoGen.defaultModelId), so we persist the *choice* — not
  // the resolved id — and keep "Default" following the setting across reloads.
  // The CD project's renderer still needs a concrete model, so resolve one here.
  // Validate an explicit picker choice against the live video-model registry.
  // A persisted `modelId` can go stale if the model is later renamed/pruned —
  // on restart it would flow into createCDProject and fail asynchronously on
  // the CD project's failureReason. Drop a now-unknown id to the resolved
  // default so the render degrades cleanly instead.
  //
  // Sentinel rule: only drop when the registry has a NON-EMPTY list to validate
  // against. An empty list means "can't validate on this platform" (e.g. every
  // video model flagged broken) — NOT "this id is unknown" — so we pass the id
  // through rather than silently swapping a possibly-valid choice for a default
  // that's equally unresolvable. This mirrors getDefaultVideoModelId, which
  // returns the configured id unchanged when there's nothing to fall back to.
  let requestedModelId = options.modelId || null;
  const knownModels = getVideoModels();
  // `null` when the registry can't be validated (empty list) — in that case
  // isKnown() is never consulted and every candidate id passes through.
  const isKnown = knownModels.length ? (id) => knownModels.some((m) => m.id === id) : null;
  if (requestedModelId && isKnown && !isKnown(requestedModelId)) {
    console.log(`⚠️ Pipeline episode video — unknown modelId "${requestedModelId}" not in registry; dropping to default`);
    requestedModelId = null;
  }
  // Resolve the concrete model the CD renderer needs. The saved videoGen
  // default can be just as stale as the explicit pick, so validate it the same
  // way before trusting it — otherwise a broken settings default would still
  // reach createCDProject and defeat the drop-to-default contract.
  // getDefaultVideoModelId() is the final fallback and self-validates against
  // the platform's available list.
  const settingsDefault = settings?.videoGen?.defaultModelId || null;
  const resolvedDefault = (settingsDefault && (!isKnown || isKnown(settingsDefault)))
    ? settingsDefault
    : getDefaultVideoModelId();
  const modelId = requestedModelId || resolvedDefault;

  const project = await createCDProject({
    name: `Pipeline: ${(series?.name || 'Series').slice(0, 60)} — ${(issue.title || issueId).slice(0, 60)}`,
    aspectRatio,
    quality,
    modelId,
    targetDurationSeconds: Math.min(600, treatment.scenes.reduce((sum, s) => sum + s.durationSeconds, 0)),
    styleSpec: series?.styleNotes || '',
    startingImageFile: null,
    userStory: issue.stages?.prose?.output || null,
    disableAudio: true,
    autoAcceptScenes: true,
    sourceIssueId: issueId,
  });
  await setCDTreatment(project.id, treatment);

  await updateStage(issueId, 'episodeVideo', {
    status: 'generating',
    cdProjectId: project.id,
    // Persist the chosen render settings so a page reload restores the
    // pickers — otherwise restart from a fresh tab would silently fall back
    // to defaults that the user can't see or adjust. modelId persists the
    // user's CHOICE (null = "Default"), so a Default pick keeps tracking the
    // videoGen.defaultModelId setting on reload instead of pinning to whatever
    // it happened to resolve to at first render.
    aspectRatio,
    quality,
    modelId: requestedModelId,
    output: '',
    errorMessage: '',
  });

  // Kick off the orchestrator — fire-and-forget so the route can return
  // immediately. Failures land on the CD project's `failureReason` field
  // and surface via the UI's CD project poll, not via this Promise.
  requestCreativeDirectorProjectStart(project.id).catch((err) =>
    console.log(`⚠️ Pipeline episode CD start failed for ${project.id}: ${err.message}`),
  );

  console.log(`🎬 Pipeline episode video — issue=${issueId.slice(0, 8)} cdProject=${project.id.slice(0, 8)} scenes=${treatment.scenes.length}`);
  return { cdProjectId: project.id, scenes: treatment.scenes.length, reused: false };
}