@blockrun/franklin 3.7.9 → 3.8.0

package/dist/tools/imagegen.d.ts

@@ -3,4 +3,18 @@
  * Uses x402 payment on Solana or Base.
  */
 import type { CapabilityHandler } from '../agent/types.js';
+import type { ContentLibrary } from '../content/library.js';
+export interface ImageGenDeps {
+    /** Optional Content library for auto-recording generations into a piece. */
+    library?: ContentLibrary;
+    /** Invoked after successful content-linked generation; lets callers persist. */
+    onContentChange?: () => void | Promise<void>;
+}
+/**
+ * Build the ImageGen capability. Passing `deps.library` enables the
+ * contentId flow: pre-flight budget check + post-generation asset
+ * recording. With no deps, behavior matches the pre-factory version.
+ */
+export declare function createImageGenCapability(deps?: ImageGenDeps): CapabilityHandler;
+/** Back-compat static capability for callers that don't want the Content bridge. */
 export declare const imageGenCapability: CapabilityHandler;

package/dist/tools/imagegen.js

@@ -6,99 +6,146 @@ 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 || 'openai/gpt-image-1';
-    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': `franklin/${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 };
+import { checkImageBudget, recordImageAsset } from '../content/record-image.js';
+function buildExecute(deps) {
+    return async function execute(input, ctx) {
+        const { prompt, output_path, size, model, contentId } = input;
+        if (!prompt) {
+            return { output: 'Error: prompt is required', isError: true };
+        }
+        // ── Content pre-flight: refuse BEFORE paying if budget can't cover this ──
+        const imageModel = model || 'openai/gpt-image-1';
+        const imageSize = size || '1024x1024';
+        if (contentId && deps.library) {
+            const decision = checkImageBudget(deps.library, contentId, imageModel, imageSize);
+            if (!decision.ok) {
+                // Normal text output, not isError — the agent should adapt (smaller
+                // size, different model, raise budget) rather than trigger retry.
+                return {
+                    output: `## Image generation skipped\n` +
+                        `- ${decision.reason}\n\n` +
+                        `No USDC was spent. Choose a cheaper model/size or raise the ` +
+                        `content budget before trying again.`,
+                };
             }
-            response = await fetch(endpoint, {
+        }
+        const chain = loadChain();
+        const apiUrl = API_URLS[chain];
+        const endpoint = `${apiUrl}/v1/images/generations`;
+        // 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': `franklin/${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: { ...headers, ...paymentHeaders },
+                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}` : '';
+            let contentSummary = '';
+            if (contentId && deps.library) {
+                const rec = recordImageAsset(deps.library, {
+                    contentId,
+                    imagePath: outPath,
+                    model: imageModel,
+                    size: imageSize,
+                });
+                if (rec.ok) {
+                    if (deps.onContentChange)
+                        await deps.onContentChange();
+                    const c = deps.library.get(contentId);
+                    contentSummary =
+                        `\n\n## Content updated\n` +
+                            `- Attached to \`${contentId}\` at est. $${rec.costUsd.toFixed(2)}\n` +
+                            (c
+                                ? `- Spent: $${c.spentUsd.toFixed(2)} / $${c.budgetUsd.toFixed(2)} cap ` +
+                                    `(remaining $${(c.budgetUsd - c.spentUsd).toFixed(2)})`
+                                : '');
+                }
+                else {
+                    // Pre-flight guarded this, but keep defensive — bookkeeping refusal
+                    // after a successful paid generation is rare (TOCTOU) but possible.
+                    contentSummary =
+                        `\n\n## Content NOT updated\n` +
+                            `- ${rec.reason}\n` +
+                            `- The image was generated and saved locally; cost was NOT recorded ` +
+                            `against the content budget.`;
+                }
+            }
+            return {
+                output: `Image saved to ${outPath} (${sizeKB}KB, ${imageSize})${revisedPrompt}\n\nOpen with: open ${outPath}${contentSummary}`,
+            };
         }
-        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 };
+        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 };
         }
-        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 };
+        finally {
+            clearTimeout(timeout);
         }
