@blockrun/franklin 3.8.2 → 3.8.4

package/dist/commands/telegram.js

@@ -0,0 +1,95 @@
+/**
+ * `franklin telegram` — start the Telegram ingress bot.
+ *
+ * Designed to run on a server / always-on laptop. Reads the bot token and
+ * owner id from env (or falls back to ~/.blockrun/config). Uses trust-mode
+ * permissions because the operator is remote — there's no terminal prompt
+ * they can answer per tool call. The owner lock in `runTelegramBot` is the
+ * real security boundary.
+ */
+import chalk from 'chalk';
+import { loadChain, API_URLS } from '../config.js';
+import { assembleInstructions } from '../agent/context.js';
+import { allCapabilities } from '../tools/index.js';
+import { loadConfig } from './config.js';
+import { runTelegramBot } from '../channel/telegram.js';
+import { findLatestSessionByChannel } from '../session/storage.js';
+export async function telegramCommand(opts) {
+    const token = process.env.TELEGRAM_BOT_TOKEN;
+    const ownerRaw = process.env.TELEGRAM_OWNER_ID;
+    if (!token || !ownerRaw) {
+        console.error(chalk.red('Missing Telegram config.'));
+        console.error(chalk.dim('\nSet two env vars before running `franklin telegram`:\n' +
+            '  TELEGRAM_BOT_TOKEN=<from @BotFather>\n' +
+            '  TELEGRAM_OWNER_ID=<your numeric Telegram user id>\n\n' +
+            'Tip: message @userinfobot on Telegram to get your user id.'));
+        process.exit(1);
+    }
+    const ownerId = parseInt(ownerRaw, 10);
+    if (!Number.isFinite(ownerId) || ownerId <= 0) {
+        console.error(chalk.red(`TELEGRAM_OWNER_ID must be a positive integer, got: ${ownerRaw}`));
+        process.exit(1);
+    }
+    const chain = loadChain();
+    const apiUrl = API_URLS[chain];
+    const config = loadConfig();
+    // Model: --model flag > config default > free default.
+    const model = opts.model ||
+        config['default-model'] ||
+        'nvidia/nemotron-ultra-253b';
+    const workingDir = process.cwd();
+    const systemInstructions = assembleInstructions(workingDir, model);
+    // Resume the most recent session tagged for THIS owner so a process
+    // restart doesn't drop the conversation. First run has no prior session
+    // and starts fresh. `/new` will lay down a new session ID within the
+    // running process; the next restart picks up the newest one again.
+    const channelTag = `telegram:${ownerId}`;
+    const prior = findLatestSessionByChannel(channelTag);
+    if (prior) {
+        console.log(chalk.dim(`  resuming session ${prior.id} (${prior.messageCount} msgs, ` +
+            `last update ${new Date(prior.updatedAt).toLocaleString()})`));
+    }
+    const agentConfig = {
+        model,
+        apiUrl,
+        chain,
+        systemInstructions,
+        capabilities: allCapabilities,
+        workingDir,
+        // No interactive terminal for permission prompts — remote operator can't
+        // answer y/n per tool. The Telegram owner lock is the security boundary.
+        permissionMode: 'trust',
+        debug: opts.debug,
+        sessionChannel: channelTag,
+        resumeSessionId: prior?.id,
+    };
+    console.log(chalk.bold.cyan('Franklin Telegram bot'));
+    console.log(chalk.dim(`  chain: ${chain}`));
+    console.log(chalk.dim(`  model: ${model}`));
+    console.log(chalk.dim(`  owner: ${ownerId}`));
+    console.log(chalk.yellow('  permission mode: trust — every tool the model picks will execute ' +
+        'without confirmation. The owner lock is your only gate.\n'));
+    // SIGINT → stop the bot cleanly. Wrap runTelegramBot so a second Ctrl-C
+    // force-exits if the cleanup path hangs.
+    let exitAttempts = 0;
+    process.on('SIGINT', () => {
+        exitAttempts++;
+        if (exitAttempts === 1) {
+            console.log(chalk.dim('\nStopping… (press Ctrl-C again to force)'));
+        }
+        else {
+            process.exit(130);
+        }
+    });
+    try {
+        await runTelegramBot(agentConfig, {
+            token,
+            ownerId,
+            log: (line) => console.log(chalk.dim(line)),
+        });
+    }
+    catch (err) {
+        console.error(chalk.red(`Telegram bot failed: ${err.message}`));
+        process.exit(1);
+    }
+}

package/dist/content/library.js

