@blockrun/franklin 3.8.34 → 3.8.36

package/dist/plugin-sdk/index.d.ts

@@ -1,7 +1,7 @@
 /**
- * RunCode Plugin SDK — public surface for plugins.
+ * Franklin Plugin SDK — public surface for plugins.
  *
- * Plugins import ONLY from '@blockrun/runcode/plugin-sdk' (or this barrel).
+ * Plugins import ONLY from '@blockrun/franklin/plugin-sdk' (or this barrel).
  * They MUST NOT import from src/** of core or other plugins.
  *
  * Core stays plugin-agnostic: adding a plugin should never require editing core.

package/dist/plugin-sdk/index.js

@@ -1,7 +1,7 @@
 /**
- * RunCode Plugin SDK — public surface for plugins.
+ * Franklin Plugin SDK — public surface for plugins.
  *
- * Plugins import ONLY from '@blockrun/runcode/plugin-sdk' (or this barrel).
+ * Plugins import ONLY from '@blockrun/franklin/plugin-sdk' (or this barrel).
  * They MUST NOT import from src/** of core or other plugins.
  *
  * Core stays plugin-agnostic: adding a plugin should never require editing core.

package/dist/plugin-sdk/plugin.d.ts

@@ -26,8 +26,8 @@ export interface PluginManifest {
     homepage?: string;
     /** License */
     license?: string;
