@blockrun/franklin 3.1.1 → 3.2.0

package/dist/social/db.js

@@ -0,0 +1,248 @@
+/**
+ * JSONL-backed dedup + reply log for Franklin's social subsystem.
+ *
+ * Deliberately avoids SQLite (no new native dep). Two files at:
+ *
+ *   ~/.blockrun/social-replies.jsonl    — append-only reply log
+ *   ~/.blockrun/social-prekeys.jsonl    — append-only snippet-level dedup
+ *
+ * Both are read into memory at startup for O(1) lookups. At 30 replies/day
+ * this hits 10K rows after a year — still <1MB, still fits in memory.
+ *
+ * Schema improvements over social-bot's bot/db.py:
+ *   - `status: 'failed'` does NOT block retry (social-bot blacklists failures
+ *     permanently, which breaks on transient network errors)
+ *   - Pre-key dedup happens BEFORE LLM call, saving tokens on duplicates
+ *   - Per-platform + per-handle scoping so running the bot with two accounts
+ *     against the same DB doesn't cross-contaminate
+ */
+import path from 'node:path';
+import fs from 'node:fs';
+import os from 'node:os';
+import crypto from 'node:crypto';
+const STORE_DIR = path.join(os.homedir(), '.blockrun');
+const REPLIES_PATH = path.join(STORE_DIR, 'social-replies.jsonl');
+const PREKEYS_PATH = path.join(STORE_DIR, 'social-prekeys.jsonl');
+// ─── In-memory indexes, loaded lazily on first use ─────────────────────────
+let repliesLoaded = false;
+let replies = [];
+let repliesByUrl = new Map(); // canonical URL → records
+let repliesToday = new Map(); // handle:platform:date → count
+let preKeysLoaded = false;
+let preKeysSet = new Set(); // composite key for O(1) lookup
+function ensureDir() {
+    if (!fs.existsSync(STORE_DIR))
+        fs.mkdirSync(STORE_DIR, { recursive: true });
+}
+function loadReplies() {
+    if (repliesLoaded)
+        return;
+    ensureDir();
+    replies = [];
+    repliesByUrl.clear();
+    repliesToday.clear();
+    if (fs.existsSync(REPLIES_PATH)) {
+        const text = fs.readFileSync(REPLIES_PATH, 'utf8');
+        for (const line of text.split('\n')) {
+            if (!line.trim())
+                continue;
+            try {
+                const rec = JSON.parse(line);
+                replies.push(rec);
+                const list = repliesByUrl.get(rec.post_url) ?? [];
+                list.push(rec);
+                repliesByUrl.set(rec.post_url, list);
+                if (rec.status === 'posted') {
+                    const dayKey = `${rec.handle}:${rec.platform}:${rec.created_at.slice(0, 10)}`;
+                    repliesToday.set(dayKey, (repliesToday.get(dayKey) ?? 0) + 1);
+                }
+            }
+            catch {
+                // Skip malformed lines — append-only file may have a partial last line
+            }
+        }
+    }
+    repliesLoaded = true;
+}
+function loadPreKeys() {
+    if (preKeysLoaded)
+        return;
+    ensureDir();
+    preKeysSet.clear();
+    if (fs.existsSync(PREKEYS_PATH)) {
+        const text = fs.readFileSync(PREKEYS_PATH, 'utf8');
+        for (const line of text.split('\n')) {
+            if (!line.trim())
+                continue;
+            try {
+                const rec = JSON.parse(line);
+                preKeysSet.add(compositePreKey(rec.platform, rec.handle, rec.pre_key));
+            }
+            catch {
+                // Skip malformed lines
+            }
+        }
+    }
+    preKeysLoaded = true;
+}
+function compositePreKey(platform, handle, preKey) {
+    return `${platform}|${handle}|${preKey}`;
+}
+// ─── Public API ────────────────────────────────────────────────────────────
+/**
+ * Compute a stable pre-key for a candidate post from its snippet fields.
+ * Used BEFORE the LLM generates a reply so we can skip duplicates without
+ * wasting any tokens.
+ */
+export function computePreKey(parts) {
+    const normalised = (parts.author ?? '').trim().toLowerCase() + '|' +
+        parts.snippet.trim().slice(0, 80).toLowerCase() + '|' +
+        (parts.time ?? '').trim();
+    return crypto.createHash('sha256').update(normalised).digest('hex').slice(0, 16);
+}
+/**
+ * Has this post been seen before (by pre-key)? If true, skip generation.
+ */
+export function hasPreKey(platform, handle, preKey) {
+    loadPreKeys();
+    return preKeysSet.has(compositePreKey(platform, handle, preKey));
+}
+/**
+ * Commit a pre-key so we don't re-consider this post. Called after we've
+ * decided to act on a post (either drafted, posted, or skipped by AI).
+ */
+export function commitPreKey(platform, handle, preKey) {
+    loadPreKeys();
+    const composite = compositePreKey(platform, handle, preKey);
+    if (preKeysSet.has(composite))
+        return;
+    preKeysSet.add(composite);
+    const rec = {
+        platform,
+        handle,
+        pre_key: preKey,
+        created_at: new Date().toISOString(),
+    };
+    ensureDir();
+    fs.appendFileSync(PREKEYS_PATH, JSON.stringify(rec) + '\n');
+}
+/**
+ * Has this canonical URL been successfully posted to before?
+ *
+ * Only counts status='posted' — unlike social-bot, we do NOT permanently
+ * blacklist 'failed' attempts, so transient errors can be retried.
+ */
+export function hasPosted(platform, handle, postUrl) {
+    loadReplies();
+    const recs = repliesByUrl.get(normaliseUrl(postUrl)) ?? [];
+    return recs.some((r) => r.platform === platform && r.handle === handle && r.status === 'posted');
+}
+/**
+ * Count today's successful posts for a handle/platform (used for daily caps).
+ */
+export function countPostedToday(platform, handle) {
+    loadReplies();
+    const today = new Date().toISOString().slice(0, 10);
+    const key = `${handle}:${platform}:${today}`;
+    return repliesToday.get(key) ?? 0;
+}
+/**
+ * Append a reply record. Status can be 'drafted' (dry-run), 'posted',
+ * 'failed' (transient, retry OK), or 'skipped' (AI returned SKIP).
+ */
+export function logReply(rec) {
+    loadReplies();
+    const record = {
+        ...rec,
+        post_url: normaliseUrl(rec.post_url),
+        created_at: new Date().toISOString(),
+    };
+    replies.push(record);
+    const list = repliesByUrl.get(record.post_url) ?? [];
+    list.push(record);
+    repliesByUrl.set(record.post_url, list);
+    if (record.status === 'posted') {
+        const dayKey = `${record.handle}:${record.platform}:${record.created_at.slice(0, 10)}`;
+        repliesToday.set(dayKey, (repliesToday.get(dayKey) ?? 0) + 1);
+    }
+    ensureDir();
+    fs.appendFileSync(REPLIES_PATH, JSON.stringify(record) + '\n');
+}
+/**
+ * Stats summary for `franklin social stats`.
+ */
+export function getStats(platform, handle) {
+    loadReplies();
+    const today = new Date().toISOString().slice(0, 10);
+    const filtered = replies.filter((r) => {
+        if (platform && r.platform !== platform)
+            return false;
+        if (handle && r.handle !== handle)
+            return false;
+        return true;
+    });
+    const byProduct = {};
+    let totalCost = 0;
+    let todayCount = 0;
+    const statusCounts = { posted: 0, failed: 0, skipped: 0, drafted: 0 };
+    for (const r of filtered) {
+        statusCounts[r.status] =
+            (statusCounts[r.status] ?? 0) + 1;
+        if (r.product)
+            byProduct[r.product] = (byProduct[r.product] ?? 0) + 1;
+        if (r.cost_usd)
+            totalCost += r.cost_usd;
+        if (r.status === 'posted' && r.created_at.startsWith(today))
+            todayCount++;
+    }
+    return {
+        total: filtered.length,
+        ...statusCounts,
+        today: todayCount,
+        totalCost,
+        byProduct,
+    };
+}
+/**
+ * Canonicalise a URL for stable dedup keys:
+ *   - lowercase host
+ *   - strip trailing slash
+ *   - strip tracking params (?s=, ?t=, utm_*)
+ *   - x.com and twitter.com are aliases
+ */
+export function normaliseUrl(raw) {
+    try {
+        const u = new URL(raw);
+        u.hostname = u.hostname.toLowerCase();
+        if (u.hostname === 'twitter.com' || u.hostname === 'mobile.twitter.com') {
+            u.hostname = 'x.com';
+        }
+        // Strip common tracking params
+        const toStrip = [];
+        u.searchParams.forEach((_v, k) => {
+            if (k.startsWith('utm_') || k === 's' || k === 't' || k === 'ref')
+                toStrip.push(k);
+        });
+        for (const k of toStrip)
+            u.searchParams.delete(k);
+        let s = u.toString();
+        if (s.endsWith('/'))
+            s = s.slice(0, -1);
+        return s;
+    }
+    catch {
+        return raw.trim();
+    }
+}
+/**
+ * Test helper — reset in-memory indexes so the next call re-reads from disk.
+ * Not exported from the public API via index.ts.
+ */
+export function _resetForTest() {
+    repliesLoaded = false;
+    preKeysLoaded = false;
+    replies = [];
+    repliesByUrl.clear();
+    repliesToday.clear();
+    preKeysSet.clear();
+}

