@blockrun/franklin 3.8.29 → 3.8.31

package/README.md

@@ -428,7 +428,7 @@ src/
 Start with **zero dollars**. Franklin defaults to free NVIDIA models that need no wallet funding.
 
 ```bash
-franklin --model nvidia/nemotron-ultra-253b
+franklin --model nvidia/qwen3-next-80b-a3b-thinking
 ```
 
 When you fund the wallet, Franklin gets more purchasing power: Sonnet, Opus, GPT, Gemini, Grok, and paid tools like Exa, DALL-E, and CoinGecko Pro.

package/dist/agent/context.js

@@ -187,7 +187,9 @@ Your training data is frozen in the past. Live-world questions MUST be answered
 - "Please check Yahoo Finance / Google Finance / Bloomberg / your broker / etc."
 - Any variant of "go look it up yourself" when TradingMarket / ExaAnswer / WebSearch would resolve it.
 
-If you find yourself about to emit one of these, stop and call the tool instead. If you don't know which ticker the user means, call ExaSearch or AskUser — never deflect.`;
+If you find yourself about to emit one of these, stop and call the tool instead. If you don't know which ticker the user means, call ExaSearch or AskUser — never deflect.
+
+**Media generation (ImageGen / VideoGen).** Pass just the user's descriptive prompt and the output path — do NOT pass \`model\`. The harness picks the right model for the requested style + budget and surfaces a cost proposal through AskUser before spending. Only pass \`model\` explicitly if the user named one specifically.`;
 }
 function getTokenEfficiencySection() {
     return `# Token Efficiency

package/dist/agent/media-router.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Media router — one LLM call that picks which image/video model fits
+ * the user's request, with alternatives and cost estimates, so the agent
+ * can show a clean AskUser proposal before spending.
+ *
+ * Principle (matches turn-analyzer): harness orchestrates, free model
+ * decides. No keyword-to-model mapping in TypeScript. Classifier reads
+ * the prompt + the current gateway catalog (pulled dynamically), picks
+ * one recommended model plus a cheaper + a premium alternative, and
+ * explains the choice in one sentence.
+ *
+ * Cost estimates come from `gateway-models.ts` — always dynamic,
+ * margin-adjusted.
+ */
+import type { ModelClient } from './llm.js';
+export type MediaKind = 'image' | 'video';
+export type MediaStyle = 'photoreal' | 'illustration' | 'anime' | 'logo' | 'concept' | 'other';
+export type MediaPriority = 'cost' | 'quality' | 'balanced';
+export interface MediaChoice {
+    model: string;
+    estimatedCostUsd: number;
+    rationale: string;
+}
+export interface MediaProposal {
+    kind: MediaKind;
+    quantity: number;
+    durationSeconds?: number;
+    maxDurationSeconds?: number;
+    recommended: MediaChoice;
+    cheaper?: MediaChoice;
+    premium?: MediaChoice;
+    intent: {
+        style: MediaStyle;
+        priority: MediaPriority;
+    };
+    totalCostUsd: number;
+}
+export declare function clearMediaRouterCache(): void;
+export interface AnalyzeMediaOpts {
+    kind: MediaKind;
+    prompt: string;
+    client: ModelClient;
+    quantity?: number;
+    durationSeconds?: number;
+    signal?: AbortSignal;
+}
+/**
+ * Pick the best model + alternatives for this media request. Returns null
+ * on any failure path (classifier timeout, parse error, empty catalog) so
+ * the caller can fall back to its old hardcoded default rather than
+ * blocking the user.
+ */
+export declare function analyzeMediaRequest(opts: AnalyzeMediaOpts): Promise<MediaProposal | null>;
+/**
+ * Render a proposal as the user-facing AskUser question. Layout matches
+ * the spec from v3.8.31 planning: recommended first with • bullet,
+ * alternatives below with ○ bullets, prices include the 5% margin note.
+ */
+export declare function renderProposalForAskUser(p: MediaProposal, userPrompt: string): {
+    question: string;
+    options: Array<{
+        id: string;
+        label: string;
+    }>;
+};

package/dist/agent/media-router.js

@@ -0,0 +1,250 @@
+/**
+ * Media router — one LLM call that picks which image/video model fits
+ * the user's request, with alternatives and cost estimates, so the agent
+ * can show a clean AskUser proposal before spending.
+ *
+ * Principle (matches turn-analyzer): harness orchestrates, free model
+ * decides. No keyword-to-model mapping in TypeScript. Classifier reads
+ * the prompt + the current gateway catalog (pulled dynamically), picks
+ * one recommended model plus a cheaper + a premium alternative, and
+ * explains the choice in one sentence.
+ *
+ * Cost estimates come from `gateway-models.ts` — always dynamic,
+ * margin-adjusted.
+ */
+import { getModelsByCategory, estimateCostUsd, defaultDurationSeconds, maxDurationSeconds, } from '../gateway-models.js';
+// ─── Classifier ─────────────────────────────────────────────────────────
+const CLASSIFIER_MODEL = process.env.FRANKLIN_MEDIA_ROUTER_MODEL || 'nvidia/llama-4-maverick';
+const TIMEOUT_MS = 3_500; // slightly more lenient than the turn-analyzer — we're asking for JSON with reasoning
+const MAX_TOKENS = 256;
+function buildSystemPrompt(kind, catalog) {
+    const catalogLines = catalog.map(m => {
+        const p = m.pricing;
+        const price = kind === 'image'
+            ? `$${(p.per_image ?? 0).toFixed(4)}/image`
+            : `$${(p.per_second ?? 0).toFixed(2)}/s (default ${p.default_duration_seconds ?? 8}s, max ${p.max_duration_seconds ?? 8}s)`;
+        return `  - ${m.id} · ${price} · ${m.description || m.name}`;
+    }).join('\n');
+    return `You pick the best ${kind} model for a user's Franklin request. Output ONE LINE of compact JSON. No markdown, no code fences, no explanation.
+
+## Catalog (${catalog.length} available ${kind} models)
+${catalogLines}
+
+## Output schema
+
+{"style":"photoreal|illustration|anime|logo|concept|other",
+ "priority":"cost|quality|balanced",
+ "recommended":{"model":"<id from catalog>","rationale":"<one sentence, <=140 chars>"},
+ "cheaper":{"model":"<id from catalog | null>","rationale":"<one sentence>"},
+ "premium":{"model":"<id from catalog | null>","rationale":"<one sentence>"}}
+
+Rules:
+- recommended is always set to an id from the catalog.
+- cheaper / premium may be null if no strictly cheaper / better option exists.
+- Never invent a model id. Use EXACTLY one of the catalog ids.
+- Match style → model: anime/illustration prefers CogView, photoreal prefers Nano Banana Pro / Grok Imagine Pro, budget-conscious picks cheapest-acceptable.
+- One sentence rationale, user-visible.
+
+Examples:
+
+Input: "a photo of a cat on Mars, photoreal"
+Output: {"style":"photoreal","priority":"balanced","recommended":{"model":"google/nano-banana-pro","rationale":"Photoreal scenes — Nano Banana Pro has strong realism at moderate cost."},"cheaper":{"model":"google/nano-banana","rationale":"Same family, lower cost, slightly less detail."},"premium":{"model":"openai/gpt-image-2","rationale":"Best photoreal fidelity when budget allows."}}
+
+Input: "赛博朋克风格的动漫角色"
+Output: {"style":"anime","priority":"balanced","recommended":{"model":"zai/cogview-4","rationale":"CogView-4 specializes in stylized/anime imagery."},"cheaper":{"model":"google/nano-banana","rationale":"Cheaper but less stylized."},"premium":{"model":"xai/grok-imagine-image-pro","rationale":"Premium detail for complex scenes."}}
+
+Input: "a 10-second cinematic drone shot over Tokyo at night"
+Output: {"style":"concept","priority":"quality","recommended":{"model":"bytedance/seedance-2.0","rationale":"Seedance 2.0 delivers the best cinematic quality."},"cheaper":{"model":"bytedance/seedance-2.0-fast","rationale":"Faster + cheaper, minor quality trade-off."},"premium":{"model":null,"rationale":"2.0 is already the top tier."}}
+
+Output JSON only, single line.`;
+}
+const cache = new Map();
+const CACHE_TTL_MS = 30_000;
+const CACHE_MAX = 32;
+function hashKey(parts) {
+    const s = parts.join('|');
+    let h = 0;
+    for (let i = 0; i < s.length; i++)
+        h = ((h << 5) - h + s.charCodeAt(i)) | 0;
+    return String(h);
+}
+export function clearMediaRouterCache() { cache.clear(); }
+// ─── Parser ─────────────────────────────────────────────────────────────
+const VALID_STYLES = new Set(['photoreal', 'illustration', 'anime', 'logo', 'concept', 'other']);
+const VALID_PRIORITIES = new Set(['cost', 'quality', 'balanced']);
+function validateChoice(raw, catalog) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const id = typeof raw.model === 'string' ? raw.model : '';
+    const model = catalog.get(id);
+    if (!model)
+        return null;
+    const rationale = typeof raw.rationale === 'string' ? raw.rationale.slice(0, 240) : '';
+    return { model, rationale };
+}
+/**
+ * Pick the best model + alternatives for this media request. Returns null
+ * on any failure path (classifier timeout, parse error, empty catalog) so
+ * the caller can fall back to its old hardcoded default rather than
+ * blocking the user.
+ */
+export async function analyzeMediaRequest(opts) {
+    if (process.env.FRANKLIN_NO_MEDIA_ROUTER === '1')
+        return null;
+    const { kind, prompt, client } = opts;
+    if (!prompt || prompt.trim().length === 0)
+        return null;
+    // Pull catalog first — if the gateway doesn't have any models in this
+    // category, there's nothing to recommend.
+    const catalog = await getModelsByCategory(kind).catch(() => []);
+    if (catalog.length === 0)
+        return null;
+    // Cache check — classifier output is stable for a given prompt + catalog
+    // version, so re-asking within 30s is waste.
+    const quantity = Math.max(1, Math.floor(opts.quantity ?? 1));
+    const key = hashKey([kind, prompt.trim().slice(0, 500), String(quantity), String(opts.durationSeconds ?? '')]);
+    const hit = cache.get(key);
+    if (hit && hit.expiresAt > Date.now())
+        return hit.value;
+    // Call the classifier.
+    const catalogMap = new Map(catalog.map(m => [m.id, m]));
+    const system = buildSystemPrompt(kind, catalog);
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), TIMEOUT_MS);
+    const signal = opts.signal ? combineSignals([opts.signal, ctrl.signal]) : ctrl.signal;
+    let raw = '';
+    try {
+        const response = await client.complete({
+            model: CLASSIFIER_MODEL,
+            system,
+            messages: [{ role: 'user', content: prompt.slice(0, 1000) }],
+            tools: [],
+            max_tokens: MAX_TOKENS,
+        }, signal);
+        for (const part of response.content) {
+            if (typeof part === 'object' && part.type === 'text' && part.text)
+                raw += part.text;
+        }
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    // Parse one-line JSON (may be wrapped in stray text).
+    const match = raw.match(/\{[\s\S]*\}/);
+    if (!match)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(match[0]);
+    }
+    catch {
+        return null;
+    }
+    const style = typeof parsed.style === 'string' && VALID_STYLES.has(parsed.style)
+        ? parsed.style : 'other';
+    const priority = typeof parsed.priority === 'string' && VALID_PRIORITIES.has(parsed.priority)
+        ? parsed.priority : 'balanced';
+    const rec = validateChoice(parsed.recommended, catalogMap);
+    if (!rec)
+        return null;
+    const cheaperChoice = validateChoice(parsed.cheaper, catalogMap);
+    const premiumChoice = validateChoice(parsed.premium, catalogMap);
+    // Build proposal with live cost estimates.
+    const durationSeconds = kind === 'video'
+        ? (opts.durationSeconds ?? defaultDurationSeconds(rec.model))
+        : undefined;
+    const maxDur = kind === 'video' ? (maxDurationSeconds(rec.model) ?? undefined) : undefined;
+    const toChoice = (c) => {
+        if (!c || c.model.id === rec.model.id)
+            return undefined;
+        return {
+            model: c.model.id,
+            estimatedCostUsd: estimateCostUsd(c.model, { quantity, duration_seconds: durationSeconds }),
+            rationale: c.rationale,
+        };
+    };
+    const recommended = {
+        model: rec.model.id,
+        estimatedCostUsd: estimateCostUsd(rec.model, { quantity, duration_seconds: durationSeconds }),
+        rationale: rec.rationale,
+    };
+    const proposal = {
+        kind,
+        quantity,
+        durationSeconds,
+        maxDurationSeconds: maxDur,
+        recommended,
+        cheaper: toChoice(cheaperChoice),
+        premium: toChoice(premiumChoice),
+        intent: { style, priority },
+        totalCostUsd: recommended.estimatedCostUsd,
+    };
+    // Evict oldest if bounded
+    if (cache.size >= CACHE_MAX) {
+        const firstKey = cache.keys().next().value;
+        if (firstKey)
+            cache.delete(firstKey);
+    }
+    cache.set(key, { value: proposal, expiresAt: Date.now() + CACHE_TTL_MS });
+    return proposal;
+}
+// ─── Presentation ───────────────────────────────────────────────────────
+/**
+ * Render a proposal as the user-facing AskUser question. Layout matches
+ * the spec from v3.8.31 planning: recommended first with • bullet,
+ * alternatives below with ○ bullets, prices include the 5% margin note.
+ */
+export function renderProposalForAskUser(p, userPrompt) {
+    const lines = [];
+    lines.push(`*Media generation proposal*`);
+    lines.push('');
+    lines.push(`Prompt: "${userPrompt.trim().slice(0, 200)}"`);
+    if (p.kind === 'video' && p.durationSeconds) {
+        const maxNote = p.maxDurationSeconds ? ` (max ${p.maxDurationSeconds}s)` : '';
+        lines.push(`Duration: ${p.durationSeconds}s${maxNote}`);
+    }
+    else if (p.kind === 'image' && p.quantity > 1) {
+        lines.push(`Quantity: ${p.quantity} images`);
+    }
+    lines.push('');
+    lines.push(`  ● Recommended  ${p.recommended.model.padEnd(32)} ~${formatUsd(p.recommended.estimatedCostUsd)}  ${p.recommended.rationale}`);
+    if (p.cheaper) {
+        lines.push(`  ○ Cheaper      ${p.cheaper.model.padEnd(32)} ~${formatUsd(p.cheaper.estimatedCostUsd)}  ${p.cheaper.rationale}`);
+    }
+    if (p.premium) {
+        lines.push(`  ○ Premium      ${p.premium.model.padEnd(32)} ~${formatUsd(p.premium.estimatedCostUsd)}  ${p.premium.rationale}`);
+    }
+    lines.push('');
+    lines.push(`  (prices include the 5% gateway fee)`);
+    const options = [];
+    options.push({ id: 'recommended', label: `Continue with ${p.recommended.model}` });
+    if (p.cheaper)
+        options.push({ id: 'cheaper', label: `Use cheaper (${p.cheaper.model})` });
+    if (p.premium)
+        options.push({ id: 'premium', label: `Use premium (${p.premium.model})` });
+    options.push({ id: 'cancel', label: 'Cancel (no charge)' });
+    return { question: lines.join('\n'), options };
+}
+function formatUsd(n) {
+    if (!Number.isFinite(n) || n <= 0)
+        return '$0.00';
+    if (n < 0.01)
+        return `$${n.toFixed(4)}`;
+    if (n < 1)
+        return `$${n.toFixed(3)}`;
+    return `$${n.toFixed(2)}`;
+}
+function combineSignals(signals) {
+    const ctrl = new AbortController();
+    for (const s of signals) {
+        if (s.aborted) {
+            ctrl.abort();
+            break;
+        }
+        s.addEventListener('abort', () => ctrl.abort(), { once: true });
+    }
+    return ctrl.signal;
+}

package/dist/gateway-models.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Dynamic model catalog from BlockRun Gateway.
+ *
+ * Pulls GET /api/v1/models once on first use, caches for 5 minutes, and
+ * exposes estimators + category filters. This replaces the hardcoded
+ * pricing/model tables Franklin used to carry — adding a new model or
+ * changing a price on BlockRun's side no longer requires a Franklin
+ * release. Gateway is the single source of truth.
+ *
+ * Per gateway team (2026-04-22): every model returns `billing_mode` and
+ * a mode-specific `pricing` object. Dispatch on billing_mode to compute
+ * an estimated charge. x402 adds a fixed 5% margin on top of base price,
+ * so actual charge = base * 1.05 (confirmed against a live 402 response
+ * on seedance-2.0-fast: 5s × $0.15 × 1.05 = $0.7875).
+ */
+export type BillingMode = 'paid' | 'free' | 'flat' | 'per_image' | 'per_second' | 'per_track';
+export interface PaidPricing {
+    input: number;
+    output: number;
+}
+export interface FlatPricing {
+    flat: number;
+}
+export interface PerImagePricing {
+    per_image: number;
+}
+export interface PerSecondPricing {
+    per_second: number;
+    default_duration_seconds?: number;
+    max_duration_seconds?: number;
+}
+export interface PerTrackPricing {
+    per_track: number;
+}
+export type ModelPricing = PaidPricing | FlatPricing | PerImagePricing | PerSecondPricing | PerTrackPricing;
+export interface GatewayModel {
+    id: string;
+    name: string;
+    description?: string;
+    owned_by?: string;
+    billing_mode: BillingMode;
+    categories: string[];
+    context_window?: number;
+    max_output?: number;
+    pricing: ModelPricing;
+}
+/** Test / reset helper. */
+export declare function clearGatewayModelsCache(): void;
+/**
+ * Fetch the model catalog, honoring the 5-minute cache. Concurrent callers
+ * during a cold cache share a single in-flight promise so we don't stampede
+ * the gateway at process start.
+ */
+export declare function getGatewayModels(): Promise<GatewayModel[]>;
+/** Return models filtered to a specific category (e.g. 'image', 'video', 'music'). */
+export declare function getModelsByCategory(category: string): Promise<GatewayModel[]>;
+/** Find a single model by ID, or null if it's not in the current catalog. */
+export declare function findModel(id: string): Promise<GatewayModel | null>;
+/** x402 gateway's fixed margin percentage applied on top of the base price. */
+export declare const GATEWAY_MARGIN = 1.05;
+export interface EstimateContext {
+    /** Number of images (per_image). Default 1. */
+    quantity?: number;
+    /** Clip length in seconds (per_second). Falls back to model's default_duration_seconds, then 8. */
+    duration_seconds?: number;
+}
+/**
+ * Estimated USD charge to generate one response from this model under the
+ * given context. Includes the 5% gateway margin. Returns 0 for free and
+ * token-metered (paid) models where a pre-call estimate isn't meaningful.
+ */
+export declare function estimateCostUsd(model: GatewayModel, ctx?: EstimateContext): number;
+/** Effective default duration for a per_second model (falls back to 8s). */
+export declare function defaultDurationSeconds(model: GatewayModel): number;
+/** Max duration the gateway will accept for a per_second model. */
+export declare function maxDurationSeconds(model: GatewayModel): number | null;

package/dist/gateway-models.js

@@ -0,0 +1,139 @@
+/**
+ * Dynamic model catalog from BlockRun Gateway.
+ *
+ * Pulls GET /api/v1/models once on first use, caches for 5 minutes, and
+ * exposes estimators + category filters. This replaces the hardcoded
+ * pricing/model tables Franklin used to carry — adding a new model or
+ * changing a price on BlockRun's side no longer requires a Franklin
+ * release. Gateway is the single source of truth.
+ *
+ * Per gateway team (2026-04-22): every model returns `billing_mode` and
+ * a mode-specific `pricing` object. Dispatch on billing_mode to compute
+ * an estimated charge. x402 adds a fixed 5% margin on top of base price,
+ * so actual charge = base * 1.05 (confirmed against a live 402 response
+ * on seedance-2.0-fast: 5s × $0.15 × 1.05 = $0.7875).
+ */
+import { loadChain, API_URLS, USER_AGENT } from './config.js';
+// ─── Cache ──────────────────────────────────────────────────────────────
+const CACHE_TTL_MS = 5 * 60_000; // 5 min — gateway rotates models, but not often
+const FETCH_TIMEOUT_MS = 4_000; // one-shot on init; don't let a slow gateway hang startup
+let cache = null;
+let inflight = null;
+/** Test / reset helper. */
+export function clearGatewayModelsCache() {
+    cache = null;
+    inflight = null;
+}
+// ─── Fetch ──────────────────────────────────────────────────────────────
+async function doFetch() {
+    const chain = loadChain();
+    const base = API_URLS[chain].replace(/\/api$/, '');
+    // The schema/JSON gate: without ?format=json the gateway returns a
+    // typed schema placeholder instead of the data envelope. Documented
+    // quirk across other endpoints too.
+    const url = `${base}/api/v1/models?format=json`;
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), FETCH_TIMEOUT_MS);
+    try {
+        const res = await fetch(url, {
+            signal: ctrl.signal,
+            headers: { 'User-Agent': USER_AGENT, Accept: 'application/json' },
+        });
+        if (!res.ok)
+            throw new Error(`Gateway models list returned HTTP ${res.status}`);
+        const body = (await res.json());
+        if (!Array.isArray(body.data))
+            throw new Error('Gateway models list missing data[]');
+        return body.data;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Fetch the model catalog, honoring the 5-minute cache. Concurrent callers
+ * during a cold cache share a single in-flight promise so we don't stampede
+ * the gateway at process start.
+ */
+export async function getGatewayModels() {
+    if (cache && cache.expiresAt > Date.now())
+        return cache.models;
+    if (inflight)
+        return inflight;
+    inflight = doFetch()
+        .then(models => {
+        cache = { models, expiresAt: Date.now() + CACHE_TTL_MS };
+        return models;
+    })
+        .catch(err => {
+        // On failure, keep the last good cache if we have one (serve stale
+        // rather than break the agent). Only hard-fail cold start.
+        if (cache)
+            return cache.models;
+        throw err;
+    })
+        .finally(() => { inflight = null; });
+    return inflight;
+}
+/** Return models filtered to a specific category (e.g. 'image', 'video', 'music'). */
+export async function getModelsByCategory(category) {
+    const all = await getGatewayModels();
+    return all.filter(m => Array.isArray(m.categories) && m.categories.includes(category));
+}
+/** Find a single model by ID, or null if it's not in the current catalog. */
+export async function findModel(id) {
+    const all = await getGatewayModels();
+    return all.find(m => m.id === id) ?? null;
+}
+// ─── Cost estimation ────────────────────────────────────────────────────
+/** x402 gateway's fixed margin percentage applied on top of the base price. */
+export const GATEWAY_MARGIN = 1.05;
+/**
+ * Estimated USD charge to generate one response from this model under the
+ * given context. Includes the 5% gateway margin. Returns 0 for free and
+ * token-metered (paid) models where a pre-call estimate isn't meaningful.
+ */
+export function estimateCostUsd(model, ctx = {}) {
+    const p = model.pricing;
+    let base = 0;
+    switch (model.billing_mode) {
+        case 'per_image':
+            base = (p.per_image ?? 0) * (ctx.quantity ?? 1);
+            break;
+        case 'per_second': {
+            const dur = ctx.duration_seconds ?? p.default_duration_seconds ?? 8;
+            base = (p.per_second ?? 0) * dur;
+            break;
+        }
+        case 'per_track':
+            base = p.per_track ?? 0;
+            break;
+        case 'flat':
+            base = p.flat ?? 0;
+            break;
+        case 'free':
+            base = 0;
+            break;
+        case 'paid':
+            // Token-metered — no pre-call estimate possible without counting
+            // the exact request/response tokens. Return 0 so the caller shows
+            // "~tokens" instead of a made-up number.
+            base = 0;
+            break;
+    }
+    return +(base * GATEWAY_MARGIN).toFixed(6);
+}
+/** Effective default duration for a per_second model (falls back to 8s). */
+export function defaultDurationSeconds(model) {
+    if (model.billing_mode !== 'per_second')
+        return 8;
+    const p = model.pricing;
+    return p.default_duration_seconds ?? 8;
+}
+/** Max duration the gateway will accept for a per_second model. */
+export function maxDurationSeconds(model) {
+    if (model.billing_mode !== 'per_second')
+        return null;
+    const p = model.pricing;
+    return p.max_duration_seconds ?? null;
+}

package/dist/panel/html.js

@@ -274,6 +274,29 @@ a:hover { text-decoration:underline; }
 .empty { color:var(--text-dim); text-align:center; padding:56px 24px; font-size:13px; }
 
 /* ── Wallet page ── */
+.chain-switcher {
+  display:inline-flex; padding:3px; gap:2px;
+  background:oklch(0 0 0 / 35%); border:1px solid var(--border);
+  border-radius:10px; margin-bottom:14px;
+}
+.chain-switcher button {
+  font-family:var(--mono); font-size:12px; font-weight:600;
+  letter-spacing:0.6px; text-transform:uppercase;
+  padding:7px 18px; border-radius:7px;
+  background:transparent; border:none; color:var(--text-muted);
+  cursor:pointer; transition:all .15s ease;
+}
+.chain-switcher button:hover:not(.active):not(:disabled) {
+  color:var(--text); background:oklch(1 0 0 / 5%);
+}
+.chain-switcher button.active {
+  background:var(--brand); color:#fff;
+}
+.chain-switcher button:disabled { opacity:0.5; cursor:wait; }
+.chain-switcher-note {
+  margin-left:10px; font-size:12px; color:var(--text-dim);
+  font-style:italic;
+}
 .wallet-grid { display:grid; grid-template-columns:1.1fr 1fr; gap:14px; }
 .wallet-grid .card { display:flex; flex-direction:column; gap:10px; }
 .wallet-receive { grid-row:span 2; align-items:flex-start; }
@@ -472,8 +495,14 @@ a:hover { text-decoration:underline; }
   <div class="tab" id="tab-wallet">
     <div class="content-header">
       <h2>Wallet</h2>
-      <p>Receive USDC, back up your key, or import an existing wallet</p>
+      <p>Receive USDC, back up your key, or switch chains</p>
+    </div>
+
+    <div class="chain-switcher" role="tablist" aria-label="Payment chain">
+      <button type="button" data-chain="base" id="chain-btn-base" role="tab">Base</button>
+      <button type="button" data-chain="solana" id="chain-btn-solana" role="tab">Solana</button>
     </div>
+    <span class="chain-switcher-note" id="chain-switcher-note"></span>
 
     <div class="wallet-grid">
       <div class="card wallet-receive">
@@ -841,6 +870,14 @@ async function loadWallet() {
   document.getElementById('wallet-balance-big').textContent = usdBig(w.balance) + ' USDC';
   document.getElementById('wallet-chain-pill').textContent = w.chain || '—';
 
+  // Chain switcher — highlight active button
+  const baseBtn = document.getElementById('chain-btn-base');
+  const solanaBtn = document.getElementById('chain-btn-solana');
+  if (baseBtn && solanaBtn) {
+    baseBtn.classList.toggle('active', w.chain === 'base');
+    solanaBtn.classList.toggle('active', w.chain === 'solana');
+  }
+
   // QR via server — never leak address to third parties
   const qrBox = document.getElementById('wallet-qr');
   const hint = document.getElementById('wallet-qr-hint');
@@ -848,7 +885,7 @@ async function loadWallet() {
     const svg = await fetch('/api/wallet/qr?data=' + encodeURIComponent(addr)).then(r => r.ok ? r.text() : null);
     qrBox.innerHTML = svg || '';
     hint.textContent = w.chain === 'solana'
-      ? 'Scan to send USDC (Solana) to this address.'
+      ? 'Scan to send USDC (Solana SPL) to this address.'
       : 'Scan to send USDC on Base to this address.';
   } else {
     qrBox.innerHTML = '';
@@ -856,6 +893,48 @@ async function loadWallet() {
   }
 }
 
+// Chain switcher — click "Base" or "Solana" to flip payment chain.
+// Creates a wallet on the target chain if one does not exist yet.
+// Note: a currently-running franklin agent reads its chain at startup,
+// so a mid-session switch only affects the next agent invocation.
+['chain-btn-base', 'chain-btn-solana'].forEach((id) => {
+  const btn = document.getElementById(id);
+  if (!btn) return;
+  btn.addEventListener('click', async () => {
+    const target = btn.getAttribute('data-chain');
+    const note = document.getElementById('chain-switcher-note');
+    const baseBtn = document.getElementById('chain-btn-base');
+    const solanaBtn = document.getElementById('chain-btn-solana');
+    // Skip if already active
+    if (btn.classList.contains('active')) return;
+    baseBtn.disabled = true;
+    solanaBtn.disabled = true;
+    note.textContent = 'Switching to ' + target + '…';
+    try {
+      const r = await fetch('/api/chain', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ chain: target }),
+      });
+      const data = await r.json().catch(() => ({}));
+      if (!r.ok || !data.ok) {
+        note.textContent = 'Error: ' + (data.error || r.statusText);
+        return;
+      }
+      note.textContent = 'Switched to ' + target + ' · restart Franklin to use this chain';
+      await loadWallet();
+      // Sidebar balance + address also refresh
+      document.getElementById('sidebar-balance').textContent = usdBig(data.balance) + ' USDC';
+      document.getElementById('sidebar-addr').textContent = (data.address || '').slice(0, 6) + '…' + (data.address || '').slice(-4);
+    } catch (err) {
+      note.textContent = 'Error: ' + (err && err.message ? err.message : 'network error');
+    } finally {
+      baseBtn.disabled = false;
+      solanaBtn.disabled = false;
+    }
+  });
+});
+
 // Copy button
 document.getElementById('wallet-copy-btn').addEventListener('click', async () => {
   const addr = document.getElementById('wallet-address-full').textContent;

package/dist/panel/server.js

@@ -6,7 +6,7 @@
 import http from 'node:http';
 import fs from 'node:fs';
 import path from 'node:path';
-import { BLOCKRUN_DIR, loadChain } from '../config.js';
+import { BLOCKRUN_DIR, loadChain, saveChain } from '../config.js';
 import { getStatsSummary } from '../stats/tracker.js';
 import { generateInsights } from '../stats/insights.js';
 import { listSessions, loadSessionHistory } from '../session/storage.js';
@@ -313,6 +313,53 @@ export function createPanelServer(port) {
                     }
                     return;
                 }
+                // ─── Chain switch (loopback only) ───────────────────────────────
+                // Switches the active payment chain (base ↔ solana) for subsequent
+                // Franklin runs. Writes ~/.blockrun/payment-chain, then ensures a
+                // wallet exists on the target chain (creates if missing). Returns
+                // the new wallet address + balance so the UI can re-render without
+                // a follow-up round trip.
+                //
+                // NOTE: a currently-running `franklin` agent reads the chain once
+                // at startup. The Panel switch takes effect immediately for Panel
+                // reads and for the *next* agent invocation, but won't flip chain
+                // mid-session for an already-running agent. UI copy makes this clear.
+                if (p === '/api/chain' && req.method === 'POST') {
+                    if (!isLoopback(req)) {
+                        json(res, { error: 'forbidden' }, 403);
+                        return;
+                    }
+                    try {
+                        const raw = await readBody(req);
+                        const body = JSON.parse(raw);
+                        const target = body.chain;
+                        if (target !== 'base' && target !== 'solana') {
+                            json(res, { error: 'chain must be "base" or "solana"' }, 400);
+                            return;
+                        }
+                        saveChain(target);
+                        // Creates-or-loads the wallet on the target chain.
+                        let address = '';
+                        let balance = 0;
+                        if (target === 'solana') {
+                            const { setupAgentSolanaWallet } = await import('@blockrun/llm');
+                            const client = await setupAgentSolanaWallet({ silent: true });
+                            address = await client.getWalletAddress();
+                            balance = await client.getBalance();
+                        }
+                        else {
+                            const { setupAgentWallet } = await import('@blockrun/llm');
+                            const client = setupAgentWallet({ silent: true });
+                            address = client.getWalletAddress();
+                            balance = await client.getBalance();
+                        }
+                        json(res, { ok: true, chain: target, address, balance });
+                    }
+                    catch (err) {
+                        json(res, { error: err.message }, 500);
+                    }
+                    return;
+                }
                 if (p === '/api/markets') {
                     // Snapshot of every active data provider for the Markets panel:
                     // pipeline wiring (which endpoint serves which asset class), live

package/dist/tools/imagegen.js

@@ -7,15 +7,60 @@ import path from 'node:path';
 import { getOrCreateWallet, getOrCreateSolanaWallet, createPaymentPayload, createSolanaPaymentPayload, parsePaymentRequired, extractPaymentDetails, solanaKeyToBytes, SOLANA_NETWORK, } from '@blockrun/llm';
 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';
 function buildExecute(deps) {
     return async function execute(input, ctx) {
         const { prompt, output_path, size, model, contentId } = input;
         if (!prompt) {
             return { output: 'Error: prompt is required', isError: true };
         }
-        // ── Content pre-flight: refuse BEFORE paying if budget can't cover this ──
-        const imageModel = model || 'openai/gpt-image-1';
+        // ── 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';
         const imageSize = size || '1024x1024';
+        const autoApprove = process.env.FRANKLIN_MEDIA_AUTO_APPROVE_ALL === '1';
+        if (!model && !autoApprove && ctx.onAskUser) {
+            try {
+                const chain = loadChain();
+                const client = new ModelClient({ apiUrl: API_URLS[chain], chain });
+                const proposal = await analyzeMediaRequest({
+                    kind: 'image',
+                    prompt,
+                    quantity: 1,
+                    client,
+                    signal: ctx.abortSignal,
+                });
+                if (proposal) {
+                    const { question, options } = renderProposalForAskUser(proposal, prompt);
+                    const labels = options.map(o => o.label);
+                    const answer = await ctx.onAskUser(question, labels);
+                    // Map the user's returned label back to an option id
+                    const chosen = options.find(o => o.label === answer) ?? { id: 'cancel' };
+                    switch (chosen.id) {
+                        case 'cheaper':
+                            imageModel = proposal.cheaper?.model ?? proposal.recommended.model;
+                            break;
+                        case 'premium':
+                            imageModel = proposal.premium?.model ?? proposal.recommended.model;
+                            break;
+                        case 'cancel':
+                            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 'recommended':
+                        default:
+                            imageModel = proposal.recommended.model;
+                    }
+                }
+            }
+            catch {
+                // Router / AskUser failed — fall back to default model silently.
+            }
+        }
         if (contentId && deps.library) {
             const decision = checkImageBudget(deps.library, contentId, imageModel, imageSize);
             if (!decision.ok) {

package/dist/tools/videogen.js

@@ -11,6 +11,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { getOrCreateWallet, getOrCreateSolanaWallet, createPaymentPayload, createSolanaPaymentPayload, parsePaymentRequired, extractPaymentDetails, solanaKeyToBytes, SOLANA_NETWORK, } from '@blockrun/llm';
 import { loadChain, API_URLS, VERSION } from '../config.js';
+import { ModelClient } from '../agent/llm.js';
+import { analyzeMediaRequest, renderProposalForAskUser } from '../agent/media-router.js';
 const DEFAULT_MODEL = 'xai/grok-imagine-video';
 const DEFAULT_DURATION = 8;
 const PRICE_PER_SECOND_USD = 0.05;
@@ -26,8 +28,51 @@ function buildExecute(deps) {
         const { prompt, output_path, model, image_url, duration_seconds, contentId } = input;
         if (!prompt)
             return { output: 'Error: prompt is required', isError: true };
-        const videoModel = model || DEFAULT_MODEL;
-        const duration = duration_seconds ?? DEFAULT_DURATION;
+        let videoModel = model || DEFAULT_MODEL;
+        let duration = duration_seconds ?? DEFAULT_DURATION;
+        // ── Media router + AskUser flow (video bills per second, always ask) ──
+        const autoApprove = process.env.FRANKLIN_MEDIA_AUTO_APPROVE_ALL === '1';
+        if (!model && !autoApprove && ctx.onAskUser) {
+            try {
+                const chain = loadChain();
+                const client = new ModelClient({ apiUrl: API_URLS[chain], chain });
+                const proposal = await analyzeMediaRequest({
+                    kind: 'video',
+                    prompt,
+                    durationSeconds: duration_seconds,
+                    client,
+                    signal: ctx.abortSignal,
+                });
+                if (proposal) {
+                    const { question, options } = renderProposalForAskUser(proposal, prompt);
+                    const labels = options.map(o => o.label);
+                    const answer = await ctx.onAskUser(question, labels);
+                    const chosen = options.find(o => o.label === answer) ?? { id: 'cancel' };
+                    switch (chosen.id) {
+                        case 'cheaper':
+                            videoModel = proposal.cheaper?.model ?? proposal.recommended.model;
+                            break;
+                        case 'premium':
+                            videoModel = proposal.premium?.model ?? proposal.recommended.model;
+                            break;
+                        case 'cancel':
+                            return {
+                                output: `## Video generation cancelled\n\nNo USDC was spent.`,
+                            };
+                        case 'recommended':
+                        default:
+                            videoModel = proposal.recommended.model;
+                    }
+                    // Use the proposal's duration — the router honored the user's
+                    // duration_seconds or filled in the model's default.
+                    if (proposal.durationSeconds)
+                        duration = proposal.durationSeconds;
+                }
+            }
+            catch {
+                // Router / AskUser failed — fall through to legacy default.
+            }
+        }
         const estCost = estimateVideoCostUsd(duration);
         if (contentId && deps.library) {
             const content = deps.library.get(contentId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/franklin",
-  "version": "3.8.29",
+  "version": "3.8.31",
   "description": "Franklin — The AI agent with a wallet. Spends USDC autonomously to get real work done. Pay per action, no subscriptions.",
   "type": "module",
   "exports": {