feat(serve): Franklin desktop agent server + backend (cloud sync, wallet holdings/swaps, cost-saver)

[KillerQueen-Z]

The Franklin-agent side of the Franklin Desktop app.

What

• franklin serve — local WebSocket agent server (localhost:3737) the desktop renderer connects to (renamed from franklin webui).
• serve/server.ts: model grouping by provider, cost-saver settings, wallet spend / token holdings / swap RPCs, cloud-first history.load/save, per-conversation session isolation, per-tool detail.
• serve/cloud-sync.ts: SIWE cloud sync — wallet as identity → franklin.run conversations API.
• stats/swap-log.ts: record swaps to ~/.blockrun/swaps.jsonl; zerox tools append on success.
• agent (llm/loop/streaming-executor/types): bloat-compaction + cost-saver gate, model fallback guards, per-tool input preview.
• Also rolls in: restore GPT-5/Grok families + real errors (fix(agent): restore GPT-5 / Grok families and surface real errors #79), image-paste fix (fix(ui): improve image paste fallback and display #78), v3.25.3.

Notes

• This is what the desktop app (BlockRunAI/franklin-desktop) bundles + connects to.

[VickyXAI]

Code review

Found 5 issues:

1. The WebSocket server accepts any connection — no origin check, no verifyClient, no auth token. Loopback binding does not protect against browsers: any web page the user visits can open ws://127.0.0.1:3737/agent and issue agent.send (which runs with permissionMode: 'trust' and can spend USDC), settings.set, wallet.tokens, and wallet.spend. This is a drive-by attack surface on a wallet-bearing agent. An Origin-header check (allow null/Electron and the known desktop origin only) or a handshake token passed by the desktop app would close it.

Franklin/src/serve/server.ts

Lines 630 to 632 in b8e5074

	});
	const wss = new WebSocket.Server({ server: httpServer, path: '/agent' });

2. The /file route streams any file on disk from an unsanitized path query param, and explicitly sets Access-Control-Allow-Origin: * — so a malicious web page can fetch('http://127.0.0.1:3737/file?path=~/.ssh/id_rsa') (or wallet key files under ~/.blockrun) and read the response cross-origin. The "loopback-only server, so a path param is fine" assumption does not hold for browser-initiated requests. Confine paths to the session work dir (resolve + prefix check) and drop the wildcard CORS header.

Franklin/src/serve/server.ts

Lines 613 to 625 in b8e5074

	const url = new URL(req.url || '/', 'http://127.0.0.1');
	if (url.pathname === '/file') {
	const p = url.searchParams.get('path') || '';
	if (!p || !fs.existsSync(p) || !fs.statSync(p).isFile()) { res.writeHead(404); res.end(); return; }
	const ext = p.toLowerCase().split('.').pop() || '';
	const mime =
	ext === 'mp3' ? 'audio/mpeg' : ext === 'wav' ? 'audio/wav' : ext === 'm4a' ? 'audio/mp4' :
	ext === 'ogg' ? 'audio/ogg' : ext === 'flac' ? 'audio/flac' :
	ext === 'mp4' ? 'video/mp4' : ext === 'webm' ? 'video/webm' :
	/^(png|jpe?g|webp|gif)$/.test(ext) ? `image/${ext === 'jpg' ? 'jpeg' : ext}` : 'application/octet-stream';
	res.writeHead(200, { 'Content-Type': mime, 'Access-Control-Allow-Origin': '*' });
	fs.createReadStream(p).pipe(res);
	return;

3. Race condition in cloudSync: it reads and rewrites the module-global lastSynced map across awaited network calls, and it is invoked fire-and-forget (void cloudSync(...)) from both history.load (migration path, server.ts L470) and history.save (L485). Two in-flight invocations interleave: the delete pass walks a stale lastSynced snapshot and can cloudDelete a conversation a concurrent call just uploaded, and the final lastSynced = current clobber means the loss is not self-healing. A simple promise-chain mutex (serialize calls) fixes it.

Franklin/src/serve/cloud-sync.ts

Lines 103 to 112 in b8e5074

	export async function cloudSync(conversations: CloudConversation[]): Promise<void> {
	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;
	}

4. The new projectCompactionSavings(history).worthIt gate wraps bloatTriggered as a whole, which includes the turnCostUsd > TURN_COST_CAP_FOR_EARLY_COMPACT ($1.00) emergency trigger added in 3.15.94 after a real $9.45 runaway session ("bloat compactor fires on $1 cost cap, not just 15-call gate"). If projected savings are under 20% when the $1 cap is crossed (plausible when recent un-compactable messages dominate), the emergency compact silently never fires and the runaway scenario returns. The ROI gate should apply only to the 15-call/$0.03 trigger, leaving the $1 cap unconditional.

Franklin/src/agent/loop.ts

Lines 1159 to 1169 in b8e5074

	// clear the floor (≥20%), which a small history can never do.
	const bloatTriggered =
	(turnToolCalls > 15 && turnCostUsd > 0.03) ||
	turnCostUsd > TURN_COST_CAP_FOR_EARLY_COMPACT;
	if (
	config.costSaver !== false &&
	!bloatCompactedThisTurn &&
	compactFailures < 3 &&
	bloatTriggered &&
	projectCompactionSavings(history).worthIt
	) {

5. zerox-base.ts records the swap immediately after sendRawTransaction returns (mempool submission, L527) — before on-chain confirmation — contradicting the swap-log.ts contract ("the swap tools ... append here on success") and the gasless tool in this same PR, which correctly gates appendSwap on final.status === 'confirmed' || 'succeeded'. A Permit2 swap that reverts on slippage will show up in the desktop wallet history as a successful swap.

Franklin/src/tools/zerox-base.ts

Lines 554 to 556 in b8e5074

	try {
	appendSwap({
	ts: Date.now(),

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[VickyXAI]

Requesting changes per the review above.

Blocking (must fix before merge):

1. WebSocket origin/auth check — the desktop app should pass a handshake token (or the server should verify the Origin header), otherwise any web page can drive a trust-mode agent with spend authority.
2. /file path confinement — restrict to the session work dir and drop Access-Control-Allow-Origin: *.

Both come from the same wrong assumption: loopback-only ≠ local-process-only. Browsers reach 127.0.0.1 freely.

Should also fix in this PR (small diffs):
3. Serialize cloudSync (promise-chain mutex) — wrong cloud deletes are data loss.
4. Keep the $1.00 emergency compact unconditional; apply the worthIt ROI gate only to the 15-call/$0.03 trigger.
5. Gate appendSwap in zerox-base.ts on receipt confirmation, matching the gasless tool.

[VickyXAI]

All five review findings addressed in 74db8bc: WS Origin allowlist + optional handshake token, /file confined to work-dir media with reflected CORS, cloudSync serialized, $1.00 emergency compact unconditional again, swap log gated on receipt confirmation. Slack/Telegram follow-ups (missing @slack/bolt dep, per-tool ping flood, English strings) fixed in the same commit. Verified live: evil-origin WS upgrade → 401, /file path escape → 403, legit media → 200.