package/dist/social/x.d.ts

@@ -0,0 +1,46 @@
+/**
+ * X (Twitter) flow for Franklin's social subsystem.
+ *
+ * Port of social-bot/bot/x_bot.py with three meaningful changes:
+ *
+ *   1. Pre-key dedup runs BEFORE the LLM call (social-bot runs it after,
+ *      wasting Sonnet tokens on every duplicate).
+ *   2. 'failed' status does NOT blacklist — only 'posted' does.
+ *      A transient network error can be retried on the next run.
+ *   3. Reply textbox is located via Playwright role selectors, not by
+ *      counting buttons in a list — less fragile to X DOM changes.
+ *
+ * Every browser interaction uses argv-based Playwright calls — zero shell
+ * injection surface even if the LLM emits `$(rm -rf /)` in reply text.
+ */
+import type { SocialConfig } from './config.js';
+import type { Chain } from '../config.js';
+export interface RunOptions {
+    config: SocialConfig;
+    model: string;
+    apiUrl: string;
+    chain: Chain;
+    dryRun: boolean;
+    debug?: boolean;
+    onProgress?: (msg: string) => void;
+}
+export interface RunResult {
+    considered: number;
+    dedupSkipped: number;
+    llmSkipped: number;
+    drafted: number;
+    posted: number;
+    failed: number;
+    totalCost: number;
+}
+export interface CandidatePost {
+    snippetRef: string;
+    articleRef: string;
+    snippet: string;
+    timeText: string;
+}
+/**
+ * Main entry point. Iterates every search query in config.x.search_queries
+ * and processes every visible candidate until the daily target is hit.
+ */
+export declare function runX(opts: RunOptions): Promise<RunResult>;