-        return { output: `Error: ${msg}`, isError: true };
-    }
-    finally {
-        clearTimeout(timeout);
-    }
+    };
 }
 // ─── Payment ───────────────────────────────────────────────────────────────
 async function signPayment(response, chain, endpoint) {
@@ -152,21 +199,37 @@ async function extractPaymentReq(response) {
     return header;
 }
 // ─── Export ────────────────────────────────────────────────────────────────
-export const imageGenCapability = {
-    spec: {
-        name: 'ImageGen',
-        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: {
-                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: openai/gpt-image-1' },
+/**
+ * Build the ImageGen capability. Passing `deps.library` enables the
+ * contentId flow: pre-flight budget check + post-generation asset
+ * recording. With no deps, behavior matches the pre-factory version.
+ */
+export function createImageGenCapability(deps = {}) {
+    return {
+        spec: {
+            name: 'ImageGen',
+            description: "Generate an image from a text prompt. 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. Pass contentId to attach the result to an existing Content " +
+                "piece: the content's budget is checked BEFORE paying, and on success " +
+                "the image is recorded as an asset with its estimated cost. Skipping " +
+                "contentId generates a one-off image with no budget tracking.",
+            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: openai/gpt-image-1' },
+                    contentId: { type: 'string', description: 'Optional Content id to attach this generation to. Pre-flight budget check + auto-record on success.' },
+                },
+                required: ['prompt'],
             },
-            required: ['prompt'],
         },
-    },
-    execute,
-    concurrent: false,
-};
+        execute: buildExecute(deps),
+        concurrent: false,
+    };
+}
+/** Back-compat static capability for callers that don't want the Content bridge. */
+export const imageGenCapability = createImageGenCapability();

package/dist/tools/index.d.ts

@@ -11,6 +11,12 @@ import { grepCapability } from './grep.js';
 import { webFetchCapability } from './webfetch.js';
 import { webSearchCapability } from './websearch.js';
 import { taskCapability } from './task.js';
+/**
+ * Reset module-level tool state that would otherwise leak between sessions
+ * when the same process runs `interactiveSession()` more than once (library
+ * callers, tests, planned daemon mode). Safe to call before every session.
+ */
+export declare function resetToolSessionState(): void;
 /** 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, };

package/dist/tools/index.js

@@ -1,21 +1,105 @@
 /**
  * Tool registry — exports all available capabilities for the agent.
  */
-import { readCapability } from './read.js';
+import os from 'node:os';
+import path from 'node:path';
+import { readCapability, clearSessionState as clearReadSessionState } from './read.js';
 import { writeCapability } from './write.js';
 import { editCapability } from './edit.js';
-import { bashCapability } from './bash.js';
+import { bashCapability, clearSessionState as clearBashSessionState } from './bash.js';
 import { globCapability } from './glob.js';
 import { grepCapability } from './grep.js';
-import { webFetchCapability } from './webfetch.js';
+import { webFetchCapability, clearSessionState as clearWebFetchSessionState } from './webfetch.js';
 import { webSearchCapability } from './websearch.js';
 import { taskCapability } from './task.js';
-import { imageGenCapability } from './imagegen.js';
+import { createImageGenCapability } from './imagegen.js';
 import { askUserCapability } from './askuser.js';
 import { tradingSignalCapability, tradingMarketCapability } from './trading.js';
 import { searchXCapability } from './searchx.js';
 import { postToXCapability } from './posttox.js';
 import { moaCapability } from './moa.js';
