@blockrun/franklin 3.26.1 → 3.27.0

package/dist/channel/telegram.js

@@ -15,11 +15,31 @@
  * Works behind NAT and through laptop sleep/wake without needing a public
  * HTTPS endpoint. `node fetch` is the only HTTP dep.
  */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
 import { setupAgentWallet, setupAgentSolanaWallet } from '@blockrun/llm';
 import { interactiveSession } from '../agent/loop.js';
 import { ModelClient } from '../agent/llm.js';
 import { extractBrainEntities } from '../brain/extract.js';
 import { extractLearnings } from '../learnings/extractor.js';
+// Per-bot prefs (persisted so a restart keeps the user's choice).
+const PREFS_FILE = path.join(os.homedir(), '.blockrun', 'telegram-prefs.json');
+function loadPrefs() {
+    try {
+        return JSON.parse(fs.readFileSync(PREFS_FILE, 'utf-8'));
+    }
+    catch {
+        return {};
+    }
+}
+function savePrefs(prefs) {
+    try {
+        fs.mkdirSync(path.dirname(PREFS_FILE), { recursive: true });
+        fs.writeFileSync(PREFS_FILE, JSON.stringify(prefs, null, 2), { mode: 0o600 });
+    }
+    catch { /* best-effort */ }
+}
 const TG_API = 'https://api.telegram.org';
 const POLL_TIMEOUT_SECONDS = 25;
 // Telegram caps messages at 4096 chars; keep a margin so our chunk headers
