@blockrun/franklin 3.0.0

package/dist/tools/imagegen.js

@@ -0,0 +1,172 @@
+/**
+ * Image Generation capability — generate images via BlockRun API.
+ * Uses x402 payment on Solana or Base.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { getOrCreateWallet, getOrCreateSolanaWallet, createPaymentPayload, createSolanaPaymentPayload, parsePaymentRequired, extractPaymentDetails, solanaKeyToBytes, SOLANA_NETWORK, } from '@blockrun/llm';
+import { loadChain, API_URLS, VERSION } from '../config.js';
+async function execute(input, ctx) {
+    const { prompt, output_path, size, model } = input;
+    if (!prompt) {
+        return { output: 'Error: prompt is required', isError: true };
+    }
+    const chain = loadChain();
+    const apiUrl = API_URLS[chain];
+    const endpoint = `${apiUrl}/v1/images/generations`;
+    const imageModel = model || 'dall-e-3';
+    const imageSize = size || '1024x1024';
+    // Default output path
+    const outPath = output_path
+        ? (path.isAbsolute(output_path) ? output_path : path.resolve(ctx.workingDir, output_path))
+        : path.resolve(ctx.workingDir, `generated-${Date.now()}.png`);
+    const body = JSON.stringify({
+        model: imageModel,
+        prompt,
+        n: 1,
+        size: imageSize,
+        response_format: 'b64_json',
+    });
+    const headers = {
+        'Content-Type': 'application/json',
+        'User-Agent': `runcode/${VERSION}`,
+    };
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 60_000); // 60s timeout
+    try {
+        // First request — will get 402
+        let response = await fetch(endpoint, {
+            method: 'POST',
+            signal: controller.signal,
+            headers,
+            body,
+        });
+        // Handle x402 payment
+        if (response.status === 402) {
+            const paymentHeaders = await signPayment(response, chain, endpoint);
+            if (!paymentHeaders) {
+                return { output: 'Payment failed. Check wallet balance with: runcode balance', isError: true };
+            }
+            response = await fetch(endpoint, {
+                method: 'POST',
+                signal: controller.signal,
+                headers: { ...headers, ...paymentHeaders },
+                body,
+            });
+        }
+        if (!response.ok) {
+            const errText = await response.text().catch(() => '');
+            return { output: `Image generation failed (${response.status}): ${errText.slice(0, 200)}`, isError: true };
+        }
+        const result = await response.json();
+        const imageData = result.data?.[0];
+        if (!imageData) {
+            return { output: 'No image data returned from API', isError: true };
+        }
+        // Save image
+        if (imageData.b64_json) {
+            const buffer = Buffer.from(imageData.b64_json, 'base64');
+            fs.mkdirSync(path.dirname(outPath), { recursive: true });
+            fs.writeFileSync(outPath, buffer);
+        }
+        else if (imageData.url) {
+            // Download from URL (with 30s timeout)
+            const dlCtrl = new AbortController();
+            const dlTimeout = setTimeout(() => dlCtrl.abort(), 30_000);
+            const imgResp = await fetch(imageData.url, { signal: dlCtrl.signal });
+            clearTimeout(dlTimeout);
+            const buffer = Buffer.from(await imgResp.arrayBuffer());
+            fs.mkdirSync(path.dirname(outPath), { recursive: true });
+            fs.writeFileSync(outPath, buffer);
+        }
+        else {
+            return { output: 'No image data (b64_json or url) in response', isError: true };
+        }
+        const fileSize = fs.statSync(outPath).size;
+        const sizeKB = (fileSize / 1024).toFixed(1);
+        const revisedPrompt = imageData.revised_prompt ? `\nRevised prompt: ${imageData.revised_prompt}` : '';
+        return {
+            output: `Image saved to ${outPath} (${sizeKB}KB, ${imageSize})${revisedPrompt}\n\nOpen with: open ${outPath}`,
+        };
+    }
+    catch (err) {
+        const msg = err.message || '';
+        if (msg.includes('abort')) {
+            return { output: 'Image generation timed out (60s limit). Try a simpler prompt.', isError: true };
+        }
+        return { output: `Error: ${msg}`, isError: true };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+// ─── Payment ───────────────────────────────────────────────────────────────
+async function signPayment(response, chain, endpoint) {
+    try {
+        const paymentHeader = await extractPaymentReq(response);
+        if (!paymentHeader)
+            return null;
+        if (chain === 'solana') {
+            const wallet = await getOrCreateSolanaWallet();
+            const paymentRequired = parsePaymentRequired(paymentHeader);
+            const details = extractPaymentDetails(paymentRequired, SOLANA_NETWORK);
+            const secretBytes = await solanaKeyToBytes(wallet.privateKey);
+            const feePayer = details.extra?.feePayer || details.recipient;
+            const payload = await createSolanaPaymentPayload(secretBytes, wallet.address, details.recipient, details.amount, feePayer, {
+                resourceUrl: details.resource?.url || endpoint,
+                resourceDescription: details.resource?.description || 'RunCode image generation',
+                maxTimeoutSeconds: details.maxTimeoutSeconds || 300,
+                extra: details.extra,
+            });
+            return { 'PAYMENT-SIGNATURE': payload };
+        }
+        else {
+            const wallet = getOrCreateWallet();
+            const paymentRequired = parsePaymentRequired(paymentHeader);
+            const details = extractPaymentDetails(paymentRequired);
+            const payload = await createPaymentPayload(wallet.privateKey, wallet.address, details.recipient, details.amount, details.network || 'eip155:8453', {
+                resourceUrl: details.resource?.url || endpoint,
+                resourceDescription: details.resource?.description || 'RunCode image generation',
+                maxTimeoutSeconds: details.maxTimeoutSeconds || 300,
+                extra: details.extra,
+            });
+            return { 'PAYMENT-SIGNATURE': payload };
+        }
+    }
+    catch (err) {
+        console.error(`[runcode] Image payment error: ${err.message}`);
+        return null;
+    }
+}
+async function extractPaymentReq(response) {
+    let header = response.headers.get('payment-required');
+    if (!header) {
+        try {
+            const body = (await response.json());
+            if (body.x402 || body.accepts) {
+                header = btoa(JSON.stringify(body));
+            }
+        }
+        catch { /* ignore */ }
+    }
+    return header;
+}
+// ─── Export ────────────────────────────────────────────────────────────────
+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.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                prompt: { type: 'string', description: 'Text description of the image to generate' },
+                output_path: { type: 'string', description: 'Where to save the image. Default: generated-<timestamp>.png in working directory' },
+                size: { type: 'string', description: 'Image size: 1024x1024, 1792x1024, or 1024x1792. Default: 1024x1024' },
+                model: { type: 'string', description: 'Image model to use. Default: dall-e-3' },
+            },
+            required: ['prompt'],
+        },
+    },
+    execute,
+    concurrent: false,
+};

