@blockrun/franklin 3.8.3 → 3.8.5

package/README.md

@@ -16,9 +16,8 @@
 <p>
   <a href="https://npmjs.com/package/@blockrun/franklin"><img src="https://img.shields.io/npm/v/@blockrun/franklin.svg?style=flat-square&color=FFD700&label=npm" alt="npm"></a>
   <a href="https://npmjs.com/package/@blockrun/franklin"><img src="https://img.shields.io/npm/dm/@blockrun/franklin.svg?style=flat-square&color=10B981&label=downloads" alt="downloads"></a>
-  <a href="https://gitlab.com/blockrunai/franklin"><img src="https://img.shields.io/gitlab/stars/blockrunai/franklin?style=flat-square&color=FFD700&label=stars" alt="stars"></a>
+  <a href="https://github.com/RunFranklin/franklin/stargazers"><img src="https://img.shields.io/github/stars/RunFranklin/franklin?style=flat-square&color=FFD700&label=stars" alt="stars"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache_2.0-blue?style=flat-square" alt="license"></a>
-  <a href="https://gitlab.com/blockrunai/franklin/-/pipelines"><img src="https://img.shields.io/gitlab/pipeline-status/blockrunai%2Ffranklin?branch=main&style=flat-square&label=ci" alt="ci"></a>
   <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-strict-3178C6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript"></a>
   <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node-%E2%89%A520-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node"></a>
   <a href="https://x402.org"><img src="https://img.shields.io/badge/x402-native-10B981?style=flat-square" alt="x402"></a>
@@ -155,9 +154,9 @@ Live data from CoinGecko. RSI, MACD, Bollinger, and volatility computed locally.
 
 Generates images via DALL-E / GPT Image directly from the CLI. Paid from your wallet — no OpenAI API key needed.
 
-### 🎯 Social growth (with setup)
+### 📱 Remote control via Telegram
 
-After running `franklin social setup && franklin social login x`, Franklin can search X, draft replies, and post with your confirmation — no X API key or developer account needed.
+Run `franklin telegram` on an always-on machine (set `TELEGRAM_BOT_TOKEN` + `TELEGRAM_OWNER_ID`) and drive Franklin from your phone. Owner-locked, session-resumable across restarts, slash commands (`/new`, `/balance`, `/status`). Trading, content, dev work — all reachable from a Telegram chat.
 
 ### 🔎 Research, code, anything with a budget
 
@@ -316,7 +315,7 @@ Trained on 2M+ real requests. Classifies your task and picks the best model from
 <td width="50%" valign="top">
 
 **🛠 16 built-in tools**
-Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch, Task, ImageGen, AskUser, SubAgent, TradingSignal, TradingMarket, SearchX, PostToX.
+Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch, Task, ImageGen, VideoGen, MemoryRecall, AskUser, SubAgent, TradingSignal, TradingMarket, TradingPortfolio, TradingOpenPosition, TradingClosePosition, TradingHistory.
 
 **💾 Persistent sessions**
 Every turn is streamed to disk with metadata. Resume any session by ID. Survives crashes, reboots, and compaction.
@@ -402,19 +401,21 @@ src/
 ├── index.ts           CLI entry (franklin + runcode alias)
 ├── banner.ts          Ben Franklin portrait + FRANKLIN gradient text
 ├── agent/             Agent loop, LLM client, compaction, commands
-├── tools/             16 built-in tools (Read/Write/Edit/Bash/Glob/Grep/
-│                      WebFetch/WebSearch/Task/ImageGen/AskUser/SubAgent/
-│                      TradingSignal/TradingMarket/SearchX/PostToX)
+├── tools/             20+ built-in tools (Read/Write/Edit/Bash/Glob/Grep/
+│                      WebFetch/WebSearch/Task/ImageGen/VideoGen/
+│                      MemoryRecall/AskUser/SubAgent/Trading*/Content*)
 ├── trading/           Market data (CoinGecko) + technical indicators
-├── social/            X browser automation (Playwright) + reply engine
-├── events/            Internal event bus (signals, posting, workflow events)
+├── content/           Content library with budget-bound media generation
+├── brain/             Cross-session entity knowledge graph
+├── channel/           Non-CLI ingress drivers (Telegram today)
+├── events/            Internal event bus
 ├── plugin-sdk/        Public plugin contract (Workflow/Plugin/Channel)
 ├── plugins/           Plugin registry + runner (plugin-agnostic)
