mulmocast 2.6.23 → 2.7.1

package/lib/utils/estimate_usage.js

@@ -0,0 +1,332 @@
+// Pre-run usage estimator: walks a MulmoScript and returns, per beat and per
+// process, the API usage a full generation run would consume. Pure and
+// browser-compatible (js-tiktoken is pure JS). No cache awareness: estimates
+// assume every asset is generated fresh.
+import { Tiktoken } from "js-tiktoken/lite";
+import o200k_base from "js-tiktoken/ranks/o200k_base";
+import { provider2TTSAgent, provider2MovieAgent, gptImageOutputTokens, getModelDuration, getModelPricing, defaultProviders, } from "../types/provider2agent.js";
+import { text2SpeechProviderSchema, text2MovieProviderSchema } from "../types/schema.js";
+import { MulmoPresentationStyleMethods } from "../methods/mulmo_presentation_style.js";
+import { MulmoBeatMethods } from "../methods/mulmo_beat.js";
+import { imagePrompt, htmlImageSystemPrompt, translateSystemPrompt, translatePrompts } from "./prompt.js";
+const MILLION = 1_000_000;
+const LATIN_CHARS_PER_TOKEN = 4;
+const CJK_CHARS_PER_SEC = 6;
+const LATIN_CHARS_PER_SEC = 15;
+// Measured ≈50 audio output tokens per second (docs/api.md § Known gaps, probed in PR #1439).
+const OPENAI_TTS_AUDIO_TOKENS_PER_SEC = 50;
+// Documented: Gemini TTS audio tokens = 25 per second of audio.
+const GEMINI_TTS_AUDIO_TOKENS_PER_SEC = 25;
+// gpt-5 completion_tokens include reasoning tokens; a simple slide measured ≈4.4k (probe 2026-07-03).
+const HTML_OUTPUT_TOKENS_GUESS = 4000;
+const TRANSLATE_OUTPUT_FACTOR = 1.2;
+// The translate action doesn't set a model, so @graphai/openai_agent's default applies.
+const TRANSLATE_DEFAULT_MODEL = "gpt-4o";
+const DEFAULT_MOVIE_DURATION_SEC = 8;
+const GPT_IMAGE_FIXED_TOKEN_MODELS = ["gpt-image-1", "gpt-image-1-mini"];
+// Fixed request framing the API adds on top of the tokenized prompt text. Both values
+// reproduced the billed prompt_tokens exactly, per record, in the 2026-07-03 probes
+// (scripts/probe/probe_estimate_vs_actual.ts): chat completions (system + user) +10,
+// image generation +6.
+const OPENAI_CHAT_INPUT_OVERHEAD_TOKENS = 10;
+const GPT_IMAGE_INPUT_OVERHEAD_TOKENS = 6;
+// What each CLI action actually consumes. translate is part of every generation scope
+// because the CLI runs it implicitly when the target/caption language differs from the
+// script language; the estimator emits zero translate records otherwise.
+const VISUAL_PROCESSES = ["image", "htmlImage", "movie", "soundEffect", "lipSync", "imageReference", "movieReference"];
+export const actionEstimateProcesses = {
+    audio: ["tts", "translate"],
+    images: [...VISUAL_PROCESSES, "translate"],
+    pdf: [...VISUAL_PROCESSES, "translate"],
+    movie: ["tts", ...VISUAL_PROCESSES, "translate"],
+    translate: ["translate"],
+};
+const isDefined = (value) => value !== undefined;
+const isKeyOf = (obj, key) => key in obj;
+let openAITokenizer;
+const countOpenAITokens = (text) => {
+    // Lazy: building the o200k_base BPE table is expensive and most importers never estimate.
+    openAITokenizer = openAITokenizer ?? new Tiktoken(o200k_base);
+    return openAITokenizer.encode(text).length;
+};
+const cjkPattern = /[⺀-鿿가-힯豈-﫿ｦ-ﾟ]/g;
+const countCjkChars = (text) => (text.match(cjkPattern) ?? []).length;
+const countHeuristicTokens = (text) => {
+    const cjkChars = countCjkChars(text);
+    return cjkChars + Math.ceil((text.length - cjkChars) / LATIN_CHARS_PER_TOKEN);
+};
+const estimateSpeechSec = (text) => {
+    const cjkChars = countCjkChars(text);
+    const latinChars = text.length - cjkChars;
+    return Math.max(1, Math.round(cjkChars / CJK_CHARS_PER_SEC + latinChars / LATIN_CHARS_PER_SEC));
+};
+const exact = (value) => ({ value, precision: "exact" });
+const estimated = (value) => ({ value, precision: "estimated" });
+const metric = (value, isExact) => ({ value, precision: isExact ? "exact" : "estimated" });
+const computeCostUSD = (pricing, record) => {
+    const tokenValue = (m, rate) => (m && rate ? (m.value * rate) / MILLION : 0);
+    const total = tokenValue(record.inputTokens, pricing.inputPerMTokensUSD) +
+        tokenValue(record.outputTokens, pricing.outputPerMTokensUSD) +
+        tokenValue(record.inputChars, pricing.perMCharsUSD) +
+        (record.predictSec && pricing.perSecUSD ? record.predictSec.value * pricing.perSecUSD : 0) +
+        (record.imageCount && pricing.perImageUSD ? record.imageCount.value * pricing.perImageUSD : 0);
+    return total > 0 ? total : undefined;
+};
+const attachCost = (record, pricingKey) => {
+    const pricing = getModelPricing(record.provider, pricingKey ?? record.model);
+    if (!pricing) {
+        return record;
+    }
+    const costUSD = computeCostUSD(pricing, record);
+    return costUSD !== undefined ? { ...record, costUSD, pricingAsOf: pricing.asOf } : record;
+};
+const buildOpenAITts = ({ speaker, text, textIsFinal, beatIndex, lang }) => {
+    const model = speaker.model ?? provider2TTSAgent.openai.defaultModel;
+    // gpt-* TTS models are token-billed; legacy tts-1 models are character-billed.
+    const tokenMetrics = model.startsWith("gpt-")
+        ? {
+            inputTokens: metric(countOpenAITokens(text), textIsFinal),
+            outputTokens: estimated(estimateSpeechSec(text) * OPENAI_TTS_AUDIO_TOKENS_PER_SEC),
+        }
+        : {};
+    return { process: "tts", beatIndex, lang, provider: "openai", model, inputChars: metric(text.length, textIsFinal), ...tokenMetrics };
+};
+const buildGeminiTts = ({ speaker, speechOptions, text, beatIndex, lang }) => {
+    // The gemini TTS agent wraps the transcript in a "Director's Notes" prompt when an instruction is set.
+    const prompt = speechOptions?.instruction ? `### DIRECTOR'S NOTES\n${speechOptions.instruction}\n\n#### TRANSCRIPT\n${text}` : text;
+    return {
+        process: "tts",
+        beatIndex,
+        lang,
+        provider: "gemini",
+        model: speaker.model ?? provider2TTSAgent.gemini.defaultModel,
+        inputTokens: estimated(countHeuristicTokens(prompt)),
+        outputTokens: estimated(estimateSpeechSec(text) * GEMINI_TTS_AUDIO_TOKENS_PER_SEC),
+    };
+};
+const buildGoogleTts = ({ speaker, text, textIsFinal, beatIndex, lang }) => {
+    // Mirrors the runtime usage record: model falls back to the voice name; billing is per character.
+    const model = speaker.model ?? speaker.voiceId;
+    return { process: "tts", beatIndex, lang, provider: "google", model, inputChars: metric(text.length, textIsFinal) };
+};
+const buildElevenLabsTts = ({ speaker, text, textIsFinal, beatIndex, lang }) => {
+    const model = speaker.model ?? provider2TTSAgent.elevenlabs.defaultModel;
+    return { process: "tts", beatIndex, lang, provider: "elevenlabs", model, inputChars: metric(text.length, textIsFinal) };
+};
+const buildKotodamaTts = ({ speaker, text, textIsFinal, beatIndex, lang }) => {
+    // Mirrors the runtime usage record: the kotodama agent reports the speaker id as the model.
+    return { process: "tts", beatIndex, lang, provider: "kotodama", model: speaker.voiceId, inputChars: metric(text.length, textIsFinal) };
+};
+const ttsRecordBuilders = {
+    openai: buildOpenAITts,
+    gemini: buildGeminiTts,
+    google: buildGoogleTts,
+    elevenlabs: buildElevenLabsTts,
+    kotodama: buildKotodamaTts,
+};
+const googleTtsPricingKey = (voiceId) => {
+    const tiers = {
+        neural2: "tts-neural2",
+        wavenet: "tts-wavenet",
+        studio: "tts-studio",
+        chirp: "tts-chirp3-hd",
+        standard: "tts-standard",
+    };
+    const lower = voiceId.toLowerCase();
+    const tier = Object.keys(tiers).find((key) => lower.includes(key));
+    return tier ? tiers[tier] : undefined;
+};
+const estimateBeatTts = (script, style, beat, beatIndex, lang) => {
+    if (beat.audio || !beat.text || script.audioParams?.suppressSpeech || !style.speechParams?.speakers) {
+        return undefined;
+    }
+    const speaker = MulmoPresentationStyleMethods.getSpeakerData(style, beat, lang);
+    const provider = text2SpeechProviderSchema.parse(speaker.provider);
+    const builder = ttsRecordBuilders[provider];
+    if (!builder) {
+        return undefined; // mock
+    }
+    // For non-default languages the TTS input is a translation that doesn't exist yet.
+    const textIsFinal = lang === (script.lang ?? "en");
+    const speechOptions = { ...speaker.speechOptions, ...beat.speechOptions };
+    const record = builder({ speaker, speechOptions, text: beat.text, textIsFinal, beatIndex, lang });
+    return attachCost(record, provider === "google" ? googleTtsPricingKey(speaker.voiceId) : undefined);
+};
+// ---- Images / movies / sound effects / lip sync ----
+const gptImageSize = (canvasSize) => {
+    if (canvasSize.width > canvasSize.height) {
+        return "1536x1024";
+    }
+    return canvasSize.width < canvasSize.height ? "1024x1536" : "1024x1024";
+};
+const gptImageOutputMetric = (model, canvasSize, quality) => {
+    const table = gptImageOutputTokens[gptImageSize(canvasSize)];
+    const knownQuality = quality === "low" || quality === "medium" || quality === "high" ? quality : undefined;
+    // Unspecified quality means API "auto"; assume "high" as the conservative upper bound.
+    const tokens = table[knownQuality ?? "high"];
+    return metric(tokens, GPT_IMAGE_FIXED_TOKEN_MODELS.includes(model) && knownQuality !== undefined);
+};
+const buildImageRecord = ({ process, provider, model, prompt, canvasSize, quality, beatIndex, refKey }) => {
+    const base = { process, beatIndex, refKey, provider, model };
+    if (provider === "openai") {
+        return {
+            ...base,
+            inputTokens: exact(countOpenAITokens(prompt) + GPT_IMAGE_INPUT_OVERHEAD_TOKENS),
+            outputTokens: gptImageOutputMetric(model, canvasSize, quality),
+        };
+    }
+    if (provider === "google") {
+        return { ...base, inputTokens: estimated(countHeuristicTokens(prompt)), imageCount: exact(1) };
+    }
+    return { ...base, imageCount: exact(1) }; // replicate bills per image
+};
+const isMovieBeat = (beat) => Boolean(beat.moviePrompt || beat.image?.type === "movie");
+// Mirrors imagePreprocessAgent: no AI image when a plugin renders the beat or the beat is movie-only.
+const needsImageGeneration = (beat) => !beat.image && !(beat.moviePrompt && !beat.imagePrompt);
+const estimateImageGeneration = (style, beat, beatIndex) => {
+    const info = MulmoPresentationStyleMethods.getImageAgentInfo(style, beat);
+    const { provider, model, quality } = info.imageParams;
+    if (!provider || provider === "mock" || !model) {
+        return undefined;
+    }
+    const prompt = imagePrompt(beat, info.imageParams.style);
+    const canvasSize = MulmoPresentationStyleMethods.getCanvasSize(style);
+    return attachCost(buildImageRecord({ process: "image", provider, model, prompt, canvasSize, quality, beatIndex }));
+};
+const estimateHtmlImage = (style, beat, beatIndex) => {
+    const info = MulmoPresentationStyleMethods.getHtmlImageAgentInfo(style);
+    if (info.provider === "mock") {
+        return undefined;
+    }
+    const fullPrompt = htmlImageSystemPrompt(MulmoPresentationStyleMethods.getCanvasSize(style)) + "\n" + (MulmoBeatMethods.getHtmlPrompt(beat) ?? "");
+    const inputTokens = info.provider === "openai"
+        ? exact(countOpenAITokens(fullPrompt) + OPENAI_CHAT_INPUT_OVERHEAD_TOKENS)
+        : estimated(countHeuristicTokens(fullPrompt) + OPENAI_CHAT_INPUT_OVERHEAD_TOKENS);
+    return attachCost({
+        process: "htmlImage",
+        beatIndex,
+        provider: info.provider,
+        model: info.model,
+        inputTokens,
+        outputTokens: estimated(HTML_OUTPUT_TOKENS_GUESS),
+    });
+};
+const beatDurationMetric = (beat) => {
+    if (beat.duration !== undefined) {
+        return exact(beat.duration);
+    }
+    return estimated(beat.text ? estimateSpeechSec(beat.text) : DEFAULT_MOVIE_DURATION_SEC);
+};
+const snapMovieDuration = (provider, model, duration) => {
+    if (!isKeyOf(provider2MovieAgent[provider].modelParams, model)) {
+        return duration;
+    }
+    const snapped = getModelDuration(provider, model, duration.value);
+    return snapped !== undefined ? metric(snapped, duration.precision === "exact") : duration;
+};
+const estimateMovieGeneration = (style, beat, beatIndex, refKey) => {
+    const info = MulmoPresentationStyleMethods.getMovieAgentInfo(style, beat);
+    const provider = text2MovieProviderSchema.parse(info.movieParams?.provider ?? defaultProviders.text2movie);
+    if (!isKeyOf(provider2MovieAgent, provider) || provider === "mock") {
+        return undefined;
+    }
+    const model = info.movieParams?.model ?? provider2MovieAgent[provider].defaultModel;
+    const duration = beat ? beatDurationMetric(beat) : estimated(DEFAULT_MOVIE_DURATION_SEC);
+    const predictSec = snapMovieDuration(provider, model, duration);
+    return attachCost({ process: refKey === undefined ? "movie" : "movieReference", beatIndex, refKey, provider, model, predictSec });
+};
+const estimateSoundEffect = (style, beat, beatIndex) => {
+    const info = MulmoPresentationStyleMethods.getSoundEffectAgentInfo(style, beat);
+    const model = beat.soundEffectParams?.model ?? style.soundEffectParams?.model ?? info.defaultModel;
+    const provider = beat.soundEffectParams?.provider ?? style.soundEffectParams?.provider ?? defaultProviders.soundEffect;
+    // Replicate bills sound effects by GPU prediction time, which differs from clip duration.
+    const predictSec = estimated(beatDurationMetric(beat).value);
+    return attachCost({ process: "soundEffect", beatIndex, provider, model, predictSec });
+};
+const estimateLipSync = (style, beat, beatIndex) => {
+    const info = MulmoPresentationStyleMethods.getLipSyncAgentInfo(style, beat);
+    const model = beat.lipSyncParams?.model ?? style.lipSyncParams?.model ?? info.defaultModel;
+    const provider = beat.lipSyncParams?.provider ?? style.lipSyncParams?.provider ?? defaultProviders.lipSync;
+    return attachCost({ process: "lipSync", beatIndex, provider, model, predictSec: beatDurationMetric(beat) });
+};
+const estimateBeatVisuals = (style, beat, beatIndex) => {
+    if (beat.htmlPrompt) {
+        // The image preprocessor returns early for htmlPrompt beats; no other generation runs.
+        return [estimateHtmlImage(style, beat, beatIndex)].filter(isDefined);
+    }
+    return [
+        needsImageGeneration(beat) ? estimateImageGeneration(style, beat, beatIndex) : undefined,
+        beat.moviePrompt ? estimateMovieGeneration(style, beat, beatIndex) : undefined,
+        beat.soundEffectPrompt && isMovieBeat(beat) ? estimateSoundEffect(style, beat, beatIndex) : undefined,
+        beat.enableLipSync ? estimateLipSync(style, beat, beatIndex) : undefined,
+    ].filter(isDefined);
+};
+// ---- Reference images / movies (imageParams.images and beat.images) ----
+const estimateReferenceImage = (style, prompt, canvasSize, refKey, beatIndex) => {
+    const info = MulmoPresentationStyleMethods.getImageAgentInfo(style);
+    const { provider, model, quality } = info.imageParams;
+    if (!provider || provider === "mock" || !model) {
+        return undefined;
+    }
+    // Mirrors generateReferenceImage: the style is appended to the reference prompt.
+    const fullPrompt = `${prompt}\n${info.imageParams.style || ""}`;
+    const size = canvasSize ?? MulmoPresentationStyleMethods.getCanvasSize(style);
+    return attachCost(buildImageRecord({ process: "imageReference", provider, model, prompt: fullPrompt, canvasSize: size, quality, refKey, beatIndex }));
+};
+const estimateMediaReferences = (style, images, beatIndex) => {
+    return Object.entries(images ?? {})
+        .map(([refKey, media]) => {
+        if (media.type === "imagePrompt") {
+            return estimateReferenceImage(style, media.prompt, media.canvasSize, refKey, beatIndex);
+        }
+        if (media.type === "moviePrompt") {
+            return estimateMovieGeneration(style, undefined, beatIndex, refKey);
+        }
+        return undefined;
+    })
+        .filter(isDefined);
+};
+// ---- Translate ----
+const buildTranslateInput = (defaultLang, text, targetLang) => {
+    const substitutions = { ":lang": defaultLang, ":beat.text": text, ":targetLang": targetLang };
+    const prompt = translatePrompts.map((line) => substitutions[line] ?? line).join("\n");
+    return translateSystemPrompt + "\n" + prompt;
+};
+const buildTranslateRecord = (defaultLang, text, targetLang, beatIndex) => {
+    const input = buildTranslateInput(defaultLang, text, targetLang);
+    return attachCost({
+        process: "translate",
+        beatIndex,
+        lang: targetLang,
+        provider: "openai",
+        model: TRANSLATE_DEFAULT_MODEL,
+        inputTokens: exact(countOpenAITokens(input) + OPENAI_CHAT_INPUT_OVERHEAD_TOKENS),
+        outputTokens: estimated(Math.ceil(countOpenAITokens(text) * TRANSLATE_OUTPUT_FACTOR)),
+    });
+};
+const estimateTranslate = (script, targetLangs) => {
+    const defaultLang = script.lang ?? "en";
+    return targetLangs
+        .filter((targetLang) => targetLang !== defaultLang)
+        .flatMap((targetLang) => script.beats.map((beat, beatIndex) => (beat.text ? buildTranslateRecord(defaultLang, beat.text, targetLang, beatIndex) : undefined)).filter(isDefined));
+};
+// ---- Entry point ----
+const defaultTargetLangs = (style, langs, defaultLang) => {
+    // Mirrors the translate action's default: the requested languages plus the caption language.
+    const candidates = [...langs, style.captionParams?.lang];
+    return [...new Set(candidates.filter((lang) => !!lang && lang !== defaultLang))];
+};
+export const estimateUsage = (script, options) => {
+    const style = options?.presentationStyle ?? script;
+    const defaultLang = script.lang ?? "en";
+    const langs = options?.langs ?? [defaultLang];
+    const targetLangs = options?.targetLangs ?? defaultTargetLangs(style, langs, defaultLang);
+    const beatRecords = script.beats.flatMap((beat, beatIndex) => [
+        ...langs.map((lang) => estimateBeatTts(script, style, beat, beatIndex, lang)).filter(isDefined),
+        ...estimateBeatVisuals(style, beat, beatIndex),
+        ...estimateMediaReferences(style, beat.images, beatIndex),
+    ]);
+    const records = [...estimateMediaReferences(style, style.imageParams?.images), ...beatRecords, ...estimateTranslate(script, targetLangs)];
+    const processes = options?.processes;
+    return processes ? records.filter((record) => processes.includes(record.process)) : records;
+};

