npm - @blockrun/franklin - Versions diffs - 3.2.4 → 3.3.1 - Mend

@blockrun/franklin 3.2.4 → 3.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (61) hide show

package/README.md +216 -233
package/dist/agent/commands.js +54 -13
package/dist/agent/context.js +31 -1
package/dist/agent/loop.js +48 -19
package/dist/agent/permissions.js +3 -3
package/dist/commands/migrate.d.ts +13 -0
package/dist/commands/migrate.js +389 -0
package/dist/commands/panel.d.ts +6 -0
package/dist/commands/panel.js +29 -0
package/dist/commands/start.js +41 -2
package/dist/events/bridge.d.ts +1 -0
package/dist/events/bridge.js +24 -0
package/dist/events/bus.d.ts +17 -0
package/dist/events/bus.js +55 -0
package/dist/events/types.d.ts +49 -0
package/dist/events/types.js +8 -0
package/dist/index.js +15 -0
package/dist/learnings/extractor.d.ts +16 -0
package/dist/learnings/extractor.js +234 -0
package/dist/learnings/index.d.ts +3 -0
package/dist/learnings/index.js +2 -0
package/dist/learnings/store.d.ts +15 -0
package/dist/learnings/store.js +130 -0
package/dist/learnings/types.d.ts +24 -0
package/dist/learnings/types.js +7 -0
package/dist/mcp/client.js +9 -2
package/dist/narrative/state.d.ts +30 -0
package/dist/narrative/state.js +69 -0
package/dist/panel/html.d.ts +5 -0
package/dist/panel/html.js +341 -0
package/dist/panel/server.d.ts +7 -0
package/dist/panel/server.js +152 -0
package/dist/session/storage.js +4 -2
package/dist/social/browser-pool.d.ts +29 -0
package/dist/social/browser-pool.js +57 -0
package/dist/social/preflight.d.ts +14 -0
package/dist/social/preflight.js +26 -0
package/dist/social/x.d.ts +8 -0
package/dist/social/x.js +9 -1
package/dist/stats/tracker.d.ts +1 -0
package/dist/stats/tracker.js +59 -13
package/dist/tools/bash.js +6 -1
package/dist/tools/index.js +3 -0
package/dist/tools/posttox.d.ts +7 -0
package/dist/tools/posttox.js +137 -0
package/dist/tools/searchx.d.ts +7 -0
package/dist/tools/searchx.js +111 -0
package/dist/tools/trading.d.ts +3 -0
package/dist/tools/trading.js +168 -0
package/dist/tools/webfetch.js +19 -9
package/dist/tools/write.js +2 -0
package/dist/trading/config.d.ts +23 -0
package/dist/trading/config.js +45 -0
package/dist/trading/data.d.ts +30 -0
package/dist/trading/data.js +112 -0
package/dist/trading/metrics.d.ts +29 -0
package/dist/trading/metrics.js +105 -0
package/dist/ui/app.js +73 -44
package/dist/ui/markdown.d.ts +9 -0
package/dist/ui/markdown.js +86 -0
package/package.json +1 -1

package/dist/panel/html.js ADDED Viewed

