@blockrun/franklin 3.8.35 → 3.8.37

package/dist/proxy/server.js

@@ -5,7 +5,7 @@ import os from 'node:os';
 import { getOrCreateWallet, getOrCreateSolanaWallet, createPaymentPayload, createSolanaPaymentPayload, parsePaymentRequired, extractPaymentDetails, solanaKeyToBytes, SOLANA_NETWORK, } from '@blockrun/llm';
 import { recordUsage } from '../stats/tracker.js';
 import { appendAudit } from '../stats/audit.js';
-import { fetchWithFallback, buildFallbackChain, DEFAULT_FALLBACK_CONFIG, ROUTING_PROFILES, } from './fallback.js';
+import { buildFallbackChain, DEFAULT_FALLBACK_CONFIG, ROUTING_PROFILES, } from './fallback.js';
 import { routeRequest, parseRoutingProfile, } from '../router/index.js';
 import { estimateCost } from '../pricing.js';
 import { VERSION } from '../config.js';
@@ -41,6 +41,57 @@ function log(...args) {
     catch { /* ignore */ }
 }
 const DEFAULT_MAX_TOKENS = 4096;
+const DEFAULT_PROXY_REQUEST_TIMEOUT_MS = 45_000;
+const DEFAULT_PROXY_STREAM_TIMEOUT_MS = 5 * 60 * 1000;
+function parseTimeoutEnv(name, fallback) {
+    const raw = process.env[name];
+    if (!raw)
+        return fallback;
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) && parsed >= 0 ? parsed : fallback;
+}
+function getProxyRequestTimeoutMs() {
+    return parseTimeoutEnv('FRANKLIN_PROXY_REQUEST_TIMEOUT_MS', DEFAULT_PROXY_REQUEST_TIMEOUT_MS);
+}
+function getProxyStreamTimeoutMs() {
+    return parseTimeoutEnv('FRANKLIN_PROXY_STREAM_TIMEOUT_MS', DEFAULT_PROXY_STREAM_TIMEOUT_MS);
+}
+function createProxyTimeoutError(label, timeoutMs) {
+    return new Error(`${label} timed out after ${timeoutMs}ms`);
+}
+async function fetchWithTimeout(url, init, timeoutMs, label) {
+    if (timeoutMs <= 0)
+        return fetch(url, init);
+    const controller = new AbortController();
+    const timeoutError = createProxyTimeoutError(label, timeoutMs);
+    const timeout = setTimeout(() => {
+        try {
+            controller.abort(timeoutError);
+        }
+        catch { /* ignore */ }
+    }, timeoutMs);
+    try {
+        return await fetch(url, { ...init, signal: controller.signal });
+    }
+    catch (err) {
+        if (controller.signal.aborted)
+            throw timeoutError;
+        throw err;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+function replaceModelInBody(body, model) {
+    try {
+        const parsed = JSON.parse(body);
+        parsed.model = model;
+        return JSON.stringify(parsed);
+    }
+    catch {
+        return body;
+    }
+}
 // Per-model last output tokens for adaptive max_tokens (avoids cross-request pollution)
 const MAX_TRACKED_MODELS = 50;
 const lastOutputByModel = new Map();
@@ -67,9 +118,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',
@@ -367,13 +420,21 @@ export function createProxy(options) {
                 };
                 let response;
                 let finalModel = requestModel;
+                const requestTimeoutMs = getProxyRequestTimeoutMs();
                 // Use fallback chain if enabled
                 if (fallbackEnabled && body && requestPath.includes('messages')) {
                     const fallbackConfig = {
                         ...DEFAULT_FALLBACK_CONFIG,
                         chain: buildFallbackChain(requestModel),
                     };
-                    const result = await fetchWithFallback(targetUrl, requestInit, body, fallbackConfig, (failedModel, status, nextModel) => {
+                    const result = await fetchWithPaymentFallback(targetUrl, requestInit, body, fallbackConfig, {
+                        method: req.method || 'POST',
+                        headers,
+                        chain,
+                        baseWallet,
+                        solanaWallet,
+                        timeoutMs: requestTimeoutMs,
+                    }, (failedModel, status, nextModel) => {
                         log(`⚠️  ${failedModel} returned ${status}, falling back to ${nextModel}`);
                     });
                     response = result.response;
@@ -386,20 +447,14 @@ export function createProxy(options) {
                     }
                 }
                 else {
-                    // Direct fetch without fallback (with timeout)
-                    const directCtrl = new AbortController();
-                    const directTimeout = setTimeout(() => directCtrl.abort(), 120_000); // 2min
-                    response = await fetch(targetUrl, { ...requestInit, signal: directCtrl.signal });
-                    clearTimeout(directTimeout);
-                }
-                // Handle 402 payment — body now has the correct model after fallback
-                if (response.status === 402) {
-                    if (chain === 'solana' && solanaWallet) {
-                        response = await handleSolanaPayment(response, targetUrl, req.method || 'POST', headers, body, solanaWallet.privateKey, solanaWallet.address);
-                    }
-                    else if (baseWallet) {
-                        response = await handleBasePayment(response, targetUrl, req.method || 'POST', headers, body, baseWallet.privateKey, baseWallet.address);
-                    }
+                    response = await fetchModelAttempt(targetUrl, requestInit, body, requestModel, {
+                        method: req.method || 'POST',
+                        headers,
+                        chain,
+                        baseWallet,
+                        solanaWallet,
+                        timeoutMs: requestTimeoutMs,
+                    });
                 }
                 const responseHeaders = {};
                 response.headers.forEach((v, k) => {
@@ -450,7 +505,7 @@ export function createProxy(options) {
                     const decoder = new TextDecoder();
                     let fullResponse = '';
                     const STREAM_CAP = 5_000_000; // 5MB cap on accumulated stream
-                    const STREAM_TIMEOUT_MS = 5 * 60 * 1000; // 5 min timeout for entire stream
+                    const STREAM_TIMEOUT_MS = getProxyStreamTimeoutMs();
                     const streamDeadline = Date.now() + STREAM_TIMEOUT_MS;
                     const pump = async () => {
                         while (true) {
@@ -561,10 +616,77 @@ export function createProxy(options) {
     });
     return server;
 }
+async function fetchModelAttempt(url, init, body, model, payment) {
+    let response = await fetchWithTimeout(url, { ...init, body: body || undefined }, payment.timeoutMs, `Proxy request for ${model}`);
+    if (response.status !== 402)
+        return response;
+    if (payment.chain === 'solana' && payment.solanaWallet) {
+        return handleSolanaPayment(response, url, payment.method, payment.headers, body, payment.solanaWallet.privateKey, payment.solanaWallet.address, payment.timeoutMs, model);
+    }
+    if (payment.baseWallet) {
+        return handleBasePayment(response, url, payment.method, payment.headers, body, payment.baseWallet.privateKey, payment.baseWallet.address, payment.timeoutMs, model);
+    }
+    return response;
+}
+/**
+ * Try each fallback model as a full x402 attempt:
+ * unpaid 402 probe, payment signing, then the paid provider call. The older
+ * flow only applied fallback to the probe, which meant a slow paid call could
+ * hang Franklin until the outer client gave up.
+ */
+async function fetchWithPaymentFallback(url, init, originalBody, config, payment, onFallback) {
+    const failedModels = [];
+    let attempts = 0;
+    for (let i = 0; i < config.chain.length && attempts < config.maxRetries; i++) {
+        const model = config.chain[i];
+        const body = replaceModelInBody(originalBody, model);
+        try {
+            attempts++;
+            const response = await fetchModelAttempt(url, init, body, model, payment);
+            if (!config.retryOn.includes(response.status)) {
+                return {
+                    response,
+                    modelUsed: model,
+                    bodyUsed: body,
+                    fallbackUsed: i > 0,
+                    attemptsCount: attempts,
+                    failedModels,
+                };
+            }
+            try {
+                await response.body?.cancel();
+            }
+            catch { /* ignore */ }
+            failedModels.push(model);
+            const nextModel = config.chain[i + 1];
+            if (nextModel && onFallback) {
+                onFallback(model, response.status, nextModel);
+            }
+            if (i < config.chain.length - 1) {
+                await sleep(config.retryDelayMs);
+            }
+        }
+        catch (err) {
+            failedModels.push(model);
+            const nextModel = config.chain[i + 1];
+            if (nextModel && onFallback) {
+                onFallback(model, 0, nextModel);
+            }
+            log(`[fallback] ${model} request error: ${err instanceof Error ? err.message : String(err)}`);
+            if (i < config.chain.length - 1) {
+                await sleep(config.retryDelayMs);
+            }
+        }
+    }
+    throw new Error(`All models in fallback chain failed: ${failedModels.join(', ')}`);
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
 // ======================================================================
 // Base (EIP-712) payment handler
 // ======================================================================
-async function handleBasePayment(response, url, method, headers, body, privateKey, fromAddress) {
+async function handleBasePayment(response, url, method, headers, body, privateKey, fromAddress, timeoutMs = getProxyRequestTimeoutMs(), model = 'unknown') {
     const paymentHeader = await extractPaymentHeader(response);
     if (!paymentHeader) {
         throw new Error('402 Payment Required — wallet may need funding. Run: franklin balance');
@@ -577,19 +699,19 @@ async function handleBasePayment(response, url, method, headers, body, privateKe
         maxTimeoutSeconds: details.maxTimeoutSeconds || 300,
         extra: details.extra,
     });
-    return fetch(url, {
+    return fetchWithTimeout(url, {
         method,
         headers: {
             ...headers,
             'PAYMENT-SIGNATURE': paymentPayload,
         },
         body: body || undefined,
-    });
+    }, timeoutMs, `Paid proxy request for ${model}`);
 }
 // ======================================================================
 // Solana payment handler
 // ======================================================================
-async function handleSolanaPayment(response, url, method, headers, body, privateKey, fromAddress) {
+async function handleSolanaPayment(response, url, method, headers, body, privateKey, fromAddress, timeoutMs = getProxyRequestTimeoutMs(), model = 'unknown') {
     const paymentHeader = await extractPaymentHeader(response);
     if (!paymentHeader) {
         throw new Error('402 Payment Required — wallet may need funding. Run: franklin balance');
@@ -604,14 +726,14 @@ async function handleSolanaPayment(response, url, method, headers, body, private
         maxTimeoutSeconds: details.maxTimeoutSeconds || 300,
         extra: details.extra,
     });
-    return fetch(url, {
+    return fetchWithTimeout(url, {
         method,
         headers: {
             ...headers,
             'PAYMENT-SIGNATURE': paymentPayload,
         },
         body: body || undefined,
-    });
+    }, timeoutMs, `Paid proxy request for ${model}`);
 }
 export function classifyRequest(body) {
     try {

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,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.`,