-├── session/           Persistent sessions + search
+├── session/           Persistent sessions + search + channel tags
 ├── stats/             Usage tracking + insights engine
 ├── ui/                Ink-based terminal UI
 ├── proxy/             Payment proxy for external tools
-├── router/            Learned model router (2M+ requests, Elo scoring)
+├── router/            Learned model router (55+ models, Elo scoring)
 ├── wallet/            Wallet management (Base + Solana)
 ├── mcp/               MCP server auto-discovery
 └── commands/          CLI subcommands
@@ -434,20 +435,23 @@ When you fund the wallet, Franklin gets more purchasing power: Sonnet, Opus, GPT
 
 ---
 
-## Social automation (advanced)
+## Remote control via Telegram
 
-Once you've tuned Franklin's reply style in chat, you can graduate to **automated batch mode**:
+Drive Franklin from anywhere with a bot token:
 
 ```bash
-franklin social setup              # install Chromium, write default config
-franklin social login x            # log in to X once (cookies persist)
-franklin social config edit        # set handle, products, search queries
-franklin social run                # dry-run — preview drafts
-franklin social run --live         # actually post to X
-franklin social stats              # posted / drafted / skipped / cost
+export TELEGRAM_BOT_TOKEN=<from @BotFather>
+export TELEGRAM_OWNER_ID=<your numeric Telegram user id>
+franklin telegram                # start the bot (owner-locked)
 ```
 
-The chat-based social tools (`SearchX`, `PostToX`) and the batch CLI (`franklin social run`) share the same engine. Chat first, automate later.
+Session state resumes across process restarts (tagged by owner id).
+Slash commands `/new`, `/balance`, `/status`, `/help` handled locally
+by the bot layer; everything else forwards to the agent. Progressive
+streaming flushes partial answers at paragraph boundaries so long
+replies don't wait for turn-end.
+
+Same wallet. Same tools. From your phone.
 
 ---
 
