@blockrun/franklin 3.16.4 → 3.17.0

package/dist/agent/context.js

@@ -150,7 +150,17 @@ RULES (violations will produce garbage output):
 6. End with: "Reply to any? Give me the number."
 7. Do NOT auto-post. Do NOT explain how the social system works.
 
-When checking notifications/mentions: Use SearchX with mode="notifications". One call, done.`;
+When the user pastes a specific tweet URL (https://x.com/<user>/status/<id>): Call SearchX with the URL as the query. The tool auto-detects URL mode and reads the post directly. Do NOT search for the URL as a keyword (always returns empty), and do NOT try WebFetch on x.com.
+
+When checking notifications/mentions: Use SearchX with mode="notifications". One call, done.
+
+If SearchX returns empty or "no article extracted" on a URL/query you believe SHOULD have content (you can see the page in the browser, or the user confirms it exists), DO NOT give up — drop down to the BrowserX primitive and drive the browser yourself:
+  1. BrowserX action="snapshot" → see what's on screen right now
+  2. BrowserX action="scroll" dy=600 → trigger lazy-render / load more
+  3. BrowserX action="snapshot" again → re-inspect after scroll
+  4. BrowserX action="click" ref=<id> → follow a permalink (refs come from the last snapshot)
+  5. BrowserX action="open" url=<other> → try a different URL (e.g. /search?q=… or a profile page)
+BrowserX shares the logged-in X session with SearchX, so authentication is already handled. Use BrowserX only for read/navigation; replies still go through PostToX with explicit user confirmation.`;
 }
 function getMissingAccessSection() {
     return `# Missing Access

package/dist/agent/error-classifier.js

@@ -184,6 +184,21 @@ export function classifyAgentError(message) {
             suggestion: 'Tool schema rejected by this model. Try /model to switch to a more permissive model (e.g. sonnet), or upgrade Franklin.',
         };
     }
+    // Unknown / typo'd model id — gateway returns HTTP 400 with a body like
+    // "Unknown model: moonshot/kimi-k2". Without this branch the error falls
+    // through to the catch-all 'unknown' category and shows the user a bare
+    // "Type: Unknown" with no actionable next step.
+    if (includesAny(err, [
+        'unknown model',
+        'model not found',
+        'model does not exist',
+        'no such model',
+    ])) {
+        return {
+            category: 'schema', label: 'Schema', isTransient: false, maxRetries: 0,
+            suggestion: 'The gateway rejected the model id (unknown / typo). Use /model to pick a valid one, or upgrade Franklin if a fallback chain references a stale id.',
+        };
+    }
     if (includesAny(err, [
         '500',
         '502',

package/dist/agent/loop.js

@@ -341,6 +341,13 @@ export function looksLikeStalledIntent(text) {
     const trimmed = text.trim();
     if (trimmed.length < 24)
         return false;
+    // If the final non-empty line is a short question to the user, the model is
+    // explicitly deferring ("Which would you prefer?", "Want me to proceed?") —
+    // that's a handoff, not a stall. Avoid re-invoking on another model and
+    // billing twice for what is in fact correct behavior.
+    const lastLine = trimmed.split(/\n+/).map(s => s.trim()).filter(Boolean).pop() ?? '';
+    if (lastLine.length > 0 && lastLine.length <= 120 && /[?？]\s*$/.test(lastLine))
+        return false;
     // Look at the last ~400 chars only — intent-to-act lives near the end.
     const tail = trimmed.slice(-400).toLowerCase();
     // Strong "I'm about to do something" markers near the tail.
@@ -1336,7 +1343,7 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
                         // Excludes nvidia/* and *-coder-* — they're the source population.
                         const TOOL_USE_FALLBACK_MODELS = [
                             'anthropic/claude-haiku-4.5',
-                            'moonshot/kimi-k2',
+                            'moonshot/kimi-k2.6',
                             'openai/gpt-5',
                             'anthropic/claude-sonnet-4.6',
                         ];

package/dist/agent/permissions.js

@@ -33,10 +33,10 @@ function isCommonDevCommand(cmd) {
     return COMMON_DEV_PATTERNS.some(p => p.test(trimmed));
 }
 // ─── Default Rules ─────────────────────────────────────────────────────────
-const READ_ONLY_TOOLS = new Set(['Read', 'Glob', 'Grep', 'WebSearch', 'Task', 'AskUser', 'ActivateTool', 'ImageGen', 'TradingSignal', 'TradingMarket', 'SearchX']);
+const READ_ONLY_TOOLS = new Set(['Read', 'Glob', 'Grep', 'WebSearch', 'Task', 'AskUser', 'ActivateTool', 'ImageGen', 'TradingSignal', 'TradingMarket', 'SearchX', 'BrowserX']);
 const DESTRUCTIVE_TOOLS = new Set(['Write', 'Edit', 'Bash']);
 const DEFAULT_RULES = {
-    allow: ['Read', 'Glob', 'Grep', 'WebSearch', 'WebFetch', 'Task', 'AskUser', 'ActivateTool', 'ImageGen', 'TradingSignal', 'TradingMarket', 'SearchX'],
+    allow: ['Read', 'Glob', 'Grep', 'WebSearch', 'WebFetch', 'Task', 'AskUser', 'ActivateTool', 'ImageGen', 'TradingSignal', 'TradingMarket', 'SearchX', 'BrowserX'],
     deny: [],
     ask: ['Write', 'Edit', 'Bash', 'Agent', 'PostToX'],
 };

package/dist/agent/tool-guard.js

@@ -183,6 +183,13 @@ export class SessionToolGuard {
     startTurn() {
         this.turn++;
         this.webSearchesThisTurn = 0;
+        // The per-tool circuit breaker exists to stop a model from burning a
+        // whole turn re-attacking a wall. It must NOT outlive the user turn that
+        // earned the failures — a fresh prompt is a fresh intent. Without this
+        // reset, three failed Bash calls (e.g. `franklin social login x` on a
+        // host without the right env) permanently disable Bash for the rest of
+        // the session, even on completely unrelated follow-ups.
+        this.toolErrorCounts.clear();
         for (const family of this.searchFamilies) {
             family.turnSearches = 0;
         }
@@ -233,6 +240,32 @@ export class SessionToolGuard {
         const cmd = String(invocation.input.command ?? '').trim();
         if (!cmd)
             return null;
+        // Reject interactive franklin subcommands that require the human at the
+        // keyboard (they spawn a non-headless Chrome and wait for the user to
+        // close it). If the agent runs them via Bash they block until timeout,
+        // burn a tool-failure strike, and contribute nothing. Tell the agent to
+        // ask the user to run them in a separate terminal instead.
+        if (/^\s*franklin\s+social\s+(login|setup)\b/.test(cmd)) {
+            return {
+                output: 'Blocked: `franklin social login` / `franklin social setup` are INTERACTIVE — ' +
+                    'they open a Chrome window the human must drive and close. They cannot run from ' +
+                    'an agent Bash call (they will hang then time out). ' +
+                    'Ask the user to run this in their own terminal, then continue once they say it is done.',
+                isError: true,
+            };
+        }
+        // `franklin social run` is a batch poster/replier that loops over the
+        // user's configured search_queries — it is not the right tool for
+        // "read this specific tweet" or "draft replies to one post". Steer the
+        // agent to SearchX (now URL-aware) instead.
+        if (/^\s*franklin\s+social\s+run\b/.test(cmd)) {
+            return {
+                output: 'Blocked: `franklin social run` is a batch reply loop over the user\'s configured ' +
+                    'queries, not a single-tweet reader. Use the SearchX tool instead — pass a tweet URL ' +
+                    'as the query to read one post, or use mode="search"/"notifications" for discovery.',
+                isError: true,
+            };
+        }
         // 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

package/dist/social/browser.js

@@ -21,6 +21,64 @@ function ensureProfileDir() {
         fs.mkdirSync(SOCIAL_PROFILE_DIR, { recursive: true });
     }
 }
+// Chrome leaves a few singleton lock files in the user-data-dir when running.
+// If the previous Chromium process crashed (or franklin was killed with -9)
+// these files survive even though no real Chrome owns the profile. The next
+// launchPersistentContext sees them and refuses to start the browser. We
+// detect that case (lock exists + no process), remove the locks, and retry.
+const SINGLETON_LOCKS = ['SingletonLock', 'SingletonCookie', 'SingletonSocket'];
+function readSingletonOwnerPid() {
+    // On macOS/Linux, Chrome writes the PID into SingletonLock as a symlink
+    // target like "hostname-12345". Parse it; if any token is a live PID, the
+    // profile is genuinely in use.
+    const lockPath = path.join(SOCIAL_PROFILE_DIR, 'SingletonLock');
+    try {
+        const target = fs.readlinkSync(lockPath);
+        const match = /-(\d+)$/.exec(target);
+        if (!match)
+            return null;
+        const pid = Number.parseInt(match[1], 10);
+        return Number.isFinite(pid) ? pid : null;
+    }
+    catch {
+        return null;
+    }
+}
+function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // ESRCH = no such process. EPERM = exists but we can't signal it (still alive).
+        return err.code === 'EPERM';
+    }
+}
+function clearStaleSingletonLocks() {
+    const pid = readSingletonOwnerPid();
+    if (pid !== null && isPidAlive(pid))
+        return false; // real Chrome still using it
+    let removedAny = false;
+    for (const name of SINGLETON_LOCKS) {
+        const p = path.join(SOCIAL_PROFILE_DIR, name);
+        try {
+            fs.rmSync(p, { force: true });
+            removedAny = true;
+        }
+        catch {
+            // ignore — file may simply not exist
+        }
+    }
+    return removedAny;
+}
+function isProfileLockError(msg) {
+    const m = msg.toLowerCase();
+    return (m.includes('profile') && (m.includes('in use') || m.includes('locked')) ||
+        m.includes('singletonlock') ||
+        m.includes('processsingleton') ||
+        m.includes('user data directory is already in use') ||
+        m.includes('failed to create a chromedriver'));
+}
 /**
  * Walk an AX tree and produce:
  *   1. A flat text dump with [depth-idx] refs (for regex-based element finding)
@@ -148,18 +206,19 @@ export class SocialBrowser {
         // Lazy import — playwright-core is ~2MB and we don't want to pay the
         // import cost on every franklin command (e.g. `franklin --version`)
         const { chromium } = await import('playwright-core');
+        const launchOnce = () => chromium.launchPersistentContext(SOCIAL_PROFILE_DIR, {
+            headless: this.opts.headless,
+            channel: this.opts.channel,
+            slowMo: this.opts.slowMo,
+            viewport: this.opts.viewport,
+            // Pretend to be a regular Chrome (not headless fingerprint)
+            args: [
+                '--disable-blink-features=AutomationControlled',
+                '--no-default-browser-check',
+            ],
+        });
         try {
-            this.context = await chromium.launchPersistentContext(SOCIAL_PROFILE_DIR, {
-                headless: this.opts.headless,
-                channel: this.opts.channel,
-                slowMo: this.opts.slowMo,
-                viewport: this.opts.viewport,
-                // Pretend to be a regular Chrome (not headless fingerprint)
-                args: [
-                    '--disable-blink-features=AutomationControlled',
-                    '--no-default-browser-check',
-                ],
-            });
+            this.context = await launchOnce();
         }
         catch (err) {
             const msg = err.message;
@@ -168,7 +227,33 @@ export class SocialBrowser {
                     `Or install manually:\n  npx playwright install chromium\n\n` +
                     `Original error: ${msg}`);
             }
-            throw err;
+            // Stale singleton-lock from a crashed Chrome / killed franklin. If no
+            // live PID owns the lock, scrub it and retry once. Don't auto-clean
+            // when a real process still owns the profile — that would corrupt
+            // their running session.
+            if (isProfileLockError(msg) || msg.toLowerCase().includes('failed to launch')) {
+                const cleared = clearStaleSingletonLocks();
+                if (cleared) {
+                    try {
+                        this.context = await launchOnce();
+                    }
+                    catch (err2) {
+                        throw new Error(`Chrome profile lock recovery failed. The profile dir at\n  ${SOCIAL_PROFILE_DIR}\n` +
+                            `had stale lock files; we removed them and retried, but launch still failed.\n` +
+                            `Close any running Chrome/Chromium using this profile and try again.\n\n` +
+                            `Original error: ${msg}\nRetry error: ${err2.message}`);
+                    }
+                }
+                else {
+                    throw new Error(`Chrome profile is in use at\n  ${SOCIAL_PROFILE_DIR}\n` +
+                        `Another franklin instance (or a Chrome with that user-data-dir) is running.\n` +
+                        `Close it and retry, or run: pkill -f social-chrome-profile\n\n` +
+                        `Original error: ${msg}`);
+                }
+            }
+            else {
+                throw err;
+            }
         }
         // Reuse existing tab if any, else open new
         const existing = this.context.pages();

package/dist/tools/browsex.d.ts

@@ -0,0 +1,17 @@
+/**
+ * BrowserX capability — low-level primitives over Franklin's social Chrome
+ * profile. Use this when SearchX's pattern matcher is too rigid and the
+ * agent needs to drive the browser iteratively: open arbitrary URLs, take
+ * fresh snapshots, scroll to load more, screenshot the viewport.
+ *
+ * Shares the same persistent profile as SearchX/PostToX (~/.blockrun/
+ * social-chrome-profile) so the X login session is reused for free.
+ *
+ * Intentionally OMITS post-side actions (type/press/click on form fields).
+ * Replying still goes through PostToX, which has its own confirmation flow.
+ * `click` IS exposed because clicking is how you navigate on an SPA — the
+ * model is instructed to only click navigation elements (tweet permalinks,
+ * profile links, "Show more"), never reply/like/follow buttons.
+ */
+import type { CapabilityHandler } from '../agent/types.js';
+export declare const browserXCapability: CapabilityHandler;

package/dist/tools/browsex.js

@@ -0,0 +1,156 @@
+/**
+ * BrowserX capability — low-level primitives over Franklin's social Chrome
+ * profile. Use this when SearchX's pattern matcher is too rigid and the
+ * agent needs to drive the browser iteratively: open arbitrary URLs, take
+ * fresh snapshots, scroll to load more, screenshot the viewport.
+ *
+ * Shares the same persistent profile as SearchX/PostToX (~/.blockrun/
+ * social-chrome-profile) so the X login session is reused for free.
+ *
+ * Intentionally OMITS post-side actions (type/press/click on form fields).
+ * Replying still goes through PostToX, which has its own confirmation flow.
+ * `click` IS exposed because clicking is how you navigate on an SPA — the
+ * model is instructed to only click navigation elements (tweet permalinks,
+ * profile links, "Show more"), never reply/like/follow buttons.
+ */
+import path from 'node:path';
+import os from 'node:os';
+import { browserPool } from '../social/browser-pool.js';
+const MAX_WAIT_MS = 15_000;
+function summariseTree(tree, max = 8000) {
+    if (tree.length <= max)
+        return tree;
+    return tree.slice(0, max) + `\n\n[…truncated; tree was ${tree.length} chars total]`;
+}
+async function execute(input, _ctx) {
+    const { action, url, ref, dy, ms, path: outPath } = input;
+    if (!action) {
+        return { output: 'Error: action is required (open|snapshot|click|scroll|screenshot|getUrl|wait)', isError: true };
+    }
+    let browser;
+    try {
+        browser = await browserPool.getBrowser();
+        switch (action) {
+            case 'open': {
+                if (!url)
+                    return { output: 'Error: open requires url', isError: true };
+                try {
+                    await browser.open(url);
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    return { output: `BrowserX open(${url}) failed: ${msg.slice(0, 200)}`, isError: true };
+                }
+                return { output: `Opened ${url}. Call action="snapshot" next to inspect the page.` };
+            }
+            case 'snapshot': {
+                try {
+                    const tree = await browser.snapshot();
+                    const out = `Page snapshot (${tree.length} chars):\n\n${summariseTree(tree)}\n\n` +
+                        `Refs are valid until the next snapshot. Use action="click" with a ref to navigate.`;
+                    return { output: out };
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    return { output: `BrowserX snapshot failed: ${msg.slice(0, 200)}`, isError: true };
+                }
+            }
+            case 'click': {
+                if (!ref)
+                    return { output: 'Error: click requires ref (from last snapshot)', isError: true };
+                try {
+                    await browser.click(ref);
+                    // Give the navigation a moment to start, then return — model can
+                    // call snapshot next to see the result.
+                    await browser.waitForTimeout(1500);
+                    const newUrl = await browser.getUrl();
+                    return { output: `Clicked ref [${ref}]. Current URL: ${newUrl}. Call action="snapshot" to see the result.` };
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    return { output: `BrowserX click(${ref}) failed: ${msg.slice(0, 200)}`, isError: true };
+                }
+            }
+            case 'scroll': {
+                const delta = Number.isFinite(dy) ? Math.max(-2000, Math.min(2000, Number(dy))) : 600;
+                try {
+                    await browser.scroll(640, 450, 0, delta);
+                    await browser.waitForTimeout(800);
+                    return { output: `Scrolled ${delta > 0 ? 'down' : 'up'} ${Math.abs(delta)}px. Call action="snapshot" to see new content.` };
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    return { output: `BrowserX scroll failed: ${msg.slice(0, 200)}`, isError: true };
+                }
+            }
+            case 'screenshot': {
+                const finalPath = outPath
+                    ? outPath
+                    : path.join(os.homedir(), '.blockrun', 'screenshots', `browsex-${Date.now()}.png`);
+                try {
+                    const fs = await import('node:fs');
+                    fs.mkdirSync(path.dirname(finalPath), { recursive: true });
+                    await browser.screenshot(finalPath);
+                    return { output: `Screenshot saved to ${finalPath}. Use the Read tool to view it.` };
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    return { output: `BrowserX screenshot failed: ${msg.slice(0, 200)}`, isError: true };
+                }
+            }
+            case 'getUrl': {
+                try {
+                    const u = await browser.getUrl();
+                    return { output: `Current URL: ${u}` };
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    return { output: `BrowserX getUrl failed: ${msg.slice(0, 200)}`, isError: true };
+                }
+            }
+            case 'wait': {
+                const waitMs = Number.isFinite(ms) ? Math.min(MAX_WAIT_MS, Math.max(0, Number(ms))) : 2000;
+                await browser.waitForTimeout(waitMs);
+                return { output: `Waited ${waitMs}ms.` };
+            }
+            default:
+                return { output: `Error: unknown action "${action}" (use open|snapshot|click|scroll|screenshot|getUrl|wait)`, isError: true };
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { output: `BrowserX error: ${msg}`, isError: true };
+    }
+    finally {
+        browserPool.releaseBrowser();
+    }
+}
+export const browserXCapability = {
+    spec: {
+        name: 'BrowserX',
+        description: 'Drive Franklin\'s social Chrome profile (logged-in to X) iteratively. ' +
+            'Use when SearchX returns empty or the page needs scrolling/clicking to surface content. ' +
+            'Actions: open(url), snapshot(), click(ref), scroll(dy), screenshot(), getUrl(), wait(ms). ' +
+            'Snapshot returns an accessibility tree with [depth-idx] refs you pass to click. ' +
+            'Refs reset on every snapshot. SAFE: do NOT use this to like/follow/post — replies go through PostToX with confirmation. ' +
+            'Typical flow: open → snapshot → click a permalink → snapshot → read content.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['open', 'snapshot', 'click', 'scroll', 'screenshot', 'getUrl', 'wait'],
+                    description: 'open: navigate to a URL. snapshot: capture the page as a ref tree. click: click an element by ref. scroll: scroll vertically by dy px. screenshot: save a PNG. getUrl: return the current URL. wait: pause for ms.',
+                },
+                url: { type: 'string', description: 'URL for open' },
+                ref: { type: 'string', description: 'AX ref (e.g. "2-17") from the last snapshot, for click' },
+                dy: { type: 'number', description: 'Vertical scroll delta in px (positive = down). Defaults to 600. Clamped to [-2000, 2000].' },
+                ms: { type: 'number', description: 'Milliseconds to wait. Defaults to 2000. Capped at 15000.' },
+                path: { type: 'string', description: 'Output path for screenshot. Defaults to ~/.blockrun/screenshots/browsex-<ts>.png.' },
+            },
+            required: ['action'],
+        },
+    },
+    execute,
+    concurrent: false,
+};

package/dist/tools/index.js

@@ -22,6 +22,7 @@ import { askUserCapability } from './askuser.js';
 import { tradingSignalCapability, tradingMarketCapability } from './trading.js';
 import { searchXCapability } from './searchx.js';
 import { postToXCapability } from './posttox.js';
+import { browserXCapability } from './browsex.js';
 import { moaCapability } from './moa.js';
 import { webhookPostCapability } from './webhook.js';
 import { walletCapability } from './wallet.js';
@@ -147,6 +148,7 @@ export const allCapabilities = [
     ...defaultContentCapabilities, // ContentCreate, ContentAddAsset, ContentShow, ContentList
     searchXCapability,
     postToXCapability,
+    browserXCapability,
     moaCapability,
     webhookPostCapability,
     walletCapability,

package/dist/tools/searchx.d.ts

@@ -7,5 +7,6 @@
  *   - **Enhanced** (with social config): adds product routing, dedup, login detection
  */
 import type { CapabilityHandler } from '../agent/types.js';
+export declare function canonicalTweetUrl(input: string): string | null;
 export declare function detectNotificationsIntent(query: string | undefined, handle: string, knownHandles?: string[]): boolean;
 export declare const searchXCapability: CapabilityHandler;

package/dist/tools/searchx.js

@@ -12,6 +12,18 @@ import { computePreKey, hasPreKey } from '../social/db.js';
 import { detectProduct } from '../social/ai.js';
 import { loadConfig, isConfigReady } from '../social/config.js';
 import { browserPool } from '../social/browser-pool.js';
+// Detect a tweet permalink the user (or a paste) handed us instead of a
+// keyword. Treat twitter.com and x.com interchangeably; trim the tracking
+// suffix (?s=20 etc.) and normalise to the canonical x.com host so the
+// browser doesn't waste a redirect hop.
+const TWEET_URL_RE = /^https?:\/\/(?:www\.|mobile\.)?(?:x|twitter)\.com\/[^/\s]+\/status\/(\d+)/i;
+export function canonicalTweetUrl(input) {
+    const m = TWEET_URL_RE.exec((input ?? '').trim());
+    if (!m)
+        return null;
+    return input.trim().replace(/^https?:\/\/(?:www\.|mobile\.)?(?:x|twitter)\.com/i, 'https://x.com')
+        .replace(/[?#].*$/, '');
+}
 // ─── Intent detection (code-level, not LLM-level) ──────────────────────────
 // When the user asks "check my @handle mentions/notifications", the tool
 // itself routes to x.com/notifications. English-only keyword fast-path;
@@ -57,12 +69,111 @@ export function detectNotificationsIntent(query, handle, knownHandles) {
         return true;
     return false;
 }
+async function readTweetByUrl(rawUrl) {
+    const url = canonicalTweetUrl(rawUrl) ?? rawUrl;
+    let browser;
+    try {
+        browser = await browserPool.getBrowser();
+        try {
+            await browser.open(url);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return {
+                output: `SearchX (url mode): failed to open ${url}: ${msg.slice(0, 200)}`,
+                isError: true,
+            };
+        }
+        // Tweet pages are SPAs that lazy-render the article block. A single
+        // 4s wait + single snapshot misses content on slow networks or when
+        // X briefly shows the auth-wall during hydration even for logged-in
+        // sessions. Retry up to 3 times with progressive backoff and a small
+        // scroll to nudge the virtual list into rendering.
+        let tree = '';
+        let articles = [];
+        const WAIT_MS = [2500, 4000, 5000];
+        let attempt = 0;
+        while (attempt < WAIT_MS.length) {
+            await browser.waitForTimeout(WAIT_MS[attempt]);
+            try {
+                tree = await browser.snapshot();
+            }
+            catch (snapErr) {
+                const snapMsg = snapErr instanceof Error ? snapErr.message : String(snapErr);
+                return {
+                    output: `SearchX (url mode): snapshot failed (${snapMsg.slice(0, 100)}). The browser session likely closed mid-flight — retry, or ask the user to run \`franklin social setup\` in a separate terminal.`,
+                    isError: true,
+                };
+            }
+            if (tree.includes('Rate limit') || tree.includes('Something went wrong')) {
+                return {
+                    output: `SearchX: X returned an error page on ${url} (rate limit or server issue). Try again in a minute.`,
+                    isError: true,
+                };
+            }
+            if (/this post is unavailable|tweet was deleted|page (doesn'?t|does not) exist|account.*suspended/i.test(tree)) {
+                return {
+                    output: `SearchX: tweet at ${url} is unavailable, deleted, or its author is suspended.`,
+                    isError: true,
+                };
+            }
+            articles = extractArticleBlocks(tree);
+            if (articles.length > 0)
+                break;
+            // Nudge the page so X mounts the lazy article block.
+            try {
+                await browser.scroll(400, 400, 0, 400);
+            }
+            catch { /* ignore */ }
+            attempt++;
+        }
+        const treeLen = tree.length;
+        if (articles.length === 0 && tree.includes('Sign in') && tree.includes('Create account')) {
+            return {
+                output: `SearchX: X is showing a login wall on ${url} after ${WAIT_MS.length} attempts. If you ARE logged in, the cached session may have expired — ask the user to run \`franklin social login x\` in a separate terminal (interactive: opens a Chrome window).`,
+                isError: true,
+            };
+        }
+        if (articles.length === 0) {
+            return {
+                output: `SearchX (url mode): no article extracted from ${url} after ${WAIT_MS.length} attempts. ` +
+                    `Page rendered ${treeLen} chars. The tweet may load with a non-standard layout — drive the browser ` +
+                    `directly with BrowserX (action="snapshot" to inspect, action="scroll" to load more, ` +
+                    `action="open" url=<other> to navigate).\n\n[debug] tree preview:\n${tree.slice(0, 600)}`,
+                isError: true,
+            };
+        }
+        const primary = articles[0];
+        const texts = findStaticText(primary.text);
+        const snippet = texts.join(' ').trim().slice(0, 1200);
+        let output = `Tweet at ${url}:\n\n${snippet}\n\n---\n`;
+        output += 'IMPORTANT: This is the real post content. ';
+        output += 'Do NOT fabricate additional context, replies, or metrics. ';
+        output += 'If the user asked for replies/comments, draft them from THIS text only.';
+        return { output };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { output: `SearchX (url mode) error: ${msg}`, isError: true };
+    }
+    finally {
+        browserPool.releaseBrowser();
+    }
+}
 async function execute(input, _ctx) {
     const { query, max_results, mode } = input;
     if (!query && mode !== 'notifications') {
         return { output: 'Error: query is required (or set mode to "notifications")', isError: true };
     }
     const maxResults = Math.min(Math.max(max_results ?? 10, 1), 50);
+    // ── URL fast-path: user pasted a tweet permalink ────────────────────
+    // SearchX is the only X-aware tool. If the input is a tweet URL we read
+    // the post directly instead of searching for its URL as a keyword (which
+    // always returns empty). Triggers on mode="url" OR auto-detected URL.
+    const tweetUrl = canonicalTweetUrl(query ?? '');
+    if (mode === 'url' || tweetUrl) {
+        return await readTweetByUrl(tweetUrl ?? query);
+    }
     // ── Config: load if available, degrade gracefully if not ────────────
     const config = loadConfig();
     const configStatus = isConfigReady(config);
@@ -93,7 +204,7 @@ async function execute(input, _ctx) {
         if (!preflight.ready) {
             if (isNotifications) {
                 return {
-                    output: 'Not logged in to X. Run `franklin social login x` first — notifications require authentication.',
+                    output: 'Not logged in to X. Ask the user to run `franklin social login x` in a separate terminal (it opens a Chrome window for them to log in and is NOT runnable by you via Bash) first — notifications require authentication.',
                     isError: true,
                 };
             }
@@ -144,7 +255,7 @@ async function execute(input, _ctx) {
         const treeLen = tree.length;
         if (isLoginWall) {
             return {
-                output: `SearchX: X is showing a login wall. Run \`franklin social login x\` to authenticate.\n\nTree preview (${treeLen} chars):\n${tree.slice(0, 500)}`,
+                output: `SearchX: X is showing a login wall. Ask the user to run \`franklin social login x\` in a separate terminal (interactive — opens a Chrome window they must drive). Do NOT try to run that command from Bash; it will hang and time out.\n\nTree preview (${treeLen} chars):\n${tree.slice(0, 500)}`,
                 isError: true,
             };
         }
@@ -279,20 +390,22 @@ export const searchXCapability = {
     spec: {
         name: 'SearchX',
         description: 'The ONLY tool that can access X (Twitter). Returns real posts with URLs. ' +
-            'Use mode "search" to find posts by keyword. Use mode "notifications" to check mentions/replies. ' +
-            'Call ONCE per topic — do not retry. WebSearch/WebFetch CANNOT access X.com.',
+            'Use mode "search" to find posts by keyword, "notifications" to check mentions/replies, ' +
+            'or "url" to read a specific tweet — you can also just pass a tweet URL as the query and ' +
+            'this tool will auto-detect URL mode. Call ONCE per topic — do not retry. ' +
+            'WebSearch/WebFetch CANNOT access X.com.',
         input_schema: {
             type: 'object',
             properties: {
-                query: { type: 'string', description: 'Search query (required for search mode, optional for notifications mode)' },
+                query: { type: 'string', description: 'Search query for "search" mode, OR a tweet URL (https://x.com/<user>/status/<id>) for "url" mode — URL is auto-detected if passed in query. Optional for "notifications" mode.' },
                 max_results: {
                     type: 'number',
-                    description: 'Max posts to return (default 10)',
+                    description: 'Max posts to return (default 10, ignored in "url" mode)',
                 },
                 mode: {
                     type: 'string',
-                    enum: ['search', 'notifications'],
-                    description: 'Mode: "search" to find posts by keyword, "notifications" to check your mentions/replies/interactions that need response. Default: search',
+                    enum: ['search', 'notifications', 'url'],
+                    description: 'Mode: "search" finds posts by keyword, "notifications" checks your mentions/replies, "url" reads a specific tweet. Default: auto (URL → "url" mode, otherwise "search").',
                 },
             },
             required: [],

package/dist/tools/webfetch.js

@@ -237,12 +237,12 @@ const BLOCKED_DOMAINS = [
     {
         pattern: /(^|\.)x\.com$/i,
         reason: 'X.com requires authenticated API',
-        alternative: 'use SearchX (the dedicated X tool) instead of WebFetch',
+        alternative: 'use SearchX. For a specific tweet URL pass it as the query (SearchX auto-detects /status/<id> URLs and reads the post directly). For keyword discovery use mode="search". WebFetch on x.com will not work.',
     },
     {
         pattern: /(^|\.)twitter\.com$/i,
         reason: 'X.com requires authenticated API',
-        alternative: 'use SearchX (the dedicated X tool) instead of WebFetch',
+        alternative: 'use SearchX. For a specific tweet URL pass it as the query (SearchX auto-detects /status/<id> URLs and reads the post directly). For keyword discovery use mode="search". WebFetch on twitter.com will not work.',
     },
     {
         pattern: /(^|\.)tiktok\.com$/i,

package/package.json

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