package/dist/tools/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Tool registry — exports all available capabilities for the agent.
+ */
+import type { CapabilityHandler } from '../agent/types.js';
+import { readCapability } from './read.js';
+import { writeCapability } from './write.js';
+import { editCapability } from './edit.js';
+import { bashCapability } from './bash.js';
+import { globCapability } from './glob.js';
+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). */
+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

@@ -0,0 +1,30 @@
+/**
+ * Tool registry — exports all available capabilities for the agent.
+ */
+import { readCapability } from './read.js';
+import { writeCapability } from './write.js';
+import { editCapability } from './edit.js';
+import { bashCapability } from './bash.js';
+import { globCapability } from './glob.js';
+import { grepCapability } from './grep.js';
+import { webFetchCapability } from './webfetch.js';
+import { webSearchCapability } from './websearch.js';
+import { taskCapability } from './task.js';
+import { imageGenCapability } from './imagegen.js';
+import { askUserCapability } from './askuser.js';
+/** All capabilities available to the runcode agent (excluding sub-agent, which needs config). */
+export const allCapabilities = [
+    readCapability,
+    writeCapability,
+    editCapability,
+    bashCapability,
+    globCapability,
+    grepCapability,
+    webFetchCapability,
+    webSearchCapability,
+    taskCapability,
+    imageGenCapability,
+    askUserCapability,
+];
+export { readCapability, writeCapability, editCapability, bashCapability, globCapability, grepCapability, webFetchCapability, webSearchCapability, taskCapability, };
+export { createSubAgentCapability } from './subagent.js';