@@ -5,8 +5,8 @@
  * risk engine, store.ts is the persistence adapter, and tools/content-execute.ts
  * wires everything into agent-facing capabilities.
  *
- * Why this exists: Claude Code / Cursor cannot carry a content project across
- * sessions. If you start drafting a podcast episode Monday and come back
+ * Why this exists: stateless coding agents can't carry a content project
+ * across sessions. If you start drafting a podcast episode Monday and come back
  * Wednesday, there's no concept of *the same* piece of work. Franklin tracks
  * outline → drafts → assets → distribution as one durable object and lets
  * the agent spend USDC (image generation, audio, stock footage) against a

package/dist/index.js

@@ -166,6 +166,15 @@ program
         });
     }
 }
+program
+    .command('telegram')
+    .description('Drive Franklin from Telegram (requires TELEGRAM_BOT_TOKEN + TELEGRAM_OWNER_ID env vars)')
+    .option('-m, --model <model>', 'Model to use (default from config)')
+    .option('--debug', 'Enable debug logging')
+    .action(async (opts) => {
+    const { telegramCommand } = await import('./commands/telegram.js');
+    await telegramCommand(opts);
+});
 program
     .command('migrate')
     .description('Import preferences and MCP servers from existing AI agent configs')

package/dist/panel/html.js

@@ -423,7 +423,7 @@ a:hover { text-decoration:underline; }
     <div class="savings-hero" id="savings-hero" style="display:none">
       <div>
         <div class="savings-detail">
-          <div class="label">Saved vs Claude Opus</div>
+          <div class="label">Saved vs Opus tier</div>
         </div>
         <div class="savings-amount" id="savings-amount">&mdash;</div>
         <div class="savings-detail">

package/dist/router/index.js

@@ -33,10 +33,10 @@ function loadLearnedWeights() {
     return null;
 }
 // ─── Tier Model Configs ───
