@blockrun/franklin 3.3.3 → 3.5.0

package/dist/tools/bash.js

@@ -161,15 +161,49 @@ function compressBuild(out) {
     });
     return collapseBlankLines(kept.join('\n')).trim() || out.trim();
 }
+const backgroundTasks = new Map();
+let bgTaskCounter = 0;
+/** Get a background task's result (called by the agent to check status). */
+export function getBackgroundTask(id) {
+    return backgroundTasks.get(id);
+}
+/** List all background tasks. */
+export function listBackgroundTasks() {
+    return [...backgroundTasks.values()];
+}
 const MAX_OUTPUT_BYTES = 512 * 1024; // 512KB capture buffer (prevents OOM)
 const MAX_RETURN_CHARS = 32_000; // 32KB return cap (~8,000 tokens) — prevents context bloat
 const DEFAULT_TIMEOUT_MS = 120_000; // 2 minutes
 async function execute(input, ctx) {
-    const { command, timeout } = input;
+    const { command, timeout, run_in_background: runInBackground } = input;
     if (!command || typeof command !== 'string') {
         return { output: 'Error: command is required', isError: true };
     }
     const timeoutMs = Math.min(timeout ?? DEFAULT_TIMEOUT_MS, 600_000);
+    // Background execution: spawn and return immediately with a task ID
+    if (runInBackground) {
+        const taskId = `bg-${++bgTaskCounter}`;
+        const desc = input.description || command.slice(0, 60);
+        const task = {
+            id: taskId,
+            command,
+            description: desc,
+            startedAt: Date.now(),
+            status: 'running',
+        };
+        backgroundTasks.set(taskId, task);
+        // Run in background — don't await
+        executeCommand(command, timeoutMs, ctx).then(result => {
+            task.status = result.isError ? 'failed' : 'completed';
+            task.result = result;
+        });
+        return {
+            output: `Background task started: ${taskId}\nCommand: ${command.slice(0, 100)}\n\nYou will be notified when it completes. Do not poll or sleep — continue with other work.`,
+        };
+    }
+    return executeCommand(command, timeoutMs, ctx);
+}
+function executeCommand(command, timeoutMs, ctx) {
     return new Promise((resolve) => {
         const shell = process.env.SHELL || '/bin/bash';
         let child;
@@ -178,7 +212,9 @@ async function execute(input, ctx) {
                 cwd: ctx.workingDir,
                 env: {
                     ...process.env,
-                    RUNCODE: '1', // Let scripts detect they're running inside runcode
+                    FRANKLIN: '1', // Let scripts detect they're running inside Franklin
+                    FRANKLIN_WORKDIR: ctx.workingDir,
+                    RUNCODE: '1', // Backwards compat
                     RUNCODE_WORKDIR: ctx.workingDir,
                 },
                 stdio: ['ignore', 'pipe', 'pipe'],
@@ -217,8 +253,8 @@ async function execute(input, ctx) {
             if (!ctx.onProgress)
                 return;
             const now = Date.now();
-            if (now - lastProgressEmit < 500)
-                return; // max 2 updates/sec
+            if (now - lastProgressEmit < 200)
+                return; // max 5 updates/sec
             lastProgressEmit = now;
             const lastLine = text.split('\n').map(l => l.trim()).filter(Boolean).pop();
             if (lastLine)
@@ -323,19 +359,108 @@ async function execute(input, ctx) {
         });
     });
 }
+/**
+ * Detect if a bash command is read-only (safe to run concurrently).
+ * Inspired by Claude Code's isSearchOrReadBashCommand — analyzes command segments
+ * to determine if ALL operations are read-only.
+ */
+const READ_ONLY_COMMANDS = new Set([
+    'ls', 'cat', 'head', 'tail', 'wc', 'du', 'df', 'file', 'stat', 'tree',
+    'find', 'grep', 'rg', 'ag', 'ack', 'which', 'whereis', 'type',
+    'echo', 'printf', 'date', 'whoami', 'hostname', 'uname', 'env', 'printenv',
+    'pwd', 'realpath', 'dirname', 'basename',
+    'jq', 'yq', 'sort', 'uniq', 'cut', 'tr', 'awk', 'sed', // sed is read-only when used in pipeline (no -i)
+    'diff', 'comm', 'less', 'more',
+]);
+const READ_ONLY_GIT_SUBCOMMANDS = new Set([
+    'status', 'log', 'diff', 'show', 'branch', 'tag', 'remote', 'stash',
+    'blame', 'shortlog', 'describe', 'rev-parse', 'rev-list', 'ls-files',
+    'ls-tree', 'ls-remote', 'config', 'reflog',
+]);
+function isReadOnlyCommand(command) {
+    // Split on operators (&&, ||, ;, |) and check each segment
+    const segments = command.split(/\s*(?:&&|\|\||[;|])\s*/);
+    for (const segment of segments) {
+        const trimmed = segment.trim();
+        if (!trimmed)
+            continue;
+        // Extract the base command (first word, ignore env vars and redirects)
+        const words = trimmed.split(/\s+/).filter(w => !w.includes('=') && !w.startsWith('>') && !w.startsWith('<'));
+        const baseCmd = words[0]?.replace(/^(sudo|time|nice)\s+/, '') || '';
+        if (baseCmd === 'git') {
+            const subCmd = words[1] || '';
+            if (!READ_ONLY_GIT_SUBCOMMANDS.has(subCmd))
+                return false;
+            continue;
+        }
+        if (baseCmd === 'npm' || baseCmd === 'npx' || baseCmd === 'yarn' || baseCmd === 'pnpm') {
+            const subCmd = words[1] || '';
+            // npm run/test/list/info are read-only; npm install/build are not
+            if (['run', 'test', 'list', 'ls', 'info', 'view', 'show', 'outdated', 'audit'].includes(subCmd))
+                continue;
+            return false;
+        }
+        // Check if it's a known read-only command
+        const baseName = baseCmd.split('/').pop() || baseCmd;
+        if (!READ_ONLY_COMMANDS.has(baseName))
+            return false;
+        // sed with -i flag is NOT read-only
+        if (baseName === 'sed' && trimmed.includes(' -i'))
+            return false;
+    }
+    return segments.some(s => s.trim().length > 0); // At least one non-empty segment
+}
 export const bashCapability = {
     spec: {
         name: 'Bash',
-        description: 'Execute a shell command and return stdout+stderr. Runs in working directory with user env. Output capped at 512KB. Default timeout: 2min, max: 10min (set via timeout param in ms).',
+        description: `Executes a given bash command and returns its output.
+
+The working directory persists between commands, but shell state does not. The shell environment is initialized from the user's profile (bash or zsh).
+
+IMPORTANT: Avoid using this tool to run \`find\`, \`grep\`, \`cat\`, \`head\`, \`tail\`, \`sed\`, \`awk\`, or \`echo\` commands, unless explicitly instructed or after you have verified that a dedicated tool cannot accomplish your task. Instead, use the appropriate dedicated tool as this will provide a much better experience for the user:
+
+- File search: Use Glob (NOT find or ls)
+- Content search: Use Grep (NOT grep or rg)
+- Read files: Use Read (NOT cat/head/tail)
+- Edit files: Use Edit (NOT sed/awk)
+- Write files: Use Write (NOT echo >/cat <<EOF)
+- Communication: Output text directly (NOT echo/printf)
+
+# Instructions
+- If your command will create new directories or files, first use this tool to run \`ls\` to verify the parent directory exists and is the correct location.
+- Always quote file paths that contain spaces with double quotes in your command (e.g., cd "path with spaces/file.txt")
+- Try to maintain your current working directory throughout the session by using absolute paths and avoiding usage of \`cd\`. You may use \`cd\` if the user explicitly requests it.
+- You may specify an optional timeout in milliseconds (up to 600000ms / 10 minutes). By default, your command will timeout after 120000ms (2 minutes).
+- When issuing multiple commands:
+  - If the commands are independent and can run in parallel, make multiple Bash tool calls in a single message.
+  - If the commands depend on each other and must run sequentially, use a single Bash call with '&&' to chain them together.
+  - Use ';' only when you need to run commands sequentially but don't care if earlier commands fail.
+  - DO NOT use newlines to separate commands (newlines are ok in quoted strings).
+- For git commands:
+  - Prefer to create a new commit rather than amending an existing commit.
+  - Before running destructive operations (e.g., git reset --hard, git push --force, git checkout --), consider whether there is a safer alternative. Only use destructive operations when truly the best approach.
+  - Never skip hooks (--no-verify) unless the user has explicitly asked for it. If a hook fails, investigate and fix the underlying issue.
+  - NEVER use git commands with the -i flag (like git rebase -i or git add -i) since they require interactive input which is not supported.
+- 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.
+
+Output is capped at 512KB capture / 32KB return.`,
         input_schema: {
             type: 'object',
             properties: {
-                command: { type: 'string', description: 'The shell command to execute' },
+                command: { type: 'string', description: 'The command to execute' },
+                description: { type: 'string', description: 'Clear, concise description of what this command does in active voice. For simple commands (git, npm), keep it brief (5-10 words): "Show working tree status", "Install dependencies". For complex commands (piped, obscure flags), add enough context: "Find and delete all .tmp files recursively"' },
                 timeout: { type: 'number', description: 'Timeout in milliseconds (default: 120000, max: 600000)' },
+                run_in_background: { type: 'boolean', description: 'Set to true to run this command in the background. Returns immediately with a task ID. Use this for long-running commands (builds, installs, deploys) when you don\'t need the result immediately. You will be notified when it completes — do NOT sleep or poll.' },
             },
             required: ['command'],
         },
     },
     execute,
-    concurrent: false,
+    concurrent: false, // Default; overridden by isConcurrentSafe for read-only commands
+    isConcurrentSafe: (input) => {
+        const cmd = input.command || '';
+        return isReadOnlyCommand(cmd);
+    },
 };

package/dist/tools/edit.js

@@ -3,7 +3,7 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
-import { partiallyReadFiles } from './read.js';
+import { partiallyReadFiles, fileReadTracker } from './read.js';
 /**
  * Normalize curly/smart quotes to straight quotes.
  * Claude Code does this to handle API-sanitized strings and editor paste artifacts.
@@ -28,8 +28,27 @@ async function execute(input, ctx) {
         return { output: 'Error: old_string and new_string are identical', isError: true };
     }
     const resolved = path.isAbsolute(filePath) ? filePath : path.resolve(ctx.workingDir, filePath);
-    // Warn if the file was only partially read — editing without full context risks mistakes
-    const isPartial = partiallyReadFiles.has(resolved);
+    // Enforce read-before-edit: the model must Read the file before editing it
+    const readRecord = fileReadTracker.get(resolved);
+    if (!readRecord) {
+        return {
+            output: `Error: you must Read this file before editing it. Use Read to understand the current content first.\nFile: ${resolved}`,
+            isError: true,
+        };
+    }
+    // Check if the file was modified since it was last read (stale write detection)
+    try {
+        const currentStat = fs.statSync(resolved);
+        if (currentStat.mtimeMs !== readRecord.mtimeMs) {
+            return {
+                output: `Warning: ${resolved} has been modified since you last read it. Read the file again to see the current content before editing.`,
+                isError: true,
+            };
+        }
+    }
+    catch { /* file may have been deleted — will be caught below */ }
+    // Check if the file was only partially read — used for smarter warning below
+    const partialInfo = partiallyReadFiles.get(resolved);
     try {
         if (!fs.existsSync(resolved)) {
             return { output: `Error: file not found: ${resolved}`, isError: true };
@@ -41,9 +60,31 @@ async function execute(input, ctx) {
             const normalized = normalizeQuotes(oldStr);
             const contentNormalized = normalizeQuotes(content);
             if (normalized !== oldStr && contentNormalized.includes(normalized)) {
-                // Find the original text in content that corresponds to the normalized match
-                const idx = contentNormalized.indexOf(normalized);
-                effectiveOldStr = content.slice(idx, idx + normalized.length);
+                // Find the original text in content that corresponds to the normalized match.
+                // IMPORTANT: We can't use normalized.length to slice the original content because
+                // smart quotes are multi-byte in UTF-8 (3 bytes) while straight quotes are 1 byte.
+                // Instead, we map the character index from the normalized string back to the original.
+                const normIdx = contentNormalized.indexOf(normalized);
+                // Walk through content character-by-character, mapping normalized positions to original positions
+                let origStart = -1;
+                let origEnd = -1;
+                let normPos = 0;
+                for (let i = 0; i < content.length; i++) {
+                    if (normPos === normIdx && origStart === -1) {
+                        origStart = i;
+                    }
+                    if (normPos === normIdx + normalized.length) {
+                        origEnd = i;
+                        break;
+                    }
+                    // Both content and contentNormalized have same character count (quote replacement is 1:1 char)
+                    normPos++;
+                }
+                if (origStart !== -1) {
+                    if (origEnd === -1)
+                        origEnd = content.length;
+                    effectiveOldStr = content.slice(origStart, origEnd);
+                }
             }
         }
         if (!content.includes(effectiveOldStr)) {
@@ -104,6 +145,9 @@ async function execute(input, ctx) {
         fs.writeFileSync(resolved, updated, 'utf-8');
         // File has been modified — remove from partial-read tracking so next read is fresh
         partiallyReadFiles.delete(resolved);
+        // Update read tracker mtime so subsequent edits don't trigger stale-write detection
+        const newStat = fs.statSync(resolved);
+        fileReadTracker.set(resolved, { mtimeMs: newStat.mtimeMs, readAt: Date.now() });
         // Build a concise diff preview
         const oldLines = effectiveOldStr.split('\n');
         const newLines = newStr.split('\n');
@@ -116,9 +160,16 @@ async function execute(input, ctx) {
         else {
             diffPreview = ` (${oldLines.length} lines → ${newLines.length} lines)`;
         }
-        const partialWarning = isPartial
-            ? '\nNote: file was only partially read before this edit.'
-            : '';
+        // Only warn about partial read if the edit target is near or beyond the read boundary.
+        // A normal Read(limit=2000) on a 10K line file shouldn't warn if editing line 50.
+        let partialWarning = '';
+        if (partialInfo) {
+            const editLine = content.slice(0, content.indexOf(effectiveOldStr)).split('\n').length;
+            const nearBoundary = editLine >= partialInfo.endLine - 10 || editLine < partialInfo.startLine;
+            if (nearBoundary) {
+                partialWarning = `\nWarning: file was only partially read (lines ${partialInfo.startLine}-${partialInfo.endLine} of ${partialInfo.totalLines}). This edit is near the boundary — consider reading more of the file.`;
+            }
+        }
         return {
             output: `Updated ${resolved} — ${matchCount} replacement${matchCount > 1 ? 's' : ''} made.${diffPreview}${partialWarning}`,
         };
@@ -131,14 +182,26 @@ async function execute(input, ctx) {
 export const editCapability = {
     spec: {
         name: 'Edit',
-        description: 'Replace exact string in a file. old_string must be unique (or use replace_all).',
+        description: `Perform exact string replacements in files.
+
+Usage:
+- You MUST use Read at least once before editing. This tool will error if you attempt an edit without reading the file first.
+- When editing text from Read output, ensure you preserve the exact indentation (tabs/spaces) as it appears AFTER the line number prefix. The line number prefix format is: line number + tab. Everything after that is the actual file content to match. Never include any part of the line number prefix in the old_string or new_string.
+- ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.
+- Only use emojis if the user explicitly requests it. Avoid adding emojis to files unless asked.
+- The edit will FAIL if old_string is not unique in the file. Either provide a larger string with more surrounding context to make it unique, or use replace_all to change every instance of old_string.
+- Use replace_all for replacing and renaming strings across the file. This parameter is useful if you want to rename a variable for instance.
+- old_string and new_string must be different.
+- If the file has been modified since your last Read (by linter, formatter, or another tool), the edit will fail with a stale-write warning. Read the file again to get the current content.
+
+IMPORTANT: Always use Edit instead of sed or awk via Bash.`,
         input_schema: {
             type: 'object',
             properties: {
-                file_path: { type: 'string', description: 'Absolute path' },
-                old_string: { type: 'string', description: 'Text to find' },
-                new_string: { type: 'string', description: 'Replacement text' },
-                replace_all: { type: 'boolean', description: 'Replace all occurrences' },
+                file_path: { type: 'string', description: 'The absolute path to the file to modify' },
+                old_string: { type: 'string', description: 'The text to replace (must be different from new_string)' },
+                new_string: { type: 'string', description: 'The text to replace it with' },
+                replace_all: { type: 'boolean', description: 'Replace all occurrences of old_string (default false)' },
             },
             required: ['file_path', 'old_string', 'new_string'],
         },

package/dist/tools/glob.js

@@ -143,12 +143,22 @@ async function execute(input, ctx) {
 export const globCapability = {
     spec: {
         name: 'Glob',
-        description: 'Find files by glob pattern (e.g. "**/*.ts", "src/**/*.tsx"). Returns up to 500 paths sorted by modification time. Skips node_modules, .git, hidden dirs.',
+        description: `Fast file pattern matching tool that works with any codebase size.
+
+Usage:
+- Supports glob patterns like "**/*.js" or "src/**/*.ts"
+- Returns matching file paths sorted by modification time (most recent first)
+- Use this when you need to find files by name patterns
+- Skips node_modules, .git, __pycache__ automatically
+- Returns up to 200 results
+- When doing an open-ended search that may require multiple rounds of globbing and grepping, use the Agent tool instead
+
+IMPORTANT: Always use Glob instead of find or ls via Bash.`,
         input_schema: {
             type: 'object',
             properties: {
-                pattern: { type: 'string', description: 'Glob pattern to match files (e.g. "**/*.ts")' },
-                path: { type: 'string', description: 'Directory to search in. Defaults to working directory.' },
+                pattern: { type: 'string', description: 'The glob pattern to match files against (e.g. "**/*.ts", "src/**/*.tsx")' },
+                path: { type: 'string', description: 'The directory to search in. Defaults to working directory.' },
             },
             required: ['pattern'],
         },

package/dist/tools/grep.js

@@ -70,6 +70,8 @@ function runRipgrep(opts, searchPath, mode, limit, cwd) {
         args.push('-U', '--multiline-dotall');
     if (opts.glob)
         args.push(`--glob=${opts.glob}`);
+    if (opts.type)
+        args.push(`--type=${opts.type}`);
     // Always exclude common noise + lock files (huge, rarely useful)
     args.push('--glob=!node_modules', '--glob=!.git', '--glob=!dist', '--glob=!*.lock', '--glob=!package-lock.json', '--glob=!pnpm-lock.yaml');
     args.push('--', opts.pattern);
@@ -81,7 +83,9 @@ function runRipgrep(opts, searchPath, mode, limit, cwd) {
             stdio: ['pipe', 'pipe', 'pipe'],
         });
         const lines = result.split('\n').filter(Boolean);
-        const limited = limit > 0 ? lines.slice(0, limit) : lines;
+        const offset = opts.offset ?? 0;
+        const sliced = offset > 0 ? lines.slice(offset) : lines;
+        const limited = limit > 0 ? sliced.slice(0, limit) : sliced;
         // Convert absolute paths to relative paths to save tokens (same as Claude Code)
         const relativized = limited.map(line => {
             // Lines: /abs/path or /abs/path:rest (content mode)
@@ -171,20 +175,34 @@ function runNativeGrep(opts, searchPath, mode, limit, cwd) {
 export const grepCapability = {
     spec: {
         name: 'Grep',
-        description: 'Search file contents by regex. Default output: file paths. output_mode "content" returns matching lines. Skips node_modules/.git/dist.',
+        description: `A powerful search tool built on ripgrep.
+
+ALWAYS use Grep for search tasks. NEVER invoke grep or rg as a Bash command. The Grep tool has been optimized for correct permissions and access.
+
+Usage:
+- Supports full regex syntax (e.g., "log.*Error", "function\\s+\\w+")
+- Filter files with glob parameter (e.g., "*.js", "**/*.tsx") or type parameter (e.g., "js", "py", "rust") — more efficient than searching all files
+- Output modes: "content" shows matching lines with context, "files_with_matches" shows only file paths (default), "count" shows match counts
+- Use context/before_context/after_context for surrounding lines (requires output_mode: "content")
+- Pattern syntax: Uses ripgrep (not grep) — literal braces need escaping (use \`interface\\{\\}\` to find \`interface{}\` in Go code)
+- Multiline matching: By default patterns match within single lines only. For cross-line patterns like \`struct \\{[\\s\\S]*?field\`, use multiline: true
+- Use Agent tool for open-ended searches requiring multiple rounds of exploration
+- Default head_limit is 250 results. Pass 0 for unlimited (use sparingly — large results waste context)`,
         input_schema: {
             type: 'object',
             properties: {
-                pattern: { type: 'string', description: 'Regex pattern' },
-                path: { type: 'string', description: 'File or dir to search (default: cwd)' },
-                glob: { type: 'string', description: 'File filter e.g. "*.ts"' },
-                output_mode: { type: 'string', description: '"content" | "files_with_matches" | "count". Default: files_with_matches' },
-                context: { type: 'number', description: 'Context lines around match' },
-                before_context: { type: 'number', description: 'Lines before match' },
-                after_context: { type: 'number', description: 'Lines after match' },
-                case_insensitive: { type: 'boolean' },
-                head_limit: { type: 'number', description: 'Max results (default 250)' },
-                multiline: { type: 'boolean', description: 'Match across lines' },
+                pattern: { type: 'string', description: 'The regular expression pattern to search for in file contents' },
+                path: { type: 'string', description: 'File or directory to search in. Defaults to working directory.' },
+                glob: { type: 'string', description: 'Glob pattern to filter files (e.g. "*.js", "*.{ts,tsx}") — maps to rg --glob' },
+                type: { type: 'string', description: 'File type to search (rg --type). Common types: js, py, rust, go, java, ts. More efficient than glob for standard file types.' },
+                output_mode: { type: 'string', description: 'Output mode: "content" shows matching lines, "files_with_matches" shows file paths (default), "count" shows match counts' },
+                context: { type: 'number', description: 'Number of lines to show before and after each match (rg -C). Requires output_mode: "content"' },
+                before_context: { type: 'number', description: 'Number of lines to show before each match (rg -B). Requires output_mode: "content"' },
+                after_context: { type: 'number', description: 'Number of lines to show after each match (rg -A). Requires output_mode: "content"' },
+                case_insensitive: { type: 'boolean', description: 'Case insensitive search (rg -i)' },
+                head_limit: { type: 'number', description: 'Limit output to first N entries. Defaults to 250. Pass 0 for unlimited (use sparingly — large results waste context).' },
+                offset: { type: 'number', description: 'Skip first N entries before applying head_limit. Defaults to 0.' },
+                multiline: { type: 'boolean', description: 'Enable multiline mode where . matches newlines and patterns can span lines (rg -U --multiline-dotall). Default: false.' },
             },
             required: ['pattern'],
         },

package/dist/tools/imagegen.js

@@ -29,7 +29,7 @@ async function execute(input, ctx) {
     });
     const headers = {
         'Content-Type': 'application/json',
-        'User-Agent': `runcode/${VERSION}`,
+        'User-Agent': `franklin/${VERSION}`,
     };
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), 60_000); // 60s timeout
@@ -134,7 +134,7 @@ async function signPayment(response, chain, endpoint) {
         }
     }
     catch (err) {
-        console.error(`[runcode] Image payment error: ${err.message}`);
+        console.error(`[franklin] Image payment error: ${err.message}`);
         return null;
     }
 }
@@ -155,7 +155,7 @@ async function extractPaymentReq(response) {
 export const imageGenCapability = {
     spec: {
         name: 'ImageGen',
-        description: 'Generate an image from a text prompt using AI (DALL-E, etc). Saves the image to a file.',
+        description: 'Generate an image from a text prompt using DALL-E. Costs USDC from the user\'s wallet — confirm before generating. Saves to a local file. Default size: 1024x1024. Do NOT call repeatedly to iterate on style — ask the user first.',
         input_schema: {
             type: 'object',
             properties: {

package/dist/tools/index.d.ts

@@ -11,7 +11,7 @@ import { grepCapability } from './grep.js';
 import { webFetchCapability } from './webfetch.js';
 import { webSearchCapability } from './websearch.js';
 import { taskCapability } from './task.js';
-/** All capabilities available to the runcode agent (excluding sub-agent, which needs config). */
+/** All capabilities available to the Franklin agent (excluding sub-agent, which needs config). */
 export declare const allCapabilities: CapabilityHandler[];
 export { readCapability, writeCapability, editCapability, bashCapability, globCapability, grepCapability, webFetchCapability, webSearchCapability, taskCapability, };
 export { createSubAgentCapability } from './subagent.js';

package/dist/tools/index.js

@@ -13,7 +13,9 @@ import { taskCapability } from './task.js';
 import { imageGenCapability } from './imagegen.js';
 import { askUserCapability } from './askuser.js';
 import { tradingSignalCapability, tradingMarketCapability } from './trading.js';
-/** All capabilities available to the runcode agent (excluding sub-agent, which needs config). */
+import { searchXCapability } from './searchx.js';
+import { postToXCapability } from './posttox.js';
+/** All capabilities available to the Franklin agent (excluding sub-agent, which needs config). */
 export const allCapabilities = [
     readCapability,
     writeCapability,
@@ -28,6 +30,8 @@ export const allCapabilities = [
     askUserCapability,
     tradingSignalCapability,
     tradingMarketCapability,
+    searchXCapability,
+    postToXCapability,
 ];
 export { readCapability, writeCapability, editCapability, bashCapability, globCapability, grepCapability, webFetchCapability, webSearchCapability, taskCapability, };
 export { createSubAgentCapability } from './subagent.js';

package/dist/tools/read.d.ts

@@ -4,8 +4,22 @@
 import type { CapabilityHandler } from '../agent/types.js';
 /**
  * Tracks files that were only partially read (offset or limit applied).
- * Edit tool uses this to warn when editing without full context.
+ * Stores the read range so Edit tool can give smarter warnings —
+ * only warns if the edit target is near/beyond the boundary of what was read.
  * Exported so edit.ts can check and clear entries.
  */
-export declare const partiallyReadFiles: Set<string>;
+export declare const partiallyReadFiles: Map<string, {
+    startLine: number;
+    endLine: number;
+    totalLines: number;
+}>;
+/**
+ * Tracks files that have been read in this session — enables read-before-edit enforcement.
+ * Stores the file's mtime at read time so we can detect stale writes.
+ * Exported so edit.ts and write.ts can check.
+ */
+export declare const fileReadTracker: Map<string, {
+    mtimeMs: number;
+    readAt: number;
+}>;
 export declare const readCapability: CapabilityHandler;

package/dist/tools/read.js

@@ -5,10 +5,17 @@ import fs from 'node:fs';
 import path from 'node:path';
 /**
  * Tracks files that were only partially read (offset or limit applied).
- * Edit tool uses this to warn when editing without full context.
+ * Stores the read range so Edit tool can give smarter warnings —
+ * only warns if the edit target is near/beyond the boundary of what was read.
  * Exported so edit.ts can check and clear entries.
  */
-export const partiallyReadFiles = new Set();
+export const partiallyReadFiles = new Map();
+/**
+ * Tracks files that have been read in this session — enables read-before-edit enforcement.
+ * Stores the file's mtime at read time so we can detect stale writes.
+ * Exported so edit.ts and write.ts can check.
+ */
+export const fileReadTracker = new Map();
 async function execute(input, ctx) {
     const { file_path: filePath, offset, limit } = input;
     if (!filePath) {
@@ -43,15 +50,21 @@ async function execute(input, ctx) {
         const maxLines = limit ?? 2000;
         const endLine = Math.min(allLines.length, startLine + maxLines);
         const slice = allLines.slice(startLine, endLine);
-        // Track partial reads — file was not read from the beginning or was truncated
+        // Track partial reads — store the range so Edit can give smarter warnings
         const isPartial = startLine > 0 || endLine < allLines.length;
         if (isPartial) {
-            partiallyReadFiles.add(resolved);
+            partiallyReadFiles.set(resolved, {
+                startLine: startLine + 1, // 1-based
+                endLine,
+                totalLines: allLines.length,
+            });
         }
         else {
             // Full read — clear any stale partial flag
             partiallyReadFiles.delete(resolved);
         }
+        // Record this read for read-before-edit/write enforcement
+        fileReadTracker.set(resolved, { mtimeMs: stat.mtimeMs, readAt: Date.now() });
         // Format with line numbers (cat -n style)
         const numbered = slice.map((line, i) => `${startLine + i + 1}\t${line}`);
         let result = numbered.join('\n');
@@ -74,13 +87,28 @@ async function execute(input, ctx) {
 export const readCapability = {
     spec: {
         name: 'Read',
-        description: 'Read file with line numbers. Use offset/limit for large files.',
+        description: `Read a file from the local filesystem. You can access any file directly by using this tool.
+
+Assume this tool is able to read all files on the machine. If the user provides a path to a file, assume that path is valid. It is okay to read a file that does not exist; an error will be returned.
+
+Usage:
+- The file_path parameter must be an absolute path, not a relative path.
+- By default, reads up to 2000 lines starting from the beginning of the file.
+- When you already know which part of the file you need, only read that part using offset/limit. This can be important for larger files.
+- Results are returned in cat -n format, with line numbers starting at 1.
+- This tool can only read files, not directories. To list a directory, use Glob or ls via Bash.
+- If you read a file that exists but has empty contents you will receive a warning.
+- Reads over 2MB are rejected — use offset/limit to read portions.
+- Cannot read binary files (images, PDFs, archives).
+- You will regularly be asked to read screenshots or images. If the user provides a path, ALWAYS use this tool to view it.
+
+IMPORTANT: Always use Read instead of cat, head, or tail via Bash. This tool provides line numbers and integrates with Edit's read-before-edit enforcement.`,
         input_schema: {
             type: 'object',
             properties: {
-                file_path: { type: 'string', description: 'Absolute path' },
-                offset: { type: 'number', description: 'Start line (1-based)' },
-                limit: { type: 'number', description: 'Max lines (default 2000)' },
+                file_path: { type: 'string', description: 'The absolute path to the file to read' },
+                offset: { type: 'number', description: 'The line number to start reading from (1-based). Only provide if the file is too large to read at once.' },
+                limit: { type: 'number', description: 'The number of lines to read. Only provide if the file is too large to read at once. Default: 2000.' },
             },
             required: ['file_path'],
         },

package/dist/tools/searchx.d.ts

@@ -1,7 +1,11 @@
 /**
  * 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 type { CapabilityHandler } from '../agent/types.js';
+export declare function detectNotificationsIntent(query: string | undefined, handle: string, knownHandles?: string[]): boolean;
 export declare const searchXCapability: CapabilityHandler;