@blockrun/franklin 3.8.4 → 3.8.6

package/README.md

@@ -16,7 +16,7 @@
 <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://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="https://github.com/BlockRunAI/Franklin/stargazers"><img src="https://img.shields.io/github/stars/BlockRunAI/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://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>
@@ -154,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
 
@@ -315,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.
@@ -401,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
@@ -433,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.
 
 ---
 
@@ -463,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://github.com/RunFranklin/franklin/issues) — bugs and feature requests
+- [Issues](https://github.com/BlockRunAI/Franklin/issues) — bugs and feature requests
 
 ---
 
 ## Development
 
 ```bash
-git clone https://github.com/RunFranklin/franklin.git
+git clone https://github.com/BlockRunAI/Franklin.git
 cd franklin
 npm install
 npm run build

package/dist/agent/loop.js

@@ -358,6 +358,10 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
     let sessionOutputTokens = 0;
     let sessionCostUsd = 0;
     let sessionSavedVsOpus = 0;
+    // Per-tool call counts aggregated across every turn. Session-scope, not
+    // per-turn. Counts the *name* of each tool invocation only — no inputs,
+    // outputs, or paths. Fed into opt-in telemetry at session end.
+    const sessionToolCounts = new Map();
     const toolGuard = new SessionToolGuard();
     const persistSessionMeta = () => {
         updateSessionMeta(sessionId, {
@@ -370,6 +374,9 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
             costUsd: sessionCostUsd,
             savedVsOpusUsd: sessionSavedVsOpus,
             ...(config.sessionChannel !== undefined ? { channel: config.sessionChannel } : {}),
+            ...(sessionToolCounts.size > 0
+                ? { toolCallCounts: Object.fromEntries(sessionToolCounts) }
+                : {}),
         });
     };
     const persistSessionMessage = (message) => {
@@ -1039,6 +1046,8 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
             for (const [inv] of results) {
                 const name = inv.name;
                 turnToolCounts.set(name, (turnToolCounts.get(name) || 0) + 1);
+                // Session-scope aggregate (drives telemetry opt-in export).
+                sessionToolCounts.set(name, (sessionToolCounts.get(name) || 0) + 1);
                 // Read file dedup: track paths already read
                 if (name === 'Read' && inv.input.file_path) {
                     readFileCache.add(inv.input.file_path);

package/dist/commands/start.js

@@ -313,6 +313,13 @@ async function runWithInkUI(agentConfig, model, workDir, version, walletInfo, on
     }
     ui.cleanup();
     flushStats();
+    // Opt-in telemetry — no-op unless user has run `franklin telemetry enable`.
+    // Appends a sanitized session summary to ~/.blockrun/telemetry.jsonl.
+    try {
+        const { recordLatestSessionIfEnabled } = await import('../telemetry/store.js');
+        recordLatestSessionIfEnabled(process.cwd(), agentConfig.chain);
+    }
+    catch { /* telemetry is best-effort */ }
     // Extract learnings from the session (async, 10s timeout, never blocks exit)
     if (sessionHistory && sessionHistory.length >= 4) {
         try {

package/dist/commands/telemetry.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `franklin telemetry` — manage the opt-in local telemetry subsystem.
+ *
+ * Subcommands:
+ *   status   — print whether telemetry is enabled, where the log lives,
+ *              and a one-line summary of what's been recorded
+ *   enable   — turn on local recording (default is OFF)
+ *   disable  — stop future recording; existing data stays on disk
+ *   view     — print every record in the log as pretty JSONL so the
+ *              user can see exactly what was captured
+ *   summary  — aggregate all records into tool-usage histograms so
+ *              positioning decisions can be made from real data
+ */
+export declare function telemetryCommand(action?: string): Promise<void>;

package/dist/commands/telemetry.js

@@ -0,0 +1,150 @@
+/**
+ * `franklin telemetry` — manage the opt-in local telemetry subsystem.
+ *
+ * Subcommands:
+ *   status   — print whether telemetry is enabled, where the log lives,
+ *              and a one-line summary of what's been recorded
+ *   enable   — turn on local recording (default is OFF)
+ *   disable  — stop future recording; existing data stays on disk
+ *   view     — print every record in the log as pretty JSONL so the
+ *              user can see exactly what was captured
+ *   summary  — aggregate all records into tool-usage histograms so
+ *              positioning decisions can be made from real data
+ */
+import chalk from 'chalk';
+import { isTelemetryEnabled, setTelemetryEnabled, readConsent, readAllRecords, telemetryPaths, } from '../telemetry/store.js';
+export async function telemetryCommand(action) {
+    const cmd = (action || 'status').toLowerCase();
+    switch (cmd) {
+        case 'status':
+            return statusCmd();
+        case 'enable':
+        case 'on':
+            return enableCmd();
+        case 'disable':
+        case 'off':
+            return disableCmd();
+        case 'view':
+        case 'log':
+            return viewCmd();
+        case 'summary':
+            return summaryCmd();
+        default:
+            console.log(chalk.yellow(`Unknown subcommand: ${action}`));
+            console.log(chalk.dim('Try: franklin telemetry [status|enable|disable|view|summary]'));
+            process.exit(1);
+    }
+}
+function statusCmd() {
+    const enabled = isTelemetryEnabled();
+    const consent = readConsent();
+    const records = readAllRecords();
+    console.log(chalk.bold('Franklin telemetry'));
+    console.log(`  state:      ${enabled ? chalk.green('enabled') : chalk.dim('disabled (default)')}`);
+    if (consent.enabledAt) {
+        console.log(`  enabled at: ${chalk.dim(new Date(consent.enabledAt).toISOString())}`);
+    }
+    if (consent.disabledAt && !enabled) {
+        console.log(`  disabled at: ${chalk.dim(new Date(consent.disabledAt).toISOString())}`);
+    }
+    console.log(`  records:    ${chalk.cyan(records.length.toString())} session${records.length === 1 ? '' : 's'} on disk`);
+    console.log(`  log file:   ${chalk.dim(telemetryPaths.log)}`);
+    console.log();
+    console.log(chalk.dim('Telemetry is local-only: no network transmission.'));
+    console.log(chalk.dim('Records contain tool-usage counts and cost totals — NOT prompts, tool inputs, tool outputs, paths, or wallet addresses.'));
+    console.log();
+    console.log(chalk.dim('Commands:'));
+    console.log(chalk.dim('  franklin telemetry enable     turn on local recording'));
+    console.log(chalk.dim('  franklin telemetry disable    stop future recording (keeps existing data)'));
+    console.log(chalk.dim('  franklin telemetry view       print every stored record verbatim'));
+    console.log(chalk.dim('  franklin telemetry summary    aggregate tool-usage histograms'));
+}
+function enableCmd() {
+    if (isTelemetryEnabled()) {
+        console.log(chalk.dim('Telemetry is already enabled.'));
+        return;
+    }
+    setTelemetryEnabled(true);
+    console.log(chalk.green('Telemetry enabled.'));
+    console.log(chalk.dim('Each session end appends one JSON line to ' + telemetryPaths.log));
+    console.log(chalk.dim('Inspect with: franklin telemetry view'));
+    console.log(chalk.dim('Disable with: franklin telemetry disable'));
+}
+function disableCmd() {
+    if (!isTelemetryEnabled()) {
+        console.log(chalk.dim('Telemetry is already disabled.'));
+        return;
+    }
+    setTelemetryEnabled(false);
+    console.log(chalk.green('Telemetry disabled. Future sessions will not be recorded.'));
+    console.log(chalk.dim('Existing data at ' + telemetryPaths.log + ' is untouched.'));
+    console.log(chalk.dim('Delete it manually if you want to clear history.'));
+}
+function viewCmd() {
+    const records = readAllRecords();
+    if (records.length === 0) {
+        console.log(chalk.dim('No telemetry records yet.'));
+        if (!isTelemetryEnabled()) {
+            console.log(chalk.dim('Telemetry is disabled — enable with: franklin telemetry enable'));
+        }
+        return;
+    }
+    for (const r of records) {
+        console.log(JSON.stringify(r, null, 2));
+        console.log(chalk.dim('─'.repeat(60)));
+    }
+}
+function summaryCmd() {
+    const records = readAllRecords();
+    if (records.length === 0) {
+        console.log(chalk.dim('No telemetry records yet.'));
+        return;
+    }
+    const toolCounts = new Map();
+    const modelCounts = new Map();
+    const driverCounts = new Map();
+    let totalCost = 0;
+    let totalSaved = 0;
+    let totalTurns = 0;
+    for (const r of records) {
+        if (r.toolCallCounts) {
+            for (const [tool, n] of Object.entries(r.toolCallCounts)) {
+                toolCounts.set(tool, (toolCounts.get(tool) || 0) + n);
+            }
+        }
+        modelCounts.set(r.model, (modelCounts.get(r.model) || 0) + 1);
+        driverCounts.set(r.driver, (driverCounts.get(r.driver) || 0) + 1);
+        totalCost += r.costUsd;
+        totalSaved += r.savedVsOpusUsd;
+        totalTurns += r.turns;
+    }
+    console.log(chalk.bold(`\nFranklin telemetry summary — ${records.length} sessions\n`));
+    console.log(`  total turns:        ${totalTurns}`);
+    console.log(`  total USDC cost:    $${totalCost.toFixed(4)}`);
+    console.log(`  saved vs Opus:      $${totalSaved.toFixed(4)}`);
+    console.log();
+    console.log(chalk.bold('  Tool usage (session aggregate):'));
+    const sortedTools = [...toolCounts.entries()].sort((a, b) => b[1] - a[1]);
+    if (sortedTools.length === 0) {
+        console.log(chalk.dim('    (no tool calls recorded)'));
+    }
+    else {
+        const maxCount = sortedTools[0][1];
+        for (const [tool, n] of sortedTools) {
+            const bar = '█'.repeat(Math.max(1, Math.round((n / maxCount) * 20)));
+            console.log(`    ${tool.padEnd(22)} ${chalk.cyan(bar)} ${n}`);
+        }
+    }
+    console.log();
+    console.log(chalk.bold('  Models:'));
+    const sortedModels = [...modelCounts.entries()].sort((a, b) => b[1] - a[1]);
+    for (const [model, n] of sortedModels) {
+        console.log(`    ${model.padEnd(36)} ${n}`);
+    }
+    console.log();
+    console.log(chalk.bold('  Drivers:'));
+    for (const [driver, n] of driverCounts.entries()) {
+        console.log(`    ${driver.padEnd(22)} ${n}`);
+    }
+    console.log();
+}

package/dist/index.js

@@ -166,6 +166,13 @@ program
         });
     }
 }
+program
+    .command('telemetry [action]')
+    .description('Manage opt-in local telemetry (status|enable|disable|view|summary)')
+    .action(async (action) => {
+    const { telemetryCommand } = await import('./commands/telemetry.js');
+    await telemetryCommand(action);
+});
 program
     .command('telegram')
     .description('Drive Franklin from Telegram (requires TELEGRAM_BOT_TOKEN + TELEGRAM_OWNER_ID env vars)')

package/dist/session/storage.d.ts

@@ -21,6 +21,13 @@ export interface SessionMeta {
      * Lets findLatestSessionByChannel pick up the right session on bot restart.
      */
     channel?: string;
+    /**
+     * Per-tool invocation counts for this session, aggregated across every
+     * turn. Populated by the agent loop at each tool-call batch. Used by the
+     * opt-in telemetry subsystem to aggregate vertical-usage signals — do NOT
+     * add any tool inputs or outputs here, just the count per tool name.
+     */
+    toolCallCounts?: Record<string, number>;
 }
 /** Get the absolute path to a session's JSONL file (for external readers like search). */
 export declare function getSessionFilePath(id: string): string;

package/dist/session/storage.js

@@ -95,6 +95,9 @@ export function updateSessionMeta(sessionId, meta) {
             ...(meta.channel !== undefined || existing?.channel !== undefined
                 ? { channel: meta.channel ?? existing?.channel }
                 : {}),
+            ...(meta.toolCallCounts !== undefined || existing?.toolCallCounts !== undefined
+                ? { toolCallCounts: meta.toolCallCounts ?? existing?.toolCallCounts }
+                : {}),
         };
         // Atomic write: tmp file + rename. Prevents corruption when parent
         // and sub-agent update the same session meta concurrently.

package/dist/telemetry/store.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Opt-in local telemetry.
+ *
+ * Principles (non-negotiable):
+ *   1. Opt-in only — default is off. A fresh install collects nothing.
+ *   2. Local only — this module writes to ~/.blockrun/telemetry.jsonl.
+ *      No network transmission, ever. A future opt-in "upload" feature
+ *      would be a separate module with its own consent gate.
+ *   3. No content — never log prompts, tool inputs, tool outputs, file
+ *      paths, or wallet addresses. Count-level aggregates only.
+ *   4. Inspectable — the log is plain JSONL, one record per session.
+ *      `franklin telemetry view` prints it. Users see exactly what was
+ *      recorded before ever considering sharing it.
+ *   5. Revocable — `franklin telemetry disable` stops future writes
+ *      and leaves historical data intact. `franklin telemetry reset`
+ *      (future) would wipe the log.
+ *
+ * Data model is a sanitized projection of SessionMeta. Nothing original
+ * is stored here that isn't already derivable from the session meta
+ * files — telemetry is just a stable, aggregation-friendly view of
+ * information the user already has.
+ */
+import type { SessionMeta } from '../session/storage.js';
+interface ConsentRecord {
+    enabled: boolean;
+    enabledAt?: number;
+    disabledAt?: number;
+}
+/** Sanitized projection of a session used for telemetry. No content. */
+export interface TelemetryRecord {
+    /** Stable per-install random UUID. Not tied to wallet or email. */
+    installId: string;
+    /** Franklin version at the time this session ran. */
+    version: string;
+    /** Session timestamp (ISO string). */
+    ts: string;
+    /** Number of user turns. */
+    turns: number;
+    /** Number of message entries (user + assistant + tool_result). */
+    messages: number;
+    /** Input / output tokens for the whole session. */
+    inputTokens: number;
+    outputTokens: number;
+    /** Cost in USDC. */
+    costUsd: number;
+    /** Savings vs Opus-tier baseline in USDC. */
+    savedVsOpusUsd: number;
+    /** Last-active model id for the session. */
+    model: string;
+    /** Chain the session settled on (base / solana). */
+    chain?: string;
+    /** Session driver — "cli" for normal use, or the channel tag for Telegram/etc. */
+    driver: string;
+    /** Per-tool invocation counts (names only, no content). */
+    toolCallCounts?: Record<string, number>;
+}
+/** Enabled-state check. Default: false. */
+export declare function isTelemetryEnabled(): boolean;
+export declare function setTelemetryEnabled(enabled: boolean): void;
+export declare function readConsent(): ConsentRecord;
+/** Stable per-install random UUID. Generated lazily on first write. */
+export declare function getOrCreateInstallId(): string;
+/**
+ * Sanitize a SessionMeta into a telemetry record. No content is added here
+ * that isn't already present in the meta — the sanitization rule is that
+ * every field must be count-level or identifier-level, never user content.
+ */
+export declare function sessionMetaToRecord(meta: SessionMeta, installId: string, chain?: string): TelemetryRecord;
+/** Append one record to the telemetry log. Silent no-op if disabled. */
+export declare function recordSession(meta: SessionMeta, chain?: string): void;
+/**
+ * Locate the session that just finished by ID or by "newest in the sessions
+ * directory whose workDir matches", then record it. Used by start.ts at
+ * exit since interactiveSession() doesn't currently thread the session id
+ * back to the caller.
+ */
+export declare function recordLatestSessionIfEnabled(workingDir: string, chain?: string): void;
+/** Read every record in the log. Returns [] if the file is missing. */
+export declare function readAllRecords(): TelemetryRecord[];
+/** File paths — surfaced so the CLI can show users where data lives. */
+export declare const telemetryPaths: {
+    consent: string;
+    log: string;
+    installId: string;
+};
+export {};

package/dist/telemetry/store.js

@@ -0,0 +1,158 @@
+/**
+ * Opt-in local telemetry.
+ *
+ * Principles (non-negotiable):
+ *   1. Opt-in only — default is off. A fresh install collects nothing.
+ *   2. Local only — this module writes to ~/.blockrun/telemetry.jsonl.
+ *      No network transmission, ever. A future opt-in "upload" feature
+ *      would be a separate module with its own consent gate.
+ *   3. No content — never log prompts, tool inputs, tool outputs, file
+ *      paths, or wallet addresses. Count-level aggregates only.
+ *   4. Inspectable — the log is plain JSONL, one record per session.
+ *      `franklin telemetry view` prints it. Users see exactly what was
+ *      recorded before ever considering sharing it.
+ *   5. Revocable — `franklin telemetry disable` stops future writes
+ *      and leaves historical data intact. `franklin telemetry reset`
+ *      (future) would wipe the log.
+ *
+ * Data model is a sanitized projection of SessionMeta. Nothing original
+ * is stored here that isn't already derivable from the session meta
+ * files — telemetry is just a stable, aggregation-friendly view of
+ * information the user already has.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { BLOCKRUN_DIR, VERSION } from '../config.js';
+const CONSENT_FILE = path.join(BLOCKRUN_DIR, 'telemetry-consent.json');
+const LOG_FILE = path.join(BLOCKRUN_DIR, 'telemetry.jsonl');
+const INSTALL_ID_FILE = path.join(BLOCKRUN_DIR, 'telemetry-install-id.txt');
+function ensureDir() {
+    fs.mkdirSync(BLOCKRUN_DIR, { recursive: true });
+}
+/** Enabled-state check. Default: false. */
+export function isTelemetryEnabled() {
+    try {
+        const raw = fs.readFileSync(CONSENT_FILE, 'utf-8');
+        const record = JSON.parse(raw);
+        return record.enabled === true;
+    }
+    catch {
+        return false;
+    }
+}
+export function setTelemetryEnabled(enabled) {
+    ensureDir();
+    const existing = readConsent();
+    const next = enabled
+        ? { enabled: true, enabledAt: Date.now() }
+        : { enabled: false, enabledAt: existing.enabledAt, disabledAt: Date.now() };
+    fs.writeFileSync(CONSENT_FILE, JSON.stringify(next, null, 2));
+}
+export function readConsent() {
+    try {
+        return JSON.parse(fs.readFileSync(CONSENT_FILE, 'utf-8'));
+    }
+    catch {
+        return { enabled: false };
+    }
+}
+/** Stable per-install random UUID. Generated lazily on first write. */
+export function getOrCreateInstallId() {
+    try {
+        const raw = fs.readFileSync(INSTALL_ID_FILE, 'utf-8').trim();
+        if (raw.length > 0)
+            return raw;
+    }
+    catch { /* first run */ }
+    ensureDir();
+    const id = crypto.randomUUID();
+    fs.writeFileSync(INSTALL_ID_FILE, id);
+    return id;
+}
+/**
+ * Sanitize a SessionMeta into a telemetry record. No content is added here
+ * that isn't already present in the meta — the sanitization rule is that
+ * every field must be count-level or identifier-level, never user content.
+ */
+export function sessionMetaToRecord(meta, installId, chain) {
+    return {
+        installId,
+        version: VERSION,
+        ts: new Date(meta.updatedAt).toISOString(),
+        turns: meta.turnCount ?? 0,
+        messages: meta.messageCount ?? 0,
+        inputTokens: meta.inputTokens ?? 0,
+        outputTokens: meta.outputTokens ?? 0,
+        costUsd: meta.costUsd ?? 0,
+        savedVsOpusUsd: meta.savedVsOpusUsd ?? 0,
+        model: meta.model ?? 'unknown',
+        chain,
+        // "cli" if no channel tag, else the channel string (e.g. "telegram:12345").
+        // Channel may include an owner id; we deliberately keep it because the
+        // install id is already user-agnostic and linking a driver to a user
+        // is necessary to distinguish "single user with Telegram" from "many
+        // users with CLI" in aggregate data. Users who don't want this strip
+        // it by running telemetry disable.
+        driver: meta.channel ?? 'cli',
+        ...(meta.toolCallCounts ? { toolCallCounts: meta.toolCallCounts } : {}),
+    };
+}
+/** Append one record to the telemetry log. Silent no-op if disabled. */
+export function recordSession(meta, chain) {
+    if (!isTelemetryEnabled())
+        return;
+    ensureDir();
+    const record = sessionMetaToRecord(meta, getOrCreateInstallId(), chain);
+    try {
+        fs.appendFileSync(LOG_FILE, JSON.stringify(record) + '\n');
+    }
+    catch {
+        // Telemetry is best-effort — never block a user session on a disk write.
+    }
+}
+/**
+ * Locate the session that just finished by ID or by "newest in the sessions
+ * directory whose workDir matches", then record it. Used by start.ts at
+ * exit since interactiveSession() doesn't currently thread the session id
+ * back to the caller.
+ */
+export function recordLatestSessionIfEnabled(workingDir, chain) {
+    if (!isTelemetryEnabled())
+        return;
+    // Lazy import to avoid a circular session/storage <-> telemetry dependency.
+    // Using require() here keeps this module synchronous for tests.
+    /* eslint-disable @typescript-eslint/no-require-imports */
+    const { listSessions } = require('../session/storage.js');
+    /* eslint-enable @typescript-eslint/no-require-imports */
+    const sessions = listSessions();
+    const match = sessions.find(s => s.workDir === workingDir);
+    if (!match)
+        return;
+    recordSession(match, chain);
+}
+/** Read every record in the log. Returns [] if the file is missing. */
+export function readAllRecords() {
+    try {
+        const raw = fs.readFileSync(LOG_FILE, 'utf-8');
+        const out = [];
+        for (const line of raw.split('\n')) {
+            if (!line.trim())
+                continue;
+            try {
+                out.push(JSON.parse(line));
+            }
+            catch { /* skip corrupt */ }
+        }
+        return out;
+    }
+    catch {
+        return [];
+    }
+}
+/** File paths — surfaced so the CLI can show users where data lives. */
+export const telemetryPaths = {
+    consent: CONSENT_FILE,
+    log: LOG_FILE,
+    installId: INSTALL_ID_FILE,
+};

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.4",
+  "version": "3.8.6",
   "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://github.com/RunFranklin/franklin"
+    "url": "git+https://github.com/BlockRunAI/Franklin.git"
   },
   "bugs": {
-    "url": "https://github.com/RunFranklin/franklin/issues"
+    "url": "https://github.com/BlockRunAI/Franklin/issues"
   },
   "homepage": "https://Franklin.run",
   "engines": {