package/lib/utils/estimate_usage_format.d.ts

@@ -0,0 +1,2 @@
+import type { UsageEstimate } from "../types/usage.js";
+export declare const formatUsageEstimates: (records: UsageEstimate[]) => string;

package/lib/utils/estimate_usage_format.js

@@ -0,0 +1,64 @@
+const METRIC_KEYS = ["inputTokens", "outputTokens", "inputChars", "predictSec", "imageCount"];
+const emptyGroup = (process, model) => ({
+    process,
+    model,
+    metrics: Object.fromEntries(METRIC_KEYS.map((key) => [key, { value: 0, estimated: false, present: false }])),
+    costUSD: 0,
+    unpricedRecords: 0,
+    records: 0,
+});
+const addMetric = (sum, metric) => {
+    if (!metric) {
+        return;
+    }
+    sum.value += metric.value;
+    sum.estimated = sum.estimated || metric.precision === "estimated";
+    sum.present = true;
+};
+const buildGroups = (records) => {
+    const groups = new Map();
+    records.forEach((record) => {
+        const key = `${record.process}|${record.provider}:${record.model}`;
+        const group = groups.get(key) ?? emptyGroup(record.process, `${record.provider}:${record.model}`);
+        METRIC_KEYS.forEach((metricKey) => addMetric(group.metrics[metricKey], record[metricKey]));
+        group.costUSD += record.costUSD ?? 0;
+        group.unpricedRecords += record.costUSD === undefined ? 1 : 0;
+        group.records += 1;
+        groups.set(key, group);
+    });
+    return [...groups.values()];
+};
+const metricCell = (sum) => {
+    if (!sum.present) {
+        return "";
+    }
+    const marker = sum.estimated ? "~" : "";
+    return `${marker}${Math.round(sum.value * 100) / 100}`;
+};
+const groupRow = (group) => {
+    const cells = [group.process, group.model, ...METRIC_KEYS.map((key) => metricCell(group.metrics[key])), group.costUSD > 0 ? group.costUSD.toFixed(4) : ""];
+    return `| ${cells.join(" | ")} |`;
+};
+const totalLine = (groups, records) => {
+    const totalCost = groups.reduce((sum, group) => sum + group.costUSD, 0);
+    const unpriced = groups.reduce((sum, group) => sum + group.unpricedRecords, 0);
+    const asOf = [...new Set(records.map((record) => record.pricingAsOf).filter((date) => !!date))].sort()[0];
+    const parts = [`Total estimated cost: ≈ $${totalCost.toFixed(4)}`];
+    if (unpriced > 0) {
+        parts.push(`(${unpriced} record(s) without pricing data)`);
+    }
+    if (asOf) {
+        parts.push(`(prices as of ${asOf})`);
+    }
+    return parts.join(" ");
+};
+export const formatUsageEstimates = (records) => {
+    if (records.length === 0) {
+        return "No billable API usage estimated.";
+    }
+    const groups = buildGroups(records);
+    const header = "| process | provider:model | input tokens | output tokens | input chars | predict sec | images | cost (USD) |";
+    const separator = "|---|---|---|---|---|---|---|---|";
+    const note = "~ marks heuristic estimates; unmarked values are exact for the given script.";
+    return [header, separator, ...groups.map(groupRow), "", totalLine(groups, records), note].join("\n");
+};