@@ -464,14 +468,14 @@ The chat-based social tools (`SearchX`, `PostToX`) and the batch CLI (`franklin
 
 - [Telegram](https://t.me/blockrunAI) — realtime help, bug reports, feature requests
 - [@BlockRunAI](https://x.com/BlockRunAI) — release notes, demos
-- [Issues](https://gitlab.com/blockrunai/franklin/-/issues) — bugs and feature requests
+- [Issues](https://github.com/RunFranklin/franklin/issues) — bugs and feature requests
 
 ---
 
 ## Development
 
 ```bash
-git clone https://gitlab.com/blockrunai/franklin.git
+git clone https://github.com/RunFranklin/franklin.git
 cd franklin
 npm install
 npm run build

package/dist/tools/exa.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Exa research capabilities — neural web search, cited Q&A, and batch
+ * URL content fetch via the BlockRun `/v1/exa/*` endpoints.
+ *
+ * Three tools:
+ *  - ExaSearch     — semantic search for URLs ($0.01/call)
+ *  - ExaAnswer     — synthesized answer with citations ($0.01/call)
+ *  - ExaReadUrls   — batch-fetch clean Markdown from URLs ($0.002/URL)
+ *
+ * Why these matter for an economic agent: ExaAnswer is Perplexity-in-a-
+ * tool — the agent gets a grounded reply with sources, avoiding the
+ * usual hallucination problem without needing to chain search + fetch
+ * + synthesize by hand. ExaReadUrls is roughly 5× cheaper than the
+ * Playwright-backed `WebFetch` for batch reading, and returns clean
+ * Markdown ready to drop into an LLM context window.
+ *
+ * All three share the same x402 payment flow (Base or Solana) — a
+ * 402 triggers a signed USDC transfer, retry succeeds.
+ */
+import type { CapabilityHandler } from '../agent/types.js';
+export declare const exaSearchCapability: CapabilityHandler;
+export declare const exaAnswerCapability: CapabilityHandler;
+export declare const exaReadUrlsCapability: CapabilityHandler;

package/dist/tools/exa.js

@@ -0,0 +1,258 @@
+/**
+ * Exa research capabilities — neural web search, cited Q&A, and batch
+ * URL content fetch via the BlockRun `/v1/exa/*` endpoints.
+ *
+ * Three tools:
+ *  - ExaSearch     — semantic search for URLs ($0.01/call)
+ *  - ExaAnswer     — synthesized answer with citations ($0.01/call)
+ *  - ExaReadUrls   — batch-fetch clean Markdown from URLs ($0.002/URL)
+ *
+ * Why these matter for an economic agent: ExaAnswer is Perplexity-in-a-
+ * tool — the agent gets a grounded reply with sources, avoiding the
+ * usual hallucination problem without needing to chain search + fetch
+ * + synthesize by hand. ExaReadUrls is roughly 5× cheaper than the
+ * Playwright-backed `WebFetch` for batch reading, and returns clean
+ * Markdown ready to drop into an LLM context window.
+ *
+ * All three share the same x402 payment flow (Base or Solana) — a
+ * 402 triggers a signed USDC transfer, retry succeeds.
+ */
+import { getOrCreateWallet, getOrCreateSolanaWallet, createPaymentPayload, createSolanaPaymentPayload, parsePaymentRequired, extractPaymentDetails, solanaKeyToBytes, SOLANA_NETWORK, } from '@blockrun/llm';
+import { loadChain, API_URLS, VERSION } from '../config.js';
+const GEN_TIMEOUT_MS = 30_000;
+// ─── Shared payment flow ─────────────────────────────────────────────
+async function postWithPayment(path, body, ctx) {
+    const chain = loadChain();
+    const apiUrl = API_URLS[chain];
+    const endpoint = `${apiUrl}${path}`;
+    const bodyStr = JSON.stringify(body);
+    const headers = {
+        'Content-Type': 'application/json',
+        'User-Agent': `franklin/${VERSION}`,
+    };
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), GEN_TIMEOUT_MS);
+    const onAbort = () => controller.abort();
+    ctx.abortSignal.addEventListener('abort', onAbort, { once: true });
+    try {
+        let response = await fetch(endpoint, {
+            method: 'POST',
+            signal: controller.signal,
+            headers,
+            body: bodyStr,
+        });
+        if (response.status === 402) {
+            const paymentHeaders = await signPayment(response, chain, endpoint);
+            if (!paymentHeaders) {
+                throw new Error('Payment signing failed — check wallet balance');
+            }
+            response = await fetch(endpoint, {
+                method: 'POST',
+                signal: controller.signal,
+                headers: { ...headers, ...paymentHeaders },
+                body: bodyStr,
+            });
+        }
+        if (!response.ok) {
+            const errText = await response.text().catch(() => '');
+            throw new Error(`Exa ${path} failed (${response.status}): ${errText.slice(0, 200)}`);
+        }
+        return (await response.json());
+    }
+    finally {
+        clearTimeout(timeout);
+        ctx.abortSignal.removeEventListener('abort', onAbort);
+    }
+}
+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 || 'Franklin Exa research',
+                maxTimeoutSeconds: details.maxTimeoutSeconds || 60,
+                extra: details.extra,
+            });
+            return { 'PAYMENT-SIGNATURE': payload };
+        }
+        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 || 'Franklin Exa research',
+            maxTimeoutSeconds: details.maxTimeoutSeconds || 60,
+            extra: details.extra,
+        });
+        return { 'PAYMENT-SIGNATURE': payload };
+    }
+    catch (err) {
+        console.error(`[franklin] Exa 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 const exaSearchCapability = {
+    spec: {
+        name: 'ExaSearch',
+        description: 'Neural web search via Exa ($0.01/call). Returns a ranked list of ' +
+            'URLs + titles for a natural-language query. Understands meaning, ' +
+            'not just keywords. Optional `category` narrows to github / news / ' +
+            '`research paper` / tweet / pdf / company / etc. Prefer this over ' +
+            'WebSearch when the query is semantic (e.g. "projects implementing ' +
+            'x402 payment middleware") rather than a literal phrase.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                query: { type: 'string', description: 'Natural-language search query' },
+                numResults: { type: 'number', description: 'Max results (default 10, max 100)' },
+                category: {
+                    type: 'string',
+                    description: 'Restrict to: github, news, research paper, linkedin profile, ' +
+                        'personal site, tweet, financial report, pdf, company',
+                },
+                startPublishedDate: { type: 'string', description: 'ISO 8601 lower bound (e.g. 2026-03-01)' },
+                endPublishedDate: { type: 'string', description: 'ISO 8601 upper bound' },
+                includeDomains: { type: 'array', items: { type: 'string' } },
+                excludeDomains: { type: 'array', items: { type: 'string' } },
+            },
+            required: ['query'],
+        },
+    },
+    execute: async (input, ctx) => {
+        const params = input;
+        if (!params.query)
+            return { output: 'Error: query is required', isError: true };
+        try {
+            const res = await postWithPayment('/v1/exa/search', params, ctx);
+            const hits = res.data?.results ?? [];
+            if (hits.length === 0) {
+                return { output: `No Exa results for "${params.query}".` };
+            }
+            const lines = [`## Exa search — ${hits.length} result${hits.length === 1 ? '' : 's'}`];
+            for (const h of hits) {
+                const date = h.publishedDate ? ` _(${h.publishedDate.slice(0, 10)})_` : '';
+                const score = h.score ? ` · score ${h.score.toFixed(2)}` : '';
+                lines.push(`\n**${h.title}**${date}${score}\n${h.url}`);
+            }
+            const cost = res.data?.costDollars?.total;
+            if (cost)
+                lines.push(`\n_Cost: $${cost.toFixed(4)}_`);
+            return { output: lines.join('\n') };
+        }
+        catch (err) {
+            return { output: `Error: ${err.message}`, isError: true };
+        }
+    },
+    concurrent: true,
+};
+export const exaAnswerCapability = {
+    spec: {
+        name: 'ExaAnswer',
+        description: "Ask a factual question, get a synthesized answer with real source " +
+            "citations ($0.01/call). Like Perplexity in a tool — grounded in " +
+            "live web content, not LLM memory. Best for 'what is X?', 'how does " +
+            "Y work?', 'what's the current state of Z?'. Prefer this over " +
+            "chaining ExaSearch + ExaReadUrls + LLM synthesis when the user " +
+            "just wants an answer with sources.",
+        input_schema: {
+            type: 'object',
+            properties: {
+                query: { type: 'string', description: 'The factual question to answer' },
+            },
+            required: ['query'],
+        },
+    },
+    execute: async (input, ctx) => {
+        const params = input;
+        if (!params.query)
+            return { output: 'Error: query is required', isError: true };
+        try {
+            const res = await postWithPayment('/v1/exa/answer', params, ctx);
+            const ans = res.data?.answer ?? '';
+            const cites = res.data?.citations ?? [];
+            const lines = [ans];
+            if (cites.length > 0) {
+                lines.push('\n**Sources**');
+                for (const c of cites)
+                    lines.push(`- [${c.title}](${c.url})`);
+            }
+            const cost = res.data?.costDollars?.total;
+            if (cost)
+                lines.push(`\n_Cost: $${cost.toFixed(4)}_`);
+            return { output: lines.join('\n') };
+        }
+        catch (err) {
+            return { output: `Error: ${err.message}`, isError: true };
+        }
+    },
+    concurrent: true,
+};
+export const exaReadUrlsCapability = {
+    spec: {
+        name: 'ExaReadUrls',
+        description: "Batch-fetch clean Markdown content from a list of URLs ($0.002/URL). " +
+            "Up to 100 URLs per call. Much cheaper than chaining 100× WebFetch, " +
+            "and returns text already stripped of HTML/boilerplate — ready to " +
+            "feed into an LLM context window. Prefer over WebFetch when reading " +
+            "multiple URLs at once or when you want clean Markdown.",
+        input_schema: {
+            type: 'object',
+            properties: {
+                urls: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'URLs to fetch (up to 100)',
+                },
+            },
+            required: ['urls'],
+        },
+    },
+    execute: async (input, ctx) => {
+        const params = input;
+        if (!params.urls || params.urls.length === 0) {
+            return { output: 'Error: urls array is required and must be non-empty', isError: true };
+        }
+        if (params.urls.length > 100) {
+            return { output: `Error: max 100 URLs per call (got ${params.urls.length})`, isError: true };
+        }
+        try {
+            const res = await postWithPayment('/v1/exa/contents', params, ctx);
+            const results = res.data?.results ?? [];
+            if (results.length === 0) {
+                return { output: `No readable content returned for the ${params.urls.length} URL(s).` };
+            }
+            const lines = [`## Fetched ${results.length} URL${results.length === 1 ? '' : 's'}`];
+            for (const r of results) {
+                lines.push(`\n### ${r.title ?? r.url}\n_Source: ${r.url}_\n\n${r.text}`);
+            }
+            const cost = res.data?.costDollars?.total;
+            if (cost)
+                lines.push(`\n_Cost: $${cost.toFixed(4)}_`);
+            return { output: lines.join('\n') };
+        }
+        catch (err) {
+            return { output: `Error: ${err.message}`, isError: true };
+        }
+    },
+    concurrent: true,
+};