@@ -0,0 +1,341 @@
+/**
+ * Franklin Panel — embedded HTML dashboard.
+ * Single page, dark theme, zero dependencies.
+ */
+export function getHTML() {
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Franklin Panel</title>
+<style>
+:root {
+  --bg: #0a0a0f;
+  --bg-card: #12121a;
+  --bg-hover: #1a1a2a;
+  --border: #2a2a3a;
+  --text: #e0e0e8;
+  --text-dim: #6a6a7a;
+  --accent: #10b981;
+  --gold: #ffd700;
+  --blue: #60a5fa;
+  --danger: #ef4444;
+  --mono: 'SF Mono','Fira Code','Cascadia Code','Menlo',monospace;
+  --sans: -apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;
+}
+* { margin:0; padding:0; box-sizing:border-box; }
+body { background:var(--bg); color:var(--text); font-family:var(--sans); font-size:14px; }
+a { color:var(--blue); text-decoration:none; }
+a:hover { text-decoration:underline; }
+header {
+  display:flex; align-items:center; justify-content:space-between;
+  padding:16px 24px; border-bottom:1px solid var(--border);
+}
+header h1 { font-size:18px; font-weight:600; }
+header h1 span { color:var(--gold); }
+.dot { width:8px; height:8px; border-radius:50%; display:inline-block; margin-left:8px; }
+.dot.on { background:var(--accent); animation:pulse 2s infinite; }
+.dot.off { background:var(--danger); }
+@keyframes pulse { 0%,100%{opacity:1} 50%{opacity:.5} }
+nav { display:flex; gap:0; border-bottom:1px solid var(--border); padding:0 24px; }
+nav button {
+  background:none; border:none; color:var(--text-dim); padding:12px 20px;
+  cursor:pointer; font-size:14px; border-bottom:2px solid transparent;
+  transition:all .15s;
+}
+nav button:hover { color:var(--text); }
+nav button.active { color:var(--accent); border-bottom-color:var(--accent); }
+main { padding:24px; max-width:1200px; margin:0 auto; }
+.grid { display:grid; grid-template-columns:repeat(auto-fit,minmax(280px,1fr)); gap:16px; }
+.card {
+  background:var(--bg-card); border:1px solid var(--border);
+  border-radius:8px; padding:16px 20px;
+}
+.card h3 { font-size:12px; color:var(--text-dim); text-transform:uppercase; letter-spacing:.5px; margin-bottom:12px; }
+.big { font-size:28px; font-weight:700; font-family:var(--mono); }
+.big.gold { color:var(--gold); }
+.big.green { color:var(--accent); }
+.sub { font-size:12px; color:var(--text-dim); margin-top:4px; }
+.bar-chart { display:flex; flex-direction:column; gap:6px; }
+.bar-row { display:flex; align-items:center; gap:8px; font-size:12px; }
+.bar-label { width:140px; overflow:hidden; text-overflow:ellipsis; white-space:nowrap; color:var(--text-dim); font-family:var(--mono); }
+.bar-fill { height:16px; border-radius:3px; background:var(--accent); min-width:2px; transition:width .3s; }
+.bar-val { font-family:var(--mono); color:var(--text-dim); font-size:11px; }
+.daily-chart { display:flex; align-items:flex-end; gap:2px; height:80px; }
+.daily-bar { flex:1; background:var(--accent); border-radius:2px 2px 0 0; min-height:2px; transition:height .3s; opacity:.7; }
+.daily-bar:hover { opacity:1; }
+.session-list { display:flex; flex-direction:column; gap:8px; }
+.session-item {
+  background:var(--bg-card); border:1px solid var(--border); border-radius:6px;
+  padding:12px 16px; cursor:pointer; transition:background .15s;
+}
+.session-item:hover { background:var(--bg-hover); }
+.session-item .meta { font-size:12px; color:var(--text-dim); font-family:var(--mono); }
+.session-detail { background:var(--bg-card); border:1px solid var(--border); border-radius:8px; padding:16px; margin-top:12px; }
+.msg { margin-bottom:12px; }
+.msg.user { color:var(--blue); }
+.msg.assistant { color:var(--text); }
+.msg pre { font-family:var(--mono); font-size:12px; white-space:pre-wrap; line-height:1.5; }
+.learning-item { padding:8px 0; border-bottom:1px solid var(--border); display:flex; gap:12px; align-items:center; }
+.learning-item:last-child { border:none; }
+.confidence { font-size:11px; font-family:var(--mono); padding:2px 6px; border-radius:3px; }
+.confidence.high { background:#10b98133; color:var(--accent); }
+.confidence.mid { background:#ffd70033; color:var(--gold); }
+.confidence.low { background:#6a6a7a33; color:var(--text-dim); }
+.search-box {
+  width:100%; padding:10px 16px; background:var(--bg-card); border:1px solid var(--border);
+  border-radius:6px; color:var(--text); font-size:14px; margin-bottom:16px; outline:none;
+}
+.search-box:focus { border-color:var(--accent); }
+.tab { display:none; }
+.tab.active { display:block; }
+.empty { color:var(--text-dim); text-align:center; padding:40px; }
+</style>
+</head>
+<body>
+<header>
+  <h1><span>◆</span> Franklin Panel</h1>
+  <div>
+    <span id="status" style="font-size:12px;color:var(--text-dim)">connecting</span>
+    <span class="dot off" id="dot"></span>
+  </div>
+</header>
+<nav>
+  <button class="active" data-tab="overview">Overview</button>
+  <button data-tab="sessions">Sessions</button>
+  <button data-tab="social">Social</button>
+  <button data-tab="learnings">Learnings</button>
+</nav>
+<main>
+  <!-- Overview -->
+  <div class="tab active" id="tab-overview">
+    <div class="grid">
+      <div class="card">
+        <h3>Wallet</h3>
+        <div class="big gold" id="balance">—</div>
+        <div class="sub" id="wallet-addr">Loading...</div>
+      </div>
+      <div class="card">
+        <h3>Total Spent</h3>
+        <div class="big green" id="total-cost">—</div>
+        <div class="sub" id="total-requests">— requests</div>
+      </div>
+      <div class="card">
+        <h3>Savings vs Opus</h3>
+        <div class="big green" id="savings">—</div>
+        <div class="sub">compared to Claude Opus pricing</div>
+      </div>
+    </div>
+    <div class="card" style="margin-top:16px">
+      <h3>Daily Cost (30 days)</h3>
+      <div class="daily-chart" id="daily-chart"></div>
+    </div>
+    <div class="card" style="margin-top:16px">
+      <h3>Model Usage</h3>
+      <div class="bar-chart" id="model-chart"></div>
+    </div>
+  </div>
+  <!-- Sessions -->
+  <div class="tab" id="tab-sessions">
+    <input class="search-box" id="session-search" placeholder="Search sessions..." />
+    <div class="session-list" id="session-list"></div>
+    <div class="session-detail" id="session-detail" style="display:none"></div>
+  </div>
+  <!-- Social -->
+  <div class="tab" id="tab-social">
+    <div class="grid" id="social-stats"></div>
+    <div class="card" style="margin-top:16px">
+      <h3>Recent Activity</h3>
+      <div id="social-feed" class="empty">No social activity yet</div>
+    </div>
+  </div>
+  <!-- Learnings -->
+  <div class="tab" id="tab-learnings">
+    <div id="learnings-list"></div>
+  </div>
+</main>
+<script>
+// Tab switching
+document.querySelectorAll('nav button').forEach(btn => {
+  btn.addEventListener('click', () => {
+    document.querySelectorAll('nav button').forEach(b => b.classList.remove('active'));
+    document.querySelectorAll('.tab').forEach(t => t.classList.remove('active'));
+    btn.classList.add('active');
+    document.getElementById('tab-' + btn.dataset.tab).classList.add('active');
+  });
+});
+// API helpers
+const api = (path) => fetch('/api/' + path).then(r => r.json()).catch(() => null);
+// Format currency
+const usd = (n) => '$' + (n || 0).toFixed(4);
+const usdBig = (n) => '$' + (n || 0).toFixed(2);
+// Load overview
+async function loadOverview() {
+  const [wallet, stats, insights] = await Promise.all([
+    api('wallet'), api('stats'), api('insights?days=30')
+  ]);
+  if (wallet) {
+    document.getElementById('balance').textContent = usdBig(wallet.balance) + ' USDC';
+    document.getElementById('wallet-addr').textContent = wallet.address + ' (' + wallet.chain + ')';
+  }
+  if (stats) {
+    document.getElementById('total-cost').textContent = usd(stats.totalCostUsd);
+    document.getElementById('total-requests').textContent = stats.totalRequests.toLocaleString() + ' requests';
+    if (stats.opusCost > 0) {
+      const pct = ((1 - stats.totalCostUsd / stats.opusCost) * 100).toFixed(0);
+      document.getElementById('savings').textContent = pct + '%';
+    }
+    // Model chart
+    const models = Object.entries(stats.byModel || {})
+      .map(([name, d]) => ({ name, cost: d.costUsd || 0 }))
+      .sort((a, b) => b.cost - a.cost)
+      .slice(0, 10);
+    const maxCost = Math.max(...models.map(m => m.cost), 0.001);
+    document.getElementById('model-chart').innerHTML = models.map(m =>
+      '<div class="bar-row">' +
+        '<span class="bar-label">' + m.name.split('/').pop() + '</span>' +
+        '<div class="bar-fill" style="width:' + (m.cost/maxCost*100) + '%"></div>' +
+        '<span class="bar-val">' + usd(m.cost) + '</span>' +
+      '</div>'
+    ).join('');
+  }
+  if (insights && insights.dailyCosts) {
+    const days = insights.dailyCosts.slice(-30);
+    const maxDay = Math.max(...days.map(d => d.cost), 0.001);
+    document.getElementById('daily-chart').innerHTML = days.map(d =>
+      '<div class="daily-bar" title="' + d.date + ': ' + usd(d.cost) + '" style="height:' + (d.cost/maxDay*100) + '%"></div>'
+    ).join('');
+  }
+}
+// Load sessions
+async function loadSessions() {
+  const sessions = await api('sessions');
+  if (!sessions || sessions.length === 0) {
+    document.getElementById('session-list').innerHTML = '<div class="empty">No sessions yet</div>';
+    return;
+  }
+  document.getElementById('session-list').innerHTML = sessions.slice(0, 50).map(s =>
+    '<div class="session-item" data-id="' + s.id + '">' +
+      '<div>' + (s.model || 'unknown') + ' — ' + s.messageCount + ' messages</div>' +
+      '<div class="meta">' + new Date(s.createdAt).toLocaleString() + ' · ' + (s.workDir || '').split('/').pop() + '</div>' +
+    '</div>'
+  ).join('');
+  document.querySelectorAll('.session-item').forEach(el => {
+    el.addEventListener('click', async () => {
+      const id = el.dataset.id;
+      const history = await api('sessions/' + encodeURIComponent(id));
+      if (!history) return;
+      const detail = document.getElementById('session-detail');
+      detail.style.display = 'block';
+      detail.innerHTML = history.map(m => {
+        const role = m.role || 'system';
+        let text = typeof m.content === 'string' ? m.content : JSON.stringify(m.content).slice(0, 500);
+        text = text.replace(/</g, '&lt;').replace(/>/g, '&gt;');
+        return '<div class="msg ' + role + '"><pre>' + role.toUpperCase() + ': ' + text + '</pre></div>';
+      }).join('');
+    });
+  });
+}
+// Session search
+let searchTimeout;
+document.getElementById('session-search').addEventListener('input', (e) => {
+  clearTimeout(searchTimeout);
+  searchTimeout = setTimeout(async () => {
+    const q = e.target.value.trim();
+    if (!q) { loadSessions(); return; }
+    const results = await api('sessions/search?q=' + encodeURIComponent(q));
+    if (!results || results.length === 0) {
+      document.getElementById('session-list').innerHTML = '<div class="empty">No results</div>';
+      return;
+    }
+    document.getElementById('session-list').innerHTML = results.map(r =>
+      '<div class="session-item">' +
+        '<div>' + r.snippet.replace(/</g, '&lt;') + '</div>' +
+        '<div class="meta">' + r.sessionId + ' · score: ' + r.score.toFixed(2) + '</div>' +
+      '</div>'
+    ).join('');
+  }, 300);
+});
+// Load social
+async function loadSocial() {
+  const social = await api('social');
+  if (!social) { return; }
+  document.getElementById('social-stats').innerHTML =
+    '<div class="card"><h3>Posted</h3><div class="big green">' + (social.posted || 0) + '</div></div>' +
+    '<div class="card"><h3>Drafted</h3><div class="big">' + (social.drafted || 0) + '</div></div>' +
+    '<div class="card"><h3>Skipped</h3><div class="big">' + (social.skipped || 0) + '</div></div>' +
+    '<div class="card"><h3>Total Cost</h3><div class="big gold">' + usd(social.totalCost || 0) + '</div></div>';
+}
+// Load learnings
+async function loadLearnings() {
+  const learnings = await api('learnings');
+  if (!learnings || learnings.length === 0) {
+    document.getElementById('learnings-list').innerHTML = '<div class="empty">No learnings yet. Franklin learns your preferences over time.</div>';
+    return;
+  }
+  document.getElementById('learnings-list').innerHTML = learnings
+    .sort((a, b) => (b.confidence * b.times_confirmed) - (a.confidence * a.times_confirmed))
+    .map(l => {
+      const cls = l.confidence >= 0.8 ? 'high' : l.confidence >= 0.5 ? 'mid' : 'low';
+      return '<div class="learning-item">' +
+        '<span class="confidence ' + cls + '">' + (l.confidence * 100).toFixed(0) + '%</span>' +
+        '<span>' + l.learning + '</span>' +
+        '<span style="margin-left:auto;color:var(--text-dim);font-size:11px">×' + l.times_confirmed + '</span>' +
+      '</div>';
+    }).join('');
+}
+// SSE
+const es = new EventSource('/api/events');
+const dot = document.getElementById('dot');
+const statusEl = document.getElementById('status');
+es.onopen = () => { dot.className = 'dot on'; statusEl.textContent = 'live'; };
+es.onerror = () => { dot.className = 'dot off'; statusEl.textContent = 'disconnected'; };
+es.onmessage = (e) => {
+  try {
+    const evt = JSON.parse(e.data);
+    if (evt.type === 'stats.updated') loadOverview();
+  } catch {}
+};
+// Init
+loadOverview();
+loadSessions();
+loadSocial();
+loadLearnings();
+// Refresh wallet balance every 30s
+setInterval(() => api('wallet').then(w => {
+  if (w) document.getElementById('balance').textContent = usdBig(w.balance) + ' USDC';
+}), 30000);
+</script>
+</body>
+</html>`;
+}

package/dist/panel/server.d.ts ADDED Viewed

@@ -0,0 +1,7 @@
+/**
+ * Franklin Panel — local HTTP server.
+ * Serves the dashboard HTML + JSON API endpoints + SSE for real-time updates.
+ * Zero external dependencies — uses node:http only.
+ */
+import http from 'node:http';
+export declare function createPanelServer(port: number): http.Server;

package/dist/panel/server.js ADDED Viewed

@@ -0,0 +1,152 @@
+/**
+ * Franklin Panel — local HTTP server.
+ * Serves the dashboard HTML + JSON API endpoints + SSE for real-time updates.
+ * Zero external dependencies — uses node:http only.
+ */
+import http from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+import { BLOCKRUN_DIR, loadChain } from '../config.js';
+import { getStatsSummary } from '../stats/tracker.js';
+import { generateInsights } from '../stats/insights.js';
+import { listSessions, loadSessionHistory } from '../session/storage.js';
+import { searchSessions } from '../session/search.js';
+import { loadLearnings } from '../learnings/store.js';
+import { getStats as getSocialStats } from '../social/db.js';
+import { getHTML } from './html.js';
+const sseClients = new Set();
+function json(res, data, status = 200) {
+    res.writeHead(status, {
+        'Content-Type': 'application/json',
+        'Access-Control-Allow-Origin': '*',
+    });
+    res.end(JSON.stringify(data));
+}
+function broadcast(data) {
+    const msg = `data: ${JSON.stringify(data)}\n\n`;
+    for (const client of sseClients) {
+        try {
+            client.write(msg);
+        }
+        catch {
+            sseClients.delete(client);
+        }
+    }
+}
+export function createPanelServer(port) {
+    const html = getHTML();
+    const server = http.createServer(async (req, res) => {
+        const url = new URL(req.url || '/', `http://localhost:${port}`);
+        const p = url.pathname;
+        // ─── HTML ──
+        if (p === '/') {
+            res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+            res.end(html);
+            return;
+        }
+        // ─── SSE ──
+        if (p === '/api/events') {
+            res.writeHead(200, {
+                'Content-Type': 'text/event-stream',
+                'Cache-Control': 'no-cache',
+                'Connection': 'keep-alive',
+                'Access-Control-Allow-Origin': '*',
+            });
+            res.write('data: {"type":"connected"}\n\n');
+            sseClients.add(res);
+            req.on('close', () => sseClients.delete(res));
+            return;
+        }
+        // ─── API ──
+        try {
+            if (p === '/api/stats') {
+                const summary = getStatsSummary();
+                json(res, {
+                    totalRequests: summary.stats.totalRequests,
+                    totalCostUsd: summary.stats.totalCostUsd,
+                    opusCost: summary.opusCost,
+                    saved: summary.saved,
+                    savedPct: summary.savedPct,
+                    avgCostPerRequest: summary.avgCostPerRequest,
+                    period: summary.period,
+                    byModel: summary.stats.byModel,
+                });
+                return;
+            }
+            if (p === '/api/insights') {
+                const days = parseInt(url.searchParams.get('days') || '30', 10);
+                const report = generateInsights(days);
+                json(res, report);
+                return;
+            }
+            if (p === '/api/sessions') {
+                const sessions = listSessions();
+                json(res, sessions);
+                return;
+            }
+            if (p.startsWith('/api/sessions/search')) {
+                const q = url.searchParams.get('q') || '';
+                const limit = parseInt(url.searchParams.get('limit') || '20', 10);
+                const results = searchSessions(q, { limit });
+                json(res, results);
+                return;
+            }
+            if (p.startsWith('/api/sessions/')) {
+                const id = decodeURIComponent(p.slice('/api/sessions/'.length));
+                const history = loadSessionHistory(id);
+                json(res, history);
+                return;
+            }
+            if (p === '/api/wallet') {
+                try {
+                    const chain = loadChain();
+                    let address = '', balance = 0;
+                    if (chain === 'solana') {
+                        const { setupAgentSolanaWallet } = await import('@blockrun/llm');
+                        const client = await setupAgentSolanaWallet({ silent: true });
+                        address = await client.getWalletAddress();
+                        balance = await client.getBalance();
+                    }
+                    else {
+                        const { setupAgentWallet } = await import('@blockrun/llm');
+                        const client = setupAgentWallet({ silent: true });
+                        address = client.getWalletAddress();
+                        balance = await client.getBalance();
+                    }
+                    json(res, { address, balance, chain });
+                }
+                catch {
+                    json(res, { address: 'not set', balance: 0, chain: loadChain() });
+                }
+                return;
+            }
+            if (p === '/api/social') {
+                const stats = getSocialStats();
+                json(res, stats);
+                return;
+            }
+            if (p === '/api/learnings') {
+                const learnings = loadLearnings();
+                json(res, learnings);
+                return;
+            }
+            // 404
+            res.writeHead(404);
+            res.end('Not found');
+        }
+        catch (err) {
+            json(res, { error: err.message }, 500);
+        }
+    });
+    // Watch stats file for changes → push to SSE clients
+    const statsFile = path.join(BLOCKRUN_DIR, 'runcode-stats.json');
+    if (fs.existsSync(statsFile)) {
+        fs.watchFile(statsFile, { interval: 2000 }, () => {
+            try {
+                broadcast({ type: 'stats.updated' });
+            }
+            catch { /* ignore */ }
+        });
+    }
+    return server;
+}

package/dist/session/storage.js CHANGED Viewed

@@ -5,6 +5,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { randomUUID } from 'node:crypto';
 import { BLOCKRUN_DIR } from '../config.js';
 const MAX_SESSIONS = 20; // Keep last 20 sessions
 let resolvedSessionsDir = null;
@@ -60,8 +61,9 @@ function withWritableSessionDir(action) {
  */
 export function createSessionId() {
     const now = new Date();
-    const ts = now.toISOString().replace(/[:.]/g, '-').slice(0, 19);
-    return `session-${ts}`;
+    const ts = now.toISOString().replace(/[:.]/g, '-');
+    const suffix = randomUUID().slice(0, 8);
+    return `session-${ts}-${suffix}`;
 }
 /**
  * Save a message to the session transcript (append-only JSONL).

package/dist/social/browser-pool.d.ts ADDED Viewed

@@ -0,0 +1,29 @@
+/**
+ * Singleton browser pool for Franklin's social subsystem.
+ * Wraps SocialBrowser with idle-timeout lifecycle management so the
+ * browser stays warm across sequential social tool calls but shuts
+ * down automatically after 5 minutes of inactivity.
+ */
+import { SocialBrowser } from './browser.js';
+declare class BrowserPool {
+    private browser;
+    private idleTimer;
+    /**
+     * Get a ready-to-use browser instance. If one is already running,
+     * reset the idle timer and return it. Otherwise launch a new one.
+     */
+    getBrowser(): Promise<SocialBrowser>;
+    /**
+     * Signal that the caller is done with the browser for now.
+     * Starts (or resets) the idle timer. When it fires the browser
+     * is closed automatically.
+     */
+    releaseBrowser(): void;
+    /**
+     * Immediately close the browser and clear the idle timer.
+     */
+    closeBrowser(): Promise<void>;
+    private resetIdleTimer;
+}
+export declare const browserPool: BrowserPool;
+export {};

package/dist/social/browser-pool.js ADDED Viewed

@@ -0,0 +1,57 @@
+/**
+ * Singleton browser pool for Franklin's social subsystem.
+ * Wraps SocialBrowser with idle-timeout lifecycle management so the
+ * browser stays warm across sequential social tool calls but shuts
+ * down automatically after 5 minutes of inactivity.
+ */
+import { SocialBrowser } from './browser.js';
+const IDLE_TIMEOUT = 5 * 60 * 1000; // 5 minutes
+class BrowserPool {
+    browser = null;
+    idleTimer = null;
+    /**
+     * Get a ready-to-use browser instance. If one is already running,
+     * reset the idle timer and return it. Otherwise launch a new one.
+     */
+    async getBrowser() {
+        if (this.browser) {
+            this.resetIdleTimer();
+            return this.browser;
+        }
+        const browser = new SocialBrowser({ headless: false });
+        await browser.launch();
+        this.browser = browser;
+        this.resetIdleTimer();
+        return this.browser;
+    }
+    /**
+     * Signal that the caller is done with the browser for now.
+     * Starts (or resets) the idle timer. When it fires the browser
+     * is closed automatically.
+     */
+    releaseBrowser() {
+        this.resetIdleTimer();
+    }
+    /**
+     * Immediately close the browser and clear the idle timer.
+     */
+    async closeBrowser() {
+        if (this.idleTimer) {
+            clearTimeout(this.idleTimer);
+            this.idleTimer = null;
+        }
+        if (this.browser) {
+            await this.browser.close();
+            this.browser = null;
+        }
+    }
+    resetIdleTimer() {
+        if (this.idleTimer) {
+            clearTimeout(this.idleTimer);
+        }
+        this.idleTimer = setTimeout(async () => {
+            await this.closeBrowser();
+        }, IDLE_TIMEOUT);
+    }
+}
+export const browserPool = new BrowserPool();

package/dist/social/preflight.d.ts ADDED Viewed

@@ -0,0 +1,14 @@
+/**
+ * Pre-flight checks before social tools can run.
+ * Validates config readiness and browser login state.
+ */
+import type { SocialBrowser } from './browser.js';
+/**
+ * Verify that social config is ready and the user is logged in to X.
+ * Returns the browser instance on success so callers can reuse it.
+ */
+export declare function checkSocialReady(): Promise<{
+    ready: boolean;
+    reason?: string;
+    browser?: SocialBrowser;
+}>;

package/dist/social/preflight.js ADDED Viewed

@@ -0,0 +1,26 @@
+/**
+ * Pre-flight checks before social tools can run.
+ * Validates config readiness and browser login state.
+ */
+import { loadConfig, isConfigReady } from './config.js';
+import { browserPool } from './browser-pool.js';
+/**
+ * Verify that social config is ready and the user is logged in to X.
+ * Returns the browser instance on success so callers can reuse it.
+ */
+export async function checkSocialReady() {
+    const cfg = loadConfig();
+    const configStatus = isConfigReady(cfg);
+    if (!configStatus.ready) {
+        return { ready: false, reason: configStatus.reason };
+    }
+    const browser = await browserPool.getBrowser();
+    await browser.open('https://x.com/home');
+    await browser.waitForTimeout(2500);
+    const tree = await browser.snapshot();
+    if (!tree.includes(cfg.x.login_detection)) {
+        browserPool.releaseBrowser();
+        return { ready: false, reason: 'Not logged in to X. Run: franklin social login x' };
+    }
+    return { ready: true, browser };
+}

package/dist/social/x.d.ts CHANGED Viewed

@@ -13,6 +13,7 @@
  * Every browser interaction uses argv-based Playwright calls — zero shell
  * injection surface even if the LLM emits `$(rm -rf /)` in reply text.
  */
+import { SocialBrowser } from './browser.js';
 import type { SocialConfig } from './config.js';
 import type { Chain } from '../config.js';
 export interface RunOptions {
@@ -44,3 +45,10 @@ export interface CandidatePost {
  * and processes every visible candidate until the daily target is hit.
  */
 export declare function runX(opts: RunOptions): Promise<RunResult>;
+/**
+ * Post a reply to the currently-open tweet page.
+ * Locates the reply textbox, types the reply (paragraphs joined with
+ * Enter+Enter), clicks the reply button, confirms the "Your post was sent"
+ * banner.
+ */
+export declare function postReply(browser: SocialBrowser, reply: string): Promise<void>;