-// Agent-first defaults. Claude Sonnet 4.6 is the industry standard for multi-step
-// tool-use agent work; cheap models keep derailing on simple agent loops.
-// Each tier's fallback ends with a cheaper option so payment/quota failures
-// don't strand users on equally expensive alternatives.
+// Agent-first defaults. Sonnet-tier models are the current sweet spot for
+// multi-step tool-use agent work; cheap models keep derailing on simple agent
+// loops. Each tier's fallback ends with a cheaper option so payment/quota
+// failures don't strand users on equally expensive alternatives.
 const AUTO_TIERS = {
     SIMPLE: {
         primary: 'google/gemini-2.5-flash',
@@ -282,7 +282,7 @@ export function routeRequest(prompt, profile = 'auto') {
     // Auto profile bypasses learned routing. The learned Elo scores grow with
     // usage volume rather than pure quality, which biased the router toward
     // cheap/weak models on agentic work. Classic AUTO_TIERS defaults are
-    // agent-tuned (Claude Sonnet as backbone) and more predictable for users.
+    // agent-tuned (Sonnet-tier backbone) and more predictable for users.
     if (profile === 'auto') {
         return classicRouteRequest(prompt, profile);
     }

package/dist/session/storage.d.ts

@@ -15,6 +15,12 @@ export interface SessionMeta {
     outputTokens?: number;
     costUsd?: number;
     savedVsOpusUsd?: number;
+    /**
+     * Origin channel tag. Unset for regular CLI sessions; set to a string like
+     * `telegram:<ownerId>` when the session was started by a non-CLI driver.
+     * Lets findLatestSessionByChannel pick up the right session on bot restart.
+     */
+    channel?: string;
 }
 /** Get the absolute path to a session's JSONL file (for external readers like search). */
 export declare function getSessionFilePath(id: string): string;
@@ -42,6 +48,12 @@ export declare function loadSessionHistory(sessionId: string): Dialogue[];
  * List all saved sessions, newest first.
  */
 export declare function listSessions(): SessionMeta[];
+/**
+ * Find the latest saved session tagged with a given channel (e.g.
+ * `telegram:12345`). Used by non-CLI drivers to resume across process
+ * restarts. Returns undefined when no matching session exists.
+ */
+export declare function findLatestSessionByChannel(channel: string): SessionMeta | undefined;
 /**
  * Prune old sessions beyond MAX_SESSIONS.
  */

package/dist/session/storage.js

@@ -92,6 +92,9 @@ export function updateSessionMeta(sessionId, meta) {
             outputTokens: meta.outputTokens ?? existing?.outputTokens ?? 0,
             costUsd: meta.costUsd ?? existing?.costUsd ?? 0,
             savedVsOpusUsd: meta.savedVsOpusUsd ?? existing?.savedVsOpusUsd ?? 0,
+            ...(meta.channel !== undefined || existing?.channel !== undefined
+                ? { channel: meta.channel ?? existing?.channel }
+                : {}),
         };
         // Atomic write: tmp file + rename. Prevents corruption when parent
         // and sub-agent update the same session meta concurrently.
@@ -176,6 +179,14 @@ export function listSessions() {
         return [];
     }
 }
+/**
+ * Find the latest saved session tagged with a given channel (e.g.
+ * `telegram:12345`). Used by non-CLI drivers to resume across process
+ * restarts. Returns undefined when no matching session exists.
+ */
+export function findLatestSessionByChannel(channel) {
+    return listSessions().find(m => m.channel === channel);
+}
 /**
  * Prune old sessions beyond MAX_SESSIONS.
  */

package/dist/social/ai.d.ts

@@ -7,8 +7,9 @@
  *
  * Key improvements over social-bot:
  *   - Uses Franklin's multi-model router (tier-based: free / cheap / premium)
- *     instead of hardcoded Claude Sonnet for every call — throwaway replies
- *     can run on free NVIDIA models, high-value leads can escalate to Opus.
+ *     instead of hardcoding one model for every call — throwaway replies
+ *     can run on free NVIDIA models, high-value leads can escalate to the
+ *     top tier.
  *   - x402 payment flow handled by ModelClient — no Anthropic billing relationship.
  *   - SKIP detection lives in the caller so we can commit a 'skipped' record
  *     for visibility in stats.

package/dist/social/ai.js

@@ -7,8 +7,9 @@
  *
  * Key improvements over social-bot:
  *   - Uses Franklin's multi-model router (tier-based: free / cheap / premium)
- *     instead of hardcoded Claude Sonnet for every call — throwaway replies
- *     can run on free NVIDIA models, high-value leads can escalate to Opus.
+ *     instead of hardcoding one model for every call — throwaway replies
+ *     can run on free NVIDIA models, high-value leads can escalate to the
+ *     top tier.
  *   - x402 payment flow handled by ModelClient — no Anthropic billing relationship.
  *   - SKIP detection lives in the caller so we can commit a 'skipped' record
  *     for visibility in stats.

package/dist/stats/insights.d.ts

@@ -21,7 +21,7 @@ export interface InsightsReport {
     totalInputTokens: number;
     /** Total output tokens in window */
     totalOutputTokens: number;
-    /** Savings vs always using Claude Opus */
+    /** Savings vs always using the Opus-tier baseline */
     savedVsOpusUsd: number;
     /** Per-model breakdown, sorted by cost desc */
     byModel: Array<{

package/dist/stats/tracker.js

@@ -207,7 +207,7 @@ export function recordUsage(model, inputTokens, outputTokens, costUsd, latencyMs
  */
 export function getStatsSummary() {
     const stats = loadStats();
-    // Calculate what it would cost with Claude Opus
+    // Calculate what it would cost with the Opus-tier baseline
     const opusCost = (stats.totalInputTokens / 1_000_000) * OPUS_PRICING.input +
         (stats.totalOutputTokens / 1_000_000) * OPUS_PRICING.output;
     const saved = opusCost - stats.totalCostUsd;

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

@@ -9,7 +9,7 @@
  *   ContentShow       — dump a single piece's state as actionable markdown
  *   ContentList       — summary of every piece, newest first
  *
- * This is the surface Claude Code and Cursor cannot cover: durable content
+ * This is the surface generic coding agents can't cover: durable content
  * state with autonomous spending gating. An agent can spin up "Franklin
  * launch thread" with a $3 budget, hit DALL-E twice for hero images, blow
  * the budget, read the refusal, pick a cheaper model, and continue — all

package/dist/tools/content-execute.js

@@ -9,7 +9,7 @@
  *   ContentShow       — dump a single piece's state as actionable markdown
  *   ContentList       — summary of every piece, newest first
  *
- * This is the surface Claude Code and Cursor cannot cover: durable content
+ * This is the surface generic coding agents can't cover: durable content
  * state with autonomous spending gating. An agent can spin up "Franklin
  * launch thread" with a $3 budget, hit DALL-E twice for hero images, blow
  * the budget, read the refusal, pick a cheaper model, and continue — all

package/dist/tools/index.js

@@ -13,6 +13,8 @@ import { webFetchCapability, clearSessionState as clearWebFetchSessionState } fr
 import { webSearchCapability } from './websearch.js';
 import { taskCapability } from './task.js';
 import { createImageGenCapability } from './imagegen.js';
+import { createVideoGenCapability } from './videogen.js';
+import { memoryRecallCapability } from './memory.js';
 import { askUserCapability } from './askuser.js';
 import { tradingSignalCapability, tradingMarketCapability } from './trading.js';
 import { searchXCapability } from './searchx.js';
@@ -34,7 +36,7 @@ import { loadLibrary as loadContentLibrary, saveLibrary as saveContentLibrary }
 // (2.5 positions fully loaded), $900 total exposure cap (keep 10% cash buffer).
 // Live prices from CoinGecko; simulated fills at 10 bps. Portfolio persists
 // to ~/.blockrun/portfolio.json across sessions — that persistence is the
-// whole point of this vertical (Claude Code / Cursor cannot carry trading
+// whole point of this vertical (stateless coding agents can't carry trading
 // state between runs).
 const DEFAULT_PORTFOLIO_PATH = path.join(os.homedir(), '.blockrun', 'portfolio.json');
 const DEFAULT_TRADE_LOG_PATH = path.join(os.homedir(), '.blockrun', 'trades.jsonl');
@@ -68,8 +70,8 @@ function buildDefaultTradingCapabilities() {
 const defaultTradingCapabilities = buildDefaultTradingCapabilities();
 // ─── Default Content Library ──────────────────────────────────────────────
 // Durable content projects at ~/.blockrun/content.json. Like the portfolio,
-// this is persistent cross-session state — something Claude Code structurally
-// cannot offer.
+// this is persistent cross-session state — something stateless coding agents
+// structurally can't offer.
 const DEFAULT_CONTENT_PATH = path.join(os.homedir(), '.blockrun', 'content.json');
 // Build a single ContentLibrary instance so both the Content capabilities and
 // the content-aware ImageGen capability share state and persistence.
@@ -90,6 +92,10 @@ const defaultImageGenCapability = createImageGenCapability({
     library: defaultContentLibrary,
     onContentChange: persistContentLibrary,
 });
+const defaultVideoGenCapability = createVideoGenCapability({
+    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
@@ -112,6 +118,8 @@ export const allCapabilities = [
     webSearchCapability,
     taskCapability,
     defaultImageGenCapability,
+    defaultVideoGenCapability,
+    memoryRecallCapability,
     askUserCapability,
     tradingSignalCapability,
     tradingMarketCapability,

package/dist/tools/memory.d.ts

@@ -0,0 +1,16 @@
+/**
+ * MemoryRecall — let the agent query Franklin's Brain explicitly.
+ *
+ * Auto-recall (in loop.ts) covers the "user just mentioned X" case, but the
+ * agent often needs to check memory on its own: "what do I already know
+ * about the user's portfolio?", "have I seen this company before?". This
+ * tool exposes the Brain's search + observation read path as a first-class
+ * capability so the agent can decide when to pull from long-term memory.
+ *
+ * Read-only. Writing to the Brain happens after-the-fact via
+ * extractBrainEntities on session end; we don't expose a write tool here
+ * because giving the model direct write access to the knowledge graph
+ * invites fabricated "facts" that never saw a real conversation.
+ */
+import type { CapabilityHandler } from '../agent/types.js';
+export declare const memoryRecallCapability: CapabilityHandler;

package/dist/tools/memory.js

@@ -0,0 +1,86 @@
+/**
+ * MemoryRecall — let the agent query Franklin's Brain explicitly.
+ *
+ * Auto-recall (in loop.ts) covers the "user just mentioned X" case, but the
+ * agent often needs to check memory on its own: "what do I already know
+ * about the user's portfolio?", "have I seen this company before?". This
+ * tool exposes the Brain's search + observation read path as a first-class
+ * capability so the agent can decide when to pull from long-term memory.
+ *
+ * Read-only. Writing to the Brain happens after-the-fact via
+ * extractBrainEntities on session end; we don't expose a write tool here
+ * because giving the model direct write access to the knowledge graph
+ * invites fabricated "facts" that never saw a real conversation.
+ */
+import { searchEntities, getEntityObservations, getEntityRelations, loadEntities, getBrainStats, } from '../brain/store.js';
+const MAX_OBS_PER_ENTITY = 5;
+const MAX_REL_PER_ENTITY = 3;
+export const memoryRecallCapability = {
+    spec: {
+        name: 'MemoryRecall',
+        description: "Query Franklin's long-term memory (the Brain) for what it already " +
+            "knows about a person, project, company, product, or concept. Use " +
+            "this BEFORE asking the user a question the memory might already " +
+            "answer, or when deciding how to act toward a named entity. Returns " +
+            "matching entities with their observations and relations. " +
+            "Read-only — observations are harvested automatically at session end.",
+        input_schema: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'Name, alias, or substring to search for. Case-insensitive.',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Max entities to return (default 5, max 15).',
+                },
+            },
+            required: ['query'],
+        },
+    },
+    execute: async (input) => {
+        const { query, limit } = input;
+        if (!query || !query.trim()) {
+            return { output: 'Error: query is required', isError: true };
+        }
+        const cap = Math.min(Math.max(1, limit ?? 5), 15);
+        const hits = searchEntities(query, cap);
+        const stats = getBrainStats();
+        if (hits.length === 0) {
+            return {
+                output: `No memory match for "${query}".\n\n` +
+                    `Brain holds ${stats.entities} entities, ${stats.observations} observations.`,
+            };
+        }
+        const entities = loadEntities();
+        const lines = [`# Memory — ${hits.length} match${hits.length === 1 ? '' : 'es'} for "${query}"`];
+        for (const hit of hits) {
+            lines.push(`\n## ${hit.name} (${hit.type})`);
+            if (hit.aliases.length > 0) {
+                lines.push(`aka: ${hit.aliases.join(', ')}`);
+            }
+            lines.push(`_referenced ${hit.reference_count}×, last seen ${new Date(hit.updated_at).toISOString().slice(0, 10)}_`);
+            const obs = getEntityObservations(hit.id)
+                .sort((a, b) => b.confidence - a.confidence)
+                .slice(0, MAX_OBS_PER_ENTITY);
+            if (obs.length > 0) {
+                lines.push('\n**Facts**');
+                for (const o of obs)
+                    lines.push(`- ${o.content}`);
+            }
+            const rels = getEntityRelations(hit.id).slice(0, MAX_REL_PER_ENTITY);
+            if (rels.length > 0) {
+                lines.push('\n**Relations**');
+                for (const r of rels) {
+                    const otherId = r.from_id === hit.id ? r.to_id : r.from_id;
+                    const other = entities.find(e => e.id === otherId);
+                    if (other)
+                        lines.push(`- ${r.type} → ${other.name}`);
+                }
+            }
+        }
+        return { output: lines.join('\n') };
+    },
+    concurrent: true,
+};

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

@@ -4,8 +4,8 @@
  * TradingOpenPosition (buy side), TradingClosePosition (sell side).
  *
  * This is the surface that differentiates Franklin from generic coding
- * agents — Claude Code and Cursor cannot hold a wallet, track positions
- * across sessions, or reason about P&L. Every output here is deliberately
+ * agents — stateless tools can't hold a wallet, track positions across
+ * sessions, or reason about P&L. Every output here is deliberately
  * information-rich so the agent has the numbers it needs to make the next
  * economic decision (cash left, risk utilization, unrealized vs realized
  * P&L, fill detail) without a follow-up tool call.

package/dist/tools/trading-execute.js

@@ -4,8 +4,8 @@
  * TradingOpenPosition (buy side), TradingClosePosition (sell side).
  *
  * This is the surface that differentiates Franklin from generic coding
- * agents — Claude Code and Cursor cannot hold a wallet, track positions
- * across sessions, or reason about P&L. Every output here is deliberately
+ * agents — stateless tools can't hold a wallet, track positions across
+ * sessions, or reason about P&L. Every output here is deliberately
  * information-rich so the agent has the numbers it needs to make the next
  * economic decision (cash left, risk utilization, unrealized vs realized
  * P&L, fill detail) without a follow-up tool call.

package/dist/tools/videogen.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Video Generation capability — generate short MP4 videos via the BlockRun
+ * /v1/videos/generations endpoint. Uses x402 payment (Base or Solana).
+ *
+ * Default model `xai/grok-imagine-video` returns an 8-second clip for ~$0.42.
+ * The endpoint is synchronous-over-polling: the HTTP connection stays open
+ * until the upstream xAI job finishes (typically 20–60s, timeout 180s), so
+ * the caller only needs to issue a single POST.
+ */
+import type { CapabilityHandler } from '../agent/types.js';
+import type { ContentLibrary } from '../content/library.js';
+export interface VideoGenDeps {
+    library?: ContentLibrary;
+    onContentChange?: () => void | Promise<void>;
+}
+export declare function createVideoGenCapability(deps?: VideoGenDeps): CapabilityHandler;
+export declare const videoGenCapability: CapabilityHandler;