package/dist/tools/index.js

@@ -14,7 +14,9 @@ import { webSearchCapability } from './websearch.js';
 import { taskCapability } from './task.js';
 import { createImageGenCapability } from './imagegen.js';
 import { createVideoGenCapability } from './videogen.js';
+import { createMusicGenCapability } from './musicgen.js';
 import { memoryRecallCapability } from './memory.js';
+import { exaSearchCapability, exaAnswerCapability, exaReadUrlsCapability } from './exa.js';
 import { askUserCapability } from './askuser.js';
 import { tradingSignalCapability, tradingMarketCapability } from './trading.js';
 import { searchXCapability } from './searchx.js';
@@ -96,6 +98,10 @@ const defaultVideoGenCapability = createVideoGenCapability({
     library: defaultContentLibrary,
     onContentChange: persistContentLibrary,
 });
+const defaultMusicGenCapability = createMusicGenCapability({
+    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
@@ -119,7 +125,11 @@ export const allCapabilities = [
     taskCapability,
     defaultImageGenCapability,
     defaultVideoGenCapability,
+    defaultMusicGenCapability,
     memoryRecallCapability,
+    exaSearchCapability,
+    exaAnswerCapability,
+    exaReadUrlsCapability,
     askUserCapability,
     tradingSignalCapability,
     tradingMarketCapability,

package/dist/tools/musicgen.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Music Generation capability — generate ~3-minute MP3 tracks via the
+ * BlockRun `/v1/audio/generations` endpoint. Uses x402 payment (Base
+ * or Solana) and shares the same pattern as VideoGen.
+ *
+ * Default model `minimax/music-2.5+` bills $0.1575/call and returns a
+ * ~3-minute track regardless of duration hint. Generation takes 1-3
+ * minutes — the HTTP connection stays open until the upstream job
+ * finishes, so the caller issues a single POST and waits.
+ *
+ * The generated URL is time-limited (~24h) from the upstream CDN, so
+ * the tool downloads the MP3 to disk immediately and stores the local
+ * path. Optional contentId integration records the track as a budget-
+ * tracked asset on a Content piece.
+ */
+import type { CapabilityHandler } from '../agent/types.js';
+import type { ContentLibrary } from '../content/library.js';
+export interface MusicGenDeps {
+    library?: ContentLibrary;
+    onContentChange?: () => void | Promise<void>;
+}
+export declare function createMusicGenCapability(deps?: MusicGenDeps): CapabilityHandler;
+export declare const musicGenCapability: CapabilityHandler;

package/dist/tools/musicgen.js

@@ -0,0 +1,248 @@
+/**
+ * Music Generation capability — generate ~3-minute MP3 tracks via the
+ * BlockRun `/v1/audio/generations` endpoint. Uses x402 payment (Base
+ * or Solana) and shares the same pattern as VideoGen.
+ *
+ * Default model `minimax/music-2.5+` bills $0.1575/call and returns a
+ * ~3-minute track regardless of duration hint. Generation takes 1-3
+ * minutes — the HTTP connection stays open until the upstream job
+ * finishes, so the caller issues a single POST and waits.
+ *
+ * The generated URL is time-limited (~24h) from the upstream CDN, so
+ * the tool downloads the MP3 to disk immediately and stores the local
+ * path. Optional contentId integration records the track as a budget-
+ * tracked asset on a Content piece.
+ */
+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';
+const DEFAULT_MODEL = 'minimax/music-2.5+';
+const PRICE_USD = 0.1575;
+// MiniMax generation is 1-3 minutes + small buffer for payment + download.
+const GEN_TIMEOUT_MS = 240_000;
+const DOWNLOAD_TIMEOUT_MS = 60_000;
+function buildExecute(deps) {
+    return async function execute(input, ctx) {
+        const { prompt, output_path, model, instrumental, lyrics, duration_seconds, contentId } = input;
+        if (!prompt)
+            return { output: 'Error: prompt is required', isError: true };
+        if (instrumental === true && lyrics) {
+            return {
+                output: 'Error: cannot set both `instrumental: true` and `lyrics` — pick one',
+                isError: true,
+            };
+        }
+        const musicModel = model || DEFAULT_MODEL;
+        if (contentId && deps.library) {
+            const content = deps.library.get(contentId);
+            if (!content) {
+                return { output: `Content ${contentId} not found. No USDC was spent.` };
+            }
+            if (content.spentUsd + PRICE_USD > content.budgetUsd + 1e-9) {
+                return {
+                    output: `## Music generation skipped\n` +
+                        `- Would exceed budget: spent $${content.spentUsd.toFixed(2)} + fixed ` +
+                        `$${PRICE_USD.toFixed(2)} > cap $${content.budgetUsd.toFixed(2)}\n\n` +
+                        `No USDC was spent.`,
+                };
+            }
+        }
+        const chain = loadChain();
+        const apiUrl = API_URLS[chain];
+        const endpoint = `${apiUrl}/v1/audio/generations`;
+        const outPath = output_path
+            ? (path.isAbsolute(output_path) ? output_path : path.resolve(ctx.workingDir, output_path))
+            : path.resolve(ctx.workingDir, `generated-${Date.now()}.mp3`);
+        const body = JSON.stringify({
+            model: musicModel,
+            prompt,
+            ...(instrumental !== undefined ? { instrumental } : {}),
+            ...(lyrics ? { lyrics } : {}),
+            ...(duration_seconds ? { duration_seconds } : {}),
+        });
+        const headers = {
+            'Content-Type': 'application/json',
+            'User-Agent': `franklin/${VERSION}`,
+        };
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), GEN_TIMEOUT_MS);
+        const onAbort = () => controller.abort();
+        ctx.abortSignal.addEventListener('abort', onAbort, { once: true });
+        try {
+            let response = await fetch(endpoint, {
+                method: 'POST',
+                signal: controller.signal,
+                headers,
+                body,
+            });
+            if (response.status === 402) {
+                const paymentHeaders = await signPayment(response, chain, endpoint);
+                if (!paymentHeaders) {
+                    return { output: 'Payment failed. Check wallet balance with: franklin 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: `Music generation failed (${response.status}): ${errText.slice(0, 300)}`,
+                    isError: true,
+                };
+            }
+            const result = (await response.json());
+            const track = result.data?.[0];
+            if (!track?.url) {
+                return { output: 'No track URL returned from API', isError: true };
+            }
+            // CDN URLs expire in ~24h — download NOW.
+            const dlCtrl = new AbortController();
+            const dlTimeout = setTimeout(() => dlCtrl.abort(), DOWNLOAD_TIMEOUT_MS);
+            const mp3Resp = await fetch(track.url, { signal: dlCtrl.signal });
+            clearTimeout(dlTimeout);
+            if (!mp3Resp.ok) {
+                return {
+                    output: `Music URL fetched but MP3 download failed (${mp3Resp.status}): ${track.url}`,
+                    isError: true,
+                };
+            }
+            const buffer = Buffer.from(await mp3Resp.arrayBuffer());
+            fs.mkdirSync(path.dirname(outPath), { recursive: true });
+            fs.writeFileSync(outPath, buffer);
+            const fileSize = fs.statSync(outPath).size;
+            const sizeMB = (fileSize / 1_048_576).toFixed(1);
+            const dur = track.duration_seconds ?? 180;
+            const lyricsPreview = track.lyrics
+                ? `\n\n**Generated lyrics:**\n\n${track.lyrics.slice(0, 600)}${track.lyrics.length > 600 ? '\n...' : ''}`
+                : '';
+            let contentSummary = '';
+            if (contentId && deps.library) {
+                const rec = deps.library.addAsset(contentId, {
+                    kind: 'audio',
+                    source: musicModel,
+                    costUsd: PRICE_USD,
+                    data: outPath,
+                });
+                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. $${PRICE_USD.toFixed(2)}\n` +
+                            (c
+                                ? `- Spent: $${c.spentUsd.toFixed(2)} / $${c.budgetUsd.toFixed(2)} cap ` +
+                                    `(remaining $${(c.budgetUsd - c.spentUsd).toFixed(2)})`
+                                : '');
+                }
+                else {
+                    contentSummary =
+                        `\n\n## Content NOT updated\n- ${rec.reason}\n- Track saved locally; ` +
+                            `cost NOT recorded against the content budget.`;
+                }
+            }
+            return {
+                output: `Track saved to ${outPath} (${sizeMB}MB, ${dur}s, ${musicModel})\n\n` +
+                    `Open with: open ${outPath}${lyricsPreview}${contentSummary}`,
+            };
+        }
+        catch (err) {
+            const msg = err.message || '';
+            if (msg.includes('abort')) {
+                return {
+                    output: `Music generation timed out or was aborted (limit ${Math.round(GEN_TIMEOUT_MS / 1000)}s).`,
+                    isError: true,
+                };
+            }
+            return { output: `Error: ${msg}`, isError: true };
+        }
+        finally {
+            clearTimeout(timeout);
+            ctx.abortSignal.removeEventListener('abort', onAbort);
+        }
+    };
+}
+// ─── 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 || 'Franklin music generation',
+                maxTimeoutSeconds: details.maxTimeoutSeconds || 300,
+                extra: details.extra,
+            });
+            return { 'PAYMENT-SIGNATURE': payload };
+        }
+        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 || 'Franklin music generation',
+            maxTimeoutSeconds: details.maxTimeoutSeconds || 300,
+            extra: details.extra,
+        });
+        return { 'PAYMENT-SIGNATURE': payload };
+    }
+    catch (err) {
+        console.error(`[franklin] Music 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 function createMusicGenCapability(deps = {}) {
+    return {
+        spec: {
+            name: 'MusicGen',
+            description: "Generate a ~3-minute MP3 track from a text prompt (plus optional " +
+                "lyrics or instrumental flag). Calls BlockRun's /v1/audio/generations. " +
+                "Costs $0.1575 USDC per call — bills a flat rate, MiniMax ignores " +
+                "duration hints and always returns ~3 min. Generation takes 1–3 " +
+                "minutes. ALWAYS confirm with the user before calling — music is " +
+                "expensive and slow. Pass contentId to attach to a Content piece " +
+                "(budget is checked before paying).",
+            input_schema: {
+                type: 'object',
+                properties: {
+                    prompt: { type: 'string', description: 'Music style / mood / description' },
+                    output_path: { type: 'string', description: 'Where to save the MP3. Default: generated-<timestamp>.mp3' },
+                    model: { type: 'string', description: 'Music model. Default: minimax/music-2.5+' },
+                    instrumental: { type: 'boolean', description: 'No vocals. Cannot combine with `lyrics`.' },
+                    lyrics: { type: 'string', description: 'Custom lyrics. Cannot combine with `instrumental: true`.' },
+                    duration_seconds: { type: 'number', description: 'Duration hint (ignored by MiniMax — always ~3 min).' },
+                    contentId: { type: 'string', description: 'Optional Content id to attach and budget against.' },
+                },
+                required: ['prompt'],
+            },
+        },
+        execute: buildExecute(deps),
+        concurrent: false,
+    };
+}
+export const musicGenCapability = createMusicGenCapability();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/franklin",
-  "version": "3.8.3",
+  "version": "3.8.5",
   "description": "Franklin — The AI agent with a wallet. Spends USDC autonomously to get real work done. Pay per action, no subscriptions.",
   "type": "module",
   "exports": {
@@ -15,8 +15,8 @@
     "./package.json": "./package.json"
   },
   "bin": {
-    "franklin": "./dist/index.js",
-    "runcode": "./dist/index.js"
+    "franklin": "dist/index.js",
+    "runcode": "dist/index.js"
   },
   "files": [
     "dist",
@@ -52,10 +52,10 @@
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "https://gitlab.com/blockrunai/franklin"
+    "url": "git+https://github.com/RunFranklin/franklin.git"
   },
   "bugs": {
-    "url": "https://gitlab.com/blockrunai/franklin/-/issues"
+    "url": "https://github.com/RunFranklin/franklin/issues"
   },
   "homepage": "https://Franklin.run",
   "engines": {