ima2-gen 1.1.20 → 1.1.21

package/lib/oauthLauncher.js

@@ -1,6 +1,7 @@
 import { isWin } from "../bin/lib/platform.js";
 import { config } from "../config.js";
 import { parseLocalhostPortFromUrl, parseOAuthReadyUrl } from "./runtimePorts.js";
+import { hasAuthFile } from "./codexDetect.js";
 import { spawn } from "node:child_process";
 export function startOAuthProxy(options = {}) {
     const oauthPort = options.oauthPort ?? config.oauth.proxyPort;
@@ -9,8 +10,17 @@ export function startOAuthProxy(options = {}) {
     let stopping = false;
     let restartTimer = null;
     let hasBeenReady = false;
+    let restartCount = 0;
+    const MAX_RESTARTS = 3;
     const spawnProxy = () => {
-        console.log(`Starting openai-oauth on port ${oauthPort}...`);
+        // Guard: don't start if no auth file exists (avoids pointless crash loops
+        // and prevents openai-oauth from corrupting state on refresh failure)
+        if (!hasAuthFile()) {
+            console.log("[gpt-oauth] No Codex auth file found. Skipping GPT OAuth proxy.");
+            options.onExit?.({ code: 0 });
+            return;
+        }
+        console.log(`Starting GPT OAuth proxy (openai-oauth) on port ${oauthPort}...`);
         const spawnedAt = Date.now();
         const child = spawn("npx", ["openai-oauth", "--port", String(oauthPort)], {
             stdio: ["ignore", "pipe", "pipe"],
@@ -23,14 +33,14 @@ export function startOAuthProxy(options = {}) {
             const msg = d.toString().trim();
             if (!msg)
                 return;
-            console.log(`[oauth] ${msg}`);
+            console.log(`[gpt-oauth] ${msg}`);
             for (const line of msg.split(/\r?\n/)) {
                 const url = parseOAuthReadyUrl(line);
                 if (!url)
                     continue;
                 const port = parseLocalhostPortFromUrl(url);
                 if (port && port !== oauthPort) {
-                    console.log(`[oauth] requested port ${oauthPort}, actual port ${port}`);
+                    console.log(`[gpt-oauth] requested port ${oauthPort}, actual port ${port}`);
                 }
                 options.onReady?.({ url, port: port || oauthPort, requestedPort: oauthPort });
                 hasBeenReady = true;
@@ -39,7 +49,7 @@ export function startOAuthProxy(options = {}) {
         child.stderr?.on("data", (d) => {
             const msg = d.toString().trim();
             if (msg && !msg.includes("npm warn"))
-                console.error(`[oauth] ${msg}`);
+                console.error(`[gpt-oauth] ${msg}`);
         });
         child.on("exit", (code) => {
             if (currentChild === child)
@@ -50,12 +60,17 @@ export function startOAuthProxy(options = {}) {
             if (uptime < 5000 && !hasBeenReady) {
                 // Crashed immediately without ever becoming ready — likely missing openai-oauth or no token.
                 // Don't restart; just mark as failed silently.
-                console.log(`[oauth] proxy exited immediately (code ${code}). Skipping — Grok-only mode is fine.`);
+                console.log(`[gpt-oauth] proxy exited immediately (code ${code}). Skipping — Grok-only mode is fine.`);
                 options.onExit?.({ code });
                 return;
             }
             options.onExit?.({ code });
-            console.log(`[oauth] exited with code ${code}, restarting in ${Math.round(restartDelayMs / 1000)}s...`);
+            if (restartCount >= MAX_RESTARTS) {
+                console.log(`[gpt-oauth] max restarts (${MAX_RESTARTS}) reached. Giving up — Grok-only mode is fine.`);
+                return;
+            }
+            restartCount++;
+            console.log(`[gpt-oauth] exited with code ${code}, restarting in ${Math.round(restartDelayMs / 1000)}s... (attempt ${restartCount}/${MAX_RESTARTS})`);
             restartTimer = setTimeout(spawnProxy, restartDelayMs);
         });
     };

package/lib/oauthLauncher.ts

@@ -1,6 +1,7 @@
 import { isWin } from "../bin/lib/platform.js";
 import { config } from "../config.js";
 import { parseLocalhostPortFromUrl, parseOAuthReadyUrl } from "./runtimePorts.js";
+import { hasAuthFile } from "./codexDetect.js";
 import { type ChildProcess, spawn } from "node:child_process";
 
 export function startOAuthProxy(options: any = {}) {
@@ -10,9 +11,19 @@ export function startOAuthProxy(options: any = {}) {
   let stopping = false;
   let restartTimer: NodeJS.Timeout | null = null;
   let hasBeenReady = false;
+  let restartCount = 0;
+  const MAX_RESTARTS = 3;
 
   const spawnProxy = () => {
-    console.log(`Starting openai-oauth on port ${oauthPort}...`);
+    // Guard: don't start if no auth file exists (avoids pointless crash loops
+    // and prevents openai-oauth from corrupting state on refresh failure)
+    if (!hasAuthFile()) {
+      console.log("[gpt-oauth] No Codex auth file found. Skipping GPT OAuth proxy.");
+      options.onExit?.({ code: 0 });
+      return;
+    }
+
+    console.log(`Starting GPT OAuth proxy (openai-oauth) on port ${oauthPort}...`);
     const spawnedAt = Date.now();
     const child = spawn("npx", ["openai-oauth", "--port", String(oauthPort)], {
       stdio: ["ignore", "pipe", "pipe"],
@@ -25,13 +36,13 @@ export function startOAuthProxy(options: any = {}) {
     child.stdout?.on("data", (d) => {
       const msg = d.toString().trim();
       if (!msg) return;
-      console.log(`[oauth] ${msg}`);
+      console.log(`[gpt-oauth] ${msg}`);
       for (const line of msg.split(/\r?\n/)) {
         const url = parseOAuthReadyUrl(line);
         if (!url) continue;
         const port = parseLocalhostPortFromUrl(url);
         if (port && port !== oauthPort) {
-          console.log(`[oauth] requested port ${oauthPort}, actual port ${port}`);
+          console.log(`[gpt-oauth] requested port ${oauthPort}, actual port ${port}`);
         }
         options.onReady?.({ url, port: port || oauthPort, requestedPort: oauthPort });
         hasBeenReady = true;
@@ -40,7 +51,7 @@ export function startOAuthProxy(options: any = {}) {
 
     child.stderr?.on("data", (d) => {
       const msg = d.toString().trim();
-      if (msg && !msg.includes("npm warn")) console.error(`[oauth] ${msg}`);
+      if (msg && !msg.includes("npm warn")) console.error(`[gpt-oauth] ${msg}`);
     });
 
     child.on("exit", (code) => {
@@ -50,12 +61,17 @@ export function startOAuthProxy(options: any = {}) {
       if (uptime < 5000 && !hasBeenReady) {
         // Crashed immediately without ever becoming ready — likely missing openai-oauth or no token.
         // Don't restart; just mark as failed silently.
-        console.log(`[oauth] proxy exited immediately (code ${code}). Skipping — Grok-only mode is fine.`);
+        console.log(`[gpt-oauth] proxy exited immediately (code ${code}). Skipping — Grok-only mode is fine.`);
         options.onExit?.({ code });
         return;
       }
       options.onExit?.({ code });
-      console.log(`[oauth] exited with code ${code}, restarting in ${Math.round(restartDelayMs / 1000)}s...`);
+      if (restartCount >= MAX_RESTARTS) {
+        console.log(`[gpt-oauth] max restarts (${MAX_RESTARTS}) reached. Giving up — Grok-only mode is fine.`);
+        return;
+      }
+      restartCount++;
+      console.log(`[gpt-oauth] exited with code ${code}, restarting in ${Math.round(restartDelayMs / 1000)}s... (attempt ${restartCount}/${MAX_RESTARTS})`);
       restartTimer = setTimeout(spawnProxy, restartDelayMs);
     });
   };

package/lib/videoContinuity.js

@@ -0,0 +1,149 @@
+import { readFile } from "node:fs/promises";
+import { basename, join } from "node:path";
+export const ACTIVE_VIDEO_PROMPT_GUIDANCE = [
+    "Active video prompt required.",
+    "Describe visual flow, motion flow, sound or no-music intent, dialogue or no-dialogue intent, and the desired ending frame.",
+    "Pace the scene to naturally fill the selected duration, expanding even short requests into an opening composition, connected motion/emotion change, and stable ending frame.",
+    "Example: From the attached last frame, the subject turns toward camera, rain sound rises, no background music, one whispered line finishes before a still close-up ending.",
+].join(" ");
+export function requireActiveVideoPrompt(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+export function safeGeneratedVideoFilename(value) {
+    if (typeof value !== "string" || !value.trim())
+        throw Object.assign(new Error("video filename required"), { status: 400 });
+    const clean = value.replace(/^\/generated\//, "").replace(/^\/+/, "");
+    if (clean.includes("..") || clean.includes("/") || clean.includes("\\")) {
+        throw Object.assign(new Error("invalid video filename"), { status: 400 });
+    }
+    if (!/\.mp4$/i.test(clean))
+        throw Object.assign(new Error("generated video input must be an .mp4 file"), { status: 400 });
+    return clean;
+}
+export async function readVideoSidecar(generatedDir, filename) {
+    const safe = safeGeneratedVideoFilename(filename);
+    try {
+        return JSON.parse(await readFile(join(generatedDir, `${safe}.json`), "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+function stringOrNull(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+function numberOrNow(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : Date.now();
+}
+function entryFromMeta(filename, meta) {
+    const revisedPrompt = stringOrNull(meta?.revisedPrompt) ?? stringOrNull(meta?.prompt);
+    if (!revisedPrompt)
+        return null;
+    return {
+        id: `clip:${filename}`,
+        ordinal: 1,
+        role: "start",
+        filename,
+        userPrompt: stringOrNull(meta?.userPrompt) ?? stringOrNull(meta?.prompt),
+        revisedPrompt,
+        createdAt: numberOrNow(meta?.createdAt),
+    };
+}
+export function normalizeVideoContinuityLineage(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    const raw = value;
+    if (!Array.isArray(raw.entries))
+        return null;
+    const entries = raw.entries
+        .map((entry, index) => {
+        if (!entry || typeof entry !== "object")
+            return null;
+        const e = entry;
+        const revisedPrompt = stringOrNull(e.revisedPrompt);
+        if (!revisedPrompt)
+            return null;
+        return {
+            id: stringOrNull(e.id) ?? `entry:${index + 1}`,
+            ordinal: index + 1,
+            role: index === 0 ? "start" : index === raw.entries.length - 1 ? "parent" : "ancestor",
+            filename: stringOrNull(e.filename),
+            userPrompt: stringOrNull(e.userPrompt),
+            revisedPrompt,
+            createdAt: numberOrNow(e.createdAt),
+        };
+    })
+        .filter((entry) => Boolean(entry));
+    if (entries.length === 0)
+        return null;
+    return {
+        lineageId: stringOrNull(raw.lineageId) ?? `lineage:${entries[0].id}`,
+        parentFilename: stringOrNull(raw.parentFilename),
+        sourceFrame: "last",
+        maxEntries: 4,
+        retention: "keep-start-plus-latest-3",
+        entries: trimLineageEntries(entries),
+    };
+}
+export function trimLineageEntries(entries) {
+    const kept = entries.length <= 4 ? entries : [entries[0], ...entries.slice(-3)];
+    return kept.map((entry, index) => ({
+        ...entry,
+        ordinal: index + 1,
+        role: index === 0 ? "start" : index === kept.length - 1 ? entry.role : "ancestor",
+    }));
+}
+export function lineageFromVideoMetadata(filename, meta) {
+    const existing = normalizeVideoContinuityLineage(meta?.videoContinuity);
+    if (existing) {
+        return { ...existing, parentFilename: filename, sourceFrame: "last" };
+    }
+    const entry = entryFromMeta(filename, meta);
+    if (!entry)
+        return null;
+    return {
+        lineageId: `lineage:${filename.replace(/\.[^.]+$/, "")}`,
+        parentFilename: filename,
+        sourceFrame: "last",
+        maxEntries: 4,
+        retention: "keep-start-plus-latest-3",
+        entries: [entry],
+    };
+}
+export function appendVideoContinuityEntry(parent, current) {
+    const parentEntries = parent?.entries ?? [];
+    const lineageId = parent?.lineageId ?? `lineage:${current.filename.replace(/\.[^.]+$/, "")}`;
+    const currentEntry = {
+        id: `clip:${current.filename}`,
+        ordinal: parentEntries.length + 1,
+        role: "current",
+        filename: current.filename,
+        userPrompt: current.userPrompt,
+        revisedPrompt: current.revisedPrompt,
+        createdAt: current.createdAt ?? Date.now(),
+    };
+    const entries = trimLineageEntries([...parentEntries.map((entry) => ({ ...entry, role: entry.role === "current" ? "parent" : entry.role })), currentEntry]);
+    return {
+        lineageId,
+        parentFilename: parent?.parentFilename ?? null,
+        sourceFrame: parent ? "last" : null,
+        maxEntries: 4,
+        retention: "keep-start-plus-latest-3",
+        entries,
+    };
+}
+export function formatVideoContinuityForPlanner(lineage) {
+    if (!lineage?.entries?.length)
+        return "";
+    const lines = [
+        "[Continuity lineage: branch-local, max 4 entries, start anchor preserved]",
+        ...lineage.entries.map((entry) => [
+            `${entry.ordinal}. Clip ${entry.ordinal} / ${entry.role}`,
+            `   file: ${entry.filename ? basename(entry.filename) : "unknown"}`,
+            `   revisedPrompt: ${entry.revisedPrompt}`,
+            entry.userPrompt ? `   userPrompt: ${entry.userPrompt}` : null,
+        ].filter(Boolean).join("\n")),
+        "Continue from the final frame and final action/audio state of the latest lineage item. Do not restart the scene.",
+    ];
+    return lines.join("\n");
+}

package/lib/videoContinuity.ts

@@ -0,0 +1,180 @@
+import { readFile } from "node:fs/promises";
+import { basename, join } from "node:path";
+
+export const ACTIVE_VIDEO_PROMPT_GUIDANCE = [
+  "Active video prompt required.",
+  "Describe visual flow, motion flow, sound or no-music intent, dialogue or no-dialogue intent, and the desired ending frame.",
+  "Pace the scene to naturally fill the selected duration, expanding even short requests into an opening composition, connected motion/emotion change, and stable ending frame.",
+  "Example: From the attached last frame, the subject turns toward camera, rain sound rises, no background music, one whispered line finishes before a still close-up ending.",
+].join(" ");
+
+export type VideoContinuityEntry = {
+  id: string;
+  ordinal: number;
+  role: "start" | "ancestor" | "parent" | "current";
+  filename: string | null;
+  userPrompt: string | null;
+  revisedPrompt: string;
+  createdAt: number;
+};
+
+export type VideoContinuityLineage = {
+  lineageId: string;
+  parentFilename: string | null;
+  sourceFrame: "last" | null;
+  maxEntries: 4;
+  retention: "keep-start-plus-latest-3";
+  entries: VideoContinuityEntry[];
+};
+
+type VideoMeta = {
+  prompt?: unknown;
+  userPrompt?: unknown;
+  revisedPrompt?: unknown;
+  createdAt?: unknown;
+  videoContinuity?: unknown;
+};
+
+export function requireActiveVideoPrompt(value: unknown): string | null {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+
+export function safeGeneratedVideoFilename(value: unknown): string {
+  if (typeof value !== "string" || !value.trim()) throw Object.assign(new Error("video filename required"), { status: 400 });
+  const clean = value.replace(/^\/generated\//, "").replace(/^\/+/, "");
+  if (clean.includes("..") || clean.includes("/") || clean.includes("\\")) {
+    throw Object.assign(new Error("invalid video filename"), { status: 400 });
+  }
+  if (!/\.mp4$/i.test(clean)) throw Object.assign(new Error("generated video input must be an .mp4 file"), { status: 400 });
+  return clean;
+}
+
+export async function readVideoSidecar(generatedDir: string, filename: string): Promise<VideoMeta | null> {
+  const safe = safeGeneratedVideoFilename(filename);
+  try {
+    return JSON.parse(await readFile(join(generatedDir, `${safe}.json`), "utf-8")) as VideoMeta;
+  } catch {
+    return null;
+  }
+}
+
+function stringOrNull(value: unknown): string | null {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+
+function numberOrNow(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : Date.now();
+}
+
+function entryFromMeta(filename: string, meta: VideoMeta | null): VideoContinuityEntry | null {
+  const revisedPrompt = stringOrNull(meta?.revisedPrompt) ?? stringOrNull(meta?.prompt);
+  if (!revisedPrompt) return null;
+  return {
+    id: `clip:${filename}`,
+    ordinal: 1,
+    role: "start",
+    filename,
+    userPrompt: stringOrNull(meta?.userPrompt) ?? stringOrNull(meta?.prompt),
+    revisedPrompt,
+    createdAt: numberOrNow(meta?.createdAt),
+  };
+}
+
+export function normalizeVideoContinuityLineage(value: unknown): VideoContinuityLineage | null {
+  if (!value || typeof value !== "object") return null;
+  const raw = value as Partial<VideoContinuityLineage>;
+  if (!Array.isArray(raw.entries)) return null;
+  const entries = raw.entries
+    .map((entry, index): VideoContinuityEntry | null => {
+      if (!entry || typeof entry !== "object") return null;
+      const e = entry as Partial<VideoContinuityEntry>;
+      const revisedPrompt = stringOrNull(e.revisedPrompt);
+      if (!revisedPrompt) return null;
+      return {
+        id: stringOrNull(e.id) ?? `entry:${index + 1}`,
+        ordinal: index + 1,
+        role: index === 0 ? "start" : index === raw.entries!.length - 1 ? "parent" : "ancestor",
+        filename: stringOrNull(e.filename),
+        userPrompt: stringOrNull(e.userPrompt),
+        revisedPrompt,
+        createdAt: numberOrNow(e.createdAt),
+      };
+    })
+    .filter((entry): entry is VideoContinuityEntry => Boolean(entry));
+  if (entries.length === 0) return null;
+  return {
+    lineageId: stringOrNull(raw.lineageId) ?? `lineage:${entries[0].id}`,
+    parentFilename: stringOrNull(raw.parentFilename),
+    sourceFrame: "last",
+    maxEntries: 4,
+    retention: "keep-start-plus-latest-3",
+    entries: trimLineageEntries(entries),
+  };
+}
+
+export function trimLineageEntries(entries: VideoContinuityEntry[]): VideoContinuityEntry[] {
+  const kept = entries.length <= 4 ? entries : [entries[0], ...entries.slice(-3)];
+  return kept.map((entry, index) => ({
+    ...entry,
+    ordinal: index + 1,
+    role: index === 0 ? "start" : index === kept.length - 1 ? entry.role : "ancestor",
+  }));
+}
+
+export function lineageFromVideoMetadata(filename: string, meta: VideoMeta | null): VideoContinuityLineage | null {
+  const existing = normalizeVideoContinuityLineage(meta?.videoContinuity);
+  if (existing) {
+    return { ...existing, parentFilename: filename, sourceFrame: "last" };
+  }
+  const entry = entryFromMeta(filename, meta);
+  if (!entry) return null;
+  return {
+    lineageId: `lineage:${filename.replace(/\.[^.]+$/, "")}`,
+    parentFilename: filename,
+    sourceFrame: "last",
+    maxEntries: 4,
+    retention: "keep-start-plus-latest-3",
+    entries: [entry],
+  };
+}
+
+export function appendVideoContinuityEntry(
+  parent: VideoContinuityLineage | null,
+  current: { filename: string; userPrompt: string | null; revisedPrompt: string; createdAt?: number },
+): VideoContinuityLineage {
+  const parentEntries = parent?.entries ?? [];
+  const lineageId = parent?.lineageId ?? `lineage:${current.filename.replace(/\.[^.]+$/, "")}`;
+  const currentEntry: VideoContinuityEntry = {
+    id: `clip:${current.filename}`,
+    ordinal: parentEntries.length + 1,
+    role: "current",
+    filename: current.filename,
+    userPrompt: current.userPrompt,
+    revisedPrompt: current.revisedPrompt,
+    createdAt: current.createdAt ?? Date.now(),
+  };
+  const entries = trimLineageEntries([...parentEntries.map((entry) => ({ ...entry, role: entry.role === "current" ? "parent" as const : entry.role })), currentEntry]);
+  return {
+    lineageId,
+    parentFilename: parent?.parentFilename ?? null,
+    sourceFrame: parent ? "last" : null,
+    maxEntries: 4,
+    retention: "keep-start-plus-latest-3",
+    entries,
+  };
+}
+
+export function formatVideoContinuityForPlanner(lineage: VideoContinuityLineage | null | undefined): string {
+  if (!lineage?.entries?.length) return "";
+  const lines = [
+    "[Continuity lineage: branch-local, max 4 entries, start anchor preserved]",
+    ...lineage.entries.map((entry) => [
+      `${entry.ordinal}. Clip ${entry.ordinal} / ${entry.role}`,
+      `   file: ${entry.filename ? basename(entry.filename) : "unknown"}`,
+      `   revisedPrompt: ${entry.revisedPrompt}`,
+      entry.userPrompt ? `   userPrompt: ${entry.userPrompt}` : null,
+    ].filter(Boolean).join("\n")),
+    "Continue from the final frame and final action/audio state of the latest lineage item. Do not restart the scene.",
+  ];
+  return lines.join("\n");
+}

package/lib/videoFrameExtract.js

@@ -0,0 +1,80 @@
+import { execFile } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { open, readFile, realpath, stat, unlink } from "node:fs/promises";
+import { extname, join, resolve, sep } from "node:path";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+const MAX_LOCAL_VIDEO_BYTES = 100 * 1024 * 1024;
+const MAX_FRAME_POSITION_SECONDS = 60 * 60;
+const FFMPEG_TIMEOUT_MS = 30_000;
+function routeError(message, status = 400) {
+    return Object.assign(new Error(message), { status });
+}
+export async function safeGeneratedFilePath(generatedDir, file, options = {}) {
+    const base = resolve(generatedDir);
+    const target = file.startsWith("/") ? resolve(file) : resolve(base, file);
+    if (target !== base && !target.startsWith(`${base}${sep}`)) {
+        throw routeError("invalid file path", 400);
+    }
+    let baseReal;
+    let targetReal;
+    try {
+        baseReal = await realpath(base);
+        targetReal = await realpath(target);
+    }
+    catch {
+        throw routeError("video file not found", 404);
+    }
+    if (targetReal !== baseReal && !targetReal.startsWith(`${baseReal}${sep}`)) {
+        throw routeError("invalid file path", 400);
+    }
+    if (options.requireMp4 && extname(targetReal).toLowerCase() !== ".mp4") {
+        throw routeError("generated video input must be an .mp4 file", 400);
+    }
+    return targetReal;
+}
+export async function assertLocalMp4(path) {
+    const info = await stat(path);
+    if (!info.isFile())
+        throw routeError("generated video input must be a file", 400);
+    if (info.size <= 0)
+        throw routeError("generated video input is empty", 400);
+    if (info.size > MAX_LOCAL_VIDEO_BYTES)
+        throw routeError("generated video input exceeds the 100MB limit", 400);
+    const fh = await open(path, "r");
+    try {
+        const header = Buffer.alloc(12);
+        const { bytesRead } = await fh.read(header, 0, header.length, 0);
+        if (bytesRead < 12 || header.subarray(4, 8).toString("ascii") !== "ftyp") {
+            throw routeError("generated video input must be an MP4 container", 400);
+        }
+    }
+    finally {
+        await fh.close();
+    }
+}
+export async function extractVideoFrame(input, output, position) {
+    const options = { timeout: FFMPEG_TIMEOUT_MS, killSignal: "SIGKILL", maxBuffer: 1024 * 1024 };
+    if (position === "last") {
+        await execFileAsync("ffmpeg", ["-y", "-sseof", "-3", "-i", input, "-update", "1", "-q:v", "1", output], options);
+        return;
+    }
+    const sec = Number(position);
+    if (!Number.isFinite(sec) || sec < 0)
+        throw new Error("position must be a non-negative number or 'last'");
+    if (sec > MAX_FRAME_POSITION_SECONDS)
+        throw new Error("position exceeds the maximum supported seek time");
+    await execFileAsync("ffmpeg", ["-y", "-ss", String(sec), "-i", input, "-vframes", "1", output], options);
+}
+export async function extractGeneratedVideoFrameB64(generatedDir, filename, position = "last") {
+    const inputPath = await safeGeneratedFilePath(generatedDir, filename, { requireMp4: true });
+    await assertLocalMp4(inputPath);
+    const tmpOut = join(generatedDir, `frame_tmp_${randomBytes(4).toString("hex")}.png`);
+    try {
+        await extractVideoFrame(inputPath, tmpOut, position);
+        return (await readFile(tmpOut)).toString("base64");
+    }
+    finally {
+        await unlink(tmpOut).catch(() => { });
+    }
+}

package/lib/videoFrameExtract.ts

@@ -0,0 +1,78 @@
+import { execFile } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { open, readFile, realpath, stat, unlink } from "node:fs/promises";
+import { extname, join, resolve, sep } from "node:path";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+const MAX_LOCAL_VIDEO_BYTES = 100 * 1024 * 1024;
+const MAX_FRAME_POSITION_SECONDS = 60 * 60;
+const FFMPEG_TIMEOUT_MS = 30_000;
+
+function routeError(message: string, status = 400): Error & { status: number } {
+  return Object.assign(new Error(message), { status });
+}
+
+export async function safeGeneratedFilePath(generatedDir: string, file: string, options: { requireMp4?: boolean } = {}): Promise<string> {
+  const base = resolve(generatedDir);
+  const target = file.startsWith("/") ? resolve(file) : resolve(base, file);
+  if (target !== base && !target.startsWith(`${base}${sep}`)) {
+    throw routeError("invalid file path", 400);
+  }
+  let baseReal: string;
+  let targetReal: string;
+  try {
+    baseReal = await realpath(base);
+    targetReal = await realpath(target);
+  } catch {
+    throw routeError("video file not found", 404);
+  }
+  if (targetReal !== baseReal && !targetReal.startsWith(`${baseReal}${sep}`)) {
+    throw routeError("invalid file path", 400);
+  }
+  if (options.requireMp4 && extname(targetReal).toLowerCase() !== ".mp4") {
+    throw routeError("generated video input must be an .mp4 file", 400);
+  }
+  return targetReal;
+}
+
+export async function assertLocalMp4(path: string): Promise<void> {
+  const info = await stat(path);
+  if (!info.isFile()) throw routeError("generated video input must be a file", 400);
+  if (info.size <= 0) throw routeError("generated video input is empty", 400);
+  if (info.size > MAX_LOCAL_VIDEO_BYTES) throw routeError("generated video input exceeds the 100MB limit", 400);
+  const fh = await open(path, "r");
+  try {
+    const header = Buffer.alloc(12);
+    const { bytesRead } = await fh.read(header, 0, header.length, 0);
+    if (bytesRead < 12 || header.subarray(4, 8).toString("ascii") !== "ftyp") {
+      throw routeError("generated video input must be an MP4 container", 400);
+    }
+  } finally {
+    await fh.close();
+  }
+}
+
+export async function extractVideoFrame(input: string, output: string, position: string): Promise<void> {
+  const options = { timeout: FFMPEG_TIMEOUT_MS, killSignal: "SIGKILL" as const, maxBuffer: 1024 * 1024 };
+  if (position === "last") {
+    await execFileAsync("ffmpeg", ["-y", "-sseof", "-3", "-i", input, "-update", "1", "-q:v", "1", output], options);
+    return;
+  }
+  const sec = Number(position);
+  if (!Number.isFinite(sec) || sec < 0) throw new Error("position must be a non-negative number or 'last'");
+  if (sec > MAX_FRAME_POSITION_SECONDS) throw new Error("position exceeds the maximum supported seek time");
+  await execFileAsync("ffmpeg", ["-y", "-ss", String(sec), "-i", input, "-vframes", "1", output], options);
+}
+
+export async function extractGeneratedVideoFrameB64(generatedDir: string, filename: string, position = "last"): Promise<string> {
+  const inputPath = await safeGeneratedFilePath(generatedDir, filename, { requireMp4: true });
+  await assertLocalMp4(inputPath);
+  const tmpOut = join(generatedDir, `frame_tmp_${randomBytes(4).toString("hex")}.png`);
+  try {
+    await extractVideoFrame(inputPath, tmpOut, position);
+    return (await readFile(tmpOut)).toString("base64");
+  } finally {
+    await unlink(tmpOut).catch(() => {});
+  }
+}