@blockrun/franklin 3.25.2 → 3.25.4

package/dist/agent/llm.js

@@ -102,6 +102,58 @@ function linkAbortSignal(parent, child) {
 function createModelTimeoutError(stage, model, timeoutMs) {
     return new Error(`Model ${stage} timed out after ${timeoutMs}ms on ${model}`);
 }
+/**
+ * Walk a tool-schema object and drop any `enum` whose entries are strings
+ * containing "/". Grok's request validator rejects such enums outright (see
+ * the call site for the verbatim upstream error). The model still sees the
+ * intended values via the tool's description text, so dropping the schema-
+ * level constraint is purely a compatibility shim — no behavioral loss.
+ */
+function stripSlashEnumsForGrok(node) {
+    if (Array.isArray(node))
+        return node.map(stripSlashEnumsForGrok);
+    if (!node || typeof node !== 'object')
+        return node;
+    const out = {};
+    for (const [k, v] of Object.entries(node)) {
+        if (k === 'enum' &&
+            Array.isArray(v) &&
+            v.some((x) => typeof x === 'string' && x.includes('/'))) {
+            continue; // drop the constraint entirely
+        }
+        out[k] = stripSlashEnumsForGrok(v);
+    }
+    return out;
+}
+/**
+ * Wrap `fetch()` so that undici's opaque `TypeError: fetch failed` is
+ * replaced with the underlying network reason (ECONNRESET, UND_ERR_*,
+ * certificate, DNS, etc.). Without this, every transient connection blip
+ * surfaces to the user as "Network: fetch failed" with no way to tell
+ * whether it's their network, the gateway, or the upstream provider.
+ *
+ * Verified 2026-06-03: stress-testing claude-sonnet-4.6 reproduces
+ * intermittent "fetch failed" (cheetah's report on 3.25.0). With this
+ * helper the message becomes e.g. "fetch failed (UND_ERR_SOCKET: other
+ * side closed)" which is actionable.
+ */
+async function fetchWithUnwrappedCause(url, init) {
+    try {
+        return await fetch(url, init);
+    }
+    catch (err) {
+        if (err instanceof Error && err.message === 'fetch failed' && err.cause) {
+            const cause = err.cause;
+            const detail = cause.code || cause.errno || cause.message;
+            if (detail) {
+                const enriched = new Error(`fetch failed (${detail})`);
+                enriched.cause = err.cause;
+                throw enriched;
+            }
+        }
+        throw err;
+    }
+}
 async function withAbortableTimeout(work, controller, timeoutError, timeoutMs) {
     if (timeoutMs <= 0)
         return work();
@@ -416,6 +468,20 @@ export class ModelClient {
         if (requestPayload['tool_choice'] !== undefined && modelDoesNotSupportToolChoice(request.model)) {
             delete requestPayload['tool_choice'];
         }
+        // ── Grok: strip enum constraints containing "/" from tool schemas ────────
+        // Verified 2026-06-03 via Franklin repro: xAI's request validator hard-
+        // rejects any tool-schema enum string containing "/", e.g.
+        //   "[engine_imposed] /properties/endpoint/enum/0: '/' in 'enum' string
+        //    value is currently not supported"
+        // The Surf tools (and a few others) use endpoint paths like
+        // "market/ranking" as enum values to constrain the model's choice. The
+        // path list is also enumerated in each tool's description text, so the
+        // model still sees the legal values — only the schema-level constraint
+        // gets dropped. Other providers keep the enum unchanged.
+        if (request.model.startsWith('xai/') && Array.isArray(requestPayload['tools'])) {
+            const tools = requestPayload['tools'];
+            requestPayload['tools'] = tools.map((tool) => stripSlashEnumsForGrok(tool));
+        }
         // ── GLM-specific optimizations ───────────────────────────────────────────
         // GLM models work best with temperature=0.8 per official zai spec.
         // Enable thinking mode only for explicit reasoning variants (-thinking-).
@@ -481,20 +547,20 @@ export class ModelClient {
             // session reached ≥3 messages (system + tool + 3 = 5). See issue #73.
             requestPayload = applyAnthropicPromptCaching(requestPayload, request);
         }
-        // ── GPT-5 / Codex: use "developer" role for system prompt ──────────────
-        // OpenAI GPT models give stronger instruction-following weight to the
-        // "developer" role. Move the top-level system prompt into messages[0]
-        // with role "developer" instead of the default "system".
-        const isGPT5OrCodex = request.model.includes('gpt-5') || request.model.includes('codex');
-        if (isGPT5OrCodex && typeof request.system === 'string' && request.system.length > 0) {
-            const systemRole = 'developer';
-            const existingMessages = requestPayload['messages'] || [];
-            requestPayload['messages'] = [
-                { role: systemRole, content: request.system },
-                ...existingMessages,
-            ];
-            delete requestPayload['system'];
-        }
+        // ── No client-side system → developer role rewrite for GPT-5/Codex ─────
+        // We used to move the top-level `system` field into `messages[0]` with
+        // role "developer" for GPT-5/Codex (OpenAI docs say that role gets
+        // stronger instruction-following weight). But the BlockRun gateway
+        // speaks Anthropic Messages, which only accepts user|assistant in
+        // messages[] — the developer-role payload returns HTTP 400 from the
+        // gateway's protocol validator BEFORE it ever reaches OpenAI:
+        //   {"error":{"message":"messages.0.role: Invalid option: expected
+        //    one of \"user\"|\"assistant\""}}
+        // Verified 2026-06-03 via direct curl + Franklin repro: all GPT-5
+        // family models (mini/nano/5.4/5.5) were silently failing under
+        // headless -p mode. Keep `system` as a top-level field and let the
+        // gateway translate to whatever the upstream needs (it already knows
+        // gpt-5 expects developer role internally).
         const body = JSON.stringify(requestPayload);
         const endpoint = `${this.apiUrl}/v1/messages`;
         const headers = {
@@ -515,7 +581,7 @@ export class ModelClient {
         const requestController = new AbortController();
         const unlinkAbort = linkAbortSignal(signal, requestController);
         try {
-            let response = await withAbortableTimeout(() => fetch(endpoint, {
+            let response = await withAbortableTimeout(() => fetchWithUnwrappedCause(endpoint, {
                 method: 'POST',
                 headers,
                 body,
@@ -530,7 +596,7 @@ export class ModelClient {
                     yield { kind: 'error', payload: { message: 'Payment signing failed' } };
                     return;
                 }
-                response = await withAbortableTimeout(() => fetch(endpoint, {
+                response = await withAbortableTimeout(() => fetchWithUnwrappedCause(endpoint, {
                     method: 'POST',
                     headers: { ...headers, ...paymentHeader },
                     body,
@@ -580,7 +646,7 @@ export class ModelClient {
                     if (this.debug) {
                         console.error(`[franklin] tool_choice rejected by upstream; retrying without it (model=${request.model})`);
                     }
-                    response = await withAbortableTimeout(() => fetch(endpoint, {
+                    response = await withAbortableTimeout(() => fetchWithUnwrappedCause(endpoint, {
                         method: 'POST',
                         headers,
                         body: retryBody,
@@ -592,7 +658,7 @@ export class ModelClient {
                             yield { kind: 'error', payload: { message: 'Payment signing failed' } };
                             return;
                         }
-                        response = await withAbortableTimeout(() => fetch(endpoint, {
+                        response = await withAbortableTimeout(() => fetchWithUnwrappedCause(endpoint, {
                             method: 'POST',
                             headers: { ...headers, ...paymentHeader },
                             body: retryBody,

package/dist/commands/start.js

@@ -420,6 +420,12 @@ async function runOneShot(agentConfig, prompt) {
         }
         else if (event.kind === 'turn_done') {
             exitCode = oneShotExitCodeForTurnReason(event.reason);
+            // Without this, headless callers see exit 1 + zero stderr — impossible
+            // to triage. Verified 2026-06-03: GPT-5 family failing with HTTP 400
+            // from the gateway looked identical to a network timeout in `-p` mode.
+            if (event.reason !== 'completed' && event.error) {
+                process.stderr.write(`\n${event.error}\n`);
+            }
             process.stdout.write('\n');
         }
     });

package/dist/ui/app.js

@@ -61,6 +61,21 @@ function encodePasteBlock(content) {
 function encodeImageBlock(absolutePath) {
     return `${IMG_BLOCK_START}${Buffer.from(absolutePath, 'utf8').toString('base64')}${IMG_BLOCK_END}`;
 }
+/**
+ * Probe the clipboard for an image and return the input-block to splice in at
+ * the cursor — an encoded `[IMG:…]` block on success, an inline
+ * `[Image rejected: …]` notice if the image was found but unusable, or null
+ * when there's no image. Shared by PromptTextInput's Ctrl+V path and VimInput
+ * (which renders instead of PromptTextInput in vim mode).
+ */
+async function readClipboardImageInjection() {
+    const img = await tryReadClipboardImage();
+    if (img && 'path' in img)
+        return encodeImageBlock(img.path);
+    if (img && 'error' in img)
+        return `[Image rejected: ${img.error}] `;
+    return null;
+}
 function decodeBlockPayload(token, startMarker, endMarker) {
     if (!token.startsWith(startMarker) || !token.endsWith(endMarker))
         return token;
@@ -126,6 +141,15 @@ function decodePromptValue(value) {
     }
     return decoded + value.slice(cursor);
 }
+function promptValueForDisplay(value) {
+    let rendered = '';
+    let cursor = 0;
+    for (const block of findPasteBlocks(value)) {
+        rendered += value.slice(cursor, block.start) + pasteSummary(block);
+        cursor = block.end;
+    }
+    return rendered + value.slice(cursor);
+}
 /**
  * Read the system clipboard, and if it currently holds an image, save it to
  * a temp file and return the absolute path. Otherwise return null.
@@ -378,6 +402,15 @@ function PromptTextInput({ value, onChange, onSubmit, placeholder = '', focus =
         onChange(nextValue);
         setCursorOffset(cursorOffsetRef.current);
     }, [onChange]);
+    const insertClipboardImageAt = useCallback((insertAt) => {
+        readClipboardImageInjection().then((injected) => {
+            if (!injected)
+                return; // no image on clipboard — nothing to do
+            const cur = valueRef.current;
+            const at = Math.min(insertAt, cur.length);
+            updateValue(cur.slice(0, at) + injected + cur.slice(at), at + injected.length);
+        }).catch(() => { });
+    }, [updateValue]);
     useInput((input, key) => {
         if (!focus)
             return;
@@ -393,7 +426,7 @@ function PromptTextInput({ value, onChange, onSubmit, placeholder = '', focus =
             pasteBufferRef.current = '';
         }
         if (key.return && !isPasting) {
-            onSubmit(decodePromptValue(currentValue));
+            onSubmit(currentValue);
             return;
         }
         if (key.home || (key.ctrl && input === 'a')) {
@@ -434,6 +467,13 @@ function PromptTextInput({ value, onChange, onSubmit, placeholder = '', focus =
             }
             return;
         }
+        // Some Linux terminals do not emit a bracketed-paste event for image-only
+        // clipboard contents. Ctrl+V gives users a raw-key fallback that probes the
+        // same clipboard image path without relying on terminal paste behavior.
+        if (key.ctrl && input === 'v') {
+            insertClipboardImageAt(currentCursorOffset);
+            return;
+        }
         if (key.upArrow || key.downArrow || key.tab || key.ctrl || key.meta)
             return;
         let text = normalizeInputNewlines(stripPasteMarkers(input));
@@ -515,7 +555,7 @@ function PromptTextInput({ value, onChange, onSubmit, placeholder = '', focus =
     return _jsx(Text, { children: rendered });
 }
 function formatUserPromptForDisplay(value) {
-    return `❯ ${decodePromptValue(value)}`;
+    return `❯ ${promptValueForDisplay(value)}`;
 }
 function disableTerminalAutoWrap() {
     if (!process.stdout.isTTY)
@@ -601,7 +641,7 @@ function InputBox({ input, setInput, onSubmit, model, balance, chain, walletTail
     const leadingGlyph = (awaitingApproval || awaitingAnswer)
         ? _jsx(Text, { color: "yellow", bold: true, children: "\u26A0 " })
         : (showSpinner ? _jsxs(Text, { color: "yellow", children: [_jsx(Spinner, { type: "dots" }), " "] }) : null);
-    return (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsxs(Box, { borderStyle: "round", borderColor: borderColor, borderDimColor: !borderColor, paddingX: 1, width: boxWidth, children: [leadingGlyph, _jsx(Box, { flexGrow: 1, children: vimMode ? (_jsx(VimInput, { value: input, onChange: setInput, onSubmit: onSubmit, placeholder: placeholder, focus: focused !== false, showMode: true, onModeChange: onVimModeChange })) : (_jsx(PromptTextInput, { value: input, onChange: setInput, onSubmit: onSubmit, placeholder: placeholder, focus: focused !== false })) })] }), _jsx(Box, { marginLeft: 2, children: _jsxs(Text, { dimColor: true, children: [busy ? _jsx(Text, { color: "yellow", children: _jsx(Spinner, { type: "dots" }) }) : null, busy ? ' ' : '', shortModelName(model), "  \u00B7  ", (() => {
+    return (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsxs(Box, { borderStyle: "round", borderColor: borderColor, borderDimColor: !borderColor, paddingX: 1, width: boxWidth, children: [leadingGlyph, _jsx(Box, { flexGrow: 1, children: vimMode ? (_jsx(VimInput, { value: input, onChange: setInput, onSubmit: onSubmit, placeholder: placeholder, focus: focused !== false, showMode: true, onModeChange: onVimModeChange, onClipboardImage: readClipboardImageInjection })) : (_jsx(PromptTextInput, { value: input, onChange: setInput, onSubmit: onSubmit, placeholder: placeholder, focus: focused !== false })) })] }), _jsx(Box, { marginLeft: 2, children: _jsxs(Text, { dimColor: true, children: [busy ? _jsx(Text, { color: "yellow", children: _jsx(Spinner, { type: "dots" }) }) : null, busy ? ' ' : '', shortModelName(model), "  \u00B7  ", (() => {
                             // Color the balance by funding state. Real session 2026-05-04
                             // had a user staring at "$0.08 USDC" in dim text wondering
                             // whether it meant "out of money" or "wrong chain". Make
@@ -1042,17 +1082,20 @@ function RunCodeApp({ initialModel, workDir, walletAddress, walletBalance, chain
                     turnTierRef.current = undefined;
                     turnSavingsRef.current = undefined;
                     turnCtxPctRef.current = undefined;
-                    onSubmit(lastPrompt);
+                    onSubmit(decodePromptValue(lastPrompt).trim());
                     return;
                 default:
-                    // All other slash commands pass through to the agent loop's command registry
+                    // All other slash commands pass through to the agent loop's command registry.
+                    // Decode here too: a slash command can carry an encoded paste/image block
+                    // as an argument, and the registry expects real text / file paths,
+                    // not the encoded block sentinels.
                     setStreamText('');
                     setThinking(false);
                     setThinkingText('');
                     setTools(new Map());
                     setWaiting(true);
                     setReady(false);
-                    onSubmit(trimmed);
+                    onSubmit(decodePromptValue(trimmed).trim());
                     return;
             }
         }
@@ -1091,7 +1134,7 @@ function RunCodeApp({ initialModel, workDir, walletAddress, walletBalance, chain
         turnTierRef.current = undefined;
         turnSavingsRef.current = undefined;
         turnCtxPctRef.current = undefined;
-        onSubmit(trimmed);
+        onSubmit(decodePromptValue(trimmed).trim());
     }, [ready, currentModel, totalCost, onSubmit, onModelChange, requestExit, lastPrompt, inputHistory, showStatus]);
     // Mouse support — OFF by default because Node stdin is shared: mouse escape
     // sequences leak into Ink's input handler as typed text. Opt in with

package/dist/ui/vim-input.d.ts

@@ -14,6 +14,11 @@ interface VimInputProps {
     focus?: boolean;
     showMode?: boolean;
     onModeChange?: (mode: VimMode) => void;
+    /** Probe the clipboard for an image and return the input-block to splice in
+     *  (or null if there's no image). Wired to the same path as PromptTextInput's
+     *  Ctrl+V fallback so vim-mode users on terminals that don't emit a
+     *  bracketed-paste event for images can still paste. */
+    onClipboardImage?: () => Promise<string | null>;
 }
-export default function VimInput({ value, onChange, onSubmit, placeholder, focus, showMode, onModeChange, }: VimInputProps): import("react/jsx-runtime").JSX.Element;
+export default function VimInput({ value, onChange, onSubmit, placeholder, focus, showMode, onModeChange, onClipboardImage, }: VimInputProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/ui/vim-input.js

@@ -56,13 +56,18 @@ function endWord(text, pos) {
         i++;
     return Math.min(i, text.length - 1);
 }
-export default function VimInput({ value, onChange, onSubmit, placeholder = '', focus = true, showMode = true, onModeChange, }) {
+export default function VimInput({ value, onChange, onSubmit, placeholder = '', focus = true, showMode = true, onModeChange, onClipboardImage, }) {
     const [mode, setMode] = useState('insert');
     const [cursor, setCursor] = useState(value.length);
     const [cmdBuf, setCmdBuf] = useState(''); // accumulated command buffer (for counts + operators)
     const [yankBuf, setYankBuf] = useState(''); // internal clipboard
     const [undoStack, setUndoStack] = useState([]); // simple undo
     const lastValueRef = useRef(value);
+    // Mirror the latest value prop every render so the async Ctrl+V clipboard
+    // insert (which resolves after the keypress) never splices into a stale
+    // string when the parent swaps `value` mid-probe — e.g. a submit clears the
+    // input, or another paste path writes first.
+    lastValueRef.current = value;
     // Keep cursor in bounds when value changes externally
     const clampedCursor = Math.min(cursor, mode === 'normal' ? Math.max(0, value.length - 1) : value.length);
     const switchMode = useCallback((newMode) => {
@@ -155,6 +160,24 @@ export default function VimInput({ value, onChange, onSubmit, placeholder = '',
                 updateValue(value.slice(0, clampedCursor), clampedCursor);
                 return;
             }
+            // Ctrl+V: clipboard-image fallback for terminals that don't emit a
+            // bracketed-paste event for image-only clipboards. Probe is async, so the
+            // handler returns now and updateValue happens when it resolves; capture
+            // the cursor offset so the block lands where the user pasted.
+            if (key.ctrl && input === 'v') {
+                if (onClipboardImage) {
+                    const at = clampedCursor;
+                    saveUndo();
+                    onClipboardImage().then((injected) => {
+                        if (!injected)
+                            return;
+                        const cur = lastValueRef.current;
+                        const pos = Math.min(at, cur.length);
+                        updateValue(cur.slice(0, pos) + injected + cur.slice(pos), pos + injected.length);
+                    }).catch(() => { });
+                }
+                return;
+            }
             // Skip control chars and tab
             if (key.ctrl || key.meta || key.tab)
                 return;

package/package.json

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