+import { createTradingCapabilities } from './trading-execute.js';
+import { Portfolio } from '../trading/portfolio.js';
+import { RiskEngine } from '../trading/risk.js';
+import { LiveExchange } from '../trading/live-exchange.js';
+import { TradingEngine } from '../trading/engine.js';
+import { loadPortfolio, savePortfolio } from '../trading/store.js';
+import { TradeLog } from '../trading/trade-log.js';
+import { getPrice as cgGetPrice } from '../trading/data.js';
+import { createContentCapabilities } from './content-execute.js';
+import { ContentLibrary } from '../content/library.js';
+import { loadLibrary as loadContentLibrary, saveLibrary as saveContentLibrary } from '../content/store.js';
+// ─── Default Trading Engine ────────────────────────────────────────────────
+// Paper trading defaults: $1000 starting bankroll, $400 per-position cap
+// (2.5 positions fully loaded), $900 total exposure cap (keep 10% cash buffer).
+// Live prices from CoinGecko; simulated fills at 10 bps. Portfolio persists
+// to ~/.blockrun/portfolio.json across sessions — that persistence is the
+// whole point of this vertical (Claude Code / Cursor cannot carry trading
+// state between runs).
+const DEFAULT_PORTFOLIO_PATH = path.join(os.homedir(), '.blockrun', 'portfolio.json');
+const DEFAULT_TRADE_LOG_PATH = path.join(os.homedir(), '.blockrun', 'trades.jsonl');
+const DEFAULT_STARTING_CASH_USD = 1_000;
+const DEFAULT_RISK_CONFIG = { maxPositionUsd: 400, maxTotalExposureUsd: 900 };
+const DEFAULT_FEE_BPS = 10;
+function buildDefaultTradingCapabilities() {
+    const portfolio = loadPortfolio(DEFAULT_PORTFOLIO_PATH) ??
+        new Portfolio({ startingCashUsd: DEFAULT_STARTING_CASH_USD });
+    const risk = new RiskEngine(DEFAULT_RISK_CONFIG);
+    const exchange = new LiveExchange({
+        pricing: { getPrice: cgGetPrice },
+        feeBps: DEFAULT_FEE_BPS,
+    });
+    const engine = new TradingEngine({ portfolio, risk, exchange });
+    const tradeLog = new TradeLog(DEFAULT_TRADE_LOG_PATH);
+    return createTradingCapabilities({
+        engine,
+        riskConfig: DEFAULT_RISK_CONFIG,
+        tradeLog,
+        onStateChange: () => {
+            try {
+                savePortfolio(portfolio, DEFAULT_PORTFOLIO_PATH);
+            }
+            catch {
+                // Persistence best-effort — never block a trade on disk failure.
+            }
+        },
+    });
+}
+const defaultTradingCapabilities = buildDefaultTradingCapabilities();
+// ─── Default Content Library ──────────────────────────────────────────────
+// Durable content projects at ~/.blockrun/content.json. Like the portfolio,
+// this is persistent cross-session state — something Claude Code structurally
+// cannot offer.
+const DEFAULT_CONTENT_PATH = path.join(os.homedir(), '.blockrun', 'content.json');
+// Build a single ContentLibrary instance so both the Content capabilities and
+// the content-aware ImageGen capability share state and persistence.
+const defaultContentLibrary = loadContentLibrary(DEFAULT_CONTENT_PATH) ?? new ContentLibrary();
+const persistContentLibrary = () => {
+    try {
+        saveContentLibrary(defaultContentLibrary, DEFAULT_CONTENT_PATH);
+    }
+    catch {
+        // Best-effort — in-memory library remains authoritative.
+    }
+};
+const defaultContentCapabilities = createContentCapabilities({
+    library: defaultContentLibrary,
+    onStateChange: persistContentLibrary,
+});
+const defaultImageGenCapability = createImageGenCapability({
+    library: defaultContentLibrary,
+    onContentChange: persistContentLibrary,
+});
+/**
+ * Reset module-level tool state that would otherwise leak between sessions
+ * when the same process runs `interactiveSession()` more than once (library
+ * callers, tests, planned daemon mode). Safe to call before every session.
+ */
+export function resetToolSessionState() {
+    clearReadSessionState();
+    clearWebFetchSessionState();
+    clearBashSessionState();
+}
 /** All capabilities available to the Franklin agent (excluding sub-agent, which needs config). */
 export const allCapabilities = [
     readCapability,
@@ -27,10 +111,12 @@ export const allCapabilities = [
     webFetchCapability,
     webSearchCapability,
     taskCapability,
-    imageGenCapability,
+    defaultImageGenCapability,
     askUserCapability,
     tradingSignalCapability,
     tradingMarketCapability,
+    ...defaultTradingCapabilities, // TradingPortfolio, TradingOpenPosition, TradingClosePosition, TradingHistory
+    ...defaultContentCapabilities, // ContentCreate, ContentAddAsset, ContentShow, ContentList
     searchXCapability,
     postToXCapability,
     moaCapability,

package/dist/tools/read.d.ts

@@ -24,4 +24,17 @@ export declare const fileReadTracker: Map<string, {
 }>;
 /** Invalidate the content cache for a file (call after Edit/Write modifies it). */
 export declare function invalidateFileCache(resolvedPath: string): void;
+/**
+ * Reset all module-level tracking state for a fresh session.
+ *
+ * These Maps live at module scope (not inside a class) because read/edit/write
+ * tools share them to enforce "read-before-edit" and to cache unchanged files.
+ * When a library caller invokes `interactiveSession()` a second time in the
+ * same process, stale entries from the prior session would:
+ *   - make Edit/Write falsely believe files were read in this session
+ *   - serve cached content for files that may have changed externally
+ *   - keep partial-read bounds from the wrong session
+ * Called from the agent loop at session start to guarantee a clean slate.
+ */
+export declare function clearSessionState(): void;
 export declare const readCapability: CapabilityHandler;

package/dist/tools/read.js

@@ -34,6 +34,23 @@ function cacheKey(resolved, offset, limit) {
 export function invalidateFileCache(resolvedPath) {
     fileContentCache.delete(resolvedPath);
 }
+/**
+ * Reset all module-level tracking state for a fresh session.
+ *
+ * These Maps live at module scope (not inside a class) because read/edit/write
+ * tools share them to enforce "read-before-edit" and to cache unchanged files.
+ * When a library caller invokes `interactiveSession()` a second time in the
+ * same process, stale entries from the prior session would:
+ *   - make Edit/Write falsely believe files were read in this session
+ *   - serve cached content for files that may have changed externally
+ *   - keep partial-read bounds from the wrong session
+ * Called from the agent loop at session start to guarantee a clean slate.
+ */
+export function clearSessionState() {
+    fileReadTracker.clear();
+    partiallyReadFiles.clear();
+    fileContentCache.clear();
+}
 async function execute(input, ctx) {
     const { file_path: filePath, offset, limit } = input;
     if (!filePath) {

package/dist/tools/trading-execute.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Trading execution capabilities. Exposes Franklin's Portfolio + RiskEngine
+ * + Exchange stack to the agent as three tools: TradingPortfolio (read),
+ * TradingOpenPosition (buy side), TradingClosePosition (sell side).
+ *
+ * This is the surface that differentiates Franklin from generic coding
+ * agents — Claude Code and Cursor cannot hold a wallet, track positions
+ * across sessions, or reason about P&L. Every output here is deliberately
+ * information-rich so the agent has the numbers it needs to make the next
+ * economic decision (cash left, risk utilization, unrealized vs realized
+ * P&L, fill detail) without a follow-up tool call.
+ *
+ * Factory-style construction (createTradingCapabilities) keeps testing
+ * clean: production code calls it with a default disk-backed engine;
+ * tests inject a MockExchange-backed engine and assert behavior without
+ * touching disk.
+ */
+import type { CapabilityHandler } from '../agent/types.js';
+import type { TradingEngine } from '../trading/engine.js';
+import type { RiskConfig } from '../trading/risk.js';
+import type { TradeLog } from '../trading/trade-log.js';
+export interface TradingCapabilitiesDeps {
+    engine: TradingEngine;
+    /** Risk config used to report "you're using X% of your position cap". */
+    riskConfig?: RiskConfig;
+    /** Optional hook run after every state-changing call (e.g., persist to disk). */
+    onStateChange?: () => void | Promise<void>;
+    /**
+     * Optional persistent trade log. When provided, opens and closes are
+     * appended to it and the TradingHistory capability is registered so the
+     * agent can query cross-session P&L.
+     */
+    tradeLog?: TradeLog;
+}
+export declare function createTradingCapabilities(deps: TradingCapabilitiesDeps): CapabilityHandler[];