-    /** Required runcode version (semver range) */
-    runcodeVersion?: string;
+    /** Required Franklin version (semver range) */
+    franklinVersion?: string;
 }
 export interface PluginProvides {
     /** This plugin contributes one or more workflows (e.g. "social", "trading") */
@@ -54,8 +54,8 @@ export interface Plugin {
 }
 /** Context passed to plugin lifecycle hooks */
 export interface PluginContext {
-    /** RunCode version */
-    runcodeVersion: string;
+    /** Franklin version */
+    franklinVersion: string;
     /** Plugin's own data directory (~/.blockrun/plugins/<id>/) */
     dataDir: string;
     /** Path to plugin's installation directory */

package/dist/plugins/registry.d.ts

@@ -3,9 +3,9 @@
  *
  * Core stays plugin-agnostic: it knows about the *interface*, not specific plugins.
  * Plugins are discovered from:
- *   1. Bundled: <runcode>/plugins-bundled/* (ships with runcode)
- *   2. User: ~/.blockrun/plugins/* (installed via `runcode plugin install`)
- *   3. Local dev: $RUNCODE_PLUGINS_DIR/* (env var for development)
+ *   1. Bundled: <franklin>/plugins-bundled/* (ships with Franklin)
+ *   2. User: ~/.blockrun/plugins/*
+ *   3. Local dev: $FRANKLIN_PLUGINS_DIR/* (or legacy $RUNCODE_PLUGINS_DIR/*)
  */
 import type { Plugin, PluginManifest } from '../plugin-sdk/plugin.js';
 export declare function getBundledPluginsDir(): string;

package/dist/plugins/registry.js

@@ -3,9 +3,9 @@
  *
  * Core stays plugin-agnostic: it knows about the *interface*, not specific plugins.
  * Plugins are discovered from:
- *   1. Bundled: <runcode>/plugins-bundled/* (ships with runcode)
- *   2. User: ~/.blockrun/plugins/* (installed via `runcode plugin install`)
- *   3. Local dev: $RUNCODE_PLUGINS_DIR/* (env var for development)
+ *   1. Bundled: <franklin>/plugins-bundled/* (ships with Franklin)
+ *   2. User: ~/.blockrun/plugins/*
+ *   3. Local dev: $FRANKLIN_PLUGINS_DIR/* (or legacy $RUNCODE_PLUGINS_DIR/*)
  */
 import fs from 'node:fs';
 import path from 'node:path';
@@ -22,7 +22,7 @@ export function getUserPluginsDir() {
     return path.join(os.homedir(), '.blockrun', 'plugins');
 }
 function getDevPluginsDir() {
-    return process.env.RUNCODE_PLUGINS_DIR || null;
+    return process.env.FRANKLIN_PLUGINS_DIR || process.env.RUNCODE_PLUGINS_DIR || null;
 }
 const loaded = new Map();
 // ─── Discovery ────────────────────────────────────────────────────────────
@@ -119,7 +119,7 @@ export async function loadAllPlugins() {
             if (plugin.onLoad) {
                 try {
                     await plugin.onLoad({
-                        runcodeVersion: getRuncodeVersion(),
+                        franklinVersion: getFranklinVersion(),
                         dataDir: path.join(os.homedir(), '.blockrun', 'plugins', manifest.id),
                         pluginDir: dir,
                         log: (msg) => process.stderr.write(`[${manifest.id}] ${msg}\n`),
@@ -149,7 +149,7 @@ export function listChannelPlugins() {
     return listPlugins().filter(p => p.plugin.channels && Object.keys(p.plugin.channels).length > 0);
 }
 // ─── Helpers ──────────────────────────────────────────────────────────────
-function getRuncodeVersion() {
+function getFranklinVersion() {
     try {
         const pkgPath = path.resolve(__dirname, '..', '..', 'package.json');
         return JSON.parse(fs.readFileSync(pkgPath, 'utf-8')).version || '0.0.0';

package/dist/pricing.js

@@ -46,6 +46,7 @@ export const MODEL_PRICING = {
     'openai/o3-mini': { input: 1.1, output: 4.4 },
     'openai/o4-mini': { input: 1.1, output: 4.4 },
     'openai/o1': { input: 15.0, output: 60.0 },
+    'openai/gpt-5.5': { input: 5.0, output: 30.0 },
     'openai/gpt-5.2-pro': { input: 21.0, output: 168.0 },
     'openai/gpt-5.4-pro': { input: 30.0, output: 180.0 },
     // Google

package/dist/proxy/server.js

@@ -67,9 +67,11 @@ const MODEL_SHORTCUTS = {
     'opus-4.6': 'anthropic/claude-opus-4.6',
     haiku: 'anthropic/claude-haiku-4.5',
     // OpenAI
-    gpt: 'openai/gpt-5.4',
-    gpt5: 'openai/gpt-5.4',
-    'gpt-5': 'openai/gpt-5.4',
+    // `gpt` / `gpt5` / `gpt-5` follow the gateway's flagship — currently 5.5.
+    gpt: 'openai/gpt-5.5',
+    gpt5: 'openai/gpt-5.5',
+    'gpt-5': 'openai/gpt-5.5',
+    'gpt-5.5': 'openai/gpt-5.5',
     'gpt-5.4': 'openai/gpt-5.4',
     'gpt-5.4-pro': 'openai/gpt-5.4-pro',
     'gpt-5.3': 'openai/gpt-5.3',

package/dist/router/index.js

@@ -44,11 +44,11 @@ const AUTO_TIERS = {
     },
     MEDIUM: {
         primary: 'anthropic/claude-sonnet-4.6',
-        fallback: ['openai/gpt-5.4', 'google/gemini-3.1-pro', 'moonshot/kimi-k2.6'],
+        fallback: ['openai/gpt-5.5', 'google/gemini-3.1-pro', 'moonshot/kimi-k2.6'],
     },
     COMPLEX: {
         primary: 'anthropic/claude-sonnet-4.6',
-        fallback: ['openai/gpt-5.4', 'anthropic/claude-opus-4.7', 'moonshot/kimi-k2.6'],
+        fallback: ['openai/gpt-5.5', 'anthropic/claude-opus-4.7', 'moonshot/kimi-k2.6'],
     },
     REASONING: {
         // Opus 4.7: step-change improvement in agentic coding over 4.6 per
@@ -93,7 +93,7 @@ const PREMIUM_TIERS = {
     },
     COMPLEX: {
         primary: 'anthropic/claude-opus-4.7',
-        fallback: ['anthropic/claude-opus-4.6', 'openai/gpt-5.4', 'anthropic/claude-sonnet-4.6'],
+        fallback: ['anthropic/claude-opus-4.6', 'openai/gpt-5.5', 'anthropic/claude-sonnet-4.6'],
     },
     REASONING: {
         primary: 'anthropic/claude-opus-4.7',

package/dist/session/storage.js

@@ -13,7 +13,7 @@ function getSessionsDir() {
     if (resolvedSessionsDir)
         return resolvedSessionsDir;
     const preferred = path.join(BLOCKRUN_DIR, 'sessions');
-    const fallback = path.join(os.tmpdir(), 'runcode', 'sessions');
+    const fallback = path.join(os.tmpdir(), 'franklin', 'sessions');
     for (const dir of [preferred, fallback]) {
         try {
             fs.mkdirSync(dir, { recursive: true });
@@ -41,7 +41,7 @@ function metaPath(id) {
 }
 function withWritableSessionDir(action) {
     const preferred = path.join(BLOCKRUN_DIR, 'sessions');
-    const fallback = path.join(os.tmpdir(), 'runcode', 'sessions');
+    const fallback = path.join(os.tmpdir(), 'franklin', 'sessions');
     try {
         action();
     }

package/dist/tools/imagegen.d.ts

@@ -4,6 +4,20 @@
  */
 import type { CapabilityHandler } from '../agent/types.js';
 import type { ContentLibrary } from '../content/library.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 declare const EDIT_SUPPORTED_MODELS: Set<string>;
+export declare const REFERENCE_IMAGE_MAX_BYTES = 4000000;
+/**
+ * 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 declare function resolveReferenceImage(input: string, workingDir: string): Promise<string>;
 export interface ImageGenDeps {
     /** Optional Content library for auto-recording generations into a piece. */
     library?: ContentLibrary;

package/dist/tools/imagegen.js

@@ -9,21 +9,124 @@ 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 { prompt, output_path, size, model, contentId } = input;
-        if (!prompt) {
+        const rawInput = input;
+        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.
+        let prompt = rawInput.prompt;
+        let skipRefine = false;
+        if (prompt.trimStart().startsWith('///')) {
+            prompt = prompt.replace(/^\s*\/\/\/\s?/, '');
+            skipRefine = true;
+        }
         // ── Media router + AskUser flow ────────────────────────────────────
         // If the caller explicitly named a model, or the env auto-approves, or
         // no AskUser bridge exists (batch / --prompt mode), skip the proposal
         // step and use the old default. Otherwise: classifier picks a fitting
-        // model, cost preview goes to AskUser, user chooses or cancels.
-        let imageModel = model || 'openai/gpt-image-1';
+        // model + rewrites the prompt, the preview goes to AskUser, user
+        // chooses or cancels.
+        // 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 });
@@ -33,6 +136,7 @@ function buildExecute(deps) {
                     quantity: 1,
                     client,
                     signal: ctx.abortSignal,
+                    skipRefine,
                 });
                 if (proposal) {
                     const { question, options } = renderProposalForAskUser(proposal, prompt);
@@ -51,9 +155,15 @@ function buildExecute(deps) {
                             return {
                                 output: `## Image generation cancelled\n\nNo USDC was spent. Ask again when ready, or pass an explicit \`model\` to skip the confirmation step.`,
                             };
+                        case 'use-raw':
+                            imageModel = proposal.recommended.model;
+                            // chosenPrompt stays as the raw input
+                            break;
                         case 'recommended':
                         default:
                             imageModel = proposal.recommended.model;
+                            if (proposal.refinedPrompt)
+                                chosenPrompt = proposal.refinedPrompt;
                     }
                 }
             }
@@ -76,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,
-            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}`,
@@ -106,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',
@@ -124,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();
@@ -146,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, {
@@ -206,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,
             });
@@ -218,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,
             });
@@ -253,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: {
@@ -267,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';