@blockrun/franklin 3.3.3 → 3.5.1

package/dist/tools/searchx.js

@@ -1,66 +1,206 @@
 /**
  * SearchX capability — search X (Twitter) for posts matching a query.
- * Returns candidate posts with snippets and product relevance scores.
- * Requires social config and X login.
+ * Returns candidate posts with snippets, tweet URLs, and product relevance scores.
+ *
+ * Works in two modes:
+ *   - **Basic** (no config): browser-only search, returns snippets + URLs
+ *   - **Enhanced** (with social config): adds product routing, dedup, login detection
  */
 import { checkSocialReady } from '../social/preflight.js';
 import { extractArticleBlocks, findRefs, findStaticText, X_TIME_LINK_PATTERN, } from '../social/a11y.js';
 import { computePreKey, hasPreKey } from '../social/db.js';
 import { detectProduct } from '../social/ai.js';
-import { loadConfig } from '../social/config.js';
+import { loadConfig, isConfigReady } from '../social/config.js';
 import { browserPool } from '../social/browser-pool.js';
+// ─── Intent detection (code-level, not LLM-level) ──────────────────────────
+// When the user asks "check my @handle mentions/notifications/互动",
+// the tool itself routes to x.com/notifications. No LLM judgment needed.
+const NOTIFICATION_KEYWORDS = [
+    'notification', 'notifications',
+    'mention', 'mentions', 'mentioned',
+    'reply', 'replies',
+    'interact', 'interaction', 'interactions',
+    '互动', '通知', '提及', '回复', '看看',
+    'check my', 'my account', 'my x',
+    'to:', 'from:', '@',
+];
+export function detectNotificationsIntent(query, handle, knownHandles) {
+    if (!query)
+        return false;
+    const q = query.toLowerCase();
+    // Collect all handles the user might reference (personal + org accounts)
+    const handles = new Set();
+    const addHandle = (h) => {
+        const clean = h.replace(/^@/, '').toLowerCase().trim();
+        if (clean.length >= 3)
+            handles.add(clean);
+    };
+    addHandle(handle);
+    if (knownHandles)
+        knownHandles.forEach(addHandle);
+    // Check if query mentions any known handle
+    let mentionsOwnHandle = false;
+    let matchedHandle = '';
+    for (const h of handles) {
+        if (q.includes(h)) {
+            mentionsOwnHandle = true;
+            matchedHandle = h;
+            break;
+        }
+    }
+    const hasInteractionKeyword = NOTIFICATION_KEYWORDS.some(kw => q.includes(kw));
+    // Route to notifications if: mentions own handle + interaction keyword
+    // OR query is literally just the handle (e.g. "blockrunai", "@BlockRunAI")
+    if (mentionsOwnHandle && hasInteractionKeyword)
+        return true;
+    if (mentionsOwnHandle && q.replace(/[@:]/g, '').trim() === matchedHandle)
+        return true;
+    return false;
+}
 async function execute(input, _ctx) {
-    const { query, max_results } = input;
-    if (!query) {
-        return { output: 'Error: query is required', isError: true };
+    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);
-    // ── Preflight: config + login ──────────────────────────────────────────
-    const preflight = await checkSocialReady();
-    if (!preflight.ready) {
-        return {
-            output: `SearchX not ready: ${preflight.reason}`,
-            isError: true,
-        };
-    }
+    // ── Config: load if available, degrade gracefully if not ────────────
     const config = loadConfig();
+    const configStatus = isConfigReady(config);
+    const enhanced = configStatus.ready;
     const handle = config.handle || 'unknown';
+    // ── Auto-detect notifications intent from query ─────────────────────
+    // Skill-level routing: the code decides, not the LLM.
+    // If the query mentions any known handle + interaction keywords,
+    // or explicitly asks for notifications, route to notifications page.
+    // Extract known handles from config: search queries may contain org handles
+    // like "BlockRunAI" even if the personal handle is "@bc1beat".
+    const knownHandles = [];
+    if (config.x?.search_queries) {
+        for (const sq of config.x.search_queries) {
+            // Extract @-handles and capitalized brand names from search queries
+            const atHandles = sq.match(/@\w+/g);
+            if (atHandles)
+                knownHandles.push(...atHandles);
+            // Also add single-word brand tokens (like "BlockRunAI")
+            const words = sq.split(/\s+/).filter(w => /^[A-Z]/.test(w) && w.length >= 5);
+            knownHandles.push(...words);
+        }
+    }
+    const isNotifications = mode === 'notifications' || detectNotificationsIntent(query, handle, knownHandles);
+    // In enhanced mode, verify login via preflight
+    if (enhanced) {
+        const preflight = await checkSocialReady();
+        if (!preflight.ready) {
+            if (isNotifications) {
+                return {
+                    output: 'Not logged in to X. Run `franklin social login x` first — notifications require authentication.',
+                    isError: true,
+                };
+            }
+            // Search can sometimes work without login — fall through
+        }
+    }
     let browser;
     try {
         browser = await browserPool.getBrowser();
-        // ── Navigate to X search ───────────────────────────────────────────
-        const searchUrl = `https://x.com/search?q=${encodeURIComponent(query)}&src=typed_query&f=live`;
-        await browser.open(searchUrl);
-        await browser.waitForTimeout(3500);
+        // ── Choose page: notifications vs search ──────────────────────────
+        const targetUrl = isNotifications
+            ? 'https://x.com/notifications'
+            : `https://x.com/search?q=${encodeURIComponent(query)}&src=typed_query&f=live`;
+        try {
+            await browser.open(targetUrl);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            browserPool.releaseBrowser();
+            if (msg.includes('Timeout') || msg.includes('timeout')) {
+                return {
+                    output: `SearchX: X.com timed out (network issue or blocked). Try again later or check your connection.`,
+                    isError: true,
+                };
+            }
+            return { output: `SearchX: Failed to open X.com: ${msg.slice(0, 200)}`, isError: true };
+        }
+        await browser.waitForTimeout(4000);
         const tree = await browser.snapshot();
+        // ── Diagnose page state ───────────────────────────────────────────
+        const isLoginWall = tree.includes('Sign in') && tree.includes('Create account');
+        const isRateLimit = tree.includes('Rate limit') || tree.includes('Something went wrong');
+        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)}`,
+                isError: true,
+            };
+        }
+        if (isRateLimit) {
+            return {
+                output: `SearchX: X returned an error page (rate limit or server issue). Try again in a minute.\n\nTree preview (${treeLen} chars):\n${tree.slice(0, 500)}`,
+                isError: true,
+            };
+        }
         // ── Extract articles ───────────────────────────────────────────────
         const articles = extractArticleBlocks(tree);
         const candidates = [];
         for (const article of articles) {
             if (candidates.length >= maxResults)
                 break;
-            // Find time-link ref (permalink to the tweet)
-            const timeRefs = findRefs(article.text, 'link', X_TIME_LINK_PATTERN);
-            if (timeRefs.length === 0)
-                continue;
-            const timeRef = timeRefs[0];
             // Extract snippet from static text (first 3 lines)
             const texts = findStaticText(article.text);
             const snippet = texts.slice(0, 3).join(' ').trim();
             if (!snippet || snippet.length < 10)
                 continue;
-            // Extract time text from the ref line
-            const timeLinkMatch = new RegExp(`\\[${timeRef}\\]\\s+link:\\s*(.+)`).exec(article.text);
-            const timeText = timeLinkMatch ? timeLinkMatch[1].trim() : '';
-            // Compute pre-key for dedup
-            const preKey = computePreKey({ snippet, time: timeText });
-            const alreadySeen = hasPreKey('x', handle, preKey);
-            // Product routing (zero-cost keyword score)
-            const product = detectProduct(snippet, config.products);
+            // Find time-link ref (permalink to the tweet) — optional
+            const timeRefs = findRefs(article.text, 'link', X_TIME_LINK_PATTERN);
+            const timeRef = timeRefs[0] ?? null;
+            // Fallback: if no time-link, try to find ANY link in the article
+            // that looks like a tweet permalink (/username/status/...)
+            let tweetUrl = null;
+            let timeText = '';
+            if (timeRef) {
+                const timeLinkMatch = new RegExp(`\\[${timeRef}\\]\\s+link:\\s*(.+)`).exec(article.text);
+                timeText = timeLinkMatch ? timeLinkMatch[1].trim() : '';
+                try {
+                    const href = await browser.getHref(timeRef);
+                    if (href) {
+                        tweetUrl = href.startsWith('http')
+                            ? href
+                            : `https://x.com${href.startsWith('/') ? '' : '/'}${href}`;
+                    }
+                }
+                catch {
+                    // Non-fatal — we still have the snippet
+                }
+            }
+            else {
+                // No time-link matched — try all links in the article for a permalink
+                const allLinks = findRefs(article.text, 'link');
+                for (const linkRef of allLinks.slice(0, 5)) {
+                    try {
+                        const href = await browser.getHref(linkRef);
+                        if (href && /\/status\/\d+/.test(href)) {
+                            tweetUrl = href.startsWith('http')
+                                ? href
+                                : `https://x.com${href.startsWith('/') ? '' : '/'}${href}`;
+                            // Extract time text from this link's label
+                            const labelMatch = new RegExp(`\\[${linkRef}\\]\\s+link:\\s*(.+)`).exec(article.text);
+                            timeText = labelMatch ? labelMatch[1].trim() : '';
+                            break;
+                        }
+                    }
+                    catch { /* try next */ }
+                }
+            }
+            // Dedup (enhanced mode only)
+            const preKey = enhanced ? computePreKey({ snippet, time: timeText }) : '';
+            const alreadySeen = enhanced ? hasPreKey('x', handle, preKey) : false;
+            // Product routing (enhanced mode only)
+            const product = enhanced ? detectProduct(snippet, config.products) : null;
             candidates.push({
                 index: candidates.length + 1,
                 snippet,
                 timeText,
+                tweetUrl,
                 preKey,
                 productMatch: product?.name ?? null,
                 alreadySeen,
@@ -68,18 +208,49 @@ async function execute(input, _ctx) {
         }
         // ── Format output ──────────────────────────────────────────────────
         if (candidates.length === 0) {
-            return { output: `No candidate posts found for query: "${query}"` };
+            // Include diagnostic info — show first article block so we can debug the parser
+            let diag;
+            if (articles.length === 0) {
+                diag = `No article blocks found in AX tree (${treeLen} chars). Tree preview:\n${tree.slice(0, 800)}`;
+            }
+            else {
+                const sample = articles[0].text.slice(0, 600);
+                diag = `Found ${articles.length} article blocks but extracted 0 candidates.\nFirst article AX dump:\n${sample}`;
+            }
+            return {
+                output: `No candidate posts found for query: "${query}"\n\n` +
+                    'Tell the user: "No X posts found for this query. Try a different keyword or check back later."\n' +
+                    'Do NOT use WebSearch or WebFetch as a fallback — they cannot access X.com content.\n' +
+                    'Do NOT fabricate or invent X post links.\n\n' +
+                    `[debug] ${diag}`,
+            };
         }
         const lines = candidates.map((c) => {
-            const seen = c.alreadySeen ? ' [SEEN]' : '';
-            const product = c.productMatch ? ` | product: ${c.productMatch}` : ' | product: none';
-            return (`${c.index}. ${c.snippet.slice(0, 200)}\n` +
-                `   time: ${c.timeText} | pre_key: ${c.preKey}${product}${seen}`);
+            const url = c.tweetUrl ? `\n   url: ${c.tweetUrl}` : '';
+            if (enhanced) {
+                const seen = c.alreadySeen ? ' [SEEN]' : '';
+                const product = c.productMatch ? ` | product: ${c.productMatch}` : ' | product: none';
+                return (`${c.index}. ${c.snippet.slice(0, 200)}${url}\n` +
+                    `   time: ${c.timeText} | pre_key: ${c.preKey}${product}${seen}`);
+            }
+            // Basic mode: simpler output
+            return (`${c.index}. ${c.snippet.slice(0, 200)}${url}\n` +
+                `   time: ${c.timeText}`);
         });
-        return {
-            output: `SearchX results for "${query}" (${candidates.length} candidates):\n\n` +
-                lines.join('\n\n'),
-        };
+        const header = isNotifications
+            ? `X Notifications (${candidates.length} items):`
+            : `SearchX results for "${query}" (${candidates.length} candidates):`;
+        let output = `${header}\n\n${lines.join('\n\n')}`;
+        // Explicit instructions to prevent model from hallucinating additional posts
+        output += '\n\n---\n';
+        output += 'IMPORTANT: The posts above are the ONLY real X posts found. ';
+        output += 'Present ONLY these posts to the user. Do NOT fabricate additional posts. ';
+        output += 'Do NOT use WebSearch or WebFetch to find X posts — they cannot access X.com content. ';
+        output += 'If the user wants more, suggest refining the search query.';
+        if (!enhanced) {
+            output += '\nTip: Run `franklin social setup` to enable product routing, dedup, and auto-replies.';
+        }
+        return { output };
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
@@ -92,18 +263,24 @@ async function execute(input, _ctx) {
 export const searchXCapability = {
     spec: {
         name: 'SearchX',
-        description: 'Search X (Twitter) for posts matching a query. Returns candidate posts ' +
-            'with snippets and product relevance scores. Requires social config and X login.',
+        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.',
         input_schema: {
             type: 'object',
             properties: {
-                query: { type: 'string', description: 'Search query' },
+                query: { type: 'string', description: 'Search query (required for search mode, optional for notifications mode)' },
                 max_results: {
                     type: 'number',
                     description: 'Max posts to return (default 10)',
                 },
+                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',
+                },
             },
-            required: ['query'],
+            required: [],
         },
     },
     execute,

package/dist/tools/subagent.js

@@ -99,12 +99,46 @@ export function createSubAgentCapability(apiUrl, chain, capabilities) {
     return {
         spec: {
             name: 'Agent',
-            description: 'Launch a sub-agent for independent tasks. The sub-agent has its own context and tools.',
+            description: `Launch a new agent to handle complex, multi-step tasks. Each agent gets its own context window, tools, and reasoning loop.
+
+## When to use
+- Tasks requiring 3+ independent tool calls (research, exploration, implementation)
+- Work that benefits from a separate context (won't pollute your main conversation)
+- Parallel execution: launch multiple agents in a single response for independent tasks
+- Open-ended codebase exploration that may require multiple rounds of globbing and grepping
+
+## When NOT to use
+- If you want to read a specific file path, use Read directly — faster and cheaper
+- If you are searching for a specific symbol like "class Foo", use Grep directly
+- If you are searching within 2-3 specific files, use Read directly
+- Simple, single-tool operations (just call the tool directly)
+- Tasks that depend on results from other pending tool calls
+
+## Writing the prompt
+Brief the agent like a smart colleague who just walked into the room — it hasn't seen this conversation, doesn't know what you've tried, doesn't understand why this task matters.
+- Explain what you're trying to accomplish and why
+- Describe what you've already learned or ruled out
+- Give enough context about the surrounding problem that the agent can make judgment calls rather than just following a narrow instruction
+- If you need a short response, say so ("report in under 200 words")
+- For lookups: hand over the exact command. For investigations: hand over the question — prescribed steps become dead weight when the premise is wrong
+- Clearly tell the agent whether you expect it to write code or just to do research (search, file reads, web fetches), since it is not aware of the user's intent
+
+Terse command-style prompts produce shallow, generic work.
+
+**Never delegate understanding.** Don't write "based on your findings, fix the bug" or "based on the research, implement it." Those phrases push synthesis onto the agent instead of doing it yourself. Write prompts that prove you understood: include file paths, line numbers, what specifically to change.
+
+## Usage notes
+- Always include a short description (3-5 words) summarizing what the agent will do
+- The agent's result is returned to you, NOT shown to the user. To show the user the result, you must send a text message summarizing it
+- Trust but verify: the agent's summary describes what it intended, not necessarily what it did. When an agent writes or edits code, check the actual changes before reporting success
+- If launching multiple agents for independent work, send them ALL in a single response with multiple Agent tool calls — this runs them in parallel
+- Use foreground (default) when you need results before you can proceed. The agent completes before your response continues
+- Do not re-read files or re-search for things the agent already found — trust its output`,
             input_schema: {
                 type: 'object',
                 properties: {
-                    prompt: { type: 'string', description: 'The task for the sub-agent to perform' },
-                    description: { type: 'string', description: 'Short description of what the sub-agent will do' },
+                    prompt: { type: 'string', description: 'The task for the sub-agent to perform. Must be self-contained — the agent has no memory of your conversation.' },
+                    description: { type: 'string', description: 'Short (3-5 word) description of the task (e.g. "Research auth patterns", "Fix import errors")' },
                     model: { type: 'string', description: 'Model for the sub-agent. Default: claude-sonnet-4.6' },
                 },
                 required: ['prompt'],

package/dist/tools/task.js

@@ -5,7 +5,7 @@
 const tasks = [];
 let nextId = 1;
 async function execute(input, _ctx) {
-    const { action, subject, description, task_id, status } = input;
+    const { action, subject, description, activeForm, task_id, status, addBlocks, addBlockedBy } = input;
     switch (action) {
         case 'create': {
             if (!subject) {
@@ -16,6 +16,9 @@ async function execute(input, _ctx) {
                 subject,
                 status: 'pending',
                 description,
+                activeForm,
+                blocks: [],
+                blockedBy: [],
             };
             tasks.push(task);
             return { output: `Task #${task.id} created: ${task.subject}` };
@@ -34,7 +37,28 @@ async function execute(input, _ctx) {
                 task.subject = subject;
             if (description)
                 task.description = description;
-            return { output: `Task #${task.id} updated: ${task.status} — ${task.subject}` };
+            if (activeForm)
+                task.activeForm = activeForm;
+            // Dependency management
+            if (addBlocks) {
+                for (const blockedId of addBlocks) {
+                    if (!task.blocks.includes(blockedId))
+                        task.blocks.push(blockedId);
+                    const blocked = tasks.find(t => t.id === blockedId);
+                    if (blocked && !blocked.blockedBy.includes(task.id))
+                        blocked.blockedBy.push(task.id);
+                }
+            }
+            if (addBlockedBy) {
+                for (const blockerId of addBlockedBy) {
+                    if (!task.blockedBy.includes(blockerId))
+                        task.blockedBy.push(blockerId);
+                    const blocker = tasks.find(t => t.id === blockerId);
+                    if (blocker && !blocker.blocks.includes(task.id))
+                        blocker.blocks.push(task.id);
+                }
+            }
+            return { output: `Updated task #${task.id} status` };
         }
         case 'list': {
             if (tasks.length === 0) {
@@ -44,7 +68,10 @@ async function execute(input, _ctx) {
             const done = tasks.filter(t => t.status === 'completed').length;
             const lines = tasks.map(t => {
                 const icon = t.status === 'completed' ? '✓' : t.status === 'in_progress' ? '→' : '○';
-                return `${icon} #${t.id} [${t.status}] ${t.subject}`;
+                const deps = t.blockedBy.length > 0
+                    ? ` (blocked by: ${t.blockedBy.map(id => `#${id}`).join(', ')})`
+                    : '';
+                return `${icon} #${t.id} [${t.status}] ${t.subject}${deps}`;
             });
             lines.push(`\n${done} done, ${pending} remaining`);
             return { output: lines.join('\n') };
@@ -67,7 +94,7 @@ async function execute(input, _ctx) {
 export const taskCapability = {
     spec: {
         name: 'Task',
-        description: 'Manage in-session tasks. Actions: create, update (status/subject), list (with summary), delete.',
+        description: 'Track multi-step work within a session. Use for complex tasks with 3+ steps to maintain progress. Do NOT use for simple single-step requests. Actions: create, update (status/subject), list, delete. Tasks are ephemeral — they reset when the session ends.',
         input_schema: {
             type: 'object',
             properties: {
@@ -75,13 +102,22 @@ export const taskCapability = {
                     type: 'string',
                     description: 'Action: "create", "update", "list", or "delete"',
                 },
-                subject: { type: 'string', description: 'Task title (for create/update)' },
-                description: { type: 'string', description: 'Task description (for create/update)' },
-                task_id: { type: 'number', description: 'Task ID (for update)' },
+                subject: { type: 'string', description: 'A brief title for the task (for create/update)' },
+                description: { type: 'string', description: 'What needs to be done (for create/update)' },
+                activeForm: { type: 'string', description: 'Present continuous form shown in spinner when in_progress (e.g., "Running tests", "Fixing bug"). If omitted, the subject is shown instead.' },
+                task_id: { type: 'number', description: 'Task ID (for update/delete)' },
                 status: {
                     type: 'string',
                     description: 'New status: "pending", "in_progress", or "completed" (for update)',
                 },
+                addBlocks: {
+                    type: 'array',
+                    description: 'Task IDs that cannot start until this task completes (for update)',
+                },
+                addBlockedBy: {
+                    type: 'array',
+                    description: 'Task IDs that must complete before this task can start (for update)',
+                },
             },
             required: ['action'],
         },

package/dist/tools/validate.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Tool description validation — catches descriptions that discourage the LLM
+ * from using tools that actually work (like SearchX's old "Requires social config").
+ */
+import type { CapabilityHandler } from '../agent/types.js';
+export interface ToolValidationIssue {
+    toolName: string;
+    issue: string;
+    severity: 'warning' | 'error';
+}
+export declare function validateToolDescriptions(tools: CapabilityHandler[]): ToolValidationIssue[];

package/dist/tools/validate.js

@@ -0,0 +1,42 @@
+/**
+ * Tool description validation — catches descriptions that discourage the LLM
+ * from using tools that actually work (like SearchX's old "Requires social config").
+ */
+// Patterns in tool descriptions that make LLMs avoid using the tool
+const BLOCKER_PATTERNS = [
+    /\brequires?\b.*\b(?:config|setup|login|install|key|token|credential)\b/i,
+    /\bmust\s+(?:configure|set\s*up|install|login)\b/i,
+    /\bneeds?\s+(?:configuration|setup|api\s*key)\b/i,
+];
+export function validateToolDescriptions(tools) {
+    const issues = [];
+    const names = new Set();
+    for (const tool of tools) {
+        const name = tool.spec.name;
+        const desc = tool.spec.description;
+        // Duplicate names
+        if (names.has(name)) {
+            issues.push({ toolName: name, issue: 'Duplicate tool name — LLM will confuse them', severity: 'error' });
+        }
+        names.add(name);
+        // Description length
+        if (desc.length < 20) {
+            issues.push({ toolName: name, issue: `Description too short (${desc.length} chars) — LLM may not understand when to use this tool`, severity: 'warning' });
+        }
+        if (desc.length > 3000) {
+            issues.push({ toolName: name, issue: `Description too long (${desc.length} chars) — wastes context window`, severity: 'warning' });
+        }
+        // Blocker patterns — phrases that make the LLM think the tool won't work
+        for (const pattern of BLOCKER_PATTERNS) {
+            if (pattern.test(desc)) {
+                issues.push({
+                    toolName: name,
+                    issue: `Description contains blocking language: "${desc.match(pattern)?.[0]}" — LLM may avoid using this tool even when it would work`,
+                    severity: 'warning',
+                });
+                break; // One warning per tool is enough
+            }
+        }
+    }
+    return issues;
+}

package/dist/tools/webfetch.js

@@ -3,6 +3,8 @@
  */
 import { USER_AGENT } from '../config.js';
 const MAX_BODY_BYTES = 256 * 1024; // 256KB
+const DEFAULT_MAX_LENGTH = 12_288;
+const HTML_READ_AHEAD_BYTES = 8_192;
 // ─── Session cache ──────────────────────────────────────────────────────────
 // Avoids re-fetching the same URL within a session (common in research tasks).
 // 15-min TTL, max 50 entries.
@@ -48,7 +50,7 @@ async function execute(input, ctx) {
     if (!['http:', 'https:'].includes(parsed.protocol)) {
         return { output: `Error: only http/https URLs are supported`, isError: true };
     }
-    const maxLen = Math.min(max_length ?? MAX_BODY_BYTES, MAX_BODY_BYTES);
+    const maxLen = Math.min(max_length ?? DEFAULT_MAX_LENGTH, MAX_BODY_BYTES);
     const key = cacheKey(url, maxLen);
     // Check cache first
     const cached = getCached(key);
@@ -82,8 +84,11 @@ async function execute(input, ctx) {
         }
         const chunks = [];
         let totalBytes = 0;
+        const readBudget = contentType.includes('html')
+            ? Math.min(maxLen + HTML_READ_AHEAD_BYTES, MAX_BODY_BYTES)
+            : maxLen;
         try {
-            while (totalBytes < maxLen) {
+            while (totalBytes < readBudget) {
                 const { done, value } = await reader.read();
                 if (done)
                     break;
@@ -95,20 +100,24 @@ async function execute(input, ctx) {
             reader.releaseLock();
         }
         const decoder = new TextDecoder();
-        let body = decoder.decode(Buffer.concat(chunks)).slice(0, maxLen);
+        const rawBody = decoder.decode(Buffer.concat(chunks));
+        let body = rawBody;
         // Format response based on content type
         if (contentType.includes('json')) {
             try {
-                const parsedJson = JSON.parse(body);
+                const parsedJson = JSON.parse(rawBody.slice(0, maxLen));
                 body = JSON.stringify(parsedJson, null, 2).slice(0, maxLen);
             }
             catch { /* leave as-is if not valid JSON */ }
         }
         else if (contentType.includes('html')) {
-            body = stripHtml(body);
+            body = stripHtml(rawBody).slice(0, maxLen);
+        }
+        else {
+            body = rawBody.slice(0, maxLen);
         }
         let output = `URL: ${url}\nStatus: ${response.status}\nContent-Type: ${contentType}\n\n${body}`;
-        if (totalBytes >= maxLen) {
+        if (totalBytes >= readBudget || rawBody.length > maxLen) {
             output += '\n\n... (content truncated)';
         }
         // Cache successful responses
@@ -141,11 +150,13 @@ function stripHtml(html) {
         .replace(/<aside[^>]*>[\s\S]*?<\/aside>/gi, '')
         .replace(/<noscript[^>]*>[\s\S]*?<\/noscript>/gi, '')
         .replace(/<svg[^>]*>[\s\S]*?<\/svg>/gi, '')
+        .replace(/<(path|g|defs|clipPath|symbol|use|mask|rect|circle|ellipse|polygon|polyline|line)\b[^>]*>/gi, ' ')
         .replace(/<form[^>]*>[\s\S]*?<\/form>/gi, '')
         // Convert block elements to newlines for readability
         .replace(/<\/?(p|div|h[1-6]|li|br|tr)[^>]*>/gi, '\n')
         // Strip remaining tags
         .replace(/<[^>]+>/g, ' ')
+        .replace(/<[^>\n]*$/g, '')
         // Decode entities
         .replace(/&nbsp;/g, ' ')
         .replace(/&amp;/g, '&')
@@ -161,7 +172,7 @@ function stripHtml(html) {
 export const webFetchCapability = {
     spec: {
         name: 'WebFetch',
-        description: 'Fetch a web page and return its content. HTML tags are stripped for readability. Results are cached for 15 minutes.',
+        description: 'Fetch a web page and return its content as text. For searching the web, use WebSearch instead. Cannot access X.com (use SearchX). Large pages are truncated. Prefer WebSearch for discovery, WebFetch for reading a specific known URL.',
         input_schema: {
             type: 'object',
             properties: {