@blockrun/franklin 3.12.2 → 3.12.3

package/dist/agent/context.js

@@ -232,6 +232,53 @@ A bare \`402\` on a POST means the endpoint is healthy and the payment flow is w
 
 **Verifying gateway health**: GET \`/v1/health/overview\` (free) is the right probe. Listing endpoints? Fetch \`/openapi.json\` and read the \`paths\` object — that is the source of truth, not your training memory.`;
 }
+function getTradingPlaybookSection() {
+    return `# Trading playbook (built-in tools)
+
+Franklin has built-in tools for live Solana DEX swaps (\`JupiterSwap\`, \`JupiterQuote\`) and DeFi-data lookups (\`DeFiLlamaProtocols\`, \`DeFiLlamaProtocol\`, \`DeFiLlamaChains\`, \`DeFiLlamaYields\`, \`DeFiLlamaPrice\`). When the user asks for live trades or DeFi data, route through these tools — NOT WebSearch, NOT Bash + curl, NOT WebFetch (those won't sign x402 payments and will hit 402 walls).
+
+## Before any live swap
+
+1. **Quote first if the user hasn't already seen the numbers.** Run \`JupiterQuote\` to surface input amount, output amount, rate, price impact, and route. Users make informed decisions when they see numbers, not vibes.
+2. **Reject \`priceImpactPct\` > 5 %** unless the user has explicitly asked to proceed despite impact. Memecoins on illiquid days routinely have 10–30 % impact — that is a money-losing trade. Tell them, ask them, then maybe proceed.
+3. **Large-swap warning above ~\$20 USD equivalent.** Estimate via stablecoin reference if available (USDC, USDT inputs are 1:1). If you can't reliably estimate, say so in the AskUser prompt: "I cannot easily price-check this output token in USD before the swap; please confirm only if you know what you are buying."
+
+## During a swap
+
+- **Default \`auto_approve: false\`.** Only set true if the user has just authorized this specific call ("yes, swap 0.01 SOL for USDC"). NEVER set auto-approve session-wide. NEVER set it to "just do all three swaps I asked about" — each swap gets its own AskUser confirmation.
+- **Be transparent about the 20 bps BlockRun referral fee.** It is shown by \`JupiterQuote\` automatically; if the user asks why, explain: it's BlockRun's integrator cut via Jupiter's official Referral Program — same mechanism Phantom and other Solana wallets use. The user is paying for the convenience layer.
+- **Surface the Solscan link prominently after execution.** Trust is built on receipts. "Done" without a signature link is a red flag for the user.
+
+## Failure handling
+
+- \`No Solana wallet found\` → run \`franklin setup solana\`. The harness usually auto-creates on first run; this error means the file is corrupt or unreadable.
+- \`/execute\` returns \`InsufficientFundsForRent\` / \`insufficient lamports\` / \`TokenAccountNotFound\` → user's Solana wallet is empty for the input mint. Show them the wallet pubkey (it was in the AskUser prompt) and tell them to send the input token to that address.
+- \`/order\` returns no transaction or 30 %+ price impact → no liquidity for the pair. Suggest a smaller amount or a different output token.
+- Live-swap session cap reached → user has done many live swaps in this session. Hard-stop is intentional; suggest \`/retry\` or set \`FRANKLIN_LIVE_SWAP_CAP\` to raise.
+
+## Never
+
+- Chain multiple live swaps without showing the running USD spent so far this turn.
+- Tell the user "I executed your trade" without the Solscan link or signature.
+- Compute USD value or P&L by guessing prices. Use \`TradingMarket\`, \`DeFiLlamaPrice\`, or \`JupiterQuote\` (with stablecoin reference) for ground truth.
+- Mix paper and live state in your reply. Paper trading lives in \`TradingPortfolio\` (\`~/.blockrun/portfolio.json\`); live swaps are recorded in \`~/.blockrun/trades.jsonl\` with \`kind: 'live'\`. Be explicit about which one you're acting in.
+
+## DeFi data (DeFiLlama tools)
+
+- Match the tool to the question.
+  - "What's pumping on Solana?" → \`DeFiLlamaProtocols(chain='Solana', top_n=10)\`
+  - "Top yield for USDC" → \`DeFiLlamaYields(symbol='USDC', stablecoin_only=true)\`
+  - "Aave's TVL" → \`DeFiLlamaProtocol(slug='aave-v3')\`
+  - "BTC price" → \`DeFiLlamaPrice(coins=['coingecko:bitcoin'])\` or \`TradingMarket\`
+- **Filter aggressively.** Default \`top_n=10\` unless the user asked for more. Raw DefiLlama payloads are 5–10 MB and will blow your context window.
+- **Never call the same DeFiLlama endpoint twice in one turn.** Each call is paid. If you find yourself doing it, your plan is wrong.
+
+## Paper vs. live
+
+- Paper trading (TradingPortfolio etc.) is for plan-grade simulation: positions, risk caps, P&L tracking, no on-chain. Use it when the user wants to "test" or "simulate" a strategy.
+- Live trading is JupiterSwap. It costs real USDC, signs an on-chain tx, and shows up on Solscan. NEVER conflate — if the user says "swap" they usually mean live; if they say "simulate" or "paper" they mean paper.
+`;
+}
 function getToolPatternsSection() {
     return `# Tool Selection Patterns
 - **Finding files**: Glob first (by name/pattern), then Grep (by content), then Read (specific file). Don't start with Read unless you know the exact path.
@@ -300,6 +347,7 @@ export function assembleInstructions(workingDir, model) {
         getMissingAccessSection(),
         getWalletKnowledgeSection(),
         getBlockRunApiSection(),
+        getTradingPlaybookSection(),
         getToolPatternsSection(),
         getTokenEfficiencySection(),
         getVerificationSection(),

package/dist/tools/jupiter.js

@@ -27,6 +27,47 @@ const BLOCKRUN_REFERRAL_FEE_BPS = 20; // 0.2% — Jupiter docs default; well bel
 const ULTRA_BASE = 'https://lite-api.jup.ag/ultra/v1';
 const ORDER_TIMEOUT_MS = 15_000;
 const EXECUTE_TIMEOUT_MS = 30_000;
+// ─── Session safety: cumulative live-swap counter ─────────────────────────
+// We removed the per-turn $-cap in v3.11.0 because it kept firing on legit
+// LLM workloads — but a live on-chain swap is irreversible, so a cap here is
+// different in kind. Default 10 swaps per Franklin process; user can override
+// via FRANKLIN_LIVE_SWAP_CAP env (set to 0 to disable). Resets on restart.
+const DEFAULT_LIVE_SWAP_CAP = 10;
+const liveSwapCap = (() => {
+    const raw = process.env.FRANKLIN_LIVE_SWAP_CAP;
+    if (!raw)
+        return DEFAULT_LIVE_SWAP_CAP;
+    const n = Number(raw);
+    if (!Number.isFinite(n))
+        return DEFAULT_LIVE_SWAP_CAP;
+    if (n <= 0)
+        return Infinity;
+    return Math.floor(n);
+})();
+let liveSwapCount = 0;
+// ─── Large-swap warning threshold ────────────────────────────────────────
+// USD value above which we surface a "Large swap" line in the AskUser
+// confirm — only computable when input is a known stablecoin. Override via
+// FRANKLIN_LIVE_SWAP_WARN_USD env (default $20).
+const DEFAULT_LARGE_SWAP_USD = 20;
+const largeSwapThresholdUsd = (() => {
+    const raw = process.env.FRANKLIN_LIVE_SWAP_WARN_USD;
+    if (!raw)
+        return DEFAULT_LARGE_SWAP_USD;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < 0)
+        return DEFAULT_LARGE_SWAP_USD;
+    return n;
+})();
+const STABLECOIN_MINTS = new Set([
+    'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', // USDC
+    'Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB', // USDT
+]);
+function estimateUsdValue(inputMint, humanAmount) {
+    if (STABLECOIN_MINTS.has(inputMint))
+        return humanAmount;
+    return null; // unknown — caller will surface a "couldn't price" warning instead
+}
 // ─── Symbol → mint shortcuts ──────────────────────────────────────────────
 // Agents prefer "USDC" / "SOL" over 44-char base58 mint addresses. Anything
 // not in this map is passed through verbatim — power users can drop in any
@@ -180,22 +221,37 @@ async function executeJupiterQuote(input) {
     }
 }
 async function executeJupiterSwap(input, ctx) {
+    // Session-cap pre-check (cheapest, fail fast).
+    if (liveSwapCount >= liveSwapCap) {
+        return {
+            output: `Live-swap session cap reached (${liveSwapCount}/${liveSwapCap}). ` +
+                `Stopping to protect your wallet — this is a deliberate guardrail, not an error in your prompt.\n\n` +
+                `To raise: \`FRANKLIN_LIVE_SWAP_CAP=20 franklin\` (or 0 to disable).\n` +
+                `To continue with a fresh count: restart Franklin (\`exit\` then re-launch).`,
+            isError: true,
+        };
+    }
     const inputMint = resolveMint(input.input_mint);
     const outputMint = resolveMint(input.output_mint);
     const inDec = decimalsFor(inputMint);
     const amountAtomic = toAtomicUnits(input.amount, inDec);