package/dist/tools/read.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Read capability — reads files with line numbers.
+ */
+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.
+ * Exported so edit.ts can check and clear entries.
+ */
+export declare const partiallyReadFiles: Set<string>;
+export declare const readCapability: CapabilityHandler;

package/dist/tools/read.js

@@ -0,0 +1,90 @@
+/**
+ * Read capability — reads files with line numbers.
+ */
+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.
+ * Exported so edit.ts can check and clear entries.
+ */
+export const partiallyReadFiles = new Set();
+async function execute(input, ctx) {
+    const { file_path: filePath, offset, limit } = input;
+    if (!filePath) {
+        return { output: 'Error: file_path is required', isError: true };
+    }
+    const resolved = path.isAbsolute(filePath) ? filePath : path.resolve(ctx.workingDir, filePath);
+    try {
+        const stat = fs.statSync(resolved);
+        if (stat.isDirectory()) {
+            // Helpfully list directory contents instead of just erroring
+            const entries = fs.readdirSync(resolved, { withFileTypes: true });
+            const dirs = entries.filter(e => e.isDirectory()).map(e => e.name + '/');
+            const files = entries.filter(e => e.isFile()).map(e => e.name);
+            const listing = [...dirs.sort(), ...files.sort()].slice(0, 100);
+            return { output: `Directory: ${resolved}\n${listing.join('\n')}${entries.length > 100 ? `\n... (${entries.length - 100} more)` : ''}` };
+        }
+        // Size guard: skip huge files
+        const maxBytes = 2 * 1024 * 1024; // 2MB
+        if (stat.size > maxBytes) {
+            return { output: `Error: file is too large (${(stat.size / 1024 / 1024).toFixed(1)}MB). Use offset/limit to read a portion.`, isError: true };
+        }
+        // Detect binary files
+        const ext = path.extname(resolved).toLowerCase();
+        const binaryExts = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.ico', '.bmp', '.pdf', '.zip', '.tar', '.gz', '.woff', '.woff2', '.ttf', '.eot', '.mp3', '.mp4', '.wav', '.avi', '.mov', '.exe', '.dll', '.so', '.dylib']);
+        if (binaryExts.has(ext)) {
+            const sizeStr = stat.size >= 1024 ? `${(stat.size / 1024).toFixed(1)}KB` : `${stat.size}B`;
+            return { output: `Binary file: ${resolved} (${ext}, ${sizeStr}). Cannot display contents.` };
+        }
+        const raw = fs.readFileSync(resolved, 'utf-8');
+        const allLines = raw.split('\n');
+        const startLine = Math.max(0, (Math.max(1, offset ?? 1)) - 1);
+        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
+        const isPartial = startLine > 0 || endLine < allLines.length;
+        if (isPartial) {
+            partiallyReadFiles.add(resolved);
+        }
+        else {
+            // Full read — clear any stale partial flag
+            partiallyReadFiles.delete(resolved);
+        }
+        // Format with line numbers (cat -n style)
+        const numbered = slice.map((line, i) => `${startLine + i + 1}\t${line}`);
+        let result = numbered.join('\n');
+        if (endLine < allLines.length) {
+            result += `\n\n... (${allLines.length - endLine} more lines. Use offset=${endLine + 1} to continue.)`;
+        }
+        return { output: result || '(empty file)' };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg.includes('ENOENT')) {
+            return { output: `Error: file not found: ${resolved}`, isError: true };
+        }
+        if (msg.includes('EACCES')) {
+            return { output: `Error: permission denied: ${resolved}`, isError: true };
+        }
+        return { output: `Error reading file: ${msg}`, isError: true };
+    }
+}
+export const readCapability = {
+    spec: {
+        name: 'Read',
+        description: 'Read file with line numbers. Use offset/limit for large files.',
+        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)' },
+            },
+            required: ['file_path'],
+        },
+    },
+    execute,
+    concurrent: true,
+};

