mulmocast 2.6.20 → 2.6.21

package/README.md

@@ -137,6 +137,14 @@ ELEVENLABS_API_KEY=your_elevenlabs_api_key
 BROWSERLESS_API_TOKEN=your_browserless_api_token # to access web in mulmo tool
 ```
 
+#### (Optional) Local usage tracking
+```bash
+MULMOCAST_DUMP_USAGE=1                 # print JSON usage dump to stdout after each CLI action
+MULMOCAST_DUMP_USAGE=/tmp/usage.json   # ...or write it to a file
+```
+
+Token / per-second / per-char usage per provider:model. See [docs/api.md](./docs/api.md#usage-tracking) for the full reference.
+
 ### Google Vertex AI
 
 For enterprise/production environments, or to use Veo movie models that are only available on Vertex AI, use Vertex AI with Application Default Credentials (ADC):

package/lib/actions/audio.js

@@ -4,6 +4,7 @@ import * as agents from "@graphai/vanilla";
 import { fileWriteAgent } from "@graphai/vanilla_node_agents";
 import { ttsOpenaiAgent, ttsGoogleAgent, ttsGeminiAgent, ttsElevenlabsAgent, ttsKotodamaAgent, addBGMAgent, combineAudioFilesAgent, mediaMockAgent, } from "../agents/index.js";
 import { audioGraphOption } from "./graph_option.js";
+import { createUsageCallback } from "../utils/usage_callback.js";
 import { getAudioArtifactFilePath, getAudioFilePath, getGroupedAudioFilePath, getOutputStudioFilePath, resolveDirPath, defaultBGMPath, mkdir, writingMessage, } from "../utils/file.js";
 import { localizedText } from "../utils/utils.js";
 import { text2hash } from "../utils/utils_node.js";
@@ -232,6 +233,7 @@ export const generateBeatAudio = async (index, context, args) => {
         mkdir(audioSegmentDirPath);
         const graph = new GraphAI(langs ? graph_tts_map : graph_tts, audioAgents, await audioGraphOption(context, settings));
         callbacks?.forEach((callback) => graph.registerCallback(callback));
+        graph.registerCallback(createUsageCallback(context));
         graph.injectValue("__mapIndex", index);
         graph.injectValue("beat", context.studio.script.beats[index]);
         graph.injectValue("studioBeat", context.studio.beats[index]);
@@ -268,6 +270,7 @@ export const audio = async (context, args) => {
         mkdir(audioSegmentDirPath);
         const graph = new GraphAI(audio_graph_data, audioAgents, await audioGraphOption(context, settings));
         callbacks?.forEach((callback) => graph.registerCallback(callback));
+        graph.registerCallback(createUsageCallback(context));
         graph.injectValue("context", context);
         graph.injectValue("audioArtifactFilePath", audioArtifactFilePath);
         graph.injectValue("audioCombinedFilePath", audioCombinedFilePath);

package/lib/actions/image_references.js

@@ -1,6 +1,7 @@
 import { GraphAI, GraphAILogger } from "graphai";
 import { getReferenceImagePath } from "../utils/file.js";
 import { imageGraphOption } from "./graph_option.js";
+import { createUsageCallback } from "../utils/usage_callback.js";
 import { MulmoPresentationStyleMethods, MulmoMediaSourceMethods } from "../methods/index.js";
 import { imageOpenaiAgent, mediaMockAgent, imageGenAIAgent, imageReplicateAgent, movieGenAIAgent, movieReplicateAgent } from "../agents/index.js";
 import { agentGenerationError, imageReferenceAction, imageFileTarget, movieFileTarget } from "../utils/error_cause.js";
@@ -43,6 +44,7 @@ export const generateReferenceImage = async (inputs) => {
     try {
         const options = await imageGraphOption(context);
         const graph = new GraphAI(image_graph_data, { imageGenAIAgent, imageOpenaiAgent, mediaMockAgent, imageReplicateAgent }, options);
+        graph.registerCallback(createUsageCallback(context));
         await graph.run();
         return imagePath;
     }
@@ -129,6 +131,7 @@ const generateReferenceMovie = async (inputs) => {
     try {
         const options = await imageGraphOption(context);
         const graph = new GraphAI(movie_graph_data, { movieGenAIAgent, movieReplicateAgent, mediaMockAgent }, options);
+        graph.registerCallback(createUsageCallback(context));
         await graph.run();
         return moviePath;
     }

package/lib/actions/images.js

@@ -15,6 +15,7 @@ import { extractImageFromMovie, ffmpegGetMediaDuration, trimMusic } from "../uti
 import { getMediaRefs, resolveBeatLocalRefs } from "./image_references.js";
 import { imagePreprocessAgent, imagePluginAgent, htmlImageGeneratorAgent } from "./image_agents.js";
 import { imageGraphOption } from "./graph_option.js";
+import { createUsageCallback } from "../utils/usage_callback.js";
 const vanillaAgents = vanilla.default ?? vanilla;
 const imageAgents = {
     imageGenAIAgent,
@@ -468,6 +469,7 @@ const generateImages = async (context, args) => {
             graph.registerCallback(callback);
         });
     }
+    graph.registerCallback(createUsageCallback(context));
     const res = await graph.run();
     return res.mergeResult;
 };
@@ -519,6 +521,7 @@ export const generateBeatImage = async (inputs) => {
                 graph.registerCallback(callback);
             });
         }
+        graph.registerCallback(createUsageCallback(context));
         await graph.run();
     }
     catch (error) {

package/lib/actions/translate.d.ts

@@ -19,6 +19,8 @@ export declare const translateTextGraph: {
             };
             output: {
                 text: string;
+                usage: string;
+                model: string;
             };
             agent: string;
         };

package/lib/actions/translate.js

@@ -5,6 +5,7 @@ import * as agents from "@graphai/vanilla";
 import { openAIAgent } from "@graphai/openai_agent";
 import { fileWriteAgent } from "@graphai/vanilla_node_agents";
 import { splitText } from "../utils/string.js";
+import { createUsageCallback } from "../utils/usage_callback.js";
 import { settings2GraphAIConfig, beatId, multiLingualObjectToArray } from "../utils/utils.js";
 import { getMultiLingual } from "../utils/context.js";
 import { currentMulmoScriptVersion } from "../types/const.js";
@@ -36,6 +37,8 @@ export const translateTextGraph = {
             },
             output: {
                 text: ".text",
+                usage: ".usage",
+                model: ".model",
             },
             // return { lang, text } <- localizedText
             agent: "openAIAgent",
@@ -253,6 +256,7 @@ export const translateBeat = async (index, context, targetLangs, args) => {
                 graph.registerCallback(callback);
             });
         }
+        graph.registerCallback(createUsageCallback(context));
         const results = await graph.run();
         const multiLingual = getMultiLingual(outputMultilingualFilePath, context.studio.beats);
         const key = beatId(context.studio.script.beats[index]?.id, index);
@@ -294,6 +298,7 @@ export const translate = async (context, args) => {
                 graph.registerCallback(callback);
             });
         }
+        graph.registerCallback(createUsageCallback(context));
         const results = await graph.run();
         writingMessage(outputMultilingualFilePath);
         if (results.mergeStudioResult) {

package/lib/agents/image_genai_agent.js

@@ -21,12 +21,21 @@ const getGeminiContents = (prompt, referenceImages) => {
     });
     return contents;
 };
-const geminiFlashResult = (response) => {
+const geminiFlashResult = (response, model) => {
     if (!response.candidates?.[0]?.content?.parts) {
         throw new Error("ERROR: generateContent returned no candidates", {
             cause: agentInvalidResponseError("imageGenAIAgent", imageAction, imageFileTarget),
         });
     }
+    const usage = response.usageMetadata
+        ? {
+            provider: "google",
+            model,
+            inputTokens: response.usageMetadata.promptTokenCount,
+            outputTokens: response.usageMetadata.candidatesTokenCount,
+            totalTokens: response.usageMetadata.totalTokenCount,
+        }
+        : undefined;
     for (const part of response.candidates[0].content.parts) {
         if (part.text) {
             GraphAILogger.info("Gemini image generation response:", part.text);
@@ -39,7 +48,7 @@ const geminiFlashResult = (response) => {
                 });
             }
             const buffer = Buffer.from(imageData, "base64");
-            return { buffer };
+            return { buffer, usage };
         }
     }
     throw new Error("ERROR: generateContent returned no image data", {
@@ -102,7 +111,7 @@ export const imageGenAIAgent = async ({ namedInputs, params, config, }) => {
         })();
         const res = await resultify(() => ai.models.generateContent(contentParams));
         if (res.ok) {
-            return geminiFlashResult(res.value);
+            return geminiFlashResult(res.value, model);
         }
         return errorProcess(res.error);
     }

package/lib/agents/image_openai_agent.js

@@ -115,6 +115,16 @@ export const imageOpenaiAgent = async ({ namedInputs, params, config, }) => {
             cause: agentInvalidResponseError("imageOpenaiAgent", imageAction, imageFileTarget),
         });
     }
+    // gpt-image-1 surfaces token usage; legacy DALL·E response shapes don't.
+    const usage = response.usage
+        ? {
+            provider: "openai",
+            model,
+            inputTokens: response.usage.input_tokens,
+            outputTokens: response.usage.output_tokens,
+            totalTokens: response.usage.total_tokens,
+        }
+        : undefined;
     const url = response.data[0].url;
     if (!url) {
         // For gpt-image-1
@@ -124,7 +134,7 @@ export const imageOpenaiAgent = async ({ namedInputs, params, config, }) => {
                 cause: agentInvalidResponseError("imageOpenaiAgent", imageAction, imageFileTarget),
             });
         }
-        return { buffer: Buffer.from(image_base64, "base64") };
+        return { buffer: Buffer.from(image_base64, "base64"), usage };
     }
     // URL response handling (legacy OpenAI image API response format)
     const res = await fetch(url);
@@ -136,7 +146,7 @@ export const imageOpenaiAgent = async ({ namedInputs, params, config, }) => {
     // 2. Read the response as an ArrayBuffer
     const arrayBuffer = await res.arrayBuffer();
     // 3. Convert the ArrayBuffer to a Node.js Buffer and return it along with url
-    return { buffer: Buffer.from(arrayBuffer) };
+    return { buffer: Buffer.from(arrayBuffer), usage };
 };
 const imageOpenaiAgentInfo = {
     name: "imageOpenaiAgent",

package/lib/agents/image_replicate_agent.js

@@ -4,6 +4,7 @@ import Replicate from "replicate";
 import { getAspectRatio } from "./movie_replicate_agent.js";
 import { apiKeyMissingError, agentIncorrectAPIKeyError, agentGenerationError, agentInvalidResponseError, imageAction, imageFileTarget, hasCause, } from "../utils/error_cause.js";
 import { provider2ImageAgent } from "../types/provider2agent.js";
+import { runReplicateWithMetrics } from "../utils/replicate_usage.js";
 // Replicate image models return one of: FileOutput (object with url() method),
 // Array<FileOutput>, string URL, or { url: string }. Normalize to URL string/URL.
 const extractImageUrl = (output) => {
@@ -44,7 +45,7 @@ export const imageReplicateAgent = async ({ namedInputs, params, config, }) => {
         });
     }
     try {
-        const output = await replicate.run(model, { input });
+        const { output, predictSec } = await runReplicateWithMetrics(replicate, model, input);
         const imageUrl = extractImageUrl(output);
         if (!imageUrl) {
             throw new Error("ERROR: generateImage returned undefined", {
@@ -59,7 +60,8 @@ export const imageReplicateAgent = async ({ namedInputs, params, config, }) => {
         }
         const arrayBuffer = await imageResponse.arrayBuffer();
         const buffer = Buffer.from(arrayBuffer);
-        return { buffer };
+        const usage = predictSec !== undefined ? { provider: "replicate", model, predictSec } : undefined;
+        return { buffer, usage };
     }
     catch (error) {
         GraphAILogger.info("Replicate generation error:", error);

package/lib/agents/lipsync_replicate_agent.js

@@ -3,6 +3,7 @@ import { GraphAILogger } from "graphai";
 import Replicate from "replicate";
 import { provider2LipSyncAgent } from "../types/provider2agent.js";
 import { apiKeyMissingError, agentGenerationError, agentFileNotExistError, imageAction, movieFileTarget, audioFileTarget, hasCause, } from "../utils/error_cause.js";
+import { runReplicateWithMetrics } from "../utils/replicate_usage.js";
 export const lipSyncReplicateAgent = async ({ namedInputs, params, config, }) => {
     const { movieFile, audioFile, imageFile } = namedInputs;
     const apiKey = config?.apiKey;
@@ -60,9 +61,7 @@ export const lipSyncReplicateAgent = async ({ namedInputs, params, config, }) =>
     }
     const model_identifier = provider2LipSyncAgent.replicate.modelParams[model]?.identifier ?? model;
     try {
-        const output = await replicate.run(model_identifier, {
-            input,
-        });
+        const { output, predictSec } = await runReplicateWithMetrics(replicate, model_identifier, input);
         if (output && typeof output === "object" && "url" in output) {
             const videoUrl = output.url();
             const videoResponse = await fetch(videoUrl);
@@ -72,7 +71,8 @@ export const lipSyncReplicateAgent = async ({ namedInputs, params, config, }) =>
                 });
             }
             const arrayBuffer = await videoResponse.arrayBuffer();
-            return { buffer: Buffer.from(arrayBuffer) };
+            const usage = predictSec !== undefined ? { provider: "replicate", model, predictSec } : undefined;
+            return { buffer: Buffer.from(arrayBuffer), usage };
         }
         return undefined;
     }

package/lib/agents/movie_genai_agent.js

@@ -3,6 +3,7 @@ import { GraphAILogger, sleep } from "graphai";
 import { GoogleGenAI, PersonGeneration } from "@google/genai";
 import { apiKeyMissingError, agentGenerationError, agentInvalidResponseError, imageAction, movieFileTarget, videoDurationTarget, unsupportedModelTarget, hasCause, } from "../utils/error_cause.js";
 import { getAspectRatio } from "../utils/utils.js";
+import { ffmpegGetMediaDuration } from "../utils/ffmpeg_utils.js";
 import { ASPECT_RATIOS } from "../types/const.js";
 import { getModelDuration, provider2MovieAgent, AUDIO_MODE_NEVER, AUDIO_MODE_ALWAYS } from "../types/provider2agent.js";
 const pollUntilDone = async (ai, operation) => {
@@ -35,7 +36,22 @@ const loadImageAsBase64 = (imagePath) => {
         mimeType: "image/png",
     };
 };
-const downloadVideo = async (ai, video, movieFile, isVertexAI) => {
+// Veo bills per second of generated video. The SDK response carries no usage
+// metadata (GenerateVideosResponse only has generatedVideos and RAI flags), so
+// we ffprobe the downloaded file to get the actual duration. Falls back to
+// undefined if ffprobe fails, which lets the billing layer use the requested
+// duration as a fallback.
+const probeDurationSec = async (movieFile) => {
+    try {
+        const { duration } = await ffmpegGetMediaDuration(movieFile);
+        return duration > 0 ? duration : undefined;
+    }
+    catch (e) {
+        GraphAILogger.warn("movieGenAIAgent: ffprobe failed, predictSec will be omitted", e);
+        return undefined;
+    }
+};
+const downloadVideo = async (ai, video, movieFile, isVertexAI, model) => {
     if (isVertexAI) {
         // Vertex AI returns videoBytes directly
         writeFileSync(movieFile, Buffer.from(video.videoBytes, "base64"));
@@ -48,7 +64,9 @@ const downloadVideo = async (ai, video, movieFile, isVertexAI) => {
         });
         await sleep(5000); // HACK: Without this, the file is not ready yet.
     }
-    return { saved: movieFile };
+    const predictSec = await probeDurationSec(movieFile);
+    const usage = predictSec !== undefined ? { provider: "google", model, predictSec } : undefined;
+    return { saved: movieFile, usage };
 };
 const createVeo31Payload = (model, prompt, aspectRatio, source) => ({
     model,
@@ -92,7 +110,7 @@ const generateExtendedVideo = async (ai, model, prompt, aspectRatio, imagePath,
             cause: agentInvalidResponseError("movieGenAIAgent", imageAction, movieFileTarget),
         });
     }
-    return downloadVideo(ai, result.video, movieFile, isVertexAI);
+    return downloadVideo(ai, result.video, movieFile, isVertexAI, model);
 };
 const generateStandardVideo = async (ai, model, prompt, aspectRatio, imagePath, lastFrameImagePath, referenceImages, duration, movieFile, isVertexAI) => {
     const capabilities = provider2MovieAgent.google.modelParams[model];
@@ -139,7 +157,7 @@ const generateStandardVideo = async (ai, model, prompt, aspectRatio, imagePath,
     const operation = await ai.models.generateVideos(payload);
     const response = await pollUntilDone(ai, operation);
     const video = getVideoFromResponse(response);
-    return downloadVideo(ai, video, movieFile, isVertexAI);
+    return downloadVideo(ai, video, movieFile, isVertexAI, model);
 };
 export const movieGenAIAgent = async ({ namedInputs, params, config, }) => {
     const { prompt, imagePath, lastFrameImagePath, referenceImages, movieFile } = namedInputs;

package/lib/agents/movie_replicate_agent.js

@@ -3,6 +3,7 @@ import { GraphAILogger } from "graphai";
 import Replicate from "replicate";
 import { apiKeyMissingError, agentGenerationError, agentInvalidResponseError, hasCause, imageAction, movieFileTarget, videoDurationTarget, unsupportedModelTarget, } from "../utils/error_cause.js";
 import { provider2MovieAgent, getModelDuration, AUDIO_MODE_OPTIONAL, AUDIO_MODE_NEVER, AUDIO_MODE_ALWAYS } from "../types/provider2agent.js";
+import { runReplicateWithMetrics } from "../utils/replicate_usage.js";
 function replicate_get_videoUrl(output) {
     if (typeof output === "string")
         return output;
@@ -93,7 +94,7 @@ async function generateMovie(model, apiKey, prompt, imagePath, lastFrameImagePat
         }
     }
     try {
-        const output = await replicate.run(model, { input });
+        const { output, predictSec } = await runReplicateWithMetrics(replicate, model, input);
         // Download the generated video
         // Some models return a FileOutput object with a url() method; others return a plain string URL.
         const videoUrl = replicate_get_videoUrl(output);
@@ -105,7 +106,7 @@ async function generateMovie(model, apiKey, prompt, imagePath, lastFrameImagePat
                 });
             }
             const arrayBuffer = await videoResponse.arrayBuffer();
-            return Buffer.from(arrayBuffer);
+            return { buffer: Buffer.from(arrayBuffer), predictSec };
         }
         return undefined;
     }
@@ -154,9 +155,10 @@ export const movieReplicateAgent = async ({ namedInputs, params, config, }) => {
         });
     }
     try {
-        const buffer = await generateMovie(model, apiKey, prompt, imagePath, lastFrameImagePath, referenceImages, aspectRatio, duration, params.generateAudio);
-        if (buffer) {
-            return { buffer };
+        const result = await generateMovie(model, apiKey, prompt, imagePath, lastFrameImagePath, referenceImages, aspectRatio, duration, params.generateAudio);
+        if (result) {
+            const usage = result.predictSec !== undefined ? { provider: "replicate", model, predictSec: result.predictSec } : undefined;
+            return { buffer: result.buffer, usage };
         }
     }
     catch (error) {

package/lib/agents/sound_effect_replicate_agent.js

@@ -3,6 +3,7 @@ import { GraphAILogger } from "graphai";
 import Replicate from "replicate";
 import { provider2SoundEffectAgent } from "../types/provider2agent.js";
 import { apiKeyMissingError, agentGenerationError, imageAction, movieFileTarget, hasCause } from "../utils/error_cause.js";
+import { runReplicateWithMetrics } from "../utils/replicate_usage.js";
 export const soundEffectReplicateAgent = async ({ namedInputs, params, config }) => {
     const { prompt, movieFile } = namedInputs;
     const apiKey = config?.apiKey;
@@ -28,9 +29,7 @@ export const soundEffectReplicateAgent = async ({ namedInputs, params, config })
     };
     try {
         const model_identifier = provider2SoundEffectAgent.replicate.modelParams[model]?.identifier ?? model;
-        const output = await replicate.run(model_identifier, {
-            input,
-        });
+        const { output, predictSec } = await runReplicateWithMetrics(replicate, model_identifier, input);
         if (output && typeof output === "object" && "url" in output) {
             const videoUrl = output.url();
             const videoResponse = await fetch(videoUrl);
@@ -40,7 +39,8 @@ export const soundEffectReplicateAgent = async ({ namedInputs, params, config })
                 });
             }
             const arrayBuffer = await videoResponse.arrayBuffer();
-            return { buffer: Buffer.from(arrayBuffer) };
+            const usage = predictSec !== undefined ? { provider: "replicate", model, predictSec } : undefined;
+            return { buffer: Buffer.from(arrayBuffer), usage };
         }
         return undefined;
     }

package/lib/agents/tts_elevenlabs_agent.js

@@ -68,9 +68,20 @@ export const ttsElevenlabsAgent = async ({ namedInputs, params, config, }) => {
             cause: agentGenerationError("ttsElevenlabsAgent", audioAction, audioFileTarget),
         });
     }
+    // ElevenLabs returns the exact billed character count in the `character-cost`
+    // header (already discounted for V2 Flash/Turbo etc. — see #1420 research).
+    // We read it BEFORE consuming the body so the header is still accessible.
+    const billedHeader = response.headers.get("character-cost");
+    const billedChars = billedHeader ? Number(billedHeader) : undefined;
     const arrayBuffer = await response.arrayBuffer();
     const buffer = Buffer.from(arrayBuffer);
-    return { buffer };
+    const usage = {
+        provider: "elevenlabs",
+        model: requestBody.model_id,
+        // Use upstream-billed amount when available (exact); fall back to raw text length.
+        inputChars: Number.isFinite(billedChars) ? billedChars : text.length,
+    };
+    return { buffer, usage };
 };
 const ttsElevenlabsAgentInfo = {
     name: "ttsElevenlabsAgent",

package/lib/agents/tts_gemini_agent.js

@@ -42,7 +42,17 @@ export const ttsGeminiAgent = async ({ namedInputs, params, config, }) => {
         const rateMatch = mimeType?.match(/rate=(\d+)/);
         const sampleRate = rateMatch ? parseInt(rateMatch[1]) : 24000;
         const rawPcm = Buffer.from(pcmBase64, "base64");
-        return { buffer: await pcmToMp3(rawPcm, sampleRate) };
+        const usedModel = model ?? provider2TTSAgent.gemini.defaultModel;
+        const usage = response.usageMetadata
+            ? {
+                provider: "gemini",
+                model: usedModel,
+                inputTokens: response.usageMetadata.promptTokenCount,
+                outputTokens: response.usageMetadata.candidatesTokenCount,
+                totalTokens: response.usageMetadata.totalTokenCount,
+            }
+            : undefined;
+        return { buffer: await pcmToMp3(rawPcm, sampleRate), usage };
     }
     catch (e) {
         if (suppressError) {

package/lib/agents/tts_google_agent.js

@@ -42,7 +42,15 @@ export const ttsGoogleAgent = async ({ namedInputs, params }) => {
     try {
         // Call the Text-to-Speech API
         const [response] = await client.synthesizeSpeech(request, { timeout: SYNTHESIZE_TIMEOUT_MS });
-        return { buffer: response.audioContent };
+        // Google Cloud TTS bills per character; SynthesizeSpeechResponse exposes
+        // no usage info. Record inputChars so the billing layer can compute cost
+        // from `model` (voice tier) + char count.
+        const usage = {
+            provider: "google",
+            model: model ?? voice ?? "default",
+            inputChars: text.length,
+        };
+        return { buffer: response.audioContent, usage };
     }
     catch (e) {
         if (suppressError) {

package/lib/agents/tts_kotodama_agent.js

@@ -44,7 +44,15 @@ export const ttsKotodamaAgent = async ({ namedInputs, params, config, }) => {
             });
         }
         const buffer = Buffer.from(json.audios[0], "base64");
-        return { buffer };
+        // Kotodama is subscription-billed externally (no public per-char rate API
+        // surface). Report inputChars + voice/decoration so the billing layer can
+        // do its own accounting.
+        const usage = {
+            provider: "kotodama",
+            model: body.speaker_id,
+            inputChars: text.length,
+        };
+        return { buffer, usage };
     }
     catch (error) {
         if (suppressError) {

package/lib/agents/tts_openai_agent.js

@@ -28,7 +28,15 @@ export const ttsOpenaiAgent = async ({ namedInputs, params, config, }) => {
         GraphAILogger.log("ttsOptions", tts_options);
         const response = await openai.audio.speech.create(tts_options);
         const buffer = Buffer.from(await response.arrayBuffer());
-        return { buffer };
+        // tts-1 / tts-1-hd bill per character. gpt-4o-mini-tts is token-based and
+        // is handled by #1428; for now we report inputChars uniformly and let the
+        // billing layer pick the right unit from `model`.
+        const usage = {
+            provider: "openai",
+            model: tts_options.model,
+            inputChars: text.length,
+        };
+        return { buffer, usage };
     }
     catch (error) {
         if (suppressError) {

package/lib/cli/commands/audio/handler.js

@@ -1,5 +1,5 @@
 import { audio } from "../../../actions/index.js";
-import { initializeContext, runTranslateIfNeeded } from "../../helpers.js";
+import { dumpUsageIfRequested, initializeContext, runTranslateIfNeeded } from "../../helpers.js";
 export const handler = async (argv) => {
     const context = await initializeContext(argv);
     if (!context) {
@@ -7,4 +7,5 @@ export const handler = async (argv) => {
     }
     await runTranslateIfNeeded(context);
     await audio(context);
+    dumpUsageIfRequested(context);
 };

package/lib/cli/commands/bundle/handler.js

@@ -1,5 +1,5 @@
 import { mulmoViewerBundle, audio, images, translate } from "../../../actions/index.js";
-import { initializeContext } from "../../helpers.js";
+import { dumpUsageIfRequested, initializeContext } from "../../helpers.js";
 import { bundleTargetLang } from "../../../types/const.js";
 export const handler = async (argv) => {
     const context = await initializeContext(argv);
@@ -11,4 +11,5 @@ export const handler = async (argv) => {
         await audio({ ...context, lang });
     }
     await audio(context).then(images).then(mulmoViewerBundle);
+    dumpUsageIfRequested(context);
 };

package/lib/cli/commands/html/handler.js

@@ -1,5 +1,5 @@
 import { images, html } from "../../../actions/index.js";
-import { initializeContext, runTranslateIfNeeded } from "../../helpers.js";
+import { dumpUsageIfRequested, initializeContext, runTranslateIfNeeded } from "../../helpers.js";
 export const handler = async (argv) => {
     const context = await initializeContext(argv);
     if (!context) {
@@ -8,4 +8,5 @@ export const handler = async (argv) => {
     await runTranslateIfNeeded(context);
     await images(context);
     await html(context, argv.image_width);
+    dumpUsageIfRequested(context);
 };

package/lib/cli/commands/image/handler.js

@@ -1,5 +1,5 @@
 import { images } from "../../../actions/index.js";
-import { initializeContext, runTranslateIfNeeded } from "../../helpers.js";
+import { dumpUsageIfRequested, initializeContext, runTranslateIfNeeded } from "../../helpers.js";
 export const handler = async (argv) => {
     const context = await initializeContext(argv);
     if (!context) {
@@ -7,4 +7,5 @@ export const handler = async (argv) => {
     }
     await runTranslateIfNeeded(context);
     await images(context);
+    dumpUsageIfRequested(context);
 };

package/lib/cli/commands/markdown/handler.js

@@ -1,5 +1,5 @@
 import { images, markdown } from "../../../actions/index.js";
-import { initializeContext, runTranslateIfNeeded } from "../../helpers.js";
+import { dumpUsageIfRequested, initializeContext, runTranslateIfNeeded } from "../../helpers.js";
 export const handler = async (argv) => {
     const context = await initializeContext(argv);
     if (!context) {
@@ -8,4 +8,5 @@ export const handler = async (argv) => {
     await runTranslateIfNeeded(context);
     await images(context);
     await markdown(context, argv.image_width);
+    dumpUsageIfRequested(context);
 };

package/lib/cli/commands/movie/handler.js

@@ -1,5 +1,5 @@
 import { audio, images, movie, captions } from "../../../actions/index.js";
-import { initializeContext, runTranslateIfNeeded } from "../../helpers.js";
+import { dumpUsageIfRequested, initializeContext, runTranslateIfNeeded } from "../../helpers.js";
 export const handler = async (argv) => {
     const context = await initializeContext(argv);
     if (!context) {
@@ -7,4 +7,5 @@ export const handler = async (argv) => {
     }
     await runTranslateIfNeeded(context, true);
     await audio(context).then(images).then(captions).then(movie);
+    dumpUsageIfRequested(context);
 };

package/lib/cli/commands/pdf/handler.js

@@ -1,5 +1,5 @@
 import { images, pdf } from "../../../actions/index.js";
-import { initializeContext, runTranslateIfNeeded } from "../../helpers.js";
+import { dumpUsageIfRequested, initializeContext, runTranslateIfNeeded } from "../../helpers.js";
 export const handler = async (argv) => {
     const context = await initializeContext(argv);
     if (!context) {
@@ -8,4 +8,5 @@ export const handler = async (argv) => {
     await runTranslateIfNeeded(context);
     await images(context);
     await pdf(context, argv.pdf_mode, argv.pdf_size);
+    dumpUsageIfRequested(context);
 };

package/lib/cli/commands/translate/handler.js

@@ -1,9 +1,10 @@
 import { translate } from "../../../actions/index.js";
-import { initializeContext } from "../../helpers.js";
+import { dumpUsageIfRequested, initializeContext } from "../../helpers.js";
 export const handler = async (argv) => {
     const context = await initializeContext(argv);
     if (!context) {
         process.exit(1);
     }
     await translate(context);
+    dumpUsageIfRequested(context);
 };

package/lib/cli/helpers.d.ts

@@ -1,6 +1,7 @@
 import type { CliArgs } from "../types/cli_types.js";
 import { FileObject, InitOptions, MulmoStudioContext } from "../types/index.js";
 export declare const runTranslateIfNeeded: (context: MulmoStudioContext, includeCaption?: boolean) => Promise<void>;
+export declare const dumpUsageIfRequested: (context: MulmoStudioContext) => void;
 export declare const setGraphAILogger: (verbose: boolean | undefined, logValues?: Record<string, unknown>) => void;
 export declare const getFileObject: (args: {
     basedir?: string;

package/lib/cli/helpers.js

@@ -14,6 +14,52 @@ export const runTranslateIfNeeded = async (context, includeCaption = false) => {
         await translate(context);
     }
 };
+const summarizeUsage = (context) => {
+    const snapshot = context.usageCollector?.snapshot() ?? [];
+    const groups = new Map();
+    for (const record of snapshot) {
+        const key = `${record.provider}:${record.model}`;
+        const group = groups.get(key) ?? {
+            provider: record.provider,
+            model: record.model,
+            records: 0,
+            inputTokens: 0,
+            outputTokens: 0,
+            totalTokens: 0,
+            predictSec: 0,
+            inputChars: 0,
+        };
+        group.records += 1;
+        group.inputTokens += record.inputTokens ?? 0;
+        group.outputTokens += record.outputTokens ?? 0;
+        group.totalTokens += record.totalTokens ?? 0;
+        group.predictSec += record.predictSec ?? 0;
+        group.inputChars += record.inputChars ?? 0;
+        groups.set(key, group);
+    }
+    return { records: snapshot.length, byModel: Array.from(groups.values()), snapshot };
+};
+// Opt-in usage dump after a CLI action completes. Controlled by
+// MULMOCAST_DUMP_USAGE:
+//   - unset / empty → no-op (zero overhead)
+//   - "1" / "true" / "stdout" → print JSON to stdout via GraphAILogger.info
+//   - any other value → treated as a file path and the JSON is written there
+//
+// The API/billing layer reads context.usageCollector directly; this is for
+// local CLI verification only.
+export const dumpUsageIfRequested = (context) => {
+    const setting = process.env.MULMOCAST_DUMP_USAGE;
+    if (!setting)
+        return;
+    const payload = summarizeUsage(context);
+    const json = JSON.stringify(payload, null, 2);
+    if (setting === "1" || setting === "true" || setting === "stdout") {
+        GraphAILogger.info(json);
+        return;
+    }
+    fs.writeFileSync(setting, json, "utf-8");
+    GraphAILogger.info(`usage written to ${setting}`);
+};
 export const setGraphAILogger = (verbose, logValues) => {
     if (verbose) {
         if (logValues) {

package/lib/tools/create_mulmo_script_from_url.d.ts

@@ -1,3 +1,3 @@
 import { ScriptingParams } from "../types/index.js";
-export declare const createMulmoScriptFromUrl: ({ urls, templateName, outDirPath, filename, cacheDirPath, llm, llm_model }: ScriptingParams) => Promise<void>;
-export declare const createMulmoScriptFromFile: (fileName: string, { templateName, outDirPath, filename, cacheDirPath, llm, llm_model, verbose }: ScriptingParams) => Promise<void>;
+export declare const createMulmoScriptFromUrl: ({ urls, templateName, outDirPath, filename, cacheDirPath, llm, llm_model, usageCollector }: ScriptingParams) => Promise<void>;
+export declare const createMulmoScriptFromFile: (fileName: string, { templateName, outDirPath, filename, cacheDirPath, llm, llm_model, verbose, usageCollector }: ScriptingParams) => Promise<void>;

package/lib/tools/create_mulmo_script_from_url.js

@@ -15,6 +15,7 @@ import { mulmoScriptSchema, urlsSchema } from "../types/schema.js";
 import { cliLoadingPlugin } from "../utils/plugins.js";
 import { graphDataScriptFromUrlPrompt } from "../utils/prompt.js";
 import { llmPair, settings2GraphAIConfig } from "../utils/utils.js";
+import { createUsageCallback } from "../utils/usage_callback.js";
 import { readFileSync } from "fs";
 dotenv.config({ quiet: true });
 const vanillaAgents = agents.default ?? agents;
@@ -207,7 +208,7 @@ const graphDataText = {
         },
     },
 };
-export const createMulmoScriptFromUrl = async ({ urls, templateName, outDirPath, filename, cacheDirPath, llm, llm_model }) => {
+export const createMulmoScriptFromUrl = async ({ urls, templateName, outDirPath, filename, cacheDirPath, llm, llm_model, usageCollector }) => {
     mkdir(outDirPath);
     mkdir(cacheDirPath);
     const parsedUrls = urlsSchema.parse(urls);
@@ -239,6 +240,7 @@ export const createMulmoScriptFromUrl = async ({ urls, templateName, outDirPath,
     graph.injectValue("llmModel", model);
     graph.injectValue("maxTokens", max_tokens);
     graph.registerCallback(cliLoadingPlugin({ nodeId: "mulmoScript", message: "Generating script..." }));
+    graph.registerCallback(createUsageCallback(usageCollector));
     const result = await graph.run();
     if (!result?.writeJSON?.path) {
         showErrorMessage("Script generation failed. Please try again.");
@@ -246,7 +248,7 @@ export const createMulmoScriptFromUrl = async ({ urls, templateName, outDirPath,
     }
     writingMessage(result?.writeJSON?.path ?? "");
 };
-export const createMulmoScriptFromFile = async (fileName, { templateName, outDirPath, filename, cacheDirPath, llm, llm_model, verbose }) => {
+export const createMulmoScriptFromFile = async (fileName, { templateName, outDirPath, filename, cacheDirPath, llm, llm_model, verbose, usageCollector }) => {
     mkdir(outDirPath);
     mkdir(cacheDirPath);
     const filePath = path.resolve(process.cwd(), fileName);
@@ -272,6 +274,7 @@ export const createMulmoScriptFromFile = async (fileName, { templateName, outDir
     if (!verbose) {
         graph.registerCallback(cliLoadingPlugin({ nodeId: "mulmoScript", message: "Generating script..." }));
     }
+    graph.registerCallback(createUsageCallback(usageCollector));
     const result = await graph.run();
     if (!result?.writeJSON?.path) {
         showErrorMessage("Script generation failed. Please try again.");

package/lib/tools/create_mulmo_script_interactively.d.ts

@@ -1,2 +1,2 @@
 import { ScriptingParams } from "../types/index.js";
-export declare const createMulmoScriptInteractively: ({ outDirPath, cacheDirPath, filename, templateName, urls, llm, llm_model }: ScriptingParams) => Promise<void>;
+export declare const createMulmoScriptInteractively: ({ outDirPath, cacheDirPath, filename, templateName, urls, llm, llm_model, usageCollector, }: ScriptingParams) => Promise<void>;

package/lib/tools/create_mulmo_script_interactively.js

@@ -14,6 +14,7 @@ import { mulmoScriptSchema } from "../types/index.js";
 import { browserlessAgent } from "@graphai/browserless_agent";
 import validateSchemaAgent from "../agents/validate_schema_agent.js";
 import { llmPair, settings2GraphAIConfig } from "../utils/utils.js";
+import { createUsageCallback } from "../utils/usage_callback.js";
 import { interactiveClarificationPrompt, prefixPrompt } from "../utils/prompt.js";
 // import { cliLoadingPlugin } from "../utils/plugins.js";
 dotenv.config({ quiet: true });
@@ -199,7 +200,7 @@ const graphData = {
         },
     },
 };
-const scrapeWebContent = async (urls, cacheDirPath) => {
+const scrapeWebContent = async (urls, cacheDirPath, usageCollector) => {
     mkdir(cacheDirPath);
     GraphAILogger.info(`${agentHeader} Scraping ${urls.length} URLs...\n`);
     const browserlessCache = browserlessCacheGenerator(cacheDirPath);
@@ -212,16 +213,17 @@ const scrapeWebContent = async (urls, cacheDirPath) => {
     ];
     const graph = new GraphAI(graphDataForScraping, { ...vanillaAgents, openAIAgent, textInputAgent, fileWriteAgent, browserlessAgent }, { agentFilters });
     graph.injectValue("urls", urls);
+    graph.registerCallback(createUsageCallback(usageCollector));
     const result = (await graph.run());
     if (!result?.sourceText?.text) {
         return "";
     }
     return `\n\n${prefixPrompt}\n${result?.sourceText.text}`;
 };
-export const createMulmoScriptInteractively = async ({ outDirPath, cacheDirPath, filename, templateName, urls, llm, llm_model }) => {
+export const createMulmoScriptInteractively = async ({ outDirPath, cacheDirPath, filename, templateName, urls, llm, llm_model, usageCollector, }) => {
     mkdir(outDirPath);
     // if urls is not empty, scrape web content and reference it in the prompt
-    const webContentPrompt = urls.length > 0 ? await scrapeWebContent(urls, cacheDirPath) : "";
+    const webContentPrompt = urls.length > 0 ? await scrapeWebContent(urls, cacheDirPath, usageCollector) : "";
     const { agent, model, max_tokens } = llmPair(llm, llm_model);
     GraphAILogger.log({ agent, model, max_tokens });
     const agentFilters = [
@@ -255,6 +257,7 @@ export const createMulmoScriptInteractively = async ({ outDirPath, cacheDirPath,
             }
         }
     });
+    graph.registerCallback(createUsageCallback(usageCollector));
     // graph.registerCallback(cliLoadingPlugin({ nodeId: "reply", message: "Loading..." }));
     GraphAILogger.info(`${agentHeader} Hi! What topic would you like me to generate about?\n`);
     await graph.run();

package/lib/tools/deep_research.d.ts

@@ -1 +1,2 @@
-export declare const deepResearch: () => Promise<void>;
+import type { UsageCollectorAPI } from "../types/usage.js";
+export declare const deepResearch: (usageCollector?: UsageCollectorAPI) => Promise<void>;

package/lib/tools/deep_research.js

@@ -7,6 +7,7 @@ import * as agents from "@graphai/vanilla";
 import tavilySearchAgent from "../agents/tavily_agent.js";
 import { cliLoadingPlugin } from "../utils/plugins.js";
 import { searchQueryPrompt, reflectionPrompt, finalAnswerPrompt } from "../utils/prompt.js";
+import { createUsageCallback } from "../utils/usage_callback.js";
 dotenv.config({ quiet: true });
 const vanillaAgents = agents.default ?? agents;
 const agentHeader = "\x1b[34m● \x1b[0m\x1b[1mAgent\x1b[0m:\x1b[0m";
@@ -246,7 +247,7 @@ const graphData = {
         },
     },
 };
-export const deepResearch = async () => {
+export const deepResearch = async (usageCollector) => {
     const agentFilters = [
         {
             name: "consoleStreamDataAgentFilter",
@@ -260,6 +261,7 @@ export const deepResearch = async () => {
     graph.registerCallback(cliLoadingPlugin({ nodeId: "reflectionAgent", message: "Analyzing search results..." }));
     graph.registerCallback(cliLoadingPlugin({ nodeId: "tavilySearchAgent", message: "Searching..." }));
     graph.registerCallback(cliLoadingPlugin({ nodeId: "finalAnswer", message: "Generating final answer..." }));
+    graph.registerCallback(createUsageCallback(usageCollector));
     GraphAILogger.info(`${agentHeader} What would you like to know?\n`);
     await graph.run();
 };

package/lib/tools/story_to_script.d.ts

@@ -1,6 +1,7 @@
 import { MulmoStoryboard, StoryToScriptGenerateMode } from "../types/index.js";
 import type { LLM } from "../types/provider2agent.js";
-export declare const storyToScript: ({ story, beatsPerScene, templateName, outdir, fileName, llm, llmModel, generateMode, }: {
+import type { UsageCollectorAPI } from "../types/usage.js";
+export declare const storyToScript: ({ story, beatsPerScene, templateName, outdir, fileName, llm, llmModel, generateMode, usageCollector, }: {
     story: MulmoStoryboard;
     beatsPerScene: number;
     templateName: string;
@@ -9,4 +10,5 @@ export declare const storyToScript: ({ story, beatsPerScene, templateName, outdi
     llm?: LLM;
     llmModel?: string;
     generateMode: StoryToScriptGenerateMode;
+    usageCollector?: UsageCollectorAPI;
 }) => Promise<void>;

package/lib/tools/story_to_script.js

@@ -10,6 +10,7 @@ import { graphDataScriptGeneratePrompt, sceneToBeatsPrompt, storyToScriptInfoPro
 import { fileWriteAgent } from "@graphai/vanilla_node_agents";
 import validateSchemaAgent from "../agents/validate_schema_agent.js";
 import { llmPair, settings2GraphAIConfig } from "../utils/utils.js";
+import { createUsageCallback } from "../utils/usage_callback.js";
 import { storyToScriptGenerateMode } from "../types/const.js";
 import { cliLoadingPlugin } from "../utils/plugins.js";
 const vanillaAgents = agents.default ?? agents;
@@ -248,7 +249,7 @@ const generateScriptPrompt = async (template, beatsPerScene, story) => {
     const script = readScriptTemplateFile(template.scriptName);
     return storyToScriptPrompt(script, beatsPerScene, story);
 };
-export const storyToScript = async ({ story, beatsPerScene, templateName, outdir, fileName, llm, llmModel, generateMode, }) => {
+export const storyToScript = async ({ story, beatsPerScene, templateName, outdir, fileName, llm, llmModel, generateMode, usageCollector, }) => {
     const template = readAndParseJson(getPromptTemplateFilePath(templateName), mulmoPromptTemplateSchema);
     const { agent, model, max_tokens } = llmPair(llm, llmModel);
     const beatsPrompt = await generateBeatsPrompt(template, beatsPerScene, story);
@@ -271,6 +272,7 @@ export const storyToScript = async ({ story, beatsPerScene, templateName, outdir
     graph.injectValue("llmModel", model);
     graph.injectValue("maxTokens", max_tokens);
     graph.registerCallback(cliLoadingPlugin({ nodeId: "script", message: "Generating script..." }));
+    graph.registerCallback(createUsageCallback(usageCollector));
     const result = await graph.run();
     writingMessage(result?.writeJSON?.path ?? "");
 };

package/lib/types/agent.d.ts

@@ -10,10 +10,12 @@ export type OpenAIImageOptions = {
     quality?: OpenAIImageQuality;
     background?: "opaque" | "transparent" | "auto";
 };
+import type { AgentUsage } from "./usage.js";
 export type AgentBufferResult = {
     buffer?: Buffer;
     saved?: string;
     text?: string;
+    usage?: AgentUsage;
 };
 export type AgentPromptInputs = {
     prompt: string;

package/lib/types/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./type.js";
 export * from "./schema.js";
 export * from "./viewer.js";
+export * from "./usage.js";

package/lib/types/index.js

@@ -1,3 +1,4 @@
 export * from "./type.js";
 export * from "./schema.js";
 export * from "./viewer.js";
+export * from "./usage.js";

package/lib/types/type.d.ts

@@ -1,4 +1,5 @@
 import { type CallbackFunction } from "graphai";
+import type { UsageCollectorAPI } from "./usage.js";
 import { langSchema, localizedTextSchema, mulmoBeatSchema, mulmoScriptSchema, mulmoStudioSchema, mulmoStudioBeatSchema, mulmoStoryboardSchema, mulmoStoryboardSceneSchema, mulmoStudioMultiLingualSchema, mulmoStudioMultiLingualArraySchema, mulmoStudioMultiLingualDataSchema, mulmoStudioMultiLingualFileSchema, speakerDictionarySchema, speakerSchema, mulmoSpeechParamsSchema, mulmoImageParamsSchema, mulmoImageParamsImagesValueSchema, mulmoImageParamsImagesSchema, mulmoFillOptionSchema, mulmoTransitionSchema, mulmoVideoFilterSchema, mulmoMovieParamsSchema, mulmoSoundEffectParamsSchema, mulmoLipSyncParamsSchema, textSlideParamsSchema, speechOptionsSchema, speakerDataSchema, mulmoCanvasDimensionSchema, mulmoPromptTemplateSchema, mulmoPromptTemplateFileSchema, text2ImageProviderSchema, text2HtmlImageProviderSchema, text2MovieProviderSchema, text2SpeechProviderSchema, mulmoPresentationStyleSchema, multiLingualTextsSchema, mulmoImageAssetSchema, mulmoMermaidMediaSchema, mulmoTextSlideMediaSchema, mulmoMarkdownMediaSchema, mulmoImageMediaSchema, mulmoChartMediaSchema, mediaSourceSchema, mediaSourceMermaidSchema, backgroundImageSchema, backgroundImageSourceSchema, mulmoSessionStateSchema, mulmoOpenAIImageModelSchema, mulmoGoogleImageModelSchema, mulmoGoogleMovieModelSchema, mulmoReplicateMovieModelSchema, mulmoImagePromptMediaSchema, mulmoMovieMediaSchema, mulmoMoviePromptMediaSchema, markdownLayoutSchema, row2Schema, grid2x2Schema } from "./schema.js";
 import { pdf_modes, pdf_sizes, storyToScriptGenerateMode } from "./const.js";
 import type { LLM } from "./provider2agent.js";
@@ -68,6 +69,7 @@ export type MulmoStudioContext = {
     sessionState: MulmoSessionState;
     presentationStyle: MulmoPresentationStyle;
     multiLingual: MulmoStudioMultiLingualArray;
+    usageCollector?: UsageCollectorAPI;
 };
 export type ScriptingParams = {
     urls: string[];
@@ -78,6 +80,7 @@ export type ScriptingParams = {
     llm_model?: string;
     llm?: LLM;
     verbose?: boolean;
+    usageCollector?: UsageCollectorAPI;
 };
 export type ImageProcessorParams = {
     beat: MulmoBeat;

package/lib/types/usage.d.ts

@@ -0,0 +1,32 @@
+export type AgentUsage = {
+    provider: string;
+    model: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    predictSec?: number;
+    inputChars?: number;
+};
+export type UsageRecord = {
+    agent: string;
+    provider: string;
+    model: string;
+    beatIndex?: number;
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    predictSec?: number;
+    inputChars?: number;
+    cached: boolean;
+    retryAttempt?: number;
+    timestamp: string;
+};
+export type UsageCollectorAPI = {
+    add(record: Omit<UsageRecord, "timestamp"> & {
+        timestamp?: string;
+    }): void;
+    snapshot(): UsageRecord[];
+    merge(other: UsageCollectorAPI): void;
+    clear(): void;
+    readonly size: number;
+};

package/lib/types/usage.js

@@ -0,0 +1 @@
+export {};

package/lib/utils/context.d.ts

@@ -1,4 +1,5 @@
 import type { MulmoStudioBeat, MulmoScript, MulmoPresentationStyle, MulmoStudioMultiLingual, FileObject } from "../types/type.js";
+import { UsageCollector } from "./usage_collector.js";
 export declare const silentMp3 = "https://github.com/receptron/mulmocast-cli/raw/refs/heads/main/assets/audio/silent300.mp3";
 export type MulmoErrorFormatter = (error: unknown) => string | null;
 export declare const setMulmoErrorFormatter: (formatter: MulmoErrorFormatter | null) => void;
@@ -5504,4 +5505,5 @@ export declare const initializeContextFromFiles: (files: FileObject, raiseError:
     force: boolean;
     backup: boolean;
     lang: string;
+    usageCollector: UsageCollector;
 } | null>;

package/lib/utils/context.js

@@ -4,6 +4,7 @@ import { beatId, multiLingualObjectToArray } from "./utils.js";
 import { mulmoStudioSchema, mulmoCaptionParamsSchema, mulmoPresentationStyleSchema } from "../types/schema.js";
 import { MulmoPresentationStyleMethods, MulmoScriptMethods, MulmoStudioMultiLingualMethod } from "../methods/index.js";
 import { loadMulmoConfig, mergeConfigWithScript } from "./mulmo_config.js";
+import { UsageCollector } from "./usage_collector.js";
 export const silentMp3 = "https://github.com/receptron/mulmocast-cli/raw/refs/heads/main/assets/audio/silent300.mp3";
 let mulmoErrorFormatter = null;
 export const setMulmoErrorFormatter = (formatter) => {
@@ -151,6 +152,7 @@ export const initializeContextFromFiles = async (files, raiseError, force, withB
             force: Boolean(force),
             backup: Boolean(withBackup),
             lang: targetLang ?? studio.script.lang, // This lang is target Language. studio.lang is default Language
+            usageCollector: new UsageCollector(),
         };
     }
     catch (error) {

package/lib/utils/filters.js

@@ -37,7 +37,7 @@ export const fileCacheAgentFilter = async (context, next) => {
         const output = (await next(context)) || undefined;
         const { buffer, text, saved } = output ?? {};
         if (saved) {
-            return true;
+            return output;
         }
         if (buffer) {
             writingMessage(file);
@@ -45,7 +45,7 @@ export const fileCacheAgentFilter = async (context, next) => {
             if (backup) {
                 await fsPromise.writeFile(getBackupFilePath(file), buffer);
             }
-            return true;
+            return output;
         }
         else if (text) {
             writingMessage(file);
@@ -53,10 +53,7 @@ export const fileCacheAgentFilter = async (context, next) => {
             if (backup) {
                 await fsPromise.writeFile(getBackupFilePath(file), text, "utf-8");
             }
-            return true;
-        }
-        else if (saved) {
-            return true;
+            return output;
         }
         GraphAILogger.log("no cache, no buffer: " + file);
         return false;

package/lib/utils/replicate_usage.d.ts

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

package/lib/utils/replicate_usage.js

@@ -0,0 +1,11 @@
+// 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) => {
+    let lastPrediction;
+    const output = await replicate.run(identifier, { input, signal }, (prediction) => {
+        lastPrediction = prediction;
+    });
+    return { output, predictSec: lastPrediction?.metrics?.predict_time };
+};

package/lib/utils/usage_callback.d.ts

@@ -0,0 +1,4 @@
+import { type CallbackFunction } from "graphai";
+import type { MulmoStudioContext } from "../types/type.js";
+import type { UsageCollectorAPI } from "../types/usage.js";
+export declare const createUsageCallback: (target: MulmoStudioContext | UsageCollectorAPI | undefined) => CallbackFunction;

package/lib/utils/usage_callback.js

@@ -0,0 +1,93 @@
+import { NodeState } from "graphai";
+// @graphai/* LLM agents (openAIAgent / geminiAgent / anthropicAgent / groqAgent)
+// return usage in the OpenAI chat-completions wire shape:
+//   { prompt_tokens, completion_tokens, total_tokens }
+// without provider/model on the usage object. We derive provider from the
+// node's agentId and model from the node's params or the spread response.
+const LLM_AGENT_TO_PROVIDER = {
+    openAIAgent: "openai",
+    geminiAgent: "google",
+    anthropicAgent: "anthropic",
+    groqAgent: "groq",
+};
+const isAgentUsage = (value) => {
+    if (!value || typeof value !== "object")
+        return false;
+    const { provider, model } = value;
+    return typeof provider === "string" && typeof model === "string";
+};
+const extractLLMUsage = (log) => {
+    const provider = log.agentId ? LLM_AGENT_TO_PROVIDER[log.agentId] : undefined;
+    if (!provider)
+        return undefined;
+    const result = log.result;
+    const u = result?.usage;
+    if (!u || typeof u.prompt_tokens !== "number" || typeof u.total_tokens !== "number")
+        return undefined;
+    const pickModel = () => {
+        const fromParams = log.params?.model;
+        if (typeof fromParams === "string")
+            return fromParams;
+        if (typeof result?.model === "string")
+            return result.model;
+        return "unknown";
+    };
+    const model = pickModel();
+    return {
+        provider,
+        model,
+        inputTokens: u.prompt_tokens,
+        outputTokens: u.completion_tokens,
+        totalTokens: u.total_tokens,
+    };
+};
+const extractUsage = (log) => {
+    // 1. mulmocast AgentUsage shape (image/TTS agents in this repo).
+    if (log.result && typeof log.result === "object") {
+        const { usage } = log.result;
+        if (isAgentUsage(usage))
+            return usage;
+    }
+    // 2. @graphai/* LLM shape — derive provider/model from log metadata.
+    return extractLLMUsage(log);
+};
+const resolveCollector = (target) => {
+    if (!target)
+        return undefined;
+    // A MulmoStudioContext has the optional `usageCollector` slot; the API itself
+    // doesn't. Distinguishing on the slot name lets either form pass through.
+    if ("usageCollector" in target)
+        return target.usageCollector;
+    return target;
+};
+// GraphAI callback that pushes any agent's reported usage into the given
+// UsageCollector when the node completes successfully. No-op when the
+// collector is absent (either undefined directly or `context.usageCollector`
+// undefined), the node fails, or the result has no `usage`.
+export const createUsageCallback = (target) => {
+    return (log, isUpdate) => {
+        if (isUpdate)
+            return;
+        if (log.state !== NodeState.Completed)
+            return;
+        const collector = resolveCollector(target);
+        if (!collector)
+            return;
+        const usage = extractUsage(log);
+        if (!usage)
+            return;
+        collector.add({
+            agent: log.agentId ?? "unknown",
+            provider: usage.provider,
+            model: usage.model,
+            beatIndex: log.mapIndex,
+            inputTokens: usage.inputTokens,
+            outputTokens: usage.outputTokens,
+            totalTokens: usage.totalTokens,
+            predictSec: usage.predictSec,
+            inputChars: usage.inputChars,
+            cached: false,
+            retryAttempt: log.retryCount,
+        });
+    };
+};

package/lib/utils/usage_collector.d.ts

@@ -0,0 +1,12 @@
+import type { UsageRecord, UsageCollectorAPI } from "../types/usage.js";
+export type { UsageRecord, UsageCollectorAPI } from "../types/usage.js";
+export declare class UsageCollector implements UsageCollectorAPI {
+    private readonly records;
+    add(record: Omit<UsageRecord, "timestamp"> & {
+        timestamp?: string;
+    }): void;
+    snapshot(): UsageRecord[];
+    merge(other: UsageCollectorAPI): void;
+    clear(): void;
+    get size(): number;
+}

package/lib/utils/usage_collector.js

@@ -0,0 +1,18 @@
+export class UsageCollector {
+    records = [];
+    add(record) {
+        this.records.push({ ...record, timestamp: record.timestamp ?? new Date().toISOString() });
+    }
+    snapshot() {
+        return this.records.map((record) => ({ ...record }));
+    }
+    merge(other) {
+        other.snapshot().forEach((record) => this.records.push({ ...record }));
+    }
+    clear() {
+        this.records.length = 0;
+    }
+    get size() {
+        return this.records.length;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mulmocast",
-  "version": "2.6.20",
+  "version": "2.6.21",
   "description": "",
   "type": "module",
   "main": "lib/index.node.js",
@@ -25,7 +25,7 @@
   },
   "resolutions": {
     "minimatch": "^10.2.5",
-    "tar": "7.5.15",
+    "tar": "7.5.16",
     "yauzl": "^3.3.1"
   },
   "bin": {
@@ -102,7 +102,7 @@
     "@inquirer/input": "^5.0.13",
     "@inquirer/select": "^5.1.5",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@modernized/fluent-ffmpeg": "^1.0.0",
+    "@modernized/fluent-ffmpeg": "^1.0.1",
     "@mozilla/readability": "^0.6.0",
     "@mulmocast/deck": "^1.1.0",
     "@tavily/core": "^0.7.3",
@@ -127,16 +127,16 @@
     "@types/jsdom": "^28.0.3",
     "@types/yargs": "^17.0.35",
     "cross-env": "^10.1.0",
-    "eslint": "^10.4.1",
+    "eslint": "^10.5.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-prettier": "^5.5.6",
     "eslint-plugin-sonarjs": "^4.0.3",
     "globals": "^17.6.0",
-    "prettier": "^3.8.3",
+    "prettier": "^3.8.4",
     "tsx": "^4.22.4",
     "typescript": "6.0.3",
-    "typescript-eslint": "^8.60.1"
+    "typescript-eslint": "^8.61.1"
   },
   "engines": {
     "node": ">=22.0.0"