@blockrun/franklin 3.0.0

package/dist/tools/webfetch.js

@@ -0,0 +1,166 @@
+/**
+ * WebFetch capability — fetch web page content.
+ */
+import { USER_AGENT } from '../config.js';
+const MAX_BODY_BYTES = 256 * 1024; // 256KB
+// ─── Session cache ──────────────────────────────────────────────────────────
+// Avoids re-fetching the same URL within a session (common in research tasks).
+// 15-min TTL, max 50 entries.
+const CACHE_TTL_MS = 15 * 60 * 1000;
+const MAX_CACHE_ENTRIES = 50;
+const fetchCache = new Map();
+function getCached(url) {
+    const entry = fetchCache.get(url);
+    if (!entry)
+        return null;
+    if (Date.now() > entry.expiresAt) {
+        fetchCache.delete(url);
+        return null;
+    }
+    return entry.output;
+}
+function setCached(url, output) {
+    // Evict oldest entry if at capacity
+    if (fetchCache.size >= MAX_CACHE_ENTRIES) {
+        const firstKey = fetchCache.keys().next().value;
+        if (firstKey)
+            fetchCache.delete(firstKey);
+    }
+    fetchCache.set(url, { output, expiresAt: Date.now() + CACHE_TTL_MS });
+}
+// ─── Execute ────────────────────────────────────────────────────────────────
+async function execute(input, _ctx) {
+    const { url, max_length } = input;
+    if (!url) {
+        return { output: 'Error: url is required', isError: true };
+    }
+    // Basic URL validation
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return { output: `Error: invalid URL: ${url}`, isError: true };
+    }
+    if (!['http:', 'https:'].includes(parsed.protocol)) {
+        return { output: `Error: only http/https URLs are supported`, isError: true };
+    }
+    // Check cache first
+    const cached = getCached(url);
+    if (cached) {
+        return { output: cached + '\n\n(cached)' };
+    }
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 30_000);
+    try {
+        const response = await fetch(url, {
+            signal: controller.signal,
+            headers: {
+                'User-Agent': USER_AGENT,
+                'Accept': 'text/html,application/json,text/plain,*/*',
+            },
+            redirect: 'follow',
+        });
+        if (!response.ok) {
+            return {
+                output: `HTTP ${response.status} ${response.statusText} for ${url}`,
+                isError: true,
+            };
+        }
+        const contentType = response.headers.get('content-type') || '';
+        const maxLen = Math.min(max_length ?? MAX_BODY_BYTES, MAX_BODY_BYTES);
+        // Read body with size limit
+        const reader = response.body?.getReader();
+        if (!reader) {
+            return { output: 'Error: no response body', isError: true };
+        }
+        const chunks = [];
+        let totalBytes = 0;
+        try {
+            while (totalBytes < maxLen) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                chunks.push(value);
+                totalBytes += value.length;
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+        const decoder = new TextDecoder();
+        let body = decoder.decode(Buffer.concat(chunks)).slice(0, maxLen);
+        // Format response based on content type
+        if (contentType.includes('json')) {
+            try {
+                const parsedJson = JSON.parse(body);
+                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);
+        }
+        let output = `URL: ${url}\nStatus: ${response.status}\nContent-Type: ${contentType}\n\n${body}`;
+        if (totalBytes >= maxLen) {
+            output += '\n\n... (content truncated)';
+        }
+        // Cache successful responses
+        setCached(url, output);
+        return { output };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg.includes('abort')) {
+            return { output: `Error: request timed out after 30s for ${url}`, isError: true };
+        }
+        return { output: `Error fetching ${url}: ${msg}`, isError: true };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+function stripHtml(html) {
+    return html
+        // Remove non-content elements
+        .replace(/<script[^>]*>[\s\S]*?<\/script>/gi, '')
+        .replace(/<style[^>]*>[\s\S]*?<\/style>/gi, '')
+        .replace(/<nav[^>]*>[\s\S]*?<\/nav>/gi, '')
+        .replace(/<header[^>]*>[\s\S]*?<\/header>/gi, '')
+        .replace(/<footer[^>]*>[\s\S]*?<\/footer>/gi, '')
+        .replace(/<aside[^>]*>[\s\S]*?<\/aside>/gi, '')
+        .replace(/<noscript[^>]*>[\s\S]*?<\/noscript>/gi, '')
+        .replace(/<svg[^>]*>[\s\S]*?<\/svg>/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, ' ')
+        // Decode entities
+        .replace(/&nbsp;/g, ' ')
+        .replace(/&amp;/g, '&')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        // Clean whitespace
+        .replace(/[ \t]+/g, ' ')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+}
+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.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                url: { type: 'string', description: 'The URL to fetch' },
+                max_length: { type: 'number', description: 'Max content bytes to return. Default: 256KB' },
+            },
+            required: ['url'],
+        },
+    },
+    execute,
+    concurrent: true,
+};

package/dist/tools/websearch.d.ts

