@blockrun/franklin 3.21.8 → 3.22.0

package/README.md

@@ -487,6 +487,18 @@ Same wallet. Same tools. From your phone.
 
 ---
 
+## Contributors
+
+External contributors whose work has shipped into Franklin:
+
+- [**@KillerQueen-Z**](https://github.com/KillerQueen-Z) — typed Phone & Voice tools (#58), permissions classifier + internal VoiceStatus polling (#59), inline-paste threshold (#60), voicemail controls (#61), PredictionMarket / Predexon v2 schema realignment + agent-loop retry guard (#62)
+- [**@BeneficialVast1048**](https://github.com/BeneficialVast1048) — VoiceCall `interruption_threshold` + `model` controls (#66)
+- [**@TateLyman**](https://github.com/TateLyman) — test path-with-spaces fix (#57)
+
+PRs welcome — see the Development section below for the local loop.
+
+---
+
 ## Development
 
 ```bash

package/dist/agent/context.js

@@ -305,8 +305,10 @@ On-chain affiliate (20 bps in sell-token, force-set server-side) flows to BlockR
 - US/CA destinations only. Marketing/sales calls require prior express consent (TCPA).
 
 **Surf — crypto data + chat (x402-paid)** via the generic \`BlockRun\` capability. ~55 curated endpoints. Tier-1 $0.001, Tier-2 $0.005, Tier-3 / chat $0.02.
-- \`/v1/surf/exchange/*\` — CEX trading pairs, prices, perps, depth, klines, funding history, long/short ratio.
-- \`/v1/surf/market/*\` — token rankings, fear/greed, futures, ETF flows, options skew, liquidations, on-chain indicators (NUPL/SOPR/MVRV), price indicators (RSI/MACD/BBANDS).
+- \`/v1/surf/market/ranking\` — token rankings (market cap, volume, change). **This is the token-ranking endpoint — there is no \`market/token-ranking\` or \`market/concept-ranking\`.**
+- \`/v1/surf/market/fear-greed\` — Fear & Greed index. \`market/futures\` — futures overview. \`market/price\` (needs \`symbol\`) — price history. \`market/etf\` (needs \`symbol\`) — spot ETF flows. \`market/options\` (needs \`symbol\`) — options skew/IV.
+- \`/v1/surf/market/{liquidation/chart,liquidation/order,onchain-indicator,price-indicator}\` — liquidations, on-chain indicators (NUPL/SOPR/MVRV), technical indicators (RSI/MACD/BBANDS). Tier-2 $0.005.
+- \`/v1/surf/exchange/{price,perp,markets,depth,klines,funding-history}\` — CEX ticker, perps, pairs catalog, depth, klines, funding.
 - \`/v1/surf/news/{feed,detail}\` — AI-curated crypto news.
 - \`/v1/surf/onchain/{bridge,yield,gas-price,tx,schema,query,sql}\` — bridge/yield rankings, gas, tx detail, **raw SQL against 80+ indexed chain tables (Tier-3, $0.02)**, structured chain query, schema introspection.
 - \`/v1/surf/token/{tokenomics,dex-trades,holders,transfers}\` — token analytics.
@@ -315,7 +317,7 @@ On-chain affiliate (20 bps in sell-token, force-set server-side) flows to BlockR
 - \`/v1/surf/fund/{detail,portfolio,ranking}\` — VC fund profiles, portfolios, ranking.
 - \`/v1/surf/project/{detail,defi/metrics,defi/ranking}\` — project profiles + DeFi protocol metrics.
 
-For Surf workflows, prefer the bundled skills (\`/surf-market\`, \`/surf-chain\`, \`/surf-social\`) — they document which endpoint to pick for which question and the cost trade-off. Skipped (use the dedicated tools instead): \`/v1/surf/prediction-market/*\` (use \`PredictionMarket\`), \`/v1/surf/search/*\` (use \`ExaSearch\`), \`/v1/surf/web/*\` (use \`BrowserX\`). The Surf chat surface (\`/v1/surf/chat/completions\`, surf-1.5) is **not currently exposed** by the BlockRun gateway — removed from the registry pending an upstream redesign around per-token billing. Do not attempt to call it; use the data endpoints above for crypto context, or any of the standard LLMs on \`/v1/chat/completions\` for general chat.
+**Endpoint discovery**: if you are unsure of the exact Surf path, do NOT guess blindly — any wrong \`/v1/surf/...\` path returns a 404 whose body lists every valid endpoint under \`available\`. Read that list and retry with a real path. The bundled skills (\`/surf-market\`, \`/surf-chain\`, \`/surf-social\`) also document which endpoint to pick for which question and the cost trade-off. Skipped (use the dedicated tools instead): \`/v1/surf/prediction-market/*\` (use \`PredictionMarket\`), \`/v1/surf/search/*\` (use \`ExaSearch\`), \`/v1/surf/web/*\` (use \`BrowserX\`). The Surf chat surface (\`/v1/surf/chat/completions\`, surf-1.5) is **not currently exposed** by the BlockRun gateway — removed from the registry pending an upstream redesign around per-token billing. Do not attempt to call it; use the data endpoints above for crypto context, or any of the standard LLMs on \`/v1/chat/completions\` for general chat.
 
 **Generic gateway primitive**: \`BlockRun({ path, method, params, body })\` is a single capability that signs x402 and forwards to ANY path under \`/api\`. Use it for Surf endpoints (above) and any future BlockRun partner that doesn't have a dedicated capability yet. Always specify the exact path; the primitive will not guess.
 

package/dist/content/image-pricing.d.ts

@@ -11,4 +11,10 @@
  * gateway ever exposes the realized payment amount on the response, that
  * should be preferred — fall back to this estimate when it's missing.
  */
-export declare function estimateImageCostUsd(model: string, size: string): number;
+/**
+ * Estimate the USD cost of `n` images for a model + size. `n` defaults to 1.
+ * Unknown models return 0 rather than a guess — a free/custom model should not
+ * carry a phantom charge against the Content budget, and surprise overcharging
+ * from a wrong guess is worse than under-counting.
+ */
+export declare function estimateImageCostUsd(model: string, size: string, n?: number): number;

package/dist/content/image-pricing.js

@@ -11,22 +11,45 @@
  * gateway ever exposes the realized payment amount on the response, that
  * should be preferred — fall back to this estimate when it's missing.
  */
-export function estimateImageCostUsd(model, size) {
-    const m = model.toLowerCase();
+/**
+ * Per-image base price by model + size. Mirrors the gateway's IMAGE_MODELS.sizes
+ * (blockrun src/lib/models.ts). These are base prices — the realized x402 charge
+ * adds a small markup — but they're close enough for budget tracking. Sizes not
+ * listed for a model fall back to that model's 1024x1024 tier.
+ */
+const PRICE_TABLE = {
+    'openai/dall-e-3': {
+        base: 0.04,
+        sizes: { '1024x1024': 0.04, '1792x1024': 0.08, '1024x1792': 0.08 },
+    },
+    'openai/gpt-image-1': {
+        base: 0.02,
+        sizes: { '1024x1024': 0.02, '1536x1024': 0.04, '1024x1536': 0.04 },
+    },
+    'openai/gpt-image-2': {
+        base: 0.06,
+        sizes: { '1024x1024': 0.06, '1536x1024': 0.12, '1024x1536': 0.12 },
+    },
+    'google/nano-banana': {
+        base: 0.05,
+        sizes: { '1024x1024': 0.05 },
+    },
+    'google/nano-banana-pro': {
+        base: 0.1,
+        sizes: { '1024x1024': 0.1, '2048x2048': 0.1, '4096x4096': 0.15 },
+    },
+};
+/**
+ * Estimate the USD cost of `n` images for a model + size. `n` defaults to 1.
+ * Unknown models return 0 rather than a guess — a free/custom model should not
+ * carry a phantom charge against the Content budget, and surprise overcharging
+ * from a wrong guess is worse than under-counting.
+ */
+export function estimateImageCostUsd(model, size, n = 1) {
+    const entry = PRICE_TABLE[model.toLowerCase()];
+    if (!entry)
+        return 0;
     const s = size.replace(/\s+/g, '');
-    if (m === 'openai/dall-e-3') {
-        if (s === '1792x1024' || s === '1024x1792')
-            return 0.08;
-        // All other sizes fall back to the standard 1024x1024 tier.
-        return 0.04;
-    }
-    if (m === 'openai/gpt-image-1') {
-        // gpt-image-1 standard tier; larger sizes would tier up but Franklin
-        // sends 1024x1024 as default.
-        return 0.042;
-    }
-    // Unknown model: return 0 rather than a guess. A free/custom model should
-    // not have a phantom charge against the Content budget, and surprise
-    // overcharging from a wrong guess is worse than under-counting.
-    return 0;
+    const perImage = entry.sizes[s] ?? entry.base;
+    return perImage * Math.max(1, n);
 }

package/dist/content/record-image.d.ts

@@ -34,7 +34,7 @@ export type RecordImageDecision = {
  * estimated cost fits; `{ ok: false, reason }` when it doesn't or the
  * content doesn't exist. Non-mutating.
  */
-export declare function checkImageBudget(library: ContentLibrary, contentId: string, model: string, size: string): {
+export declare function checkImageBudget(library: ContentLibrary, contentId: string, model: string, size: string, count?: number): {
     ok: true;
 } | {
     ok: false;

package/dist/content/record-image.js

@@ -20,12 +20,12 @@ import { estimateImageCostUsd } from './image-pricing.js';
  * estimated cost fits; `{ ok: false, reason }` when it doesn't or the
  * content doesn't exist. Non-mutating.
  */
-export function checkImageBudget(library, contentId, model, size) {
+export function checkImageBudget(library, contentId, model, size, count = 1) {
     const content = library.get(contentId);
     if (!content) {
         return { ok: false, reason: `Content ${contentId} not found` };
     }
-    const cost = estimateImageCostUsd(model, size);
+    const cost = estimateImageCostUsd(model, size, count);
     if (content.spentUsd + cost > content.budgetUsd + 1e-9) {
         return {
             ok: false,

package/dist/tools/blockrun.js

@@ -237,12 +237,21 @@ export const blockrunCapability = {
         }
         catch { /* best-effort */ }
         if (!result.ok) {
-            const detail = typeof result.body?.error === 'string'
-                ? result.body.error
-                : `HTTP ${result.status}`;
+            const b = result.body;
+            const detail = typeof b?.error === 'string' ? b.error : `HTTP ${result.status}`;
             const fullOutput = result.raw || JSON.stringify(result.body, null, 2);
+            // Surface the gateway's self-correction hints into the model-visible
+            // output. On a wrong path the Surf route returns `available: [...all
+            // valid paths]` (and often a `message`); without this the model only
+            // saw "Not Found" and kept guessing until the tool-failure circuit
+            // breaker tripped. The list comes straight from the live registry, so
+            // it's always complete and in sync — no drift.
+            const hint = typeof b?.message === 'string' ? `\n${b.message}` : '';
+            const avail = Array.isArray(b?.available)
+                ? `\nValid endpoints: ${b.available.filter((x) => typeof x === 'string').join(', ')}`
+                : '';
             return {
-                output: `BlockRun ${method} ${path} failed: ${detail} (status ${result.status}). No charge if status is 4xx pre-payment.`,
+                output: `BlockRun ${method} ${path} failed: ${detail} (status ${result.status}). No charge if status is 4xx pre-payment.${hint}${avail}`,
                 fullOutput,
                 isError: true,
             };

package/dist/tools/imagegen.d.ts

@@ -5,11 +5,28 @@
 import type { CapabilityHandler } from '../agent/types.js';
 import type { ContentLibrary } from '../content/library.js';
 /**
- * Models that accept a reference image via /v1/images/image2image. Currently
- * limited to OpenAI's edit endpoint — Gemini Nano Banana Pro and Grok Imagine
- * Image Pro need gateway-side support before they can be wired in here.
+ * Models that accept a reference image via /v1/images/image2image. Mirrors the
+ * gateway's EDIT_SUPPORTED_MODELS (src/app/api/v1/images/image2image/route.ts):
+ * both OpenAI gpt-image-* and Google Nano Banana support image-to-image edits.
  */
 export declare const EDIT_SUPPORTED_MODELS: Set<string>;
+/**
+ * Mask-based inpainting is OpenAI-only. Gemini (Nano Banana) does prompt-based
+ * edits with no mask concept. Mirrors the gateway's MASK_SUPPORTED_MODELS.
+ */
+export declare const MASK_SUPPORTED_MODELS: Set<string>;
+/**
+ * Output-image count ceiling. The gateway has no hard max but price scales with
+ * n, so cap client-side to keep a typo from draining the wallet.
+ */
+export declare const MAX_OUTPUT_IMAGES = 4;
+/**
+ * Valid sizes per known image model, mirroring the gateway's IMAGE_MODELS.sizes
+ * (src/lib/models.ts). Used to fail cheaply before paying when a caller or the
+ * media router picks a size the model rejects. Models absent from this table
+ * (custom / future gateway models) skip validation and let the gateway decide.
+ */
+export declare const IMAGE_MODEL_SIZES: Record<string, string[]>;
 export declare const REFERENCE_IMAGE_MAX_BYTES = 4000000;
 /**
  * Normalize a reference image into a base64 data URI for the gateway. The
@@ -24,6 +41,8 @@ export interface ImageGenDeps {
     /** Invoked after successful content-linked generation; lets callers persist. */
     onContentChange?: () => void | Promise<void>;
 }
+/** Insert a `-{idx}` suffix before the file extension: a.png → a-2.png. */
+export declare function withIndexSuffix(p: string, idx: number): string;
 /**
  * Build the ImageGen capability. Passing `deps.library` enables the
  * contentId flow: pre-flight budget check + post-generation asset