package/dist/social/x.js

@@ -0,0 +1,284 @@
+/**
+ * X (Twitter) flow for Franklin's social subsystem.
+ *
+ * Port of social-bot/bot/x_bot.py with three meaningful changes:
+ *
+ *   1. Pre-key dedup runs BEFORE the LLM call (social-bot runs it after,
+ *      wasting Sonnet tokens on every duplicate).
+ *   2. 'failed' status does NOT blacklist — only 'posted' does.
+ *      A transient network error can be retried on the next run.
+ *   3. Reply textbox is located via Playwright role selectors, not by
+ *      counting buttons in a list — less fragile to X DOM changes.
+ *
+ * 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 { findRefs, findStaticText, extractArticleBlocks, X_TIME_LINK_PATTERN } from './a11y.js';
+import { computePreKey, hasPreKey, commitPreKey, hasPosted, countPostedToday, logReply, } from './db.js';
+import { detectProduct, generateReply } from './ai.js';
+/**
+ * Main entry point. Iterates every search query in config.x.search_queries
+ * and processes every visible candidate until the daily target is hit.
+ */
+export async function runX(opts) {
+    const log = opts.onProgress ?? (() => { });
+    const handle = opts.config.handle || 'unknown';
+    const result = {
+        considered: 0,
+        dedupSkipped: 0,
+        llmSkipped: 0,
+        drafted: 0,
+        posted: 0,
+        failed: 0,
+        totalCost: 0,
+    };
+    const alreadyToday = countPostedToday('x', handle);
+    const remainingBudget = Math.max(0, opts.config.x.daily_target - alreadyToday);
+    if (remainingBudget === 0) {
+        log(`Daily target of ${opts.config.x.daily_target} already hit today. Nothing to do.`);
+        return result;
+    }
+    log(`Daily budget: ${remainingBudget} posts remaining (of ${opts.config.x.daily_target})`);
+    const browser = new SocialBrowser({ headless: false });
+    try {
+        await browser.launch();
+        log('Browser launched. Checking login state…');
+        // Verify we're logged in. If the login_detection string isn't visible on
+        // x.com's home page, the user needs to run `franklin social login x`.
+        await browser.open('https://x.com/home');
+        await browser.waitForTimeout(2500);
+        const homeTree = await browser.snapshot();
+        const loginMarker = opts.config.x.login_detection || opts.config.handle;
+        if (loginMarker && !homeTree.includes(loginMarker)) {
+            throw new Error(`Not logged in to x.com (looked for "${loginMarker}" on /home). ` +
+                `Run: franklin social login x`);
+        }
+        log('Login confirmed.');
+        let postedThisRun = 0;
+        for (const query of opts.config.x.search_queries) {
+            if (postedThisRun >= remainingBudget) {
+                log(`Hit daily budget (${postedThisRun}) — stopping early.`);
+                break;
+            }
+            log(`\nSearching X for: ${query}`);
+            const searchUrl = `https://x.com/search?q=${encodeURIComponent(query)}&src=typed_query&f=live`;
+            await browser.open(searchUrl);
+            await browser.waitForTimeout(3500);
+            const searchTree = await browser.snapshot();
+            const articles = extractArticleBlocks(searchTree);
+            log(`  Found ${articles.length} posts in results`);
+            for (const article of articles) {
+                if (postedThisRun >= remainingBudget)
+                    break;
+                result.considered++;
+                // Extract the clickable time-link (our open-tweet handle) and the
+                // first visible static text (our snippet).
+                const timeRefs = findRefs(article.text, 'link', X_TIME_LINK_PATTERN);
+                if (timeRefs.length === 0)
+                    continue;
+                const timeRef = timeRefs[0];
+                const texts = findStaticText(article.text);
+                const snippet = texts.slice(0, 3).join(' ').trim();
+                if (!snippet || snippet.length < 20)
+                    continue;
+                const timeLinkMatch = new RegExp(`\\[${timeRef}\\][^\\n]*`).exec(article.text);
+                const timeText = timeLinkMatch ? timeLinkMatch[0] : '';
+                // ── Pre-key dedup: BEFORE any LLM call ──
+                const preKey = computePreKey({ snippet, time: timeText });
+                if (hasPreKey('x', handle, preKey)) {
+                    result.dedupSkipped++;
+                    continue;
+                }
+                // Product routing (zero-cost keyword score)
+                const product = detectProduct(snippet, opts.config.products);
+                if (!product) {
+                    commitPreKey('x', handle, preKey); // never retry — no product matches
+                    continue;
+                }
+                log(`\n  → ${snippet.slice(0, 80)}…`);
+                log(`    product: ${product.name}`);
+                // Generate reply (this is where we spend LLM tokens)
+                let gen;
+                try {
+                    gen = await generateReply({
+                        post: { title: snippet.slice(0, 120), snippet, platform: 'x' },
+                        product,
+                        config: opts.config,
+                        model: opts.model,
+                        apiUrl: opts.apiUrl,
+                        chain: opts.chain,
+                        debug: opts.debug,
+                    });
+                }
+                catch (err) {
+                    log(`    ✗ generateReply failed: ${err.message}`);
+                    commitPreKey('x', handle, preKey);
+                    continue;
+                }
+                result.totalCost += gen.cost;
+                if (!gen.reply) {
+                    log(`    AI said SKIP`);
+                    result.llmSkipped++;
+                    commitPreKey('x', handle, preKey);
+                    logReply({
+                        platform: 'x',
+                        handle,
+                        post_url: `preview:${preKey}`,
+                        post_title: snippet.slice(0, 120),
+                        post_snippet: snippet,
+                        reply_text: '',
+                        product: product.name,
+                        status: 'skipped',
+                        cost_usd: gen.cost,
+                    });
+                    continue;
+                }
+                result.drafted++;
+                log(`    draft: ${gen.reply}`);
+                // ── Dry-run short-circuit ──
+                if (opts.dryRun) {
+                    commitPreKey('x', handle, preKey);
+                    logReply({
+                        platform: 'x',
+                        handle,
+                        post_url: `preview:${preKey}`,
+                        post_title: snippet.slice(0, 120),
+                        post_snippet: snippet,
+                        reply_text: gen.reply,
+                        product: product.name,
+                        status: 'drafted',
+                        cost_usd: gen.cost,
+                    });
+                    continue;
+                }
+                // ── Live path: open the tweet, dedup by canonical URL, post ──
+                let canonicalUrl = '';
+                try {
+                    await browser.click(timeRef);
+                    await browser.waitForTimeout(3000);
+                    canonicalUrl = await browser.getUrl();
+                }
+                catch (err) {
+                    log(`    ✗ failed to open tweet: ${err.message}`);
+                    logReply({
+                        platform: 'x',
+                        handle,
+                        post_url: `preview:${preKey}`,
+                        post_title: snippet.slice(0, 120),
+                        post_snippet: snippet,
+                        reply_text: gen.reply,
+                        product: product.name,
+                        status: 'failed',
+                        error_msg: `open-tweet: ${err.message}`,
+                        cost_usd: gen.cost,
+                    });
+                    result.failed++;
+                    commitPreKey('x', handle, preKey);
+                    continue;
+                }
+                if (hasPosted('x', handle, canonicalUrl)) {
+                    log(`    already posted to ${canonicalUrl} — backing out`);
+                    commitPreKey('x', handle, preKey);
+                    await browser.press('Alt+ArrowLeft').catch(() => { });
+                    await browser.waitForTimeout(1500);
+                    continue;
+                }
+                // Post the reply
+                try {
+                    await postReply(browser, gen.reply);
+                    log(`    ✓ posted to ${canonicalUrl}`);
+                    result.posted++;
+                    postedThisRun++;
+                    logReply({
+                        platform: 'x',
+                        handle,
+                        post_url: canonicalUrl,
+                        post_title: snippet.slice(0, 120),
+                        post_snippet: snippet,
+                        reply_text: gen.reply,
+                        product: product.name,
+                        status: 'posted',
+                        cost_usd: gen.cost,
+                    });
+                    commitPreKey('x', handle, preKey);
+                    // Respect the rate-limit / anti-spam delay between successes
+                    await browser.waitForTimeout(opts.config.x.min_delay_seconds * 1000);
+                }
+                catch (err) {
+                    log(`    ✗ post failed: ${err.message}`);
+                    result.failed++;
+                    logReply({
+                        platform: 'x',
+                        handle,
+                        post_url: canonicalUrl,
+                        post_title: snippet.slice(0, 120),
+                        post_snippet: snippet,
+                        reply_text: gen.reply,
+                        product: product.name,
+                        status: 'failed',
+                        error_msg: err.message,
+                        cost_usd: gen.cost,
+                    });
+                    // Don't commitPreKey — allow retry on next run
+                    await browser.press('Escape').catch(() => { });
+                    await browser.waitForTimeout(2000);
+                }
+            }
+        }
+    }
+    finally {
+        await browser.close();
+    }
+    return result;
+}
+/**
+ * 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.
+ */
+async function postReply(browser, reply) {
+    // Snapshot and find the reply textbox
+    const tree = await browser.snapshot();
+    const boxRefs = findRefs(tree, 'textbox', 'Post (your reply|text).*');
+    if (boxRefs.length === 0) {
+        // Fallback: any textbox containing "reply" or "post"
+        const fallback = findRefs(tree, 'textbox', '(?:[Rr]eply|[Pp]ost).*');
+        if (fallback.length === 0)
+            throw new Error('reply textbox not found');
+        await browser.click(fallback[0]);
+    }
+    else {
+        await browser.click(boxRefs[0]);
+    }
+    await browser.waitForTimeout(700);
+    // Type paragraphs separated by double-enter.
+    // Strip any `$` so it never triggers a variable interpolation in some
+    // downstream tool. (Not required for Playwright argv, but defense in depth.)
+    const paragraphs = reply.split(/\n{2,}/).map((p) => p.replace(/\s+$/, ''));
+    for (let i = 0; i < paragraphs.length; i++) {
+        if (i > 0) {
+            await browser.press('Enter');
+            await browser.press('Enter');
+        }
+        await browser.type(paragraphs[i]);
+    }
+    await browser.waitForTimeout(700);
+    // Click the reply (submit) button. The modal's submit button is labelled
+    // "Reply" — we take the FIRST match because the inline compose-below-tweet
+    // form and the modal don't coexist in the DOM.
+    const snapAfter = await browser.snapshot();
+    const replyBtns = findRefs(snapAfter, 'button', 'Reply');
+    if (replyBtns.length === 0)
+        throw new Error('reply submit button not found');
+    // If multiple reply buttons (e.g. a toolbar Reply + submit Reply), the
+    // submit is usually the last one with the 'Reply' label.
+    await browser.click(replyBtns[replyBtns.length - 1]);
+    await browser.waitForTimeout(2500);
+    // Confirm
+    const confirm = await browser.snapshot();
+    if (!/Your post was sent|Reply sent|Your reply was sent/.test(confirm)) {
+        throw new Error('post-send confirmation banner not found');
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/franklin",
-  "version": "3.1.1",
+  "version": "3.2.0",
   "description": "Franklin — The AI agent with a wallet. Spends USDC autonomously to get real work done. Pay per action, no subscriptions.",
   "type": "module",
   "exports": {
@@ -70,6 +70,7 @@
     "ink": "^6.8.0",
     "ink-spinner": "^5.0.0",
     "ink-text-input": "^6.0.0",
+    "playwright-core": "^1.49.1",
     "react": "^19.2.4"
   },
   "devDependencies": {