@blockrun/franklin 3.8.7 → 3.8.9

package/dist/agent/bash-guard.js

@@ -16,8 +16,24 @@ const DANGEROUS_PATTERNS = [
     [/\brm\s+-[a-zA-Z]*[rR][a-zA-Z]*\s+[/~]/, 'recursive delete on root/home'],
     [/\brm\s+-[a-zA-Z]*[rR][a-zA-Z]*f/, 'forced recursive delete'],
     [/\brm\s+-[a-zA-Z]*f[a-zA-Z]*[rR]/, 'forced recursive delete'],
+    [/\brm\s+-[a-zA-Z]*f\s+\//, 'forced delete at filesystem root'],
     [/\bmkfs\b/, 'format filesystem'],
     [/\bdd\s+.*of=/, 'raw disk write'],
+    [/\btruncate\s+-s\s+0\b/, 'truncate file to zero'],
+    [/>\s*\/dev\/(sd|nvme|disk|hd)/, 'write to raw block device'],
+    // Silently overwriting with mv/cp
+    [/\bmv\s+-f\b/, 'mv -f overwrites target silently'],
+    [/\bcp\s+-[a-zA-Z]*f[a-zA-Z]*r/, 'cp -rf can overwrite directory trees silently'],
+    // Writes to system-level paths — most agents should NEVER touch these.
+    // Redirections (`>`, `>>`) or tee'ing to /etc/, /usr/, /boot/, /var/lib/ etc.
+    [/>\s*\/(etc|usr|bin|sbin|boot|lib|lib64|var\/lib|sys|proc)\//, 'write to system path'],
+    [/\btee\s+.*\s+\/(etc|usr|bin|sbin|boot|lib|lib64|var\/lib|sys|proc)\//, 'tee to system path'],
+    // Extract tar/zip at filesystem root — classic traversal foot-gun.
+    [/\btar\s+.*-C\s+\/(?!tmp|var\/tmp|home)/, 'extract archive to system path'],
+    [/\bunzip\s+.*-d\s+\/(?!tmp|var\/tmp|home)/, 'unzip to system path'],
+    // Shell-out of untrusted text
+    [/\beval\s/, 'eval executes arbitrary shell'],
+    [/\bexec\s+(bash|sh|zsh)/, 'exec replaces the shell process'],
     // Git irreversible operations
     [/\bgit\s+push\s+.*--force\b/, 'force push'],
     [/\bgit\s+push\s+-f\b/, 'force push'],
@@ -25,11 +41,14 @@ const DANGEROUS_PATTERNS = [
     [/\bgit\s+clean\s+-[a-zA-Z]*f/, 'git clean — deletes untracked files'],
     [/\bgit\s+checkout\s+--\s+\./, 'discard all working changes'],
     [/\bgit\s+branch\s+-D\b/, 'force delete branch'],
+    [/\bgit\s+filter-(repo|branch)\b/, 'history rewrite'],
     // Database destructive
     [/\bDROP\s+(TABLE|DATABASE|SCHEMA)\b/i, 'drop database objects'],
     [/\bTRUNCATE\s+TABLE\b/i, 'truncate table'],
+    [/\bDELETE\s+FROM\s+\S+\s*;?\s*$/i, 'DELETE without WHERE'],
     // System-level danger
     [/\bchmod\s+(-R\s+)?777\b/, 'world-writable permissions'],
+    [/\bchown\s+-R\s+\S+\s+\//, 'recursive chown at root'],
     // Pipe-to-shell: catch sudo/env prefixes and common shell variants (bash/sh/zsh/ksh/dash/fish).
     // The optional `-e`/`-x` flags after the shell binary are intentionally allowed by \b;
     // what we block is the routing of downloaded content into an interpreter.
@@ -38,11 +57,21 @@ const DANGEROUS_PATTERNS = [
     // Command substitution of a downloader into argv — `$(curl …)` or `` `curl …` ``.
     [/\$\(\s*(curl|wget|fetch)\b/, 'command substitution of network downloader'],
     [/`\s*(curl|wget|fetch)\b[^`]*`/, 'backtick substitution of network downloader'],
+    // Privilege escalation wrappers to destructive ops — order matters: the
+    // specific `sudo rm` pattern is listed first so its tailored message wins.
     [/\bsudo\s+rm\b/, 'sudo delete'],
+    [/\b(sudo|doas|su\s+-c)\s+.*\b(mv|dd|chmod|chown|mkfs|shutdown|reboot)\b/, 'privileged destructive op'],
+    // sed -i (in-place) on any system path
+    [/\bsed\s+-i(\s+'')?\s+.*\/(etc|usr|bin|sbin|boot|lib)\//, 'in-place edit of system path'],
     // Kill/shutdown
     [/\bkill\s+-9\s+-1\b/, 'kill all processes'],
+    [/\bkillall\s/, 'killall targets matching processes globally'],
     [/\bshutdown\b/, 'system shutdown'],
     [/\breboot\b/, 'system reboot'],
+    [/\bpoweroff\b/, 'system poweroff'],
+    // Cryptocurrency key exfiltration / secret exposure
+    [/\bcat\s+.*\.env(\.\w+)?\s*\|/, 'env file piped — potential secret exfiltration'],
+    [/\bcat\s+.*(\.ssh|\.gnupg)\/.*\s*\|/, 'ssh/gpg key piped — potential secret exfiltration'],
 ];
 // ─── Safe Commands ────────────────────────────────────────────────────────
 // If ALL segments use these commands, auto-approve.

package/dist/agent/loop.js

@@ -13,6 +13,8 @@ import { optimizeHistory, CAPPED_MAX_TOKENS, ESCALATED_MAX_TOKENS, getMaxOutputT
 import { classifyAgentError } from './error-classifier.js';
 import { SessionToolGuard } from './tool-guard.js';
 import { resetToolSessionState } from '../tools/index.js';
+import { CORE_TOOL_NAMES, dynamicToolsEnabled } from '../tools/tool-categories.js';
+import { createActivateToolCapability } from '../tools/activate.js';
 import { recordUsage } from '../stats/tracker.js';
 import { recordSessionUsage } from '../stats/session-tracker.js';
 import { appendAudit, extractLastUserPrompt } from '../stats/audit.js';
@@ -317,11 +319,33 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
         chain: config.chain,
         debug: config.debug,
     });
+    // ── Dynamic tool visibility ──
+    // Register ActivateTool before building the capability map so the agent
+    // can always reach the meta-tool. When FRANKLIN_DYNAMIC_TOOLS=0 is set,
+    // `activeTools` is seeded with every registered name — behaves as the
+    // pre-3.8.9 static registry.
     const capabilityMap = new Map();
     for (const cap of config.capabilities) {
         capabilityMap.set(cap.spec.name, cap);
     }
-    const toolDefs = config.capabilities.map((c) => c.spec);
+    const activeTools = new Set();
+    const dynamicTools = dynamicToolsEnabled();
+    if (dynamicTools) {
+        for (const name of CORE_TOOL_NAMES) {
+            if (capabilityMap.has(name))
+                activeTools.add(name);
+        }
+    }
+    else {
+        for (const cap of config.capabilities)
+            activeTools.add(cap.spec.name);
+    }
+    const activateToolCap = createActivateToolCapability({ activeTools, allTools: capabilityMap });
+    capabilityMap.set(activateToolCap.spec.name, activateToolCap);
+    if (dynamicTools)
+        activeTools.add(activateToolCap.spec.name);
+    const allToolDefs = [...capabilityMap.values()].map(c => c.spec);
+    const buildCallToolDefs = () => dynamicTools ? allToolDefs.filter(t => activeTools.has(t.name)) : allToolDefs;
     const maxTurns = config.maxTurns ?? 15;
     const workDir = config.workingDir ?? process.cwd();
     const permissions = new PermissionManager(config.permissionMode ?? 'default', config.permissionPromptFn);
@@ -576,6 +600,20 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
                     '4. Think step by step — show your reasoning explicitly when it adds value\n' +
                     'Prioritize correctness and thoroughness over speed.');
             }
+            // ── Dynamic tool visibility hint ──
+            // When the core/on-demand split is active, tell every model up front
+            // that its tool list is intentionally small and that extras can be
+            // pulled via ActivateTool. Kept byte-stable across turns (no tool
+            // names inlined) so the prompt cache still holds.
+            if (dynamicTools && allToolDefs.length > activeTools.size) {
+                systemParts.push('# Tool Inventory\n' +
+                    'Your current tool list is intentionally minimal. Additional tools ' +
+                    '(web search, image/video/music generation, trading, content, brain ' +
+                    'recall, etc.) are available on demand. Call `ActivateTool()` with ' +
+                    'no arguments to see what is available, then call `ActivateTool({ ' +
+                    '"names": ["<name>"] })` to enable the ones you need. Activated ' +
+                    'tools become visible on the next turn.');
+            }
             // ── Context awareness injection ──
             // Tell the model how full its context window is so it can self-regulate.
             // At high usage, nudge it to be concise and avoid unnecessary tool calls.
@@ -669,7 +707,10 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
             }
             // Build per-call tool defs, max_tokens, and system prompt
             // (planning calls get no tools + short output + planning prompt)
-            let callToolDefs = toolDefs;
+            // Dynamic visibility: `buildCallToolDefs()` returns only the active set
+            // (core + any the agent pulled via ActivateTool). Re-evaluated every
+            // turn so newly activated tools take effect immediately.
+            let callToolDefs = buildCallToolDefs();
             let callMaxTokens = maxTokens;
             let callSystemPrompt = systemPrompt;
             if (planActive && loopCount === 1) {
@@ -918,6 +959,24 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
             const opusCost = (inputTokens / 1_000_000) * OPUS_PRICING.input
                 + (usage.outputTokens / 1_000_000) * OPUS_PRICING.output;
             sessionSavedVsOpus += Math.max(0, opusCost - costEstimate);
+            // ── Max-spend guard ──
+            // Session-level cost ceiling. Cron/daily drivers pass this to bound a
+            // single run ("spend at most $0.50 for today's digest"); interactive
+            // users can pass it to feel safe walking away. Hits as soon as accumulated
+            // cost crosses the cap — the last call that tipped us over still runs,
+            // but no further API calls are made.
+            const maxSpend = config.maxSpendUsd;
+            if (typeof maxSpend === 'number' && Number.isFinite(maxSpend) && maxSpend > 0 &&
+                sessionCostUsd >= maxSpend) {
+                onEvent({
+                    kind: 'text_delta',
+                    text: `\n\n_Max-spend reached: $${sessionCostUsd.toFixed(4)} ≥ cap $${maxSpend.toFixed(2)}. ` +
+                        `Stopping session — further calls would exceed the budget._\n`,
+                });
+                persistSessionMeta();
+                onEvent({ kind: 'turn_done', reason: 'budget' });
+                return history;
+            }
             // ── Max output tokens recovery ──
             if (stopReason === 'max_tokens' && recoveryAttempts < MAX_RECOVERY_ATTEMPTS) {
                 recoveryAttempts++;

package/dist/agent/permissions.js

@@ -33,10 +33,10 @@ function isCommonDevCommand(cmd) {
     return COMMON_DEV_PATTERNS.some(p => p.test(trimmed));
 }
 // ─── Default Rules ─────────────────────────────────────────────────────────
-const READ_ONLY_TOOLS = new Set(['Read', 'Glob', 'Grep', 'WebSearch', 'Task', 'AskUser', 'ImageGen', 'TradingSignal', 'TradingMarket', 'SearchX']);
+const READ_ONLY_TOOLS = new Set(['Read', 'Glob', 'Grep', 'WebSearch', 'Task', 'AskUser', 'ActivateTool', 'ImageGen', 'TradingSignal', 'TradingMarket', 'SearchX']);
 const DESTRUCTIVE_TOOLS = new Set(['Write', 'Edit', 'Bash']);
 const DEFAULT_RULES = {
-    allow: ['Read', 'Glob', 'Grep', 'WebSearch', 'WebFetch', 'Task', 'AskUser', 'ImageGen', 'TradingSignal', 'TradingMarket', 'SearchX'],
+    allow: ['Read', 'Glob', 'Grep', 'WebSearch', 'WebFetch', 'Task', 'AskUser', 'ActivateTool', 'ImageGen', 'TradingSignal', 'TradingMarket', 'SearchX'],
     deny: [],
     ask: ['Write', 'Edit', 'Bash', 'Agent', 'PostToX'],
 };

package/dist/agent/types.d.ts

@@ -155,4 +155,11 @@ export interface AgentConfig {
      * unset. Format: "<driver>:<owner-or-chat-id>", e.g. "telegram:12345".
      */
     sessionChannel?: string;
+    /**
+     * Hard cap on total USD spend for this session. When accumulated API cost
+     * crosses the cap, the loop stops with `reason: 'budget'`. Zero/negative
+     * values disable the cap. Primary use case: cron/daily drivers that must
+     * bound a single run to keep autonomous execution inside a known envelope.
+     */
+    maxSpendUsd?: number;
 }

package/dist/commands/doctor.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `franklin doctor` — one-command health check.
+ *
+ * The single highest-leverage onboarding improvement: most early failures
+ * are environmental (Node too old, no wallet, wrong chain, unreachable
+ * gateway, malformed MCP config). `franklin doctor` pokes each of those in
+ * sequence, prints a verdict per check, and exits non-zero if anything is
+ * broken so CI scripts can gate on it.
+ *
+ * Human-readable by default. Pass `--json` for machine-parseable output
+ * (useful for the ink REPL `/doctor` or external monitoring).
+ */
+export declare function doctorCommand(opts?: {
+    json?: boolean;
+}): Promise<void>;

package/dist/commands/doctor.js

@@ -0,0 +1,251 @@
+/**
+ * `franklin doctor` — one-command health check.
+ *
+ * The single highest-leverage onboarding improvement: most early failures
+ * are environmental (Node too old, no wallet, wrong chain, unreachable
+ * gateway, malformed MCP config). `franklin doctor` pokes each of those in
+ * sequence, prints a verdict per check, and exits non-zero if anything is
+ * broken so CI scripts can gate on it.
+ *
+ * Human-readable by default. Pass `--json` for machine-parseable output
+ * (useful for the ink REPL `/doctor` or external monitoring).
+ */
+import chalk from 'chalk';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { setupAgentWallet, setupAgentSolanaWallet, } from '@blockrun/llm';
+import { loadChain, API_URLS, VERSION, BLOCKRUN_DIR } from '../config.js';
+import { isTelemetryEnabled, readAllRecords } from '../telemetry/store.js';
+async function runChecks() {
+    const out = [];
+    // ── 1. Runtime ────────────────────────────────────────────────────
+    const nodeVer = process.versions.node;
+    const nodeMajor = parseInt(nodeVer.split('.')[0], 10);
+    out.push({
+        name: 'Node.js',
+        status: nodeMajor >= 20 ? 'ok' : 'fail',
+        detail: `${nodeVer}${nodeMajor >= 20 ? '' : ' — require >= 20'}`,
+        remedy: nodeMajor >= 20 ? undefined : 'Upgrade Node.js: https://nodejs.org',
+    });
+    // ── 2. Franklin version ───────────────────────────────────────────
+    out.push({
+        name: 'Franklin',
+        status: 'ok',
+        detail: `v${VERSION}`,
+    });
+    // ── 3. BLOCKRUN_DIR writable ──────────────────────────────────────
+    try {
+        fs.mkdirSync(BLOCKRUN_DIR, { recursive: true });
+        const probe = path.join(BLOCKRUN_DIR, '.doctor-probe');
+        fs.writeFileSync(probe, 'ok');
+        fs.unlinkSync(probe);
+        out.push({
+            name: 'Config directory',
+            status: 'ok',
+            detail: BLOCKRUN_DIR,
+        });
+    }
+    catch (err) {
+        out.push({
+            name: 'Config directory',
+            status: 'fail',
+            detail: `${BLOCKRUN_DIR} — ${err.message}`,
+            remedy: `Check permissions on ${BLOCKRUN_DIR} or unset HOME override`,
+        });
+    }
+    // ── 4. Chain configuration ────────────────────────────────────────
+    let chain = null;
+    try {
+        chain = loadChain();
+        out.push({
+            name: 'Chain',
+            status: 'ok',
+            detail: chain,
+        });
+    }
+    catch (err) {
+        out.push({
+            name: 'Chain',
+            status: 'fail',
+            detail: `failed to load — ${err.message}`,
+            remedy: 'Run: franklin setup base  (or: franklin setup solana)',
+        });
+    }
+    // ── 5. Wallet ─────────────────────────────────────────────────────
+    let walletBalance = null;
+    let walletAddress = '';
+    if (chain) {
+        try {
+            if (chain === 'solana') {
+                const client = await setupAgentSolanaWallet({ silent: true });
+                walletAddress = await client.getWalletAddress();
+                walletBalance = await client.getBalance();
+            }
+            else {
+                const client = setupAgentWallet({ silent: true });
+                walletAddress = client.getWalletAddress();
+                walletBalance = await client.getBalance();
+            }
+            out.push({
+                name: 'Wallet',
+                status: 'ok',
+                detail: `${walletAddress.slice(0, 10)}…${walletAddress.slice(-6)}`,
+            });
+            out.push({
+                name: 'USDC balance',
+                status: walletBalance > 0 ? 'ok' : 'warn',
+                detail: `$${walletBalance.toFixed(2)}${walletBalance === 0 ? ' — free-tier models only' : ''}`,
+                remedy: walletBalance === 0
+                    ? `Send USDC on ${chain} to ${walletAddress} to unlock paid models`
+                    : undefined,
+            });
+        }
+        catch (err) {
+            const msg = err.message || '';
+            out.push({
+                name: 'Wallet',
+                status: 'fail',
+                detail: `error — ${msg.slice(0, 120)}`,
+                remedy: msg.includes('ENOENT') || msg.includes('wallet') || msg.includes('key')
+                    ? 'Run: franklin setup'
+                    : 'Check network / wallet file permissions',
+            });
+        }
+    }
+    // ── 6. Gateway reachability ───────────────────────────────────────
+    if (chain) {
+        const apiUrl = API_URLS[chain];
+        try {
+            const ctl = new AbortController();
+            const t = setTimeout(() => ctl.abort(), 5000);
+            const res = await fetch(`${apiUrl}/health`, { signal: ctl.signal }).catch(() => null);
+            clearTimeout(t);
+            if (res && res.ok) {
+                out.push({
+                    name: 'Gateway',
+                    status: 'ok',
+                    detail: apiUrl,
+                });
+            }
+            else {
+                // Fall back to a HEAD on the messages endpoint — some deployments
+                // don't expose /health but the API is up.
+                const ctl2 = new AbortController();
+                const t2 = setTimeout(() => ctl2.abort(), 5000);
+                const res2 = await fetch(`${apiUrl}/v1/messages`, {
+                    method: 'HEAD',
+                    signal: ctl2.signal,
+                }).catch(() => null);
+                clearTimeout(t2);
+                out.push({
+                    name: 'Gateway',
+                    status: res2 ? 'ok' : 'fail',
+                    detail: res2 ? apiUrl : `unreachable: ${apiUrl}`,
+                    remedy: res2 ? undefined : 'Check network or try the other chain',
+                });
+            }
+        }
+        catch (err) {
+            out.push({
+                name: 'Gateway',
+                status: 'fail',
+                detail: `${apiUrl} — ${err.message}`,
+            });
+        }
+    }
+    // ── 7. MCP config ─────────────────────────────────────────────────
+    const mcpPath = path.join(BLOCKRUN_DIR, 'mcp.json');
+    if (fs.existsSync(mcpPath)) {
+        try {
+            const raw = fs.readFileSync(mcpPath, 'utf-8');
+            const parsed = JSON.parse(raw);
+            const count = Object.keys(parsed.mcpServers || {}).length;
+            out.push({
+                name: 'MCP servers',
+                status: 'ok',
+                detail: `${count} configured in ${mcpPath}`,
+            });
+        }
+        catch (err) {
+            out.push({
+                name: 'MCP servers',
+                status: 'warn',
+                detail: `${mcpPath} has invalid JSON — ${err.message}`,
+                remedy: `Fix or delete ${mcpPath}`,
+            });
+        }
+    }
+    else {
+        out.push({
+            name: 'MCP servers',
+            status: 'ok',
+            detail: 'none configured',
+        });
+    }
+    // ── 8. Telemetry ──────────────────────────────────────────────────
+    const telEnabled = isTelemetryEnabled();
+    if (telEnabled) {
+        const records = readAllRecords();
+        out.push({
+            name: 'Telemetry',
+            status: 'ok',
+            detail: `enabled — ${records.length} session${records.length === 1 ? '' : 's'} recorded`,
+        });
+    }
+    else {
+        out.push({
+            name: 'Telemetry',
+            status: 'ok',
+            detail: 'disabled (default)',
+        });
+    }
+    // ── 9. Shell / PATH hint ──────────────────────────────────────────
+    const which = process.env.PATH || '';
+    const hasHomebrew = which.includes('/opt/homebrew/bin') || which.includes('/usr/local/bin');
+    if (os.platform() === 'darwin' && !hasHomebrew) {
+        out.push({
+            name: 'PATH',
+            status: 'warn',
+            detail: 'Homebrew paths not in PATH',
+            remedy: 'Add /opt/homebrew/bin to PATH in ~/.zshrc',
+        });
+    }
+    return out;
+}
+function printHuman(checks) {
+    console.log(chalk.bold('\n  franklin doctor\n'));
+    for (const c of checks) {
+        const icon = c.status === 'ok' ? chalk.green('✓') :
+            c.status === 'warn' ? chalk.yellow('⚠') :
+                chalk.red('✗');
+        console.log(`  ${icon}  ${c.name.padEnd(18)} ${chalk.dim(c.detail)}`);
+        if (c.remedy) {
+            console.log(`     ${chalk.dim('↳')} ${chalk.yellow(c.remedy)}`);
+        }
+    }
+    const fails = checks.filter(c => c.status === 'fail').length;
+    const warns = checks.filter(c => c.status === 'warn').length;
+    console.log();
+    if (fails > 0) {
+        console.log(chalk.red(`  ${fails} check${fails === 1 ? '' : 's'} failed. See remedies above.`));
+    }
+    else if (warns > 0) {
+        console.log(chalk.yellow(`  All criticals ok. ${warns} warning${warns === 1 ? '' : 's'} above — safe to ignore for now.`));
+    }
+    else {
+        console.log(chalk.green('  All clear. Ready to run: franklin'));
+    }
+    console.log();
+}
+export async function doctorCommand(opts = {}) {
+    const checks = await runChecks();
+    if (opts.json) {
+        const fails = checks.filter(c => c.status === 'fail').length;
+        process.stdout.write(JSON.stringify({ checks, healthy: fails === 0 }, null, 2) + '\n');
+        process.exit(fails > 0 ? 1 : 0);
+    }
+    printHuman(checks);
+    const fails = checks.filter(c => c.status === 'fail').length;
+    process.exit(fails > 0 ? 1 : 0);
+}

package/dist/commands/start.d.ts

@@ -7,6 +7,10 @@ interface StartOptions {
     resume?: string | boolean | 'picker';
     /** Continue: resume most recent session matching the current working directory */
     continue?: boolean;
+    /** Hard USD cap on total session spend. Stops the loop when exceeded. */
+    maxSpend?: string | number;
+    /** Run a single prompt non-interactively, then exit. For cron/scripted use. */
+    prompt?: string;
 }
 export declare function startCommand(options: StartOptions): Promise<void>;
 export {};

package/dist/commands/start.js

@@ -74,6 +74,49 @@ export async function startCommand(options) {
         // Default: free NVIDIA model — zero wallet charges until user explicitly switches
         model = 'nvidia/nemotron-ultra-253b';
     }
+    const workDir = process.cwd();
+    // --prompt batch mode: skip all interactive startup UI/side effects so
+    // stdout stays clean for cron/scripts. Keep the capability surface to the
+    // built-ins only — no panel, no MCP autoconnect, no wallet/banner chatter.
+    if (options.prompt) {
+        if (options.resume === true || options.resume === 'picker') {
+            console.error(chalk.red('`--prompt` requires `--resume` to include an explicit session id.'));
+            process.exitCode = 1;
+            return;
+        }
+        const systemInstructions = assembleInstructions(workDir, model);
+        const subAgent = createSubAgentCapability(apiUrl, chain, allCapabilities, model);
+        const { registerMoAConfig } = await import('../tools/moa.js');
+        registerMoAConfig(apiUrl, chain, model);
+        const capabilities = [...allCapabilities, subAgent];
+        if (options.debug) {
+            const issues = validateToolDescriptions(capabilities);
+            for (const issue of issues) {
+                console.error(`[validate] ${issue.severity}: ${issue.toolName} — ${issue.issue}`);
+            }
+        }
+        const agentConfig = {
+            model,
+            apiUrl,
+            chain,
+            systemInstructions,
+            capabilities,
+            maxTurns: 100,
+            workingDir: workDir,
+            permissionMode: 'trust',
+            debug: options.debug,
+            resumeSessionId: (typeof options.resume === 'string' && options.resume !== 'picker')
+                ? options.resume
+                : continueResolvedId,
+            ...(options.maxSpend != null
+                ? { maxSpendUsd: Number(options.maxSpend) }
+                : {}),
+        };
+        const exitCode = await runOneShot(agentConfig, options.prompt);
+        flushStats();
+        process.exitCode = exitCode;
+        return;
+    }
     // Warn when a paid model is active so users know they'll be charged
     const FREE_MODELS = new Set([
         'nvidia/nemotron-ultra-253b',
@@ -114,7 +157,6 @@ export async function startCommand(options) {
         catch { /* migration is optional */ }
     }
     printBanner(version);
-    const workDir = process.cwd();
     // Auto-start panel in background unless explicitly disabled.
     // Binds loopback-only (wallet secrets on /api/wallet/secret — never expose on LAN).
     let panelUrl;
@@ -240,9 +282,13 @@ export async function startCommand(options) {
         workingDir: workDir,
         // Non-TTY (piped) input = scripted mode → trust all tools automatically.
         // Interactive TTY = default mode (prompts for Bash/Write/Edit).
-        permissionMode: (options.trust || !process.stdin.isTTY) ? 'trust' : 'default',
+        // --prompt is also scripted; the cron driver never sees a TTY.
+        permissionMode: (options.trust || options.prompt || !process.stdin.isTTY) ? 'trust' : 'default',
         debug: options.debug,
         resumeSessionId,
+        ...(options.maxSpend != null
+            ? { maxSpendUsd: Number(options.maxSpend) }
+            : {}),
     };
     // Bootstrap learnings from existing CLAUDE.md on first run (async, non-blocking)
     Promise.all([
@@ -262,6 +308,30 @@ export async function startCommand(options) {
         await runWithBasicUI(agentConfig, model, workDir);
     }
 }
+// ─── One-shot mode (franklin --prompt "...") ──────────────────────────────
+// Used by cron drivers. Non-interactive, prints text deltas to stdout as
+// they stream, honors --max-spend, exits 0 on completion / 1 on error.
+async function runOneShot(agentConfig, prompt) {
+    let delivered = false;
+    let exitCode = 0;
+    const getInput = async () => {
+        if (delivered)
+            return null;
+        delivered = true;
+        return prompt;
+    };
+    await interactiveSession(agentConfig, getInput, (event) => {
+        if (event.kind === 'text_delta') {
+            process.stdout.write(event.text);
+        }
+        else if (event.kind === 'turn_done') {
+            if (event.reason === 'error')
+                exitCode = 1;
+            process.stdout.write('\n');
+        }
+    });
+    return exitCode;
+}
 // ─── Ink UI (interactive terminal) ─────────────────────────────────────────
 async function runWithInkUI(agentConfig, model, workDir, version, walletInfo, onBalanceReady, fetchBalance) {
     const startSnapshot = snapshotStats();

package/dist/index.js

@@ -43,6 +43,8 @@ program
     .option('--trust', 'Trust mode — skip permission prompts for all tools')
     .option('-r, --resume [sessionId]', 'Resume a session by ID (or show picker if omitted)')
     .option('-c, --continue', 'Continue the most recent session in this directory')
+    .option('--max-spend <usd>', 'Hard USD cap on total session API spend — session stops when exceeded')
+    .option('-p, --prompt <text>', 'Run a single prompt non-interactively (for cron/scripted use)')
     .action((options) => startCommand({ ...options, version }));
 program
     .command('resume [sessionId]')
@@ -166,6 +168,14 @@ program
         });
     }
 }
+program
+    .command('doctor')
+    .description('One-command health check (node, wallet, chain, gateway, MCP, telemetry)')
+    .option('--json', 'Machine-readable output')
+    .action(async (opts) => {
+    const { doctorCommand } = await import('./commands/doctor.js');
+    await doctorCommand(opts);
+});
 program
     .command('telemetry [action]')
     .description('Manage opt-in local telemetry (status|enable|disable|view|summary)')
@@ -201,7 +211,7 @@ const args = process.argv.slice(2);
 const firstArg = args[0];
 const HELP_FLAGS = new Set(['-h', '--help']);
 const VERSION_FLAGS = new Set(['-V', '--version']);
-const START_ONLY_FLAGS = new Set(['--trust', '--debug', '-m', '--model', '-r', '--resume', '-c', '--continue']);
+const START_ONLY_FLAGS = new Set(['--trust', '--debug', '-m', '--model', '-r', '--resume', '-c', '--continue', '-p', '--prompt', '--max-spend']);
 function hasAnyFlag(argv, flags) {
     return argv.some(arg => flags.has(arg));
 }
@@ -219,6 +229,12 @@ function parseStartFlags(argv, startIdx = 0) {
         else if ((arg === '-m' || arg === '--model') && argv[i + 1]) {
             opts.model = argv[++i];
         }
+        else if ((arg === '-p' || arg === '--prompt') && argv[i + 1]) {
+            opts.prompt = argv[++i];
+        }
+        else if (arg === '--max-spend' && argv[i + 1]) {
+            opts.maxSpend = argv[++i];
+        }
         else if (arg === '-c' || arg === '--continue') {
             opts.continue = true;
         }