package/lib/utils/fetch.d.ts

@@ -0,0 +1,28 @@
+export declare const DEFAULT_FETCH_TIMEOUT_MS = 30000;
+export declare const FETCH_DOWNLOAD_TIMEOUT_MS = 60000;
+export declare const FETCH_MEDIA_DOWNLOAD_TIMEOUT_MS = 180000;
+export declare const FETCH_API_TIMEOUT_MS = 120000;
+export type SafeFetchResponse = {
+    ok: boolean;
+    status: number;
+    statusText: string;
+    headers: {
+        get(name: string): string | null;
+    };
+    arrayBuffer(): Promise<ArrayBuffer>;
+    text(): Promise<string>;
+    json<T = unknown>(): Promise<T>;
+};
+/**
+ * fetch() with an AbortController timeout that covers the whole exchange —
+ * headers AND body.
+ *
+ * A stalled connection otherwise yields a promise that never resolves or
+ * rejects; callers relying on GraphAI `retry` never recover because retry only
+ * fires on rejection. The body is read once under the same deadline (a server
+ * that sends headers and then stalls mid-body would otherwise hang the caller's
+ * body read), and the bytes are handed back through a lightweight result so the
+ * caller does not buffer them a second time. An optional caller `signal` is
+ * composed with the timeout so upstream cancellation still works.
+ */
+export declare const safeFetch: (url: string | URL, init?: Parameters<typeof fetch>[1], timeoutMs?: number) => Promise<SafeFetchResponse>;

