@blockrun/franklin 3.15.1 → 3.15.3

package/dist/agent/tool-guard.d.ts

@@ -1,4 +1,5 @@
 import type { CapabilityInvocation, CapabilityResult, ExecutionScope } from './types.js';
+export declare const BLOCKING_POLL_LOOP_RE: RegExp;
 export declare function normalizeSearchQuery(query: string): {
     normalized: string;
     tokens: string[];

package/dist/agent/tool-guard.js

@@ -38,6 +38,13 @@ function globKey(invocation) {
     const path = normalizePath(String(invocation.input.path ?? ''));
     return `${pattern}::${path}`;
 }
+// Detect a blocking poll-loop in a foreground bash command:
+// any `for|while|until` loop containing a `sleep` of ≥1 second. This is
+// the canonical antipattern that makes the agent feel frozen — see
+// beforeBash() for the full rationale and the recommended alternatives.
+// Use [\s\S] for cross-line match so we catch multi-line scripts; require
+// `sleep [1-9]` so trivial `sleep 0` / `sleep 0.1` micro-pauses don't trip.
+export const BLOCKING_POLL_LOOP_RE = /\b(?:for|while|until)\b[\s\S]*?\bsleep\s+[1-9]/;
 const WRITE_KEYWORDS = (() => {
     const words = [
         'rm', 'mv', 'cp', 'mkdir', 'touch', 'chmod', 'chown', 'ln',
@@ -212,6 +219,30 @@ export class SessionToolGuard {
         const cmd = String(invocation.input.command ?? '').trim();
         if (!cmd)
             return null;
+        // Reject blocking poll-loops in foreground bash. A single bash call with
+        // `sleep N` inside a for/while/until loop blocks the agent for the full
+        // duration — the UI repeats the same status line and the user almost
+        // always cancels before it finishes. The right pattern is `Detach`
+        // (persistent background task) or `run_in_background: true`.
+        const runInBackground = Boolean(invocation.input.run_in_background);
+        if (!runInBackground && BLOCKING_POLL_LOOP_RE.test(cmd)) {
+            return {
+                output: 'Blocked: this Bash command runs `sleep` inside a for/while/until loop in the ' +
+                    'foreground. That blocks the agent for the full poll duration and looks frozen ' +
+                    'to the user — they almost always cancel before it finishes.\n\n' +
+                    'Use the `Detach` tool for polling-style work (waiting for an Apify run, video ' +
+                    'generation, deploy, build, or any external async job to complete). It returns ' +
+                    'a runId immediately and the polling continues persistently. Check status later ' +
+                    'with `franklin task wait <runId>` or `franklin task tail <runId>` via a ' +
+                    'separate Bash call.\n\n' +
+                    'If you need the result inline, break the loop into discrete single-poll Bash ' +
+                    'calls — poll once, reason about the status, then decide whether to poll again. ' +
+                    'Or, if the upstream API has a sync variant (e.g. Apify\'s ' +
+                    '`run-sync-get-dataset-items`), use that with a `timeout` of 300000–600000 ms ' +
+                    'instead of orchestrating async + poll yourself.',
+                isError: true,
+            };
+        }
         // Only dedup deterministic read-only commands. Skip anything writing/network/long-running.
         if (WRITE_KEYWORDS.test(cmd))
             return null;

package/dist/tools/bash.js

@@ -511,6 +511,10 @@ IMPORTANT: Avoid using this tool to run \`find\`, \`grep\`, \`cat\`, \`head\`, \
 - Avoid unnecessary \`sleep\` commands:
   - Do not sleep between commands that can run immediately — just run them.
   - Do not retry failing commands in a sleep loop — diagnose the root cause.
+  - Do NOT write \`sleep\` inside a for/while/until loop in a single foreground Bash call to poll an external async job. That blocks the agent for the whole poll duration and looks frozen to the user; they will cancel before it finishes. Pick one:
+    1. Use the \`Detach\` tool for polling-style work (waiting for an Apify run, video generation, deploy, or build to complete). It returns a runId immediately and the polling runs persistently; check status later with \`franklin task wait/tail <runId>\`.
+    2. Use the upstream sync endpoint when one exists (e.g. Apify's \`run-sync-get-dataset-items\`) with an explicit \`timeout\` up to 600000ms — usually simpler than orchestrating async + poll yourself.
+    3. Break the poll into discrete single-call polls — one poll per Bash call, reason about the status between calls, decide whether to poll again. The user can then see progress and course-correct.
 
 Output is capped at 512KB capture / 32KB return.`,
         input_schema: {

package/dist/tools/detach.js

@@ -32,13 +32,16 @@ export const detachCapability = {
         description: "Run a Bash command as a detached background job. Returns immediately " +
             "with a runId. The command continues even if Franklin exits or the user " +
             "closes their terminal. Use this for any iteration over more than ~20 " +
-            "items, large data fetches, paginated API loops, or anything you'd " +
-            "otherwise loop on turn-by-turn (which would burn turns and trip " +
-            "timeouts). The agent's job is to design and orchestrate, not to be " +
-            "the for-loop. Pair with a script that writes a checkpoint file so " +
-            "progress survives restarts. Tail logs with `franklin task tail " +
-            "<runId> --follow` and check completion with `franklin task wait " +
-            "<runId>`.",
+            "items, large data fetches, paginated API loops, polling external async " +
+            "jobs (waiting for an Apify run / video generation / deploy / build to " +
+            "complete), or anything you'd otherwise loop on turn-by-turn (which " +
+            "would burn turns and trip timeouts). The agent's job is to design and " +
+            "orchestrate, not to be the for-loop. Pair with a script that writes a " +
+            "checkpoint file so progress survives restarts. Tail logs with " +
+            "`franklin task tail <runId> --follow` and check completion with " +
+            "`franklin task wait <runId>`. ALWAYS prefer Detach over a single " +
+            "foreground Bash call with `sleep` inside a for/while/until loop — that " +
+            "antipattern blocks the agent for the full duration and looks frozen.",
         input_schema: {
             type: 'object',
             properties: {

package/dist/ui/app.js

@@ -99,6 +99,11 @@ function formatAgentErrorForDisplay(error) {
 }
 function RunCodeApp({ initialModel, workDir, walletAddress, walletBalance, chain, startWithPicker, onSubmit, onModelChange, onAbort, onExit, }) {
     const { exit } = useApp();
+    // Track terminal rows so we can cap the dynamic-region height. Ink wipes the
+    // terminal scrollback (via ansiEscapes.clearTerminal → \x1b[3J) whenever the
+    // dynamic output exceeds rows, so any tall live region (streaming text,
+    // model picker) must be windowed to preserve "scroll to the start" history.
+    const { rows: termRows } = useTerminalSize();
     const [input, setInput] = useState('');
     const [streamText, setStreamText] = useState('');
     const [thinking, setThinking] = useState(false);
@@ -761,7 +766,7 @@ function RunCodeApp({ initialModel, workDir, walletAddress, walletBalance, chain
                                     setAskUserRequest(null);
                                     setAskUserInput('');
                                     r(answer);
-                                }, focus: true })] })] })), expandableTool && (() => {
+                                }, focus: true })] })] })), expandableTool && !permissionRequest && !askUserRequest && (() => {
                 const tool = expandableTool;
                 const elapsedFmt = tool.elapsed >= 1000
                     ? `${(tool.elapsed / 1000).toFixed(1)}s`
@@ -776,18 +781,46 @@ function RunCodeApp({ initialModel, workDir, walletAddress, walletBalance, chain
                         const lines = thinkingText.split('\n').filter(Boolean).slice(-3);
                         return (_jsx(Box, { flexDirection: "column", marginLeft: 2, children: lines.map((line, i) => (_jsxs(Text, { dimColor: true, wrap: "truncate-end", children: ['⎿  ', line.slice(0, 120)] }, i))) }));
                     })()] })), waiting && !thinking && tools.size === 0 && (_jsx(Box, { marginLeft: 2, children: _jsxs(Text, { color: "yellow", children: [_jsx(Spinner, { type: "dots" }), ' ', _jsxs(Text, { dimColor: true, children: [shortModelName(currentModel), completedTools.length > 0 ? ` · step ${completedTools.length + 1}` : ''] })] }) })), streamText && (() => {
-                const { rendered, partial } = renderMarkdownStreaming(streamText);
-                return (_jsx(Box, { marginTop: 0, marginBottom: 0, marginLeft: 2, children: _jsxs(Text, { wrap: "wrap", children: [rendered, rendered && partial ? '\n' : '', partial] }) }));
-            })(), responsePreview && !streamText && (_jsx(Box, { flexDirection: "column", marginBottom: 0, marginLeft: 2, children: _jsx(Text, { wrap: "wrap", children: renderMarkdown(responsePreview) }) })), inPicker && (() => {
-                let flatIdx = 0;
-                return (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsxs(Box, { marginLeft: 2, children: [_jsx(Text, { bold: true, children: "Select a model " }), _jsx(Text, { dimColor: true, children: "(\u2191\u2193 navigate, Enter select, Esc cancel)" })] }), PICKER_CATEGORIES.map((cat) => (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsx(Box, { marginLeft: 2, children: _jsxs(Text, { dimColor: true, children: ["\u2500\u2500 ", cat.category, " \u2500\u2500"] }) }), cat.models.map((m) => {
-                                    const myIdx = flatIdx++;
-                                    const isSelected = myIdx === pickerIdx;
-                                    const isCurrent = m.id === currentModel;
-                                    const isHighlight = m.highlight === true;
-                                    return (_jsxs(Box, { marginLeft: 2, children: [_jsxs(Text, { inverse: isSelected, color: isSelected ? 'cyan' : isHighlight ? 'yellow' : undefined, bold: isSelected || isHighlight, children: [' ', m.label.padEnd(26), ' '] }), _jsxs(Text, { dimColor: true, children: [" ", m.shortcut.padEnd(14)] }), _jsx(Text, { color: m.price === 'FREE' ? 'green' : isHighlight ? 'yellow' : undefined, dimColor: !isHighlight && m.price !== 'FREE', children: m.price }), isCurrent && _jsx(Text, { color: "green", children: " \u2190" })] }, m.id));
-                                })] }, cat.category))), _jsx(Box, { marginTop: 1, marginLeft: 2, children: _jsx(Text, { dimColor: true, children: "Your conversation stays above \u2014 picking a model keeps all history intact." }) })] }));
-            })(), !inPicker && (_jsx(InputBox, { input: (permissionRequest || askUserRequest) ? '' : input, setInput: (permissionRequest || askUserRequest) ? () => { } : setInput, onSubmit: (permissionRequest || askUserRequest) ? () => { } : handleSubmit, model: currentModel, balance: liveBalance, chain: chain, walletTail: walletAddress && walletAddress.length >= 4 && !walletAddress.startsWith('not set') ? walletAddress.slice(-4) : undefined, sessionCost: totalCost, queued: queuedInputs[0] || undefined, queuedCount: queuedInputs.length, focused: !permissionRequest && !askUserRequest, busy: !askUserRequest && (waiting || thinking || tools.size > 0), contextPct: contextPct, vimMode: vimEnabled, onVimModeChange: setCurrentVimMode }))] }));
+                const maxLines = Math.max(8, termRows - 12);
+                const lines = streamText.split('\n');
+                const truncated = lines.length > maxLines;
+                const visible = truncated ? lines.slice(-maxLines).join('\n') : streamText;
+                const { rendered, partial } = renderMarkdownStreaming(visible);
+                return (_jsxs(Box, { flexDirection: "column", marginTop: 0, marginBottom: 0, marginLeft: 2, children: [truncated && (_jsxs(Text, { dimColor: true, children: ["\u2191 ", lines.length - maxLines, " earlier line", lines.length - maxLines === 1 ? '' : 's', " \u2014 full response will appear in scrollback when this turn finishes"] })), _jsxs(Text, { wrap: "wrap", children: [rendered, rendered && partial ? '\n' : '', partial] })] }));
+            })(), responsePreview && !streamText && !permissionRequest && !askUserRequest && (_jsx(Box, { flexDirection: "column", marginBottom: 0, marginLeft: 2, children: _jsx(Text, { wrap: "wrap", children: renderMarkdown(responsePreview) }) })), inPicker && (() => {
+                const totalModels = PICKER_MODELS_FLAT.length;
+                const maxModels = Math.max(6, termRows - 12);
+                let start = Math.max(0, pickerIdx - Math.floor(maxModels / 2));
+                let end = Math.min(totalModels, start + maxModels);
+                // Expand window backward if we hit the bottom of the list, so we
+                // always fill `maxModels` rows when the list is long enough.
+                if (end - start < maxModels)
+                    start = Math.max(0, end - maxModels);
+                const hiddenAbove = start;
+                const hiddenBelow = totalModels - end;
+                // Pre-compute each category's base offset into the flat model list so
+                // we can map (cat, localIdx) → globalIdx in one pass without re-walking.
+                let cursor = 0;
+                const catBases = PICKER_CATEGORIES.map((cat) => {
+                    const base = cursor;
+                    cursor += cat.models.length;
+                    return base;
+                });
+                return (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsxs(Box, { marginLeft: 2, children: [_jsx(Text, { bold: true, children: "Select a model " }), _jsx(Text, { dimColor: true, children: "(\u2191\u2193 navigate, Enter select, Esc cancel)" })] }), hiddenAbove > 0 && (_jsx(Box, { marginLeft: 2, marginTop: 1, children: _jsxs(Text, { dimColor: true, children: ["\u2191 ", hiddenAbove, " more above"] }) })), PICKER_CATEGORIES.map((cat, catIdx) => {
+                            const base = catBases[catIdx];
+                            const visible = cat.models
+                                .map((m, localIdx) => ({ m, globalIdx: base + localIdx }))
+                                .filter(({ globalIdx }) => globalIdx >= start && globalIdx < end);
+                            if (visible.length === 0)
+                                return null;
+                            return (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsx(Box, { marginLeft: 2, children: _jsxs(Text, { dimColor: true, children: ["\u2500\u2500 ", cat.category, " \u2500\u2500"] }) }), visible.map(({ m, globalIdx }) => {
+                                        const isSelected = globalIdx === pickerIdx;
+                                        const isCurrent = m.id === currentModel;
+                                        const isHighlight = m.highlight === true;
+                                        return (_jsxs(Box, { marginLeft: 2, children: [_jsxs(Text, { inverse: isSelected, color: isSelected ? 'cyan' : isHighlight ? 'yellow' : undefined, bold: isSelected || isHighlight, children: [' ', m.label.padEnd(26), ' '] }), _jsxs(Text, { dimColor: true, children: [" ", m.shortcut.padEnd(14)] }), _jsx(Text, { color: m.price === 'FREE' ? 'green' : isHighlight ? 'yellow' : undefined, dimColor: !isHighlight && m.price !== 'FREE', children: m.price }), isCurrent && _jsx(Text, { color: "green", children: " \u2190" })] }, m.id));
+                                    })] }, cat.category));
+                        }), hiddenBelow > 0 && (_jsx(Box, { marginLeft: 2, marginTop: 1, children: _jsxs(Text, { dimColor: true, children: ["\u2193 ", hiddenBelow, " more below"] }) })), _jsx(Box, { marginTop: 1, marginLeft: 2, children: _jsx(Text, { dimColor: true, children: "Your conversation stays above \u2014 picking a model keeps all history intact." }) })] }));
+            })(), !inPicker && !permissionRequest && !askUserRequest && (_jsx(InputBox, { input: input, setInput: setInput, onSubmit: handleSubmit, model: currentModel, balance: liveBalance, chain: chain, walletTail: walletAddress && walletAddress.length >= 4 && !walletAddress.startsWith('not set') ? walletAddress.slice(-4) : undefined, sessionCost: totalCost, queued: queuedInputs[0] || undefined, queuedCount: queuedInputs.length, focused: !permissionRequest && !askUserRequest, busy: !askUserRequest && (waiting || thinking || tools.size > 0), contextPct: contextPct, vimMode: vimEnabled, onVimModeChange: setCurrentVimMode }))] }));
 }
 export function launchInkUI(opts) {
     let resolveInput = null;

package/package.json

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