@@ -93,6 +113,10 @@ export async function runTelegramBot(agentConfig, opts) {
         running: true,
         restartRequested: false,
         stoppedBy: undefined,
+        // Tool names used in the current turn → one summary at turn end (not one
+        // message per call). `showTools` gates whether that summary is sent.
+        toolsUsed: [],
+        showTools: loadPrefs().showTools ?? true,
     };
     // ── Telegram HTTP helpers ────────────────────────────────────────────
     const api = async (method, body) => {
@@ -135,11 +159,20 @@ export async function runTelegramBot(agentConfig, opts) {
     // ── Slash commands (handled by the bot, not the agent) ──────────────
     const handleSlashCommand = async (chatId, text) => {
         const cmd = text.trim().toLowerCase();
+        // `/tools` toggles the per-turn tool summary (takes on/off, or bare = flip).
+        if (cmd === '/tools' || cmd.startsWith('/tools ')) {
+            const arg = cmd.slice('/tools'.length).trim();
+            state.showTools = arg === 'on' ? true : arg === 'off' ? false : !state.showTools;
+            savePrefs({ showTools: state.showTools });
+            await sendMessage(chatId, `🔧 Tool summary: ${state.showTools ? 'on ✅' : 'off'}`);
+            return true;
+        }
         switch (cmd) {
             case '/start':
             case '/help':
                 await sendMessage(chatId, 'Franklin bot\n\n' +
                     '/new — start a fresh conversation (clears history)\n' +
+                    '/tools [on|off] — toggle the per-turn tool-usage summary\n' +
                     '/balance — show wallet USDC balance\n' +
                     '/status — show chain, model, and session stats\n' +
                     '/help — this message\n\n' +
@@ -149,6 +182,9 @@ export async function runTelegramBot(agentConfig, opts) {
                 state.restartRequested = true;
                 // Drain any pending input and wake the session so it unwinds.
                 state.inputQueue.length = 0;
+                // Drop tools recorded by a turn this reset interrupts, so they don't
+                // leak into the new conversation's first summary.
+                state.toolsUsed = [];
                 {
                     const waiters = state.inputWaiters.splice(0);
                     for (const w of waiters)
@@ -226,16 +262,16 @@ export async function runTelegramBot(agentConfig, opts) {
                 }
                 break;
             case 'capability_start':
-                // Best-effort signal that the agent is working. Flush any buffered
-                // text first so the user sees the narrative order correctly.
-                if (state.currentChatId !== undefined) {
-                    if (state.responseBuffer.trim()) {
-                        const chatId = state.currentChatId;
-                        const text = state.responseBuffer.trim();
-                        state.responseBuffer = '';
-                        void sendMessage(chatId, text);
-                    }
-                    void sendMessage(state.currentChatId, `⏳ ${event.name}…`);
+                // Record the tool (for the turn-end summary) and flush buffered text so
+                // narrative order reads right. No per-tool message — a multi-tool run
+                // otherwise floods the chat.
+                if (event.name)
+                    state.toolsUsed.push(event.name);
+                if (state.currentChatId !== undefined && state.responseBuffer.trim()) {
+                    const chatId = state.currentChatId;
+                    const text = state.responseBuffer.trim();
+                    state.responseBuffer = '';
+                    void sendMessage(chatId, text);
                 }
                 break;
             case 'turn_done': {
@@ -244,6 +280,12 @@ export async function runTelegramBot(agentConfig, opts) {
                 state.responseBuffer = '';
                 if (chatId !== undefined && text)
                     void sendChunked(chatId, text);
+                // One tool summary per turn (toggle with /tools).
+                if (chatId !== undefined && state.showTools && state.toolsUsed.length) {
+                    const uniq = [...new Set(state.toolsUsed)];
+                    void sendMessage(chatId, `🔧 Used ${state.toolsUsed.length} tool${state.toolsUsed.length === 1 ? '' : 's'}: ${uniq.join(' · ')}`);
+                }
+                state.toolsUsed = [];
                 if (event.reason === 'error' && event.error && chatId !== undefined) {
                     void sendMessage(chatId, `❌ Error: ${event.error}`);
                 }
@@ -252,10 +294,18 @@ export async function runTelegramBot(agentConfig, opts) {
         }
     };
     // ── Long-poll loop (runs concurrently with interactiveSession) ──────
+    // Captured from getMe so the group @mention gate knows the bot's handle/id.
+    let botUsername;
+    let botId;
     const pollLoop = async () => {
         try {
             const me = await api('getMe', {});
-            log(`[telegram] connected as @${me.username ?? '(unknown)'} — owner=${opts.ownerId}`);
+            botUsername = me.username;
+            botId = me.id;
+            log(`[telegram] connected as @${me.username ?? '(unknown)'} — owner=${opts.ownerId}` +
+                (opts.allowedUsers && opts.allowedUsers.size
+                    ? ` + ${opts.allowedUsers.size} allowed user(s)`
+                    : ''));
         }
         catch (err) {
             state.stoppedBy = err;
@@ -283,23 +333,42 @@ export async function runTelegramBot(agentConfig, opts) {
                 const msg = u.message;
                 if (!msg?.text || !msg.from)
                     continue;
-                if (msg.from.id !== opts.ownerId) {
+                // In groups, only act when the bot is addressed: @mentioned (incl. the
+                // `/cmd@bot` form) or replied to. Everything else — plain chatter AND
+                // bare slash commands — is ignored SILENTLY. Private chats need no mention.
+                const isGroup = !!msg.chat.type && msg.chat.type !== 'private';
+                let text = msg.text;
+                if (isGroup) {
+                    const tag = botUsername ? `@${botUsername}` : '';
+                    const mentioned = !!tag && text.toLowerCase().includes(tag.toLowerCase());
+                    const repliedToBot = !!botId && msg.reply_to_message?.from?.id === botId;
+                    if (!mentioned && !repliedToBot)
+                        continue;
+                    // Strip the @mention so the agent gets a clean prompt.
+                    if (mentioned && tag) {
+                        text = text.replace(new RegExp(tag.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'ig'), '').trim();
+                    }
+                }
+                if (!text)
+                    continue; // mention with no actual content
+                const isAuthorized = msg.from.id === opts.ownerId || !!opts.allowedUsers?.has(msg.from.id);
+                if (!isAuthorized) {
                     void sendMessage(msg.chat.id, 'Not authorized.');
                     log(`[telegram] rejected unauthorized sender id=${msg.from.id} ` +
                         `username=@${msg.from.username ?? 'n/a'}`);
                     continue;
                 }
-                log(`[telegram] ← ${msg.text.slice(0, 80)}${msg.text.length > 80 ? '…' : ''}`);
+                log(`[telegram] ← ${text.slice(0, 80)}${text.length > 80 ? '…' : ''}`);
                 // Intercept bot slash commands before handing off to the agent.
-                if (msg.text.trim().startsWith('/')) {
+                if (text.trim().startsWith('/')) {
                     state.currentChatId = msg.chat.id;
-                    const handled = await handleSlashCommand(msg.chat.id, msg.text);
+                    const handled = await handleSlashCommand(msg.chat.id, text);
                     if (handled)
                         continue;
                     // Unknown slash command: fall through to agent (which has its own
                     // slash handling for /retry, /model, /cost, …).
                 }
-                enqueueInput(msg.chat.id, msg.text);
+                enqueueInput(msg.chat.id, text);
             }
         }
     };

package/dist/commands/config.d.ts

@@ -1,3 +1,5 @@
+declare const VALID_KEYS: readonly ["default-model", "sonnet-model", "opus-model", "haiku-model", "smart-routing", "permission-mode", "max-turns", "auto-compact", "cost-saver", "session-save", "debug", "zerox-api-key", "base-rpc-url"];
+type ConfigKey = (typeof VALID_KEYS)[number];
 export interface AppConfig {
     'default-model'?: string;
     'sonnet-model'?: string;
@@ -7,6 +9,8 @@ export interface AppConfig {
     'permission-mode'?: string;
     'max-turns'?: string;
     'auto-compact'?: string;
+    /** Research-bloat compaction toggle for the desktop ("false" disables). */
+    'cost-saver'?: string;
     'session-save'?: string;
     'debug'?: string;
     /** 0x V2 Swap API key for Base swaps. Free at https://dashboard.0x.org. Each user supplies their own; the on-chain affiliate fee routes to BlockRun regardless. */
@@ -15,4 +19,7 @@ export interface AppConfig {
     'base-rpc-url'?: string;
 }
 export declare function loadConfig(): AppConfig;
+/** Persist a single config key (used by the desktop server for live toggles). */
+export declare function setConfigValue(key: ConfigKey, value: string): void;
 export declare function configCommand(action: string, keyOrUndefined?: string, value?: string): void;
+export {};

package/dist/commands/config.js

@@ -13,6 +13,7 @@ const VALID_KEYS = [
     'permission-mode',
     'max-turns',
     'auto-compact',
+    'cost-saver',
     'session-save',
     'debug',
     'zerox-api-key',
@@ -48,6 +49,12 @@ function saveConfig(config) {
 function isValidKey(key) {
     return VALID_KEYS.includes(key);
 }
+/** Persist a single config key (used by the desktop server for live toggles). */
+export function setConfigValue(key, value) {
+    const config = loadConfig();
+    config[key] = value;
+    saveConfig(config);
+}
 export function configCommand(action, keyOrUndefined, value) {
     if (action === 'list') {
         const config = loadConfig();

package/dist/commands/serve.d.ts

@@ -0,0 +1,7 @@
+interface ServeOptions {
+    port?: string;
+    workDir?: string;
+    debug?: boolean;
+}
+export declare function serveCommand(options: ServeOptions): Promise<void>;
+export {};

package/dist/commands/serve.js

@@ -0,0 +1,7 @@
+import path from 'node:path';
+import { startServer } from '../serve/server.js';
+export async function serveCommand(options) {
+    const port = Number(options.port) || 3737;
+    const workDir = options.workDir ? path.resolve(options.workDir) : process.cwd();
+    await startServer({ port, workDir, debug: !!options.debug });
+}

package/dist/commands/slack.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `franklin slack` — start the Slack ingress bot.
+ *
+ * Designed to run on a server / always-on laptop. Reads the bot token, app
+ * token, and the user allowlist from env (or ~/.blockrun/config). Uses
+ * trust-mode permissions because the operator is remote — there's no terminal
+ * prompt they can answer per tool call. The `SLACK_ALLOWED_USERS` allowlist in
+ * `runSlackBot` is the real security boundary, mirroring Telegram's owner lock.
+ */
+interface SlackCommandOptions {
+    model?: string;
+    debug?: boolean;
+}
+export declare function slackCommand(opts: SlackCommandOptions): Promise<void>;
+export {};

package/dist/commands/slack.js

@@ -0,0 +1,118 @@
+/**
+ * `franklin slack` — start the Slack ingress bot.
+ *
+ * Designed to run on a server / always-on laptop. Reads the bot token, app
+ * token, and the user allowlist from env (or ~/.blockrun/config). Uses
+ * trust-mode permissions because the operator is remote — there's no terminal
+ * prompt they can answer per tool call. The `SLACK_ALLOWED_USERS` allowlist in
+ * `runSlackBot` is the real security boundary, mirroring Telegram's owner lock.
+ */
+import chalk from 'chalk';
+import { loadChain, API_URLS } from '../config.js';
+import { assembleInstructions } from '../agent/context.js';
+import { allCapabilities } from '../tools/index.js';
+import { loadMcpConfig } from '../mcp/config.js';
+import { connectMcpServers, disconnectMcpServers } from '../mcp/client.js';
+import { loadConfig } from './config.js';
+import { runSlackBot } from '../channel/slack.js';
+import { findLatestSessionByChannel } from '../session/storage.js';
+export async function slackCommand(opts) {
+    const botToken = process.env.SLACK_BOT_TOKEN;
+    const appToken = process.env.SLACK_APP_TOKEN;
+    const allowedRaw = process.env.SLACK_ALLOWED_USERS;
+    if (!botToken || !appToken || !allowedRaw) {
+        console.error(chalk.red('Missing Slack config.'));
+        console.error(chalk.dim('\nSet three env vars before running `franklin slack`:\n' +
+            '  SLACK_BOT_TOKEN=<xoxb-… Bot User OAuth token>\n' +
+            '  SLACK_APP_TOKEN=<xapp-… app-level token with connections:write>\n' +
+            '  SLACK_ALLOWED_USERS=<comma-separated Slack user ids, e.g. U01ABC,U02DEF>\n\n' +
+            'Socket Mode must be enabled on the app, and the bot must be invited to\n' +
+            'the channel (/invite @your-bot). Find a user id via their profile →\n' +
+            '⋮ → Copy member ID.'));
+        process.exit(1);
+    }
+    const allowedUsers = new Set(allowedRaw.split(',').map((s) => s.trim()).filter(Boolean));
+    if (allowedUsers.size === 0) {
+        console.error(chalk.red('SLACK_ALLOWED_USERS is empty — that would deny everyone.'));
+        process.exit(1);
+    }
+    const chain = loadChain();
+    const apiUrl = API_URLS[chain];
+    const config = loadConfig();
+    const model = opts.model ||
+        config['default-model'] ||
+        'nvidia/qwen3-coder-480b';
+    const workingDir = process.cwd();
+    const systemInstructions = assembleInstructions(workingDir, model);
+    // Connect MCP servers (Notion, etc.) so the bot exposes their tools — mirrors
+    // what `franklin start` does. Without this the bot only has built-in tools.
+    const mcpConfig = loadMcpConfig(workingDir);
+    let mcpTools = [];
+    const mcpServerCount = Object.keys(mcpConfig.mcpServers).filter((k) => !mcpConfig.mcpServers[k].disabled).length;
+    if (mcpServerCount > 0) {
+        try {
+            mcpTools = await connectMcpServers(mcpConfig, opts.debug);
+            if (mcpTools.length > 0) {
+                console.log(chalk.dim(`  MCP:    ${mcpTools.length} tools from ${mcpServerCount} server(s)`));
+            }
+        }
+        catch (err) {
+            console.error(chalk.yellow(`  MCP error: ${err.message}`));
+        }
+    }
+    // Resume the most recent session tagged for THIS workspace bot so a process
+    // restart doesn't drop the conversation. MVP v1 keeps one shared session per
+    // bot (see channel/slack.ts), so the channel tag is workspace-scoped.
+    const channelTag = 'slack:shared';
+    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, ...mcpTools],
+        workingDir,
+        // No interactive terminal for permission prompts — remote operator can't
+        // answer y/n per tool. The Slack allowlist is the security boundary.
+        permissionMode: 'trust',
+        debug: opts.debug,
+        sessionChannel: channelTag,
+        resumeSessionId: prior?.id,
+    };
+    console.log(chalk.bold.cyan('Franklin Slack bot'));
+    console.log(chalk.dim(`  chain: ${chain}`));
+    console.log(chalk.dim(`  model: ${model}`));
+    console.log(chalk.dim(`  allowed users: ${allowedUsers.size}`));
+    console.log(chalk.yellow('  permission mode: trust — every tool the model picks will execute ' +
+        'without confirmation. The allowlist is your only gate.\n'));
+    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 runSlackBot(agentConfig, {
+            botToken,
+            appToken,
+            allowedUsers,
+            debug: opts.debug,
+            log: (line) => console.log(chalk.dim(line)),
+        });
+    }
+    catch (err) {
+        console.error(chalk.red(`Slack bot failed: ${err.message}`));
+        process.exit(1);
+    }
+    finally {
+        disconnectMcpServers().catch(() => { });
+    }
+}

package/dist/commands/telegram.js

@@ -30,6 +30,14 @@ export async function telegramCommand(opts) {
         console.error(chalk.red(`TELEGRAM_OWNER_ID must be a positive integer, got: ${ownerRaw}`));
         process.exit(1);
     }
+    // Optional allowlist: extra numeric user ids that may drive the bot (e.g. other
+    // people in a group). Comma-separated. Owner is always allowed.
+    const allowedUsers = new Set([ownerId]);
+    for (const raw of (process.env.TELEGRAM_ALLOWED_USERS ?? '').split(',')) {
+        const id = parseInt(raw.trim(), 10);
+        if (Number.isFinite(id) && id > 0)
+            allowedUsers.add(id);
+    }
     const chain = loadChain();
     const apiUrl = API_URLS[chain];
     const config = loadConfig();
@@ -85,6 +93,7 @@ export async function telegramCommand(opts) {
         await runTelegramBot(agentConfig, {
             token,
             ownerId,
+            allowedUsers,
             log: (line) => console.log(chalk.dim(line)),
         });
     }

package/dist/index.js

@@ -20,6 +20,7 @@ import { configCommand } from './commands/config.js';
 import { statsCommand } from './commands/stats.js';
 import { logsCommand } from './commands/logs.js';
 import { daemonCommand } from './commands/daemon.js';
+import { slackCommand } from './commands/slack.js';
 import { initCommand } from './commands/init.js';
 import { uninitCommand } from './commands/uninit.js';
 import { proxyCommand } from './commands/proxy.js';
@@ -79,6 +80,12 @@ program
     .description('Manage franklin background proxy (start|stop|status)')
     .option('-p, --port <port>', 'Proxy port', '8402')
     .action((action, options) => daemonCommand(action, options));
+program
+    .command('slack')
+    .description('Run the Slack ingress bot (Socket Mode)')
+    .option('--model <model>', 'Model to use')
+    .option('--debug', 'Verbose Slack/Bolt logging')
+    .action((options) => slackCommand(options));
 program
     .command('panel')
     .description('Open the Franklin dashboard (localhost:3100)')
@@ -87,6 +94,16 @@ program
     const { panelCommand } = await import('./commands/panel.js');
     await panelCommand(options);
 });
+program
+    .command('serve')
+    .description('Run the local agent server for the desktop app / browser UI (WebSocket on localhost:3737)')
+    .option('-p, --port <port>', 'Agent server port', '3737')
+    .option('--work-dir <dir>', 'Working directory for tools (default: cwd)')
+    .option('--debug', 'Verbose logging')
+    .action(async (options) => {
+    const { serveCommand } = await import('./commands/serve.js');
+    await serveCommand(options);
+});
 program
     .command('models')
     .description('List available models and pricing')
@@ -325,5 +342,10 @@ else if (!firstArg || firstArg.startsWith('-')) {
     process.exit(process.exitCode ?? 0);
 }
 else {
-    program.parse();
+    // Force node-style argv slicing. When the CLI is embedded and run via
+    // Electron-as-node (ELECTRON_RUN_AS_NODE=1, e.g. the desktop app spawning
+    // `franklin serve`), commander otherwise detects `process.versions.electron`
+    // + no defaultApp and slices argv as a packaged-electron app — treating the
+    // script path as the command. `from: 'node'` keeps [exec, script, ...args].
+    program.parse(process.argv, { from: 'node' });
 }

package/dist/serve/cloud-sync.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Cloud sync for desktop chat history — the local agent acts as the bridge.
+ *
+ * Identity is the local Base wallet (~/.blockrun). We run the SAME SIWE flow a
+ * browser does against franklin.run (/api/try/auth/nonce → sign → verify), hold
+ * the session, and proxy conversation load/save/delete to the existing
+ * /api/try/conversations API (GCS-backed, per-wallet). So the desktop and the
+ * web share one history keyed by wallet — and the web server needs no changes.
+ *
+ * Everything is best-effort: callers fall back to the local file on any failure
+ * (offline, not-deployed, auth hiccup), so cloud sync never breaks local use.
+ */
+export interface CloudConversation {
+    id: string;
+    title: string;
+    createdAt: number;
+    updatedAt: number;
+    messages: unknown[];
+}
+export declare function isCloudSyncEnabled(): boolean;
+export declare function cloudList(): Promise<CloudConversation[]>;
+/** Reconcile cloud to match the given local list: upsert changed, delete removed. */
+export declare function cloudSync(conversations: CloudConversation[]): Promise<void>;

package/dist/serve/cloud-sync.js

@@ -0,0 +1,120 @@
+/**
+ * Cloud sync for desktop chat history — the local agent acts as the bridge.
+ *
+ * Identity is the local Base wallet (~/.blockrun). We run the SAME SIWE flow a
+ * browser does against franklin.run (/api/try/auth/nonce → sign → verify), hold
+ * the session, and proxy conversation load/save/delete to the existing
+ * /api/try/conversations API (GCS-backed, per-wallet). So the desktop and the
+ * web share one history keyed by wallet — and the web server needs no changes.
+ *
+ * Everything is best-effort: callers fall back to the local file on any failure
+ * (offline, not-deployed, auth hiccup), so cloud sync never breaks local use.
+ */
+import { getOrCreateWallet } from '@blockrun/llm';
+import { privateKeyToAccount } from 'viem/accounts';
+const CLOUD_BASE = process.env.FRANKLIN_CLOUD_URL || 'https://franklin.run';
+const NONCE_COOKIE = 'franklin_try_nonce';
+const SESSION_COOKIE = 'franklin_try_session';
+const TIMEOUT = 8000;
+export function isCloudSyncEnabled() {
+    return process.env.FRANKLIN_CLOUD_SYNC !== 'off';
+}
+let sessionCookie = null;
+// Track what we've pushed so save only sends changed/removed conversations.
+let lastSynced = new Map();
+function getSetCookie(res, name) {
+    const list = res.headers.getSetCookie?.() ?? [];
+    for (const c of list)
+        if (c.startsWith(name + '='))
+            return c.split(';')[0];
+    return null;
+}
+async function login() {
+    const nonceRes = await fetch(`${CLOUD_BASE}/api/try/auth/nonce`, { signal: AbortSignal.timeout(TIMEOUT) });
+    if (!nonceRes.ok)
+        throw new Error(`nonce ${nonceRes.status}`);
+    const nonceCookie = getSetCookie(nonceRes, NONCE_COOKIE);
+    const { nonce } = (await nonceRes.json());
+    if (!nonce || !nonceCookie)
+        throw new Error('no nonce');
+    const { privateKey, address } = getOrCreateWallet();
+    const account = privateKeyToAccount(privateKey);
+    const message = `Sign in to Franklin Desktop\n\nNonce: ${nonce}`;
+    const signature = await account.signMessage({ message });
+    const verifyRes = await fetch(`${CLOUD_BASE}/api/try/auth/verify`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Cookie: nonceCookie },
+        body: JSON.stringify({ address, message, signature }),
+        signal: AbortSignal.timeout(TIMEOUT),
+    });
+    if (!verifyRes.ok)
+        throw new Error(`verify ${verifyRes.status}`);
+    const session = getSetCookie(verifyRes, SESSION_COOKIE);
+    if (!session)
+        throw new Error('no session cookie');
+    sessionCookie = session;
+}
+async function authed(path, init = {}) {
+    if (!sessionCookie)
+        await login();
+    const doFetch = () => fetch(`${CLOUD_BASE}${path}`, {
+        ...init,
+        headers: { ...(init.headers || {}), Cookie: sessionCookie },
+        signal: AbortSignal.timeout(TIMEOUT),
+    });
+    let res = await doFetch();
+    if (res.status === 401) {
+        sessionCookie = null;
+        await login();
+        res = await doFetch();
+    }
+    return res;
+}
+export async function cloudList() {
+    const res = await authed('/api/try/conversations');
+    if (!res.ok)
+        throw new Error(`list ${res.status}`);
+    const j = (await res.json());
+    const convos = Array.isArray(j.conversations) ? j.conversations : [];
+    lastSynced = new Map(convos.map((c) => [c.id, c.updatedAt]));
+    return convos;
+}
+async function cloudPut(c) {
+    const res = await authed(`/api/try/conversations/${encodeURIComponent(c.id)}`, {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(c),
+    });
+    if (!res.ok)
+        throw new Error(`put ${res.status}`);
+}
+async function cloudDelete(id) {
+    try {
+        await authed(`/api/try/conversations/${encodeURIComponent(id)}`, { method: 'DELETE' });
+    }
+    catch { /* ignore */ }
+}
+// Sync passes are serialized: cloudSync is called fire-and-forget from both
+// history.load (migration) and history.save, and a pass reads + rewrites the
+// module-level `lastSynced` map across awaited network calls. Two interleaved
+// passes corrupt that shared state — worst case the delete sweep walks a stale
+// snapshot and removes a conversation a concurrent pass just uploaded.
+let syncQueue = Promise.resolve();
+/** Reconcile cloud to match the given local list: upsert changed, delete removed. */
+export function cloudSync(conversations) {
+    const run = syncQueue.then(() => doCloudSync(conversations));
+    syncQueue = run.catch(() => { }); // keep the chain alive after a failed pass
+    return run;
+}
+async function doCloudSync(conversations) {
+    const current = new Map(conversations.map((c) => [c.id, c.updatedAt]));
+    for (const c of conversations) {
+        if (lastSynced.get(c.id) !== c.updatedAt)
+            await cloudPut(c);
+    }
+    for (const id of [...lastSynced.keys()]) {
+        if (!current.has(id))
+            await cloudDelete(id);
+    }
+    lastSynced = current;
+}

package/dist/serve/server.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Franklin agent server (local WebSocket — drives the desktop app & browser UI).
+ *
+ * Serves the local React WebUI (franklin-webui / the desktop app) over a single
+ * WebSocket using the envelope wire protocol the UI already speaks:
+ *
+ *   client → { id, kind, payload }      (agent.send / session.* / wallet.info / …)
+ *   server → { id, kind, payload }      (agent.text / agent.step / agent.done / …)
+ *
+ * Unlike `franklin panel` (a read-only dashboard), this actually runs agent
+ * turns: it drives the real `interactiveSession` loop from src/agent/loop.ts —
+ * same tools, wallet, routing and signing as the CLI. The browser/desktop is
+ * just a different head on the same agent.
+ *
+ * Single-window assumption: one long-lived agent session per server process,
+ * fed by a getUserInput queue. Good enough for the desktop app; multi-session
+ * fan-out can come later.
+ */
+interface ServerOptions {
+    port: number;
+    workDir: string;
+    debug?: boolean;
+}
+export declare function startServer(opts: ServerOptions): Promise<void>;
+export {};