package/lib/utils/fetch.js

@@ -0,0 +1,52 @@
+// Timeout budgets for the different kinds of network waits. Generous safety
+// nets against a stalled socket — NOT tight deadlines — so legitimate slow
+// responses still succeed while a genuine hang becomes a rejection.
+export const DEFAULT_FETCH_TIMEOUT_MS = 30_000; // small assets (reference/background images, JSON)
+export const FETCH_DOWNLOAD_TIMEOUT_MS = 60_000; // generated image download
+export const FETCH_MEDIA_DOWNLOAD_TIMEOUT_MS = 180_000; // large video/audio download
+export const FETCH_API_TIMEOUT_MS = 120_000; // generation API POST (e.g. TTS text -> audio)
+/**
+ * fetch() with an AbortController timeout that covers the whole exchange —
+ * headers AND body.
+ *
+ * A stalled connection otherwise yields a promise that never resolves or
+ * rejects; callers relying on GraphAI `retry` never recover because retry only
+ * fires on rejection. The body is read once under the same deadline (a server
+ * that sends headers and then stalls mid-body would otherwise hang the caller's
+ * body read), and the bytes are handed back through a lightweight result so the
+ * caller does not buffer them a second time. An optional caller `signal` is
+ * composed with the timeout so upstream cancellation still works.
+ */
+export const safeFetch = async (url, init = {}, timeoutMs = DEFAULT_FETCH_TIMEOUT_MS) => {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    const externalSignal = init?.signal ?? undefined;
+    const forwardAbort = () => controller.abort();
+    externalSignal?.addEventListener("abort", forwardAbort, { once: true });
+    if (externalSignal?.aborted)
+        controller.abort();
+    try {
+        const response = await fetch(url, { ...init, signal: controller.signal });
+        const body = await response.arrayBuffer();
+        const decode = () => new TextDecoder().decode(body);
+        return {
+            ok: response.ok,
+            status: response.status,
+            statusText: response.statusText,
+            headers: response.headers,
+            arrayBuffer: async () => body,
+            text: async () => decode(),
+            json: async () => JSON.parse(decode()),
+        };
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === "AbortError") {
+            throw new Error(`Fetch timeout after ${timeoutMs}ms: ${url}`);
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timeoutId);
+        externalSignal?.removeEventListener("abort", forwardAbort);
+    }
+};