@@ -0,0 +1,5 @@
+/**
+ * WebSearch capability — search the web via BlockRun API or DuckDuckGo fallback.
+ */
+import type { CapabilityHandler } from '../agent/types.js';
+export declare const webSearchCapability: CapabilityHandler;

package/dist/tools/websearch.js

@@ -0,0 +1,103 @@
+/**
+ * WebSearch capability — search the web via BlockRun API or DuckDuckGo fallback.
+ */
+import { VERSION } from '../config.js';
+async function execute(input, _ctx) {
+    const { query, max_results } = input;
+    if (!query) {
+        return { output: 'Error: query is required', isError: true };
+    }
+    const maxResults = Math.min(Math.max(max_results ?? 5, 1), 20);
+    // Try DuckDuckGo HTML search (no API key needed)
+    try {
+        const encoded = encodeURIComponent(query);
+        const url = `https://html.duckduckgo.com/html/?q=${encoded}`;
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 15_000);
+        const response = await fetch(url, {
+            signal: controller.signal,
+            headers: {
+                'User-Agent': `runcode/${VERSION} (coding-agent)`,
+            },
+        });
+        clearTimeout(timeout);
+        if (!response.ok) {
+            return { output: `Search failed: HTTP ${response.status}`, isError: true };
+        }
+        const html = await response.text();
+        const results = parseDuckDuckGoResults(html, maxResults);
+        if (results.length === 0) {
+            return { output: `No results found for: ${query}` };
+        }
+        const formatted = results
+            .map((r, i) => `${i + 1}. ${r.title}\n   ${r.url}\n   ${r.snippet}`)
+            .join('\n\n');
+        return { output: `Search results for "${query}":\n\n${formatted}` };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg.includes('abort')) {
+            return { output: `Search timed out after 15s for: ${query}`, isError: true };
+        }
+        return { output: `Search error: ${msg}`, isError: true };
+    }
+}
+function parseDuckDuckGoResults(html, maxResults) {
+    const results = [];
+    // Primary parser: match result blocks by class names
+    const linkRegex = /<a[^>]*class="result__a"[^>]*href="([^"]*)"[^>]*>([\s\S]*?)<\/a>/gi;
+    const snippetRegex = /<a[^>]*class="result__snippet"[^>]*>([\s\S]*?)<\/a>/gi;
+    let links = [...html.matchAll(linkRegex)];
+    let snippets = [...html.matchAll(snippetRegex)];
+    // Fallback parser if primary finds nothing (DDG may have updated HTML)
+    if (links.length === 0) {
+        const fallbackLink = /<a[^>]*class="[^"]*result[^"]*"[^>]*href="([^"]*)"[^>]*>([\s\S]*?)<\/a>/gi;
+        links = [...html.matchAll(fallbackLink)];
+    }
+    for (let i = 0; i < Math.min(links.length, maxResults); i++) {
+        const link = links[i];
+        const snippet = snippets[i];
+        let url = link[1] || '';
+        // DuckDuckGo wraps URLs in redirect — extract the actual URL
+        const uddgMatch = url.match(/uddg=([^&]+)/);
+        if (uddgMatch) {
+            url = decodeURIComponent(uddgMatch[1]);
+        }
+        // Skip internal DDG links
+        if (url.startsWith('/') || url.includes('duckduckgo.com'))
+            continue;
+        results.push({
+            title: stripTags(link[2] || '').trim(),
+            url,
+            snippet: stripTags(snippet?.[1] || '').trim(),
+        });
+    }
+    return results;
+}
+function stripTags(html) {
+    return html
+        .replace(/<[^>]+>/g, '')
+        .replace(/&amp;/g, '&')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/&nbsp;/g, ' ')
+        .replace(/\s+/g, ' ');
+}
+export const webSearchCapability = {
+    spec: {
+        name: 'WebSearch',
+        description: 'Search the web and return results with titles, URLs, and snippets.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                query: { type: 'string', description: 'The search query' },
+                max_results: { type: 'number', description: 'Max number of results. Default: 5' },
+            },
+            required: ['query'],
+        },
+    },
+    execute,
+    concurrent: true,
+};

package/dist/tools/write.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Write capability — creates or overwrites files.
+ */
+import type { CapabilityHandler } from '../agent/types.js';
+export declare const writeCapability: CapabilityHandler;

package/dist/tools/write.js

