@blockrun/franklin 3.8.34 → 3.8.35

package/README.md

@@ -480,10 +480,12 @@ cd franklin
 npm install
 npm run build
 npm test              # deterministic local tests — no API calls
-npm run test:e2e      # live e2e tests — hits real models, needs wallet
+npm run test:e2e      # live e2e tests — free smoke works unfunded; paid tools need network + funded wallet
 node dist/index.js --help
 ```
 
+For the recommended live validation order and failure triage, see [docs/live-e2e-checklist.md](docs/live-e2e-checklist.md).
+
 **Contributing:** open an issue first to discuss meaningful changes. PRs welcome on bugs, docs, new models in pricing, and new tools.
 
 ---

package/dist/agent/context.js

@@ -189,7 +189,7 @@ Your training data is frozen in the past. Live-world questions MUST be answered
 
 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.`;
+**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, refines loose prompts using a 5-slot template (scene / subject / details / use case / constraints), and surfaces both the refinement and a cost proposal through AskUser before spending. If the user wants their prompt left exactly as written, prefix it with \`///\` to skip refinement. Only pass \`model\` explicitly if the user named one specifically.`;
 }
 function getTokenEfficiencySection() {
     return `# Token Efficiency

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

@@ -33,9 +33,35 @@ export interface MediaProposal {
         style: MediaStyle;
         priority: MediaPriority;
     };
+    /**
+     * A fuller rewrite of the user's prompt, following the 5-slot template
+     * (scene/subject/details/use-case/constraints). Null when the classifier
+     * judged the input already well-specified, or when the env opt-out is set,
+     * or when the rewrite was identical to the raw input. When non-null, the
+     * AskUser layout surfaces it as "Refined:" with a "Use ORIGINAL" option.
+     */
+    refinedPrompt: string | null;
+    refinementSummary: string;
     totalCostUsd: number;
 }
 export declare function clearMediaRouterCache(): void;
+/**
+ * Normalize a refined prompt: trim, cap length, reject obvious junk.
+ * Returns null when the value should be treated as absent (missing,
+ * non-string, empty after trim).
+ *
+ * Exported for testability — invariants matter more here than elsewhere
+ * because the output is user-visible and paid for.
+ */
+export declare function validateRefined(raw: unknown, maxChars: number): string | null;
+/**
+ * Whitespace-insensitive, case-insensitive identity check — if the
+ * classifier's "refinement" is just the input with different spacing,
+ * don't bother the user with a "Refined:" block.
+ */
+export declare function isEffectivelyIdentical(a: string, b: string): boolean;
+export declare const REFINED_PROMPT_MAX_CHARS = 500;
+export declare const REFINEMENT_SUMMARY_LIMIT = 80;
 export interface AnalyzeMediaOpts {
     kind: MediaKind;
     prompt: string;
@@ -43,6 +69,13 @@ export interface AnalyzeMediaOpts {
     quantity?: number;
     durationSeconds?: number;
     signal?: AbortSignal;
+    /**
+     * One-shot opt-out — caller stripped a `///` prefix from the user's input
+     * and wants the proposal rendered without a Refined block or Use-original
+     * option. The classifier still runs (for model selection), but the
+     * refinement is discarded at parse time.
+     */
+    skipRefine?: boolean;
 }
 /**
  * Pick the best model + alternatives for this media request. Returns null

package/dist/agent/media-router.js

@@ -16,7 +16,9 @@ import { getModelsByCategory, estimateCostUsd, defaultDurationSeconds, maxDurati
 // ─── 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;
+const MAX_TOKENS = 384; // bumped from 256 to leave room for refined_prompt (≤500 chars) + refinement_summary (≤80)
+const REFINED_MAX_CHARS = 500;
+const REFINEMENT_SUMMARY_MAX_CHARS = 80;
 function buildSystemPrompt(kind, catalog) {
     const catalogLines = catalog.map(m => {
         const p = m.pricing;
@@ -25,7 +27,7 @@ function buildSystemPrompt(kind, catalog) {
             : `$${(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.
+    return `You pick the best ${kind} model for a user's Franklin request AND refine the user's prompt. Output ONE LINE of compact JSON. No markdown, no code fences, no explanation.
 
 ## Catalog (${catalog.length} available ${kind} models)
 ${catalogLines}
@@ -34,6 +36,8 @@ ${catalogLines}
 
 {"style":"photoreal|illustration|anime|logo|concept|other",
  "priority":"cost|quality|balanced",
+ "refined_prompt":"<rewritten prompt in the user's language, <=${REFINED_MAX_CHARS} chars, or null if already well-specified>",
+ "refinement_summary":"<one short sentence, <=${REFINEMENT_SUMMARY_MAX_CHARS} chars, user-visible>",
  "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>"}}
@@ -45,16 +49,33 @@ Rules:
 - 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.
 
+## Refinement (emit refined_prompt + refinement_summary)
+
+If the user's prompt is missing ≥3 of these 5 slots, rewrite to fill them. If it already has ≥3 covered, set refined_prompt to null and refinement_summary to "Already well-specified".
+
+  1. Scene       — location, time of day, environment, background
+  2. Subject     — primary focus (who / what), preserved EXACTLY from the user's input (no substitution)
+  3. Details     — materials, textures, lighting, camera/lens feel, composition, mood (concrete visual facts, not praise)
+  4. Use Case    — editorial photo, product mockup, UI screen, logo, storyboard frame, social-media cover, etc.
+  5. Constraints — aspect ratio, what must not drift (no watermark, preserve face, no text), hard asks
+
+Anti-slop rules:
+- Concrete visual facts ("overcast daylight", "brushed aluminum") beat vague praise ("stunning", "cinematic masterpiece").
+- Wrap literal text that must appear in the image in double quotes. Spell difficult words letter-by-letter.
+- One revision per turn — do not combine conflicting asks.
+- Natural language, not keyword-tag format.
+- refined_prompt stays in the same language as the user input. Chinese in → Chinese out.
+
 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."}}
+Output: {"style":"photoreal","priority":"balanced","refined_prompt":"Eye-level photograph of a cat standing on the rust-colored Martian surface, late-afternoon low sun casting long shadows, distant canyon rim in the background, 50mm feel, shallow depth of field, editorial photo use, no watermark.","refinement_summary":"Added scene, lighting, lens, use case, constraint.","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."}}
+Output: {"style":"anime","priority":"balanced","refined_prompt":"赛博朋克风格的动漫角色，站在霓虹灯映照的雨夜街道上，身穿合成纤维夹克与金属反光饰件，头顶全息广告牌漂浮，低角度视角，强烈青粉对比，海报用，居中构图。","refinement_summary":"补全了场景、光线、材质、用途、构图。","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: {"style":"concept","priority":"quality","refined_prompt":null,"refinement_summary":"Already well-specified.","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.`;
 }
@@ -82,6 +103,33 @@ function validateChoice(raw, catalog) {
     const rationale = typeof raw.rationale === 'string' ? raw.rationale.slice(0, 240) : '';
     return { model, rationale };
 }
+/**
+ * Normalize a refined prompt: trim, cap length, reject obvious junk.
+ * Returns null when the value should be treated as absent (missing,
+ * non-string, empty after trim).
+ *
+ * Exported for testability — invariants matter more here than elsewhere
+ * because the output is user-visible and paid for.
+ */
+export function validateRefined(raw, maxChars) {
+    if (typeof raw !== 'string')
+        return null;
+    const trimmed = raw.trim();
+    if (trimmed.length === 0)
+        return null;
+    return trimmed.slice(0, maxChars);
+}
+/**
+ * Whitespace-insensitive, case-insensitive identity check — if the
+ * classifier's "refinement" is just the input with different spacing,
+ * don't bother the user with a "Refined:" block.
+ */
+export function isEffectivelyIdentical(a, b) {
+    const normalize = (s) => s.toLowerCase().replace(/\s+/g, ' ').trim();
+    return normalize(a) === normalize(b);
+}
+export const REFINED_PROMPT_MAX_CHARS = REFINED_MAX_CHARS;
+export const REFINEMENT_SUMMARY_LIMIT = REFINEMENT_SUMMARY_MAX_CHARS;
 /**
  * Pick the best model + alternatives for this media request. Returns null
  * on any failure path (classifier timeout, parse error, empty catalog) so
@@ -100,12 +148,18 @@ export async function analyzeMediaRequest(opts) {
     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.
+    // version, so re-asking within 30s is waste. Cache stores the FULL
+    // classifier response (refinement + model picks); the per-call mask for
+    // skipRefine / FRANKLIN_NO_MEDIA_PROMPT_REFINE is applied on the way out
+    // so the same cache entry serves callers with different opt-out flags.
     const quantity = Math.max(1, Math.floor(opts.quantity ?? 1));
+    const globalOptOut = process.env.FRANKLIN_NO_MEDIA_PROMPT_REFINE === '1';
+    const shouldDiscard = globalOptOut || opts.skipRefine === true;
+    const maskRefinement = (p) => shouldDiscard ? { ...p, refinedPrompt: null, refinementSummary: '' } : p;
     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;
+        return maskRefinement(hit.value);
     // Call the classifier.
     const catalogMap = new Map(catalog.map(m => [m.id, m]));
     const system = buildSystemPrompt(kind, catalog);
@@ -152,6 +206,15 @@ export async function analyzeMediaRequest(opts) {
         return null;
     const cheaperChoice = validateChoice(parsed.cheaper, catalogMap);
     const premiumChoice = validateChoice(parsed.premium, catalogMap);
+    // Refinement fields. The cache stores the full classifier output; the
+    // per-call mask is applied on the way out via maskRefinement() above, so
+    // here we just normalize + discard rewrites that are effectively the
+    // same as the raw input (drift-proof).
+    let refinedPrompt = validateRefined(parsed.refined_prompt, REFINED_MAX_CHARS);
+    const refinementSummary = validateRefined(parsed.refinement_summary, REFINEMENT_SUMMARY_MAX_CHARS) ?? '';
+    if (refinedPrompt !== null && isEffectivelyIdentical(refinedPrompt, prompt)) {
+        refinedPrompt = null;
+    }
     // Build proposal with live cost estimates.
     const durationSeconds = kind === 'video'
         ? (opts.durationSeconds ?? defaultDurationSeconds(rec.model))
@@ -180,6 +243,8 @@ export async function analyzeMediaRequest(opts) {
         cheaper: toChoice(cheaperChoice),
         premium: toChoice(premiumChoice),
         intent: { style, priority },
+        refinedPrompt,
+        refinementSummary,
         totalCostUsd: recommended.estimatedCostUsd,
     };
     // Evict oldest if bounded
@@ -189,7 +254,7 @@ export async function analyzeMediaRequest(opts) {
             cache.delete(firstKey);
     }
     cache.set(key, { value: proposal, expiresAt: Date.now() + CACHE_TTL_MS });
-    return proposal;
+    return maskRefinement(proposal);
 }
 // ─── Presentation ───────────────────────────────────────────────────────
 /**
@@ -202,6 +267,13 @@ export function renderProposalForAskUser(p, userPrompt) {
     lines.push(`*Media generation proposal*`);
     lines.push('');
     lines.push(`Prompt: "${userPrompt.trim().slice(0, 200)}"`);
+    if (p.refinedPrompt) {
+        lines.push('');
+        lines.push(`Refined: ${p.refinedPrompt}`);
+        if (p.refinementSummary) {
+            lines.push(`  (${p.refinementSummary})`);
+        }
+    }
     if (p.kind === 'video' && p.durationSeconds) {
         const maxNote = p.maxDurationSeconds ? ` (max ${p.maxDurationSeconds}s)` : '';
         lines.push(`Duration: ${p.durationSeconds}s${maxNote}`);
@@ -220,11 +292,17 @@ export function renderProposalForAskUser(p, userPrompt) {
     lines.push('');
     lines.push(`  (prices include the 5% gateway fee)`);
     const options = [];
-    options.push({ id: 'recommended', label: `Continue with ${p.recommended.model}` });
+    const recLabel = p.refinedPrompt
+        ? `Continue with refined prompt + ${p.recommended.model}`
+        : `Continue with ${p.recommended.model}`;
+    options.push({ id: 'recommended', label: recLabel });
     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})` });
+    if (p.refinedPrompt) {
+        options.push({ id: 'use-raw', label: `Use ORIGINAL prompt + ${p.recommended.model}` });
+    }
     options.push({ id: 'cancel', label: 'Cancel (no charge)' });
     return { question: lines.join('\n'), options };
 }

package/dist/tools/imagegen.js

@@ -11,17 +11,29 @@ 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) {
+        const rawInput = input;
+        const { output_path, size, model, contentId } = rawInput;
+        if (!rawInput.prompt) {
             return { output: 'Error: prompt is required', 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.
+        // model + rewrites the prompt, the preview goes to AskUser, user
+        // chooses or cancels.
         let imageModel = model || 'openai/gpt-image-1';
         const imageSize = size || '1024x1024';
+        let chosenPrompt = prompt;
         const autoApprove = process.env.FRANKLIN_MEDIA_AUTO_APPROVE_ALL === '1';
         if (!model && !autoApprove && ctx.onAskUser) {
             try {
@@ -33,6 +45,7 @@ function buildExecute(deps) {
                     quantity: 1,
                     client,
                     signal: ctx.abortSignal,
+                    skipRefine,
                 });
                 if (proposal) {
                     const { question, options } = renderProposalForAskUser(proposal, prompt);
@@ -51,9 +64,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;
                     }
                 }
             }
@@ -83,7 +102,7 @@ function buildExecute(deps) {
             : path.resolve(ctx.workingDir, `generated-${Date.now()}.png`);
         const body = JSON.stringify({
             model: imageModel,
-            prompt,
+            prompt: chosenPrompt,
             n: 1,
             size: imageSize,
             response_format: 'b64_json',

package/dist/tools/videogen.js

@@ -25,11 +25,21 @@ function estimateVideoCostUsd(durationSeconds = DEFAULT_DURATION) {
 }
 function buildExecute(deps) {
     return async function execute(input, ctx) {
-        const { prompt, output_path, model, image_url, duration_seconds, contentId } = input;
-        if (!prompt)
+        const rawInput = input;
+        const { output_path, model, image_url, duration_seconds, contentId } = rawInput;
+        if (!rawInput.prompt)
             return { output: 'Error: prompt is required', isError: true };
+        // One-shot refinement opt-out: leading `///` tells Franklin "don't
+        // refine this prompt." Strip the prefix and pass skipRefine through.
+        let prompt = rawInput.prompt;
+        let skipRefine = false;
+        if (prompt.trimStart().startsWith('///')) {
+            prompt = prompt.replace(/^\s*\/\/\/\s?/, '');
+            skipRefine = true;
+        }
         let videoModel = model || DEFAULT_MODEL;
         let duration = duration_seconds ?? DEFAULT_DURATION;
+        let chosenPrompt = prompt;
         // ── 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) {
@@ -42,6 +52,7 @@ function buildExecute(deps) {
                     durationSeconds: duration_seconds,
                     client,
                     signal: ctx.abortSignal,
+                    skipRefine,
                 });
                 if (proposal) {
                     const { question, options } = renderProposalForAskUser(proposal, prompt);
@@ -59,9 +70,15 @@ function buildExecute(deps) {
                             return {
                                 output: `## Video generation cancelled\n\nNo USDC was spent.`,
                             };
+                        case 'use-raw':
+                            videoModel = proposal.recommended.model;
+                            // chosenPrompt stays as the raw input
+                            break;
                         case 'recommended':
                         default:
                             videoModel = proposal.recommended.model;
+                            if (proposal.refinedPrompt)
+                                chosenPrompt = proposal.refinedPrompt;
                     }
                     // Use the proposal's duration — the router honored the user's
                     // duration_seconds or filled in the model's default.
@@ -96,7 +113,7 @@ function buildExecute(deps) {
             : path.resolve(ctx.workingDir, `generated-${Date.now()}.mp4`);
         const body = JSON.stringify({
             model: videoModel,
-            prompt,
+            prompt: chosenPrompt,
             ...(image_url ? { image_url } : {}),
             ...(duration_seconds ? { duration_seconds } : {}),
         });

package/package.json

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