package/lib/utils/file.js

@@ -8,6 +8,7 @@ import { MulmoStudioContextMethods } from "../methods/index.js";
 import { mulmoPromptTemplateSchema } from "../types/schema.js";
 import { getMulmoScriptTemplateSystemPrompt } from "./prompt.js";
 import { resolveAssetFile } from "./asset_import.js";
+import { safeFetch } from "./fetch.js";
 const promptTemplateDirName = "./assets/templates";
 const scriptTemplateDirName = "./scripts/templates";
 const __filename = fileURLToPath(import.meta.url);
@@ -43,7 +44,7 @@ export function readMulmoScriptFile(arg2, errorMessage) {
 }
 export const fetchMulmoScriptFile = async (url) => {
     try {
-        const res = await fetch(url);
+        const res = await safeFetch(url);
         if (!res.ok) {
             return { result: false, status: res.status };
         }

package/lib/utils/image_plugins/bg_image_util.js

@@ -1,6 +1,6 @@
 import { MulmoMediaSourceMethods } from "../../methods/mulmo_media_source.js";
 import { resolveStyle } from "./utils.js";
-const DEFAULT_FETCH_TIMEOUT_MS = 30000;
+import { safeFetch, DEFAULT_FETCH_TIMEOUT_MS } from "../fetch.js";
 /**
  * Resolve background image from beat level and global level settings.
  * Beat level takes precedence over global level.
@@ -25,26 +25,13 @@ export const resolveBackgroundImage = (beatBackgroundImage, globalBackgroundImag
  * Fetch URL and convert to data URL with timeout
  */
 const fetchUrlAsDataUrl = async (url, timeoutMs = DEFAULT_FETCH_TIMEOUT_MS) => {
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
-    try {
-        const response = await fetch(url, { signal: controller.signal });
-        if (!response.ok) {
-            throw new Error(`Failed to fetch background image: ${url} (${response.status})`);
-        }
-        const buffer = Buffer.from(await response.arrayBuffer());
-        const contentType = response.headers.get("content-type") || "image/png";
-        return `data:${contentType};base64,${buffer.toString("base64")}`;
-    }
-    catch (error) {
-        if (error instanceof Error && error.name === "AbortError") {
-            throw new Error(`Fetch timeout for background image: ${url}`);
-        }
-        throw error;
-    }
-    finally {
-        clearTimeout(timeoutId);
+    const response = await safeFetch(url, {}, timeoutMs);
+    if (!response.ok) {
+        throw new Error(`Failed to fetch background image: ${url} (${response.status})`);
     }
+    const buffer = Buffer.from(await response.arrayBuffer());
+    const contentType = response.headers.get("content-type") || "image/png";
+    return `data:${contentType};base64,${buffer.toString("base64")}`;
 };
 /**
  * Convert BackgroundImage to CSS string

package/lib/utils/openai_client.js

@@ -1,4 +1,8 @@
 import OpenAI, { AzureOpenAI } from "openai";
+// Explicit per-request timeout so a stalled connection rejects (and the SDK's
+// default maxRetries=2 re-issues it) instead of hanging on the SDK's 10-minute
+// default. gpt-image-1 generation is typically well under this.
+const OPENAI_REQUEST_TIMEOUT_MS = 120_000;
 /**
  * Detects if the given URL is an Azure OpenAI endpoint
  * Safely parses the URL and checks if the hostname ends with ".openai.azure.com"
@@ -26,10 +30,12 @@ export const createOpenAIClient = (options) => {
             apiKey,
             endpoint: baseURL,
             apiVersion: apiVersion ?? "2025-04-01-preview",
+            timeout: OPENAI_REQUEST_TIMEOUT_MS,
         });
     }
     return new OpenAI({
         apiKey,
         baseURL,
+        timeout: OPENAI_REQUEST_TIMEOUT_MS,
     });
 };

package/lib/utils/replicate_usage.d.ts

@@ -1,5 +1,8 @@
 import type Replicate from "replicate";
-export declare const runReplicateWithMetrics: (replicate: Replicate, identifier: `${string}/${string}` | `${string}/${string}:${string}`, input: object, signal?: AbortSignal) => Promise<{
+export declare const runReplicateWithMetrics: (replicate: Replicate, identifier: `${string}/${string}` | `${string}/${string}:${string}`, input: object, options?: {
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}) => Promise<{
     output: unknown;
     predictSec?: number;
 }>;

package/lib/utils/replicate_usage.js

@@ -1,11 +1,31 @@
+// Generous safety net against a stalled run — video models (seedance/kling)
+// legitimately run for minutes — not a tight deadline.
+const REPLICATE_RUN_TIMEOUT_MS = 600_000;
 // Capture Replicate's exact billed seconds (`metrics.predict_time`) via the
 // progress callback on `replicate.run()`. Avoids switching the four
 // replicate agents from `.run()` to `predictions.create()` + poll, which
 // would be a much bigger blast radius.
-export const runReplicateWithMetrics = async (replicate, identifier, input, signal) => {
+//
+// A timeout aborts the run so a stalled job rejects (and the caller's GraphAI
+// `retry` can recover) instead of hanging forever. An optional caller `signal`
+// is composed with the timeout so upstream cancellation still works.
+export const runReplicateWithMetrics = async (replicate, identifier, input, options = {}) => {
+    const { timeoutMs = REPLICATE_RUN_TIMEOUT_MS, signal: externalSignal } = options;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    const forwardAbort = () => controller.abort();
+    externalSignal?.addEventListener("abort", forwardAbort, { once: true });
+    if (externalSignal?.aborted)
+        controller.abort();
     let lastPrediction;
-    const output = await replicate.run(identifier, { input, signal }, (prediction) => {
-        lastPrediction = prediction;
-    });
-    return { output, predictSec: lastPrediction?.metrics?.predict_time };
+    try {
+        const output = await replicate.run(identifier, { input, signal: controller.signal }, (prediction) => {
+            lastPrediction = prediction;
+        });
+        return { output, predictSec: lastPrediction?.metrics?.predict_time };
+    }
+    finally {
+        clearTimeout(timeoutId);
+        externalSignal?.removeEventListener("abort", forwardAbort);
+    }
 };

package/lib/utils/sdk_timeout.d.ts

@@ -0,0 +1,3 @@
+export declare const GENAI_REQUEST_TIMEOUT_MS = 120000;
+export declare const REPLICATE_RUN_TIMEOUT_MS = 600000;
+export declare const VIDEO_POLL_TIMEOUT_MS = 1200000;

package/lib/utils/sdk_timeout.js

@@ -0,0 +1,7 @@
+// Timeout budgets for provider SDK calls (OpenAI has its own in openai_client.ts).
+// Generous safety nets against a stalled connection or a never-completing
+// operation — NOT tight deadlines. A stall becomes a rejection so the caller's
+// GraphAI `retry` can recover instead of hanging forever.
+export const GENAI_REQUEST_TIMEOUT_MS = 120_000; // per @google/genai API call (kick-off / each poll)
+export const REPLICATE_RUN_TIMEOUT_MS = 600_000; // whole replicate.run() job (video models run minutes)
+export const VIDEO_POLL_TIMEOUT_MS = 1_200_000; // wall-clock cap for a long-running Veo video operation

package/lib/utils/zip.js

@@ -1,5 +1,5 @@
 import fs from "fs";
-import archiver from "archiver";
+import { ZipArchive } from "archiver";
 import path from "path";
 /**
  * Promise-based ZIP archive builder
@@ -18,7 +18,7 @@ export class ZipBuilder {
     constructor(outputPath) {
         this.outputPath = outputPath;
         this.output = fs.createWriteStream(outputPath);
-        this.archive = archiver("zip", {
+        this.archive = new ZipArchive({
             zlib: { level: 9 }, // Maximum compression level
         });
         // Pipe archive data to the file