package/dist/tools/subagent.d.ts

@@ -0,0 +1,5 @@
+/**
+ * SubAgent capability — spawn a child agent for independent tasks.
+ */
+import type { CapabilityHandler } from '../agent/types.js';
+export declare function createSubAgentCapability(apiUrl: string, chain: 'base' | 'solana', capabilities: CapabilityHandler[]): CapabilityHandler;

package/dist/tools/subagent.js

@@ -0,0 +1,116 @@
+/**
+ * SubAgent capability — spawn a child agent for independent tasks.
+ */
+import { ModelClient } from '../agent/llm.js';
+import { assembleInstructions } from '../agent/context.js';
+// These will be injected at registration time
+let registeredApiUrl = '';
+let registeredChain = 'base';
+let registeredCapabilities = [];
+async function execute(input, ctx) {
+    const { prompt, description, model } = input;
+    if (!prompt) {
+        return { output: 'Error: prompt is required', isError: true };
+    }
+    const client = new ModelClient({
+        apiUrl: registeredApiUrl,
+        chain: registeredChain,
+    });
+    const capabilityMap = new Map();
+    // Sub-agents get a subset of tools (no sub-agent recursion)
+    const subTools = registeredCapabilities.filter(c => c.spec.name !== 'Agent');
+    for (const cap of subTools) {
+        capabilityMap.set(cap.spec.name, cap);
+    }
+    const toolDefs = subTools.map(c => c.spec);
+    const systemInstructions = assembleInstructions(ctx.workingDir);
+    const systemPrompt = systemInstructions.join('\n\n');
+    const history = [
+        { role: 'user', content: prompt },
+    ];
+    const maxTurns = 30;
+    const SUB_AGENT_TIMEOUT_MS = 5 * 60 * 1000; // 5 minute total timeout
+    const deadline = Date.now() + SUB_AGENT_TIMEOUT_MS;
+    let turn = 0;
+    let finalText = '';
+    while (turn < maxTurns) {
+        if (Date.now() > deadline) {
+            return { output: `[${description || 'sub-agent'}] timed out after 5 minutes (${turn} turns completed).`, isError: true };
+        }
+        turn++;
+        const { content: parts } = await client.complete({
+            model: model || 'anthropic/claude-sonnet-4.6',
+            messages: history,
+            system: systemPrompt,
+            tools: toolDefs,
+            max_tokens: 16384,
+            stream: true,
+        }, ctx.abortSignal);
+        history.push({ role: 'assistant', content: parts });
+        // Collect text and invocations
+        const invocations = [];
+        for (const part of parts) {
+            if (part.type === 'text') {
+                finalText = part.text;
+            }
+            else if (part.type === 'tool_use') {
+                invocations.push(part);
+            }
+        }
+        if (invocations.length === 0)
+            break;
+        // Execute tools
+        const outcomes = [];
+        for (const inv of invocations) {
+            const handler = capabilityMap.get(inv.name);
+            let result;
+            if (handler) {
+                try {
+                    result = await handler.execute(inv.input, ctx);
+                }
+                catch (err) {
+                    result = {
+                        output: `Error: ${err.message}`,
+                        isError: true,
+                    };
+                }
+            }
+            else {
+                result = { output: `Unknown tool: ${inv.name}`, isError: true };
+            }
+            outcomes.push({
+                type: 'tool_result',
+                tool_use_id: inv.id,
+                content: result.output,
+                is_error: result.isError,
+            });
+        }
+        history.push({ role: 'user', content: outcomes });
+    }
+    const label = description || 'sub-agent';
+    return {
+        output: finalText || `[${label}] completed after ${turn} turn(s) with no text output.`,
+    };
+}
+export function createSubAgentCapability(apiUrl, chain, capabilities) {
+    registeredApiUrl = apiUrl;
+    registeredChain = chain;
+    registeredCapabilities = capabilities;
+    return {
+        spec: {
+            name: 'Agent',
+            description: 'Launch a sub-agent for independent tasks. The sub-agent has its own context and tools.',
+            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' },
+                    model: { type: 'string', description: 'Model for the sub-agent. Default: claude-sonnet-4.6' },
+                },
+                required: ['prompt'],
+            },
+        },
+        execute,
+        concurrent: false,
+    };
+}

