@blockrun/franklin 3.8.35 → 3.8.36

package/dist/tools/imagegen.js

@@ -9,13 +9,89 @@ import { loadChain, API_URLS, VERSION } from '../config.js';
 import { checkImageBudget, recordImageAsset } from '../content/record-image.js';
 import { ModelClient } from '../agent/llm.js';
 import { analyzeMediaRequest, renderProposalForAskUser } from '../agent/media-router.js';
+import { recordUsage } from '../stats/tracker.js';
+import { findModel, estimateCostUsd } from '../gateway-models.js';
+/**
+ * Models that accept a reference image via /v1/images/image2image. Currently
+ * limited to OpenAI's edit endpoint — Gemini Nano Banana Pro and Grok Imagine
+ * Image Pro need gateway-side support before they can be wired in here.
+ */
+export const EDIT_SUPPORTED_MODELS = new Set([
+    'openai/gpt-image-1',
+    'openai/gpt-image-2',
+]);
+export const REFERENCE_IMAGE_MAX_BYTES = 4_000_000;
+/**
+ * Normalize a reference image into a base64 data URI for the gateway. The
+ * /v1/images/image2image endpoint validates `image` against /^data:image\//,
+ * so http(s) URLs and local paths both have to be inlined client-side before
+ * posting. Already-formed data URIs pass through.
+ */
+export async function resolveReferenceImage(input, workingDir) {
+    if (input.startsWith('data:image/'))
+        return input;
+    if (/^https?:\/\//i.test(input)) {
+        const ctrl = new AbortController();
+        const timeout = setTimeout(() => ctrl.abort(), 30_000);
+        try {
+            const resp = await fetch(input, { signal: ctrl.signal });
+            if (!resp.ok) {
+                throw new Error(`Reference image fetch failed: ${resp.status} ${resp.statusText}`);
+            }
+            const contentType = (resp.headers.get('content-type') || '').toLowerCase().split(';')[0].trim();
+            if (!contentType.startsWith('image/')) {
+                throw new Error(`Reference image URL returned non-image content-type: ${contentType || '(none)'}`);
+            }
+            const buf = Buffer.from(await resp.arrayBuffer());
+            if (buf.byteLength > REFERENCE_IMAGE_MAX_BYTES) {
+                throw new Error(`Reference image too large: ${(buf.byteLength / 1_000_000).toFixed(1)}MB > ${(REFERENCE_IMAGE_MAX_BYTES / 1_000_000).toFixed(1)}MB cap.`);
+            }
+            return `data:${contentType};base64,${buf.toString('base64')}`;
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    // Treat as local file path.
+    const resolved = path.isAbsolute(input) ? input : path.resolve(workingDir, input);
+    const stat = fs.statSync(resolved);
+    if (stat.size > REFERENCE_IMAGE_MAX_BYTES) {
+        throw new Error(`Reference image too large: ${(stat.size / 1_000_000).toFixed(1)}MB > ${(REFERENCE_IMAGE_MAX_BYTES / 1_000_000).toFixed(1)}MB cap. Resize or crop first.`);
+    }
+    const ext = path.extname(resolved).toLowerCase();
+    const mimeMap = {
+        '.png': 'image/png',
+        '.jpg': 'image/jpeg',
+        '.jpeg': 'image/jpeg',
+        '.gif': 'image/gif',
+        '.webp': 'image/webp',
+    };
+    const mime = mimeMap[ext];
+    if (!mime) {
+        throw new Error(`Unsupported reference image extension ${ext || '(none)'}. Use .png/.jpg/.jpeg/.gif/.webp.`);
+    }
+    const bytes = fs.readFileSync(resolved);
+    return `data:${mime};base64,${bytes.toString('base64')}`;
+}
 function buildExecute(deps) {
     return async function execute(input, ctx) {
         const rawInput = input;
-        const { output_path, size, model, contentId } = rawInput;
+        const { output_path, size, model, contentId, image_url } = rawInput;
         if (!rawInput.prompt) {
             return { output: 'Error: prompt is required', isError: true };
         }
+        // Resolve the reference image (if any) before any paid call so we fail
+        // cheaply on bad paths / oversize attachments. Holds the resolved data URI
+        // / http URL that gets posted to /v1/images/image2image.
+        let referenceImage;
+        if (image_url) {
+            try {
+                referenceImage = await resolveReferenceImage(image_url, ctx.workingDir);
+            }
+            catch (err) {
+                return { output: `Error: ${err.message}`, isError: true };
+            }
+        }
         // One-shot refinement opt-out: leading `///` tells Franklin "don't
         // refine this prompt, I wrote it the way I want it." Strip the prefix
         // and pass skipRefine through to the router.
@@ -31,11 +107,26 @@ function buildExecute(deps) {
         // step and use the old default. Otherwise: classifier picks a fitting
         // model + rewrites the prompt, the preview goes to AskUser, user
         // chooses or cancels.
-        let imageModel = model || 'openai/gpt-image-1';
+        // Reference-image mode forces an edit-capable model. If the caller named
+        // an unsupported one, fail loudly so we don't silently downgrade their
+        // request to text-only generation.
+        if (referenceImage && model && !EDIT_SUPPORTED_MODELS.has(model)) {
+            return {
+                output: `Error: model ${model} does not support reference images. ` +
+                    `Use one of: ${[...EDIT_SUPPORTED_MODELS].join(', ')}.`,
+                isError: true,
+            };
+        }
+        let imageModel = model || (referenceImage ? 'openai/gpt-image-2' : 'openai/gpt-image-1');
         const imageSize = size || '1024x1024';
         let chosenPrompt = prompt;
+        // Skip the proposal flow when a reference image is set: the media router
+        // doesn't know which models support image-to-image, so its suggestions
+        // would frequently be unusable (text-only models). Default to gpt-image-1
+        // for now; a future router upgrade can pick between the four edit-capable
+        // models based on the prompt.
         const autoApprove = process.env.FRANKLIN_MEDIA_AUTO_APPROVE_ALL === '1';
-        if (!model && !autoApprove && ctx.onAskUser) {
+        if (!model && !autoApprove && ctx.onAskUser && !referenceImage) {
             try {
                 const chain = loadChain();
                 const client = new ModelClient({ apiUrl: API_URLS[chain], chain });
@@ -95,18 +186,30 @@ function buildExecute(deps) {
         }
         const chain = loadChain();
         const apiUrl = API_URLS[chain];
-        const endpoint = `${apiUrl}/v1/images/generations`;
+        // Reference-image mode hits the dedicated /v1/images/image2image endpoint;
+        // otherwise stay on text-to-image generations.
+        const endpoint = referenceImage
+            ? `${apiUrl}/v1/images/image2image`
+            : `${apiUrl}/v1/images/generations`;
         // Default output path
         const outPath = output_path
             ? (path.isAbsolute(output_path) ? output_path : path.resolve(ctx.workingDir, output_path))
             : path.resolve(ctx.workingDir, `generated-${Date.now()}.png`);
-        const body = JSON.stringify({
-            model: imageModel,
-            prompt: chosenPrompt,
-            n: 1,
-            size: imageSize,
-            response_format: 'b64_json',
-        });
+        const body = JSON.stringify(referenceImage
+            ? {
+                model: imageModel,
+                prompt: chosenPrompt,
+                image: referenceImage,
+                size: imageSize,
+                n: 1,
+            }
+            : {
+                model: imageModel,
+                prompt: chosenPrompt,
+                n: 1,
+                size: imageSize,
+                response_format: 'b64_json',
+            });
         const headers = {
             'Content-Type': 'application/json',
             'User-Agent': `franklin/${VERSION}`,
@@ -125,7 +228,7 @@ function buildExecute(deps) {
             if (response.status === 402) {
                 const paymentHeaders = await signPayment(response, chain, endpoint);
                 if (!paymentHeaders) {
-                    return { output: 'Payment failed. Check wallet balance with: runcode balance', isError: true };
+                    return { output: 'Payment failed. Check wallet balance with: franklin balance', isError: true };
                 }
                 response = await fetch(endpoint, {
                     method: 'POST',
@@ -143,12 +246,23 @@ function buildExecute(deps) {
             if (!imageData) {
                 return { output: 'No image data returned from API', isError: true };
             }
-            // Save image
+            // Save image. The /v1/images/image2image endpoint returns Gemini results
+            // as a data URI in `url`, so decode those locally instead of going through
+            // fetch — saves a network round-trip and avoids data:-URI fetch quirks.
             if (imageData.b64_json) {
                 const buffer = Buffer.from(imageData.b64_json, 'base64');
                 fs.mkdirSync(path.dirname(outPath), { recursive: true });
                 fs.writeFileSync(outPath, buffer);
             }
+            else if (imageData.url && imageData.url.startsWith('data:')) {
+                const match = imageData.url.match(/^data:[^;]+;base64,(.+)$/);
+                if (!match) {
+                    return { output: 'Malformed data URI in response', isError: true };
+                }
+                const buffer = Buffer.from(match[1], 'base64');
+                fs.mkdirSync(path.dirname(outPath), { recursive: true });
+                fs.writeFileSync(outPath, buffer);
+            }
             else if (imageData.url) {
                 // Download from URL (with 30s timeout)
                 const dlCtrl = new AbortController();
@@ -165,6 +279,20 @@ function buildExecute(deps) {
             const fileSize = fs.statSync(outPath).size;
             const sizeKB = (fileSize / 1024).toFixed(1);
             const revisedPrompt = imageData.revised_prompt ? `\nRevised prompt: ${imageData.revised_prompt}` : '';
+            // Stats: record this generation so it shows up in `franklin insights`
+            // alongside chat spend. Before this, media generations bypassed
+            // recordUsage entirely (only LLM chat calls were tracked), so the
+            // insights panel under-reported total spend and never surfaced
+            // image-generation models in its "top models" list. Fire-and-forget —
+            // stats write must not fail a user-visible generation.
+            void (async () => {
+                try {
+                    const m = await findModel(imageModel);
+                    const estCost = m ? estimateCostUsd(m, { quantity: 1 }) : 0;
+                    recordUsage(imageModel, 0, 0, estCost, 0);
+                }
+                catch { /* ignore stats errors */ }
+            })();
             let contentSummary = '';
             if (contentId && deps.library) {
                 const rec = recordImageAsset(deps.library, {
@@ -225,7 +353,7 @@ async function signPayment(response, chain, endpoint) {
             const feePayer = details.extra?.feePayer || details.recipient;
             const payload = await createSolanaPaymentPayload(secretBytes, wallet.address, details.recipient, details.amount, feePayer, {
                 resourceUrl: details.resource?.url || endpoint,
-                resourceDescription: details.resource?.description || 'RunCode image generation',
+                resourceDescription: details.resource?.description || 'Franklin image generation',
                 maxTimeoutSeconds: details.maxTimeoutSeconds || 300,
                 extra: details.extra,
             });
@@ -237,7 +365,7 @@ async function signPayment(response, chain, endpoint) {
             const details = extractPaymentDetails(paymentRequired);
             const payload = await createPaymentPayload(wallet.privateKey, wallet.address, details.recipient, details.amount, details.network || 'eip155:8453', {
                 resourceUrl: details.resource?.url || endpoint,
-                resourceDescription: details.resource?.description || 'RunCode image generation',
+                resourceDescription: details.resource?.description || 'Franklin image generation',
                 maxTimeoutSeconds: details.maxTimeoutSeconds || 300,
                 extra: details.extra,
             });
@@ -272,13 +400,16 @@ export function createImageGenCapability(deps = {}) {
     return {
         spec: {
             name: 'ImageGen',
-            description: "Generate an image from a text prompt. Costs USDC from the user's wallet " +
-                "— confirm before generating. Saves to a local file. Default size: " +
-                "1024x1024. Do NOT call repeatedly to iterate on style — ask the user " +
-                "first. Pass contentId to attach the result to an existing Content " +
-                "piece: the content's budget is checked BEFORE paying, and on success " +
-                "the image is recorded as an asset with its estimated cost. Skipping " +
-                "contentId generates a one-off image with no budget tracking.",
+            description: "Generate an image from a text prompt — optionally with a reference " +
+                "image for style transfer / character consistency / edits. Costs USDC " +
+                "from the user's wallet — confirm before generating. Saves to a local " +
+                "file. Default size: 1024x1024. Do NOT call repeatedly to iterate on " +
+                "style — ask the user first. Pass contentId to attach the result to " +
+                "an existing Content piece: the content's budget is checked BEFORE " +
+                "paying, and on success the image is recorded as an asset with its " +
+                "estimated cost. Skipping contentId generates a one-off image with no " +
+                "budget tracking. When image_url is set, only edit-capable models " +
+                "(openai/gpt-image-1, openai/gpt-image-2) are accepted.",
             input_schema: {
                 type: 'object',
                 properties: {
@@ -286,6 +417,7 @@ export function createImageGenCapability(deps = {}) {
                     output_path: { type: 'string', description: 'Where to save the image. Default: generated-<timestamp>.png in working directory' },
                     size: { type: 'string', description: 'Image size: 1024x1024, 1792x1024, or 1024x1792. Default: 1024x1024' },
                     model: { type: 'string', description: 'Image model to use. Default: openai/gpt-image-1' },
+                    image_url: { type: 'string', description: 'Optional reference image (image-to-image / style transfer). Accepts an http(s) URL, a data URI, or a local file path. Only works with edit-capable models.' },
                     contentId: { type: 'string', description: 'Optional Content id to attach this generation to. Pre-flight budget check + auto-record on success.' },
                 },
                 required: ['prompt'],

package/dist/tools/read.js

@@ -84,7 +84,34 @@ async function execute(input, ctx) {
         // (some binaries have no extension: `.env.enc`, `.data`, compiled tools
         // without suffixes, etc. Content sniff catches those.)
         const ext = path.extname(resolved).toLowerCase();
-        const binaryExts = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.ico', '.bmp', '.pdf', '.zip', '.tar', '.gz', '.woff', '.woff2', '.ttf', '.eot', '.mp3', '.mp4', '.wav', '.avi', '.mov', '.exe', '.dll', '.so', '.dylib']);
+        // Image extensions → load as vision content so models with vision (Sonnet,
+        // GPT-4o, Gemini) actually see the bytes instead of a "Binary file" stub.
+        // The agent loop wraps `images` into tool_result.content for provider APIs.
+        const IMAGE_MEDIA_TYPES = {
+            '.png': 'image/png',
+            '.jpg': 'image/jpeg',
+            '.jpeg': 'image/jpeg',
+            '.gif': 'image/gif',
+            '.webp': 'image/webp',
+        };
+        if (IMAGE_MEDIA_TYPES[ext]) {
+            const sizeStr = stat.size >= 1024 ? `${(stat.size / 1024).toFixed(1)}KB` : `${stat.size}B`;
+            // Anthropic accepts up to 5MB base64; cap raw bytes at ~3.75MB to be safe.
+            const IMAGE_MAX_BYTES = 3_750_000;
+            if (stat.size > IMAGE_MAX_BYTES) {
+                return {
+                    output: `Image file: ${resolved} (${ext}, ${sizeStr}). Too large to inline for vision (>${Math.round(IMAGE_MAX_BYTES / 1_000_000)}MB). Resize or crop first.`,
+                };
+            }
+            const bytes = fs.readFileSync(resolved);
+            const base64 = bytes.toString('base64');
+            fileReadTracker.set(resolved, { mtimeMs: stat.mtimeMs, readAt: Date.now() });
+            return {
+                output: `Image file: ${resolved} (${ext}, ${sizeStr}). Rendered below for vision-capable models.`,
+                images: [{ mediaType: IMAGE_MEDIA_TYPES[ext], base64 }],
+            };
+        }
+        const binaryExts = new Set(['.ico', '.bmp', '.pdf', '.zip', '.tar', '.gz', '.woff', '.woff2', '.ttf', '.eot', '.mp3', '.mp4', '.wav', '.avi', '.mov', '.exe', '.dll', '.so', '.dylib']);
         if (binaryExts.has(ext)) {
             const sizeStr = stat.size >= 1024 ? `${(stat.size / 1024).toFixed(1)}KB` : `${stat.size}B`;
             return { output: `Binary file: ${resolved} (${ext}, ${sizeStr}). Cannot display contents.` };
@@ -163,7 +190,7 @@ Usage:
 - This tool can only read files, not directories. To list a directory, use Glob or ls via Bash.
 - If you read a file that exists but has empty contents you will receive a warning.
 - Reads over 2MB are rejected — use offset/limit to read portions.
-- Cannot read binary files (images, PDFs, archives).
+- Image files (.png, .jpg, .jpeg, .gif, .webp) are loaded as vision content — vision-capable models see the actual image. Other binary files (PDFs, archives, fonts) cannot be displayed.
 - You will regularly be asked to read screenshots or images. If the user provides a path, ALWAYS use this tool to view it.
 
 IMPORTANT: Always use Read instead of cat, head, or tail via Bash. This tool provides line numbers and integrates with Edit's read-before-edit enforcement.`,

package/dist/tools/videogen.d.ts

@@ -3,9 +3,20 @@
  * /v1/videos/generations endpoint. Uses x402 payment (Base or Solana).
  *
  * Default model `xai/grok-imagine-video` returns an 8-second clip for ~$0.42.
- * The endpoint is synchronous-over-polling: the HTTP connection stays open
- * until the upstream xAI job finishes (typically 20–60s, timeout 180s), so
- * the caller only needs to issue a single POST.
+ * Seedance 2.0 (bytedance/seedance-2.0 and -fast) runs longer — up to a few
+ * minutes for a 10s clip.
+ *
+ * Flow (async since blockrun@654cd35):
+ *   1. POST /v1/videos/generations with signed x-payment header. The server
+ *      verifies payment (does NOT settle), submits the upstream job, and
+ *      returns 202 { id, poll_url, status: "queued" }.
+ *   2. GET the poll_url with the SAME x-payment header every ~5s until
+ *      status=completed. On the first completed poll the server backs up
+ *      the MP4 to GCS, settles payment, and returns the video URL.
+ *   3. Download the MP4 and write it locally.
+ *
+ * If the upstream job fails, the server returns status=failed and no USDC
+ * is ever transferred. If the client never polls, no charge either.
  */
 import type { CapabilityHandler } from '../agent/types.js';
 import type { ContentLibrary } from '../content/library.js';

package/dist/tools/videogen.js

@@ -3,9 +3,20 @@
  * /v1/videos/generations endpoint. Uses x402 payment (Base or Solana).
  *
  * Default model `xai/grok-imagine-video` returns an 8-second clip for ~$0.42.
- * The endpoint is synchronous-over-polling: the HTTP connection stays open
- * until the upstream xAI job finishes (typically 20–60s, timeout 180s), so
- * the caller only needs to issue a single POST.
+ * Seedance 2.0 (bytedance/seedance-2.0 and -fast) runs longer — up to a few
+ * minutes for a 10s clip.
+ *
+ * Flow (async since blockrun@654cd35):
+ *   1. POST /v1/videos/generations with signed x-payment header. The server
+ *      verifies payment (does NOT settle), submits the upstream job, and
+ *      returns 202 { id, poll_url, status: "queued" }.
+ *   2. GET the poll_url with the SAME x-payment header every ~5s until
+ *      status=completed. On the first completed poll the server backs up
+ *      the MP4 to GCS, settles payment, and returns the video URL.
+ *   3. Download the MP4 and write it locally.
+ *
+ * If the upstream job fails, the server returns status=failed and no USDC
+ * is ever transferred. If the client never polls, no charge either.
  */
 import fs from 'node:fs';
 import path from 'node:path';
@@ -13,12 +24,17 @@ import { getOrCreateWallet, getOrCreateSolanaWallet, createPaymentPayload, creat
 import { loadChain, API_URLS, VERSION } from '../config.js';
 import { ModelClient } from '../agent/llm.js';
 import { analyzeMediaRequest, renderProposalForAskUser } from '../agent/media-router.js';
+import { recordUsage } from '../stats/tracker.js';
+import { findModel, estimateCostUsd } from '../gateway-models.js';
 const DEFAULT_MODEL = 'xai/grok-imagine-video';
 const DEFAULT_DURATION = 8;
 const PRICE_PER_SECOND_USD = 0.05;
-// Long ceiling — the endpoint synchronously waits for xAI's async job (up to
-// ~180s). Give ourselves a bit of headroom for the GCS backup + settle step.
-const GEN_TIMEOUT_MS = 210_000;
+// POST submit is fast (~3-20s). Generation is async upstream (60-300s for
+// Seedance, 20-90s for Grok). We poll until completed, then download. The
+// server signs authorizations for 600s — keep the overall budget below that.
+const SUBMIT_TIMEOUT_MS = 30_000;
+const POLL_INTERVAL_MS = 5_000;
+const POLL_MAX_WAIT_MS = 480_000; // 8 min — covers Seedance worst case
 const DOWNLOAD_TIMEOUT_MS = 60_000;
 function estimateVideoCostUsd(durationSeconds = DEFAULT_DURATION) {
     return Math.max(1, durationSeconds) * PRICE_PER_SECOND_USD;
@@ -121,26 +137,32 @@ function buildExecute(deps) {
             'Content-Type': 'application/json',
             'User-Agent': `franklin/${VERSION}`,
         };
-        const controller = new AbortController();
-        const timeout = setTimeout(() => controller.abort(), GEN_TIMEOUT_MS);
-        // Abort on user cancel too
-        const onAbort = () => controller.abort();
-        ctx.abortSignal.addEventListener('abort', onAbort, { once: true });
+        const onAbort = (ctrl) => () => ctrl.abort();
+        // Phase 1: submit the job. First POST triggers a 402; we sign and retry.
+        // The signed paymentHeaders must be reused on every GET poll — the server
+        // uses the authorization to verify identity on each poll and settles on
+        // the first completed response.
+        const submitCtrl = new AbortController();
+        const submitTimeout = setTimeout(() => submitCtrl.abort(), SUBMIT_TIMEOUT_MS);
+        const submitAbort = onAbort(submitCtrl);
+        ctx.abortSignal.addEventListener('abort', submitAbort, { once: true });
+        let paymentHeaders = null;
+        let submitResult;
         try {
             let response = await fetch(endpoint, {
                 method: 'POST',
-                signal: controller.signal,
+                signal: submitCtrl.signal,
                 headers,
                 body,
             });
             if (response.status === 402) {
-                const paymentHeaders = await signPayment(response, chain, endpoint);
+                paymentHeaders = await signPayment(response, chain, endpoint);
                 if (!paymentHeaders) {
                     return { output: 'Payment failed. Check wallet balance with: franklin balance', isError: true };
                 }
                 response = await fetch(endpoint, {
                     method: 'POST',
-                    signal: controller.signal,
+                    signal: submitCtrl.signal,
                     headers: { ...headers, ...paymentHeaders },
                     body,
                 });
@@ -148,22 +170,71 @@ function buildExecute(deps) {
             if (!response.ok) {
                 const errText = await response.text().catch(() => '');
                 return {
-                    output: `Video generation failed (${response.status}): ${errText.slice(0, 300)}`,
+                    output: `Video submit failed (${response.status}): ${errText.slice(0, 300)}`,
                     isError: true,
                 };
             }
-            const result = (await response.json());
-            const videoData = result.data?.[0];
-            if (!videoData?.url) {
-                return { output: 'No video URL returned from API', isError: true };
+            submitResult = await response.json();
+        }
+        catch (err) {
+            const msg = err.message || '';
+            if (msg.includes('abort')) {
+                return {
+                    output: `Video submit timed out or was aborted after ${Math.round(SUBMIT_TIMEOUT_MS / 1000)}s.`,
+                    isError: true,
+                };
             }
+            return { output: `Error submitting video job: ${msg}`, isError: true };
+        }
+        finally {
+            clearTimeout(submitTimeout);
+            ctx.abortSignal.removeEventListener('abort', submitAbort);
+        }
+        if (!submitResult.poll_url || !paymentHeaders) {
+            return { output: 'API did not return a poll_url for the video job', isError: true };
+        }
+        // Phase 2: poll GET /v1/videos/generations/{id} with the SAME signed
+        // x-payment header until the job completes. Server settles on the first
+        // completed poll and returns the backed-up video URL.
+        const origin = new URL(apiUrl).origin;
+        const pollEndpoint = submitResult.poll_url.startsWith('http')
+            ? submitResult.poll_url
+            : `${origin}${submitResult.poll_url}`;
+        const outcome = await pollUntilReady(pollEndpoint, { ...headers, ...paymentHeaders }, ctx.abortSignal);
+        if (outcome.kind === 'timed_out') {
+            return {
+                output: `Video generation did not complete within ${Math.round(POLL_MAX_WAIT_MS / 1000)}s. ` +
+                    `No USDC was charged (settlement only fires on completion).`,
+                isError: true,
+            };
+        }
+        if (outcome.kind === 'failed') {
+            return {
+                output: `Video generation failed upstream: ${outcome.error ?? 'unknown error'}. No USDC was charged.`,
+                isError: true,
+            };
+        }
+        const videoData = outcome.data;
+        const videoUrl = videoData.url;
+        if (!videoUrl) {
+            return { output: 'No video URL returned from API', isError: true };
+        }
+        try {
             // Download the MP4
             const dlCtrl = new AbortController();
             const dlTimeout = setTimeout(() => dlCtrl.abort(), DOWNLOAD_TIMEOUT_MS);
-            const vidResp = await fetch(videoData.url, { signal: dlCtrl.signal });
-            clearTimeout(dlTimeout);
+            const dlAbort = onAbort(dlCtrl);
+            ctx.abortSignal.addEventListener('abort', dlAbort, { once: true });
+            let vidResp;
+            try {
+                vidResp = await fetch(videoUrl, { signal: dlCtrl.signal });
+            }
+            finally {
+                clearTimeout(dlTimeout);
+                ctx.abortSignal.removeEventListener('abort', dlAbort);
+            }
             if (!vidResp.ok) {
-                return { output: `Video fetched URL but download failed (${vidResp.status}): ${videoData.url}`, isError: true };
+                return { output: `Video fetched URL but download failed (${vidResp.status}): ${videoUrl}`, isError: true };
             }
             const buffer = Buffer.from(await vidResp.arrayBuffer());
             fs.mkdirSync(path.dirname(outPath), { recursive: true });
@@ -171,6 +242,21 @@ function buildExecute(deps) {
             const fileSize = fs.statSync(outPath).size;
             const sizeMB = (fileSize / 1_048_576).toFixed(1);
             const dur = videoData.duration_seconds ?? duration;
+            // Stats: record this generation so it shows up in `franklin insights`
+            // alongside chat spend. Before this, media generations bypassed
+            // recordUsage entirely, so the insights panel under-reported total
+            // spend and never surfaced video models in its "top models" list.
+            // Prefer the live gateway price when the model is in the catalog;
+            // fall back to the legacy $0.05/s estimate otherwise. Fire-and-
+            // forget — stats write must not fail a user-visible generation.
+            void (async () => {
+                try {
+                    const m = await findModel(videoModel);
+                    const estCost = m ? estimateCostUsd(m, { duration_seconds: dur }) : estimateVideoCostUsd(dur);
+                    recordUsage(videoModel, 0, 0, estCost, 0);
+                }
+                catch { /* ignore stats errors */ }
+            })();
             let contentSummary = '';
             if (contentId && deps.library) {
                 const rec = deps.library.addAsset(contentId, {
@@ -208,18 +294,63 @@ function buildExecute(deps) {
             const msg = err.message || '';
             if (msg.includes('abort')) {
                 return {
-                    output: `Video generation timed out or was aborted (limit ${Math.round(GEN_TIMEOUT_MS / 1000)}s).`,
+                    output: `Video download timed out or was aborted after ${Math.round(DOWNLOAD_TIMEOUT_MS / 1000)}s.`,
                     isError: true,
                 };
             }
             return { output: `Error: ${msg}`, isError: true };
         }
-        finally {
-            clearTimeout(timeout);
-            ctx.abortSignal.removeEventListener('abort', onAbort);
-        }
     };
 }
+/**
+ * Poll the GET /v1/videos/generations/{id} endpoint until the job reaches a
+ * terminal state. Reuses the caller's signed x-payment header verbatim on
+ * every request — the server verifies the same authorization each poll and
+ * settles on the first completed response.
+ */
+async function pollUntilReady(pollEndpoint, headers, userAbort) {
+    const deadline = Date.now() + POLL_MAX_WAIT_MS;
+    while (Date.now() < deadline) {
+        if (userAbort.aborted)
+            throw new Error('aborted');
+        const resp = await fetch(pollEndpoint, { method: 'GET', headers, signal: userAbort });
+        // 202 = still queued/in_progress; 200 = completed or failed.
+        if (resp.status === 202 || resp.status === 200) {
+            const body = (await resp.json().catch(() => ({})));
+            if (body.status === 'completed' && body.data?.[0]?.url) {
+                return { kind: 'completed', data: body.data[0] };
+            }
+            if (body.status === 'failed') {
+                return { kind: 'failed', error: body.error };
+            }
+            // queued / in_progress — sleep and try again.
+        }
+        else if (resp.status === 429 || resp.status >= 500) {
+            // Transient — back off briefly. Fall through to the sleep below.
+        }
+        else {
+            const text = await resp.text().catch(() => '');
+            throw new Error(`Poll failed (${resp.status}): ${text.slice(0, 300)}`);
+        }
+        await sleep(POLL_INTERVAL_MS, userAbort);
+    }
+    return { kind: 'timed_out' };
+}
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal.aborted)
+            return reject(new Error('aborted'));
+        const t = setTimeout(() => {
+            signal.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(t);
+            reject(new Error('aborted'));
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+}
 // ─── Payment ───────────────────────────────────────────────────────────────
 async function signPayment(response, chain, endpoint) {
     try {
@@ -235,7 +366,9 @@ async function signPayment(response, chain, endpoint) {
             const payload = await createSolanaPaymentPayload(secretBytes, wallet.address, details.recipient, details.amount, feePayer, {
                 resourceUrl: details.resource?.url || endpoint,
                 resourceDescription: details.resource?.description || 'Franklin video generation',
-                maxTimeoutSeconds: details.maxTimeoutSeconds || 300,
+                // Video poll can take up to 8 min; honor the server's advertised
+                // value (blockrun sends 600s) and fall back to 600 not 300.
+                maxTimeoutSeconds: details.maxTimeoutSeconds || 600,
                 extra: details.extra,
             });
             return { 'PAYMENT-SIGNATURE': payload };

package/dist/tools/webhook.js

@@ -15,6 +15,7 @@
  * session.
  */
 import { isIP } from 'node:net';
+import { VERSION } from '../config.js';
 const DEFAULT_TIMEOUT_MS = 15_000;
 const MAX_BODY_BYTES = 512 * 1024; // 512 KB is generous for a chat push.
 function isPrivateHost(hostname) {
@@ -101,7 +102,7 @@ async function execute(input, ctx) {
     }
     const finalHeaders = {
         'Content-Type': contentType,
-        'User-Agent': 'franklin/3.8.9 (webhook)',
+        'User-Agent': `franklin/${VERSION} (webhook)`,
         ...(headers ?? {}),
     };
     const ctrl = new AbortController();

package/dist/trading/providers/coingecko/client.js

@@ -6,8 +6,9 @@
  * cooldown, user-agent, timeout, and in-memory cache.
  */
 import { recordFetch } from '../telemetry.js';
+import { VERSION } from '../../../config.js';
 const BASE = 'https://api.coingecko.com/api/v3';
-const UA = 'franklin/3.8.9 (trading)';
+const UA = `franklin/${VERSION} (trading)`;
 const TIMEOUT_MS = 10_000;
 // Ticker → CoinGecko slug. Not exhaustive; unknown tickers fall through to
 // lowercase and let CoinGecko either accept the slug or 404.