@blockrun/franklin 3.25.1 → 3.25.3

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

@@ -19,6 +19,7 @@ import { estimateCost } from '../pricing.js';
 import { formatTokens, shortModelName } from '../stats/format.js';
 import { mouse, forceDisableMouseTracking } from './mouse.js';
 import { resolveAskUserAnswer } from './ask-user-answer.js';
+import { looksLikeImagePasteStub } from './paste-heuristics.js';
 // ─── Full-width input box ──────────────────────────────────────────────────
 const BRACKETED_PASTE_START = '[200~';
 const BRACKETED_PASTE_END = '[201~';
@@ -445,53 +446,58 @@ function PromptTextInput({ value, onChange, onSubmit, placeholder = '', focus =
             const buffered = pasteBufferRef.current;
             pasteBufferRef.current = '';
             pasteActiveRef.current = false;
-            // Image-paste detection. Original heuristic (3.25.0) only probed the
-            // clipboard when the bracketed-paste buffer was empty, assuming Cmd+V
-            // on an image-only clipboard always arrived as an empty paste. That
-            // assumption holds for macOS Terminal/iTerm2 but NOT for several Linux
-            // terminals — some send a filename, a `file://` URI, or a short binary
-            // header alongside the image, which made the gate skip the probe and
-            // the image silently dropped (user-reported on Kali: the clipboard
-            // image was readable by other tools but Franklin couldn't paste it).
-            // Verified in a Lima Ubuntu VM with xclip — non-empty buffer triggered
-            // the skip.
-            //
-            // Fix: ALWAYS probe the clipboard on a paste-end. If an image is there,
-            // it wins; the bracketed-paste buffer text is treated as terminal noise
-            // and dropped. If no image, fall through to the normal text-paste path
-            // (collapse-to-block or inline) so text pastes are unaffected. The
-            // probe is async (osascript / xclip / wl-paste shell-out, 30-100 ms),
-            // so the handler returns immediately and updateValue happens when the
-            // Promise resolves.
+            // Image-paste detection. Cmd+V on a clipboard image arrives as an empty
+            // bracketed paste on macOS Terminal/iTerm2; several Linux terminals
+            // instead emit a filename, a `file://` URI, or the raw image header
+            // alongside it (3.25.0 only probed on an empty buffer, so those Linux
+            // shapes silently dropped the image — fixed in #77). We probe the system
+            // clipboard for an image only when the buffer *looks* like one of those
+            // stubs; genuine text is inserted synchronously below so the common
+            // paste path never waits on the async osascript / xclip / wl-paste
+            // shell-out (30-100 ms, but a cold spawn can be more).
             const insertAt = currentCursorOffset;
-            tryReadClipboardImage().then((img) => {
-                if (img && 'path' in img) {
-                    // Image wins — drop the bracketed-paste buffer (likely a stub the
-                    // terminal sent for the image).
-                    const injected = encodeImageBlock(img.path);
-                    const cur = valueRef.current;
-                    const at = Math.min(insertAt, cur.length);
-                    updateValue(cur.slice(0, at) + injected + cur.slice(at), at + injected.length);
+            const insertPastedText = (buf, baseOffset) => {
+                if (buf.length === 0)
                     return;
-                }
-                if (img && 'error' in img) {
-                    const injected = `[Image rejected: ${img.error}] `;
-                    const cur = valueRef.current;
-                    const at = Math.min(insertAt, cur.length);
-                    updateValue(cur.slice(0, at) + injected + cur.slice(at), at + injected.length);
-                    return;
-                }
-                // No image on the clipboard — treat as a normal text paste.
-                if (buffered.length === 0)
-                    return;
-                const lineCount = buffered.split('\n').length;
+                const lineCount = buf.split('\n').length;
                 const textToInsert = lineCount >= PASTE_COLLAPSE_LINE_THRESHOLD
-                    ? encodePasteBlock(buffered)
-                    : buffered;
+                    ? encodePasteBlock(buf)
+                    : buf;
                 const cur = valueRef.current;
-                const at = Math.min(insertAt, cur.length);
+                const at = Math.min(baseOffset, cur.length);
                 updateValue(cur.slice(0, at) + textToInsert + cur.slice(at), at + textToInsert.length);
-            }).catch(() => { });
+            };
+            if (looksLikeImagePasteStub(buffered)) {
+                // The probe is async; the handler returns now and updateValue happens
+                // when the Promise resolves. insertAt (captured above) pins the result
+                // to where the user pasted even if the cursor moved meanwhile.
+                tryReadClipboardImage().then((img) => {
+                    if (img && 'path' in img) {
+                        // Image wins — drop the bracketed-paste buffer (the terminal stub).
+                        const injected = encodeImageBlock(img.path);
+                        const cur = valueRef.current;
+                        const at = Math.min(insertAt, cur.length);
+                        updateValue(cur.slice(0, at) + injected + cur.slice(at), at + injected.length);
+                        return;
+                    }
+                    if (img && 'error' in img) {
+                        const injected = `[Image rejected: ${img.error}] `;
+                        const cur = valueRef.current;
+                        const at = Math.min(insertAt, cur.length);
+                        updateValue(cur.slice(0, at) + injected + cur.slice(at), at + injected.length);
+                        return;
+                    }
+                    // No image after all — the stub was literal text (e.g. a lone
+                    // "photo.png" the user actually typed). Insert it as text.
+                    insertPastedText(buffered, insertAt);
+                }).catch(() => {
+                    // Probe failed unexpectedly — don't lose the paste; insert as text.
+                    insertPastedText(buffered, insertAt);
+                });
+                return;
+            }
+            // Genuine text paste — insert synchronously, no clipboard probe.
+            insertPastedText(buffered, currentCursorOffset);
             return;
         }
         if (!text) {

package/dist/ui/paste-heuristics.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Pure heuristics for the bracketed-paste handler in app.tsx, split out so they
+ * can be unit-tested without pulling in Ink/React.
+ */
+/**
+ * Does a bracketed-paste buffer look like a terminal's stand-in for an image
+ * paste rather than genuine pasted text?
+ *
+ * Cmd+V on a clipboard image yields an *empty* buffer on macOS Terminal/iTerm2,
+ * but several Linux terminals instead emit a filename, a `file://` URI, or the
+ * raw image header alongside the paste. Those shapes — and only those — warrant
+ * the (async, 30-100 ms) clipboard probe in app.tsx. Substantial text returns
+ * `false` so it can be inserted synchronously, keeping the common paste path
+ * instant instead of waiting on an osascript / xclip / wl-paste shell-out.
+ *
+ * False positives are harmless: a literal text paste of "photo.png" probes the
+ * clipboard, finds no image, and falls through to the text path anyway.
+ */
+export declare function looksLikeImagePasteStub(buffered: string): boolean;

package/dist/ui/paste-heuristics.js

@@ -0,0 +1,40 @@
+/**
+ * Pure heuristics for the bracketed-paste handler in app.tsx, split out so they
+ * can be unit-tested without pulling in Ink/React.
+ */
+// Image filenames a terminal might substitute for a pasted image. Anchored, so
+// only a string that *is* such a path matches — not prose that mentions one.
+const IMAGE_FILE_EXT = /\.(png|jpe?g|gif|webp|bmp|tiff?|heic|heif|avif)$/i;
+/**
+ * Does a bracketed-paste buffer look like a terminal's stand-in for an image
+ * paste rather than genuine pasted text?
+ *
+ * Cmd+V on a clipboard image yields an *empty* buffer on macOS Terminal/iTerm2,
+ * but several Linux terminals instead emit a filename, a `file://` URI, or the
+ * raw image header alongside the paste. Those shapes — and only those — warrant
+ * the (async, 30-100 ms) clipboard probe in app.tsx. Substantial text returns
+ * `false` so it can be inserted synchronously, keeping the common paste path
+ * instant instead of waiting on an osascript / xclip / wl-paste shell-out.
+ *
+ * False positives are harmless: a literal text paste of "photo.png" probes the
+ * clipboard, finds no image, and falls through to the text path anyway.
+ */
+export function looksLikeImagePasteStub(buffered) {
+    // macOS image paste: empty / whitespace-only bracketed paste.
+    if (buffered.trim().length === 0)
+        return true;
+    // Raw binary the terminal dumped (e.g. PNG's \x1a, or bytes that failed
+    // UTF-8 decoding into U+FFFD). Genuine text never carries control chars
+    // other than tab / newline / carriage return.
+    if (/[\x00-\x08\x0b\x0c\x0e-\x1f�]/.test(buffered))
+        return true;
+    // A single-line file reference the terminal sent instead of the image bytes.
+    const trimmed = buffered.trim();
+    if (!trimmed.includes('\n')) {
+        if (/^file:\/\//i.test(trimmed))
+            return true; // file:// URI
+        if (IMAGE_FILE_EXT.test(trimmed))
+            return true; // bare filename / path
+    }
+    return false;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/franklin",
-  "version": "3.25.1",
+  "version": "3.25.3",
   "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": {