package/dist/tools/task.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Task capability — in-session task tracking for the agent.
+ */
+import type { CapabilityHandler } from '../agent/types.js';
+export declare const taskCapability: CapabilityHandler;

package/dist/tools/task.js

@@ -0,0 +1,91 @@
+/**
+ * Task capability — in-session task tracking for the agent.
+ */
+// In-memory task store (per session)
+const tasks = [];
+let nextId = 1;
+async function execute(input, _ctx) {
+    const { action, subject, description, task_id, status } = input;
+    switch (action) {
+        case 'create': {
+            if (!subject) {
+                return { output: 'Error: subject is required for create', isError: true };
+            }
+            const task = {
+                id: nextId++,
+                subject,
+                status: 'pending',
+                description,
+            };
+            tasks.push(task);
+            return { output: `Task #${task.id} created: ${task.subject}` };
+        }
+        case 'update': {
+            if (!task_id) {
+                return { output: 'Error: task_id is required for update', isError: true };
+            }
+            const task = tasks.find(t => t.id === task_id);
+            if (!task) {
+                return { output: `Error: task #${task_id} not found`, isError: true };
+            }
+            if (status)
+                task.status = status;
+            if (subject)
+                task.subject = subject;
+            if (description)
+                task.description = description;
+            return { output: `Task #${task.id} updated: ${task.status} — ${task.subject}` };
+        }
+        case 'list': {
+            if (tasks.length === 0) {
+                return { output: 'No tasks.' };
+            }
+            const pending = tasks.filter(t => t.status !== 'completed').length;
+            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}`;
+            });
+            lines.push(`\n${done} done, ${pending} remaining`);
+            return { output: lines.join('\n') };
+        }
+        case 'delete': {
+            if (!task_id) {
+                return { output: 'Error: task_id is required for delete', isError: true };
+            }
+            const idx = tasks.findIndex(t => t.id === task_id);
+            if (idx === -1) {
+                return { output: `Error: task #${task_id} not found`, isError: true };
+            }
+            const removed = tasks.splice(idx, 1)[0];
+            return { output: `Task #${removed.id} deleted: ${removed.subject}` };
+        }
+        default:
+            return { output: `Error: unknown action "${action}". Use create, update, or list.`, isError: true };
+    }
+}
+export const taskCapability = {
+    spec: {
+        name: 'Task',
+        description: 'Manage in-session tasks. Actions: create, update (status/subject), list (with summary), delete.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                action: {
+                    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)' },
+                status: {
+                    type: 'string',
+                    description: 'New status: "pending", "in_progress", or "completed" (for update)',
+                },
+            },
+            required: ['action'],
+        },
+    },
+    execute,
+    concurrent: false,
+};

package/dist/tools/webfetch.d.ts

@@ -0,0 +1,5 @@
+/**
+ * WebFetch capability — fetch web page content.
+ */
+import type { CapabilityHandler } from '../agent/types.js';
+export declare const webFetchCapability: CapabilityHandler;