@@ -0,0 +1,114 @@
+/**
+ * Write capability — creates or overwrites files.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+function withTrailingSep(value) {
+    return value.endsWith(path.sep) ? value : value + path.sep;
+}
+function isWithinDir(target, dir) {
+    const normalizedTarget = path.resolve(target);
+    const normalizedDir = withTrailingSep(path.resolve(dir));
+    return normalizedTarget === normalizedDir.slice(0, -1) || normalizedTarget.startsWith(normalizedDir);
+}
+function getAllowedTempDirs() {
+    const candidates = new Set([path.resolve(os.tmpdir())]);
+    for (const dir of [...candidates]) {
+        try {
+            candidates.add(path.resolve(fs.realpathSync(dir)));
+        }
+        catch {
+            // Best effort only.
+        }
+        if (dir.startsWith('/private/')) {
+            candidates.add(dir.slice('/private'.length));
+        }
+        else {
+            candidates.add(path.join('/private', dir));
+        }
+    }
+    return [...candidates];
+}
+async function execute(input, ctx) {
+    const { file_path: filePath, content } = input;
+    if (!filePath) {
+        return { output: 'Error: file_path is required', isError: true };
+    }
+    if (content === undefined || content === null) {
+        return { output: 'Error: content is required', isError: true };
+    }
+    const resolved = path.isAbsolute(filePath) ? filePath : path.resolve(ctx.workingDir, filePath);
+    // Safety: block system paths and sensitive home directories
+    // Resolve symlinks to prevent traversal attacks
+    const home = os.homedir();
+    const allowedTempDirs = getAllowedTempDirs();
+    const dangerousPaths = [
+        '/etc/', '/usr/', '/bin/', '/sbin/', '/var/', '/System/',
+        path.join(home, '.ssh') + '/',
+        path.join(home, '.aws') + '/',
+        path.join(home, '.kube') + '/',
+        path.join(home, '.gnupg') + '/',
+        path.join(home, '.config/gcloud') + '/',
+    ];
+    // Check both the resolved path and the real path (after symlink resolution)
+    const checkPath = (p) => !allowedTempDirs.some(dir => isWithinDir(p, dir)) &&
+        dangerousPaths.some(dp => p.startsWith(dp));
+    if (checkPath(resolved)) {
+        return { output: `Error: refusing to write to sensitive path: ${resolved}`, isError: true };
+    }
+    // Also check parent dir's real path if it already exists (symlink protection)
+    const parentDir = path.dirname(resolved);
+    try {
+        if (fs.existsSync(parentDir)) {
+            const realParent = fs.realpathSync(parentDir);
+            if (checkPath(realParent + '/')) {
+                return { output: `Error: refusing to write — path resolves to sensitive location: ${realParent}`, isError: true };
+            }
+        }
+    }
+    catch { /* parent doesn't exist yet, will be created */ }
+    // Also check if target file itself is a symlink to a sensitive location
+    try {
+        if (fs.existsSync(resolved) && fs.lstatSync(resolved).isSymbolicLink()) {
+            const realTarget = fs.realpathSync(resolved);
+            if (checkPath(realTarget)) {
+                return { output: `Error: refusing to write — symlink resolves to sensitive location: ${realTarget}`, isError: true };
+            }
+        }
+    }
+    catch { /* file doesn't exist yet, ok */ }
+    try {
+        // Ensure parent directory exists
+        const parentDir = path.dirname(resolved);
+        fs.mkdirSync(parentDir, { recursive: true });
+        const existed = fs.existsSync(resolved);
+        fs.writeFileSync(resolved, content, 'utf-8');
+        const lineCount = content.split('\n').length;
+        const byteCount = Buffer.byteLength(content, 'utf-8');
+        const sizeStr = byteCount >= 1024 ? `${(byteCount / 1024).toFixed(1)}KB` : `${byteCount}B`;
+        return {
+            output: `${existed ? 'Updated' : 'Created'} ${resolved} (${lineCount} lines, ${sizeStr})`,
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { output: `Error writing file: ${msg}`, isError: true };
+    }
+}
+export const writeCapability = {
+    spec: {
+        name: 'Write',
+        description: 'Create or overwrite a file.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                file_path: { type: 'string', description: 'Absolute path' },
+                content: { type: 'string', description: 'File content' },
+            },
+            required: ['file_path', 'content'],
+        },
+    },
+    execute,
+    concurrent: false,
+};

package/dist/ui/app.d.ts

@@ -0,0 +1,26 @@
+/**
+ * RunCode ink-based terminal UI.
+ * Real-time streaming, thinking animation, tool progress, slash commands.
+ */
+import type { StreamEvent } from '../agent/types.js';
+export interface InkUIHandle {
+    handleEvent: (event: StreamEvent) => void;
+    updateModel: (model: string) => void;
+    updateBalance: (balance: string) => void;
+    onTurnDone: (cb: () => void) => void;
+    waitForInput: () => Promise<string | null>;
+    onAbort: (cb: () => void) => void;
+    cleanup: () => void;
+    requestPermission: (toolName: string, description: string) => Promise<'yes' | 'no' | 'always'>;
+    requestAskUser: (question: string, options?: string[]) => Promise<string>;
+}
+export declare function launchInkUI(opts: {
+    model: string;
+    workDir: string;
+    version: string;
+    walletAddress?: string;
+    walletBalance?: string;
+    chain?: string;
+    showPicker?: boolean;
+    onModelChange?: (model: string) => void;
+}): InkUIHandle;