-    // Load wallet first — fail fast if Solana isn't set up.
+    // Load wallet — `getOrCreateSolanaWallet` auto-creates on first run, so this
+    // path firing means the file is corrupt or the .blockrun dir is unreadable.
     let keypair;
     try {
         keypair = await loadSolanaKeypair();
     }
     catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
         return {
-            output: `No Solana wallet found. Run \`franklin setup solana\` to generate one, or check ~/.blockrun/solana-wallet.json.\n` +
-                `(${err instanceof Error ? err.message : 'unknown error'})`,
+            output: `Couldn't load your Solana wallet. ` +
+                `Run \`franklin setup solana\` to (re)generate one. ` +
+                `If that's already worked before, check ~/.blockrun/solana-wallet.json is readable.\n\n` +
+                `Underlying error: ${msg}`,
             isError: true,
         };
     }
+    const walletAddress = keypair.publicKey.toBase58();
     // Step 1 — fetch order with our referral identity attached.
     let order;
     try {
@@ -203,7 +259,7 @@ async function executeJupiterSwap(input, ctx) {
             inputMint,
             outputMint,
             amount: amountAtomic,
-            taker: keypair.publicKey.toBase58(),
+            taker: walletAddress,
         });
     }
     catch (err) {
@@ -221,8 +277,16 @@ async function executeJupiterSwap(input, ctx) {
     // Step 2 — confirm with user (unless explicit auto_approve override).
     if (!input.auto_approve && ctx.onAskUser) {
         const quoteText = formatQuote(order);
-        const question = `Execute this Jupiter swap?\n\n${quoteText}\n\nWallet: ${keypair.publicKey.toBase58()}`;
-        const answer = await ctx.onAskUser(question, ['Confirm', 'Cancel']);
+        const usdEst = estimateUsdValue(inputMint, input.amount);
+        const sections = ['Execute this Jupiter swap?', '', quoteText];
+        if (usdEst != null && usdEst >= largeSwapThresholdUsd) {
+            sections.push('', `⚠ Large swap warning — input is ~$${usdEst.toFixed(2)} (above $${largeSwapThresholdUsd} threshold). Confirm only if this matches your intent.`);
+        }
+        else if (usdEst == null) {
+            sections.push('', `Note: input is not a stablecoin, so I cannot price-check this in USD before signing. Verify the output amount matches your intent.`);
+        }
+        sections.push('', `Wallet: ${walletAddress}`, `Live-swap session count: ${liveSwapCount}/${liveSwapCap === Infinity ? '∞' : liveSwapCap}`);
+        const answer = await ctx.onAskUser(sections.join('\n'), ['Confirm', 'Cancel']);
         if (answer.toLowerCase() !== 'confirm') {
             return { output: 'Swap cancelled by user.' };
         }
@@ -248,6 +312,19 @@ async function executeJupiterSwap(input, ctx) {
             requestId: order.requestId,
         });
         if (exec.status !== 'Success') {
+            const errStr = (exec.error ?? '').toLowerCase();
+            const looksInsufficient = errStr.includes('insufficient') ||
+                errStr.includes('lamports') ||
+                errStr.includes('tokenaccountnotfound') ||
+                errStr.includes('not enough');
+            if (looksInsufficient) {
+                return {
+                    output: `Swap failed: insufficient balance. Your Solana wallet (${walletAddress}) does not hold enough of the input token.\n\n` +
+                        `Send ${symbolFor(inputMint)} to that address (or fund it via the Franklin UI), then retry.\n\n` +
+                        `Underlying error: ${exec.error ?? exec.code ?? 'unknown'}`,
+                    isError: true,
+                };
+            }
             return {
                 output: `Jupiter Ultra /execute reported ${exec.status}` +
                     (exec.error ? `: ${exec.error}` : '') +
@@ -255,6 +332,7 @@ async function executeJupiterSwap(input, ctx) {
                 isError: true,
             };
         }
+        liveSwapCount += 1;
         const sig = exec.signature ?? '<unknown>';
         const explorer = `https://solscan.io/tx/${sig}`;
         return {
@@ -263,6 +341,7 @@ async function executeJupiterSwap(input, ctx) {
                 formatQuote(order),
                 `Signature: ${sig}`,
                 explorer,
+                `(Session live-swap count: ${liveSwapCount}/${liveSwapCap === Infinity ? '∞' : liveSwapCap})`,
             ].join('\n'),
         };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/franklin",
-  "version": "3.12.2",
+  "version": "3.12.3",
   "description": "Franklin — The AI agent with a wallet. Spends USDC autonomously to get real work done. Pay per action, no subscriptions.",
   "type": "module",
   "exports": {