@blockrun/franklin 3.1.2 → 3.2.1

package/dist/social/ai.d.ts

@@ -0,0 +1,61 @@
+/**
+ * AI layer for Franklin's social subsystem.
+ *
+ * Two functions mirroring social-bot/bot/ai_engine.py:
+ *   - detectProduct()   — keyword-score product router (no LLM, zero cost)
+ *   - generateReply()   — calls Franklin's ModelClient for actual reply text
+ *
+ * Key improvements over social-bot:
+ *   - Uses Franklin's multi-model router (tier-based: free / cheap / premium)
+ *     instead of hardcoded Claude Sonnet for every call — throwaway replies
+ *     can run on free NVIDIA models, high-value leads can escalate to Opus.
+ *   - x402 payment flow handled by ModelClient — no Anthropic billing relationship.
+ *   - SKIP detection lives in the caller so we can commit a 'skipped' record
+ *     for visibility in stats.
+ */
+import type { ProductConfig, SocialConfig } from './config.js';
+import type { Chain } from '../config.js';
+export interface GenerateReplyOptions {
+    post: {
+        title: string;
+        snippet: string;
+        platform: 'x' | 'reddit';
+    };
+    product: ProductConfig;
+    config: SocialConfig;
+    model: string;
+    apiUrl: string;
+    chain: Chain;
+    debug?: boolean;
+}
+export interface GenerateReplyResult {
+    reply: string | null;
+    raw: string;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    cost: number;
+}
+/**
+ * Score each product by how many of its trigger_keywords appear in the post.
+ * Returns the top-scoring product, or null if no product has any matches.
+ *
+ * Deterministic, zero-cost, debuggable. Social-bot uses the exact same
+ * pattern and it's the right call for this stage — no need to pay an LLM
+ * to ask "which of my products does this post mention".
+ */
+export declare function detectProduct(postText: string, products: ProductConfig[]): ProductConfig | null;
+/**
+ * Build the system prompt for a given product + style ruleset.
+ */
+export declare function buildSystemPrompt(product: ProductConfig, config: SocialConfig): string;
+/**
+ * Build the user prompt containing the post content.
+ */
+export declare function buildUserPrompt(post: GenerateReplyOptions['post']): string;
+/**
+ * Generate a reply via Franklin's ModelClient. Returns { reply: null } if
+ * the model said SKIP or the output was too short to be useful.
+ */
+export declare function generateReply(opts: GenerateReplyOptions): Promise<GenerateReplyResult>;

package/dist/social/ai.js

@@ -0,0 +1,103 @@
+/**
+ * AI layer for Franklin's social subsystem.
+ *
+ * Two functions mirroring social-bot/bot/ai_engine.py:
+ *   - detectProduct()   — keyword-score product router (no LLM, zero cost)
+ *   - generateReply()   — calls Franklin's ModelClient for actual reply text
+ *
+ * Key improvements over social-bot:
+ *   - Uses Franklin's multi-model router (tier-based: free / cheap / premium)
+ *     instead of hardcoded Claude Sonnet for every call — throwaway replies
+ *     can run on free NVIDIA models, high-value leads can escalate to Opus.
+ *   - x402 payment flow handled by ModelClient — no Anthropic billing relationship.
+ *   - SKIP detection lives in the caller so we can commit a 'skipped' record
+ *     for visibility in stats.
+ */
+import { ModelClient } from '../agent/llm.js';
+import { estimateCost } from '../pricing.js';
+/**
+ * Score each product by how many of its trigger_keywords appear in the post.
+ * Returns the top-scoring product, or null if no product has any matches.
+ *
+ * Deterministic, zero-cost, debuggable. Social-bot uses the exact same
+ * pattern and it's the right call for this stage — no need to pay an LLM
+ * to ask "which of my products does this post mention".
+ */
+export function detectProduct(postText, products) {
+    if (products.length === 0)
+        return null;
+    const text = postText.toLowerCase();
+    let best = null;
+    for (const p of products) {
+        let score = 0;
+        for (const kw of p.trigger_keywords) {
+            if (text.includes(kw.toLowerCase()))
+                score++;
+        }
+        if (!best || score > best.score) {
+            best = { product: p, score };
+        }
+    }
+    return best && best.score > 0 ? best.product : null;
+}
+/**
+ * Build the system prompt for a given product + style ruleset.
+ */
+export function buildSystemPrompt(product, config) {
+    const rules = config.reply_style.rules.map((r) => `- ${r}`).join('\n');
+    return (`You are replying on behalf of the maker of "${product.name}".\n\n` +
+        `Product description:\n${product.description}\n\n` +
+        `Reply style rules:\n${rules}\n\n` +
+        `You are hands-on, experienced, and speak from lived reality. ` +
+        `You never sound like a marketer. You do not use emojis or hashtags. ` +
+        `If the post is not a good fit for the product, reply with exactly: SKIP`);
+}
+/**
+ * Build the user prompt containing the post content.
+ */
+export function buildUserPrompt(post) {
+    return (`Platform: ${post.platform}\n` +
+        `Post title: ${post.title.slice(0, 200)}\n\n` +
+        `Post content:\n${post.snippet.slice(0, 800)}\n\n` +
+        `Write a reply following the rules in the system prompt. ` +
+        `If the post is not relevant to the product, respond with SKIP only.`);
+}
+/**
+ * Generate a reply via Franklin's ModelClient. Returns { reply: null } if
+ * the model said SKIP or the output was too short to be useful.
+ */
+export async function generateReply(opts) {
+    const system = buildSystemPrompt(opts.product, opts.config);
+    const user = buildUserPrompt(opts.post);
+    const maxLen = opts.config.x.max_length;
+    const client = new ModelClient({
+        apiUrl: opts.apiUrl,
+        chain: opts.chain,
+        debug: opts.debug,
+    });
+    const result = await client.complete({
+        model: opts.model,
+        messages: [{ role: 'user', content: user }],
+        system,
+        max_tokens: 400,
+        stream: true,
+        temperature: 0.7,
+    });
+    // Extract the text from content parts
+    const text = result.content
+        .filter((p) => p.type === 'text')
+        .map((p) => p.text)
+        .join('')
+        .trim();
+    const cost = estimateCost(opts.model, result.usage.inputTokens, result.usage.outputTokens, 1);
+    // SKIP detection — model may say "SKIP", "SKIP." or short/empty
+    if (!text || text.toUpperCase().startsWith('SKIP') || text.length < 20) {
+        return { reply: null, raw: text, usage: result.usage, cost };
+    }
+    // Trim to max length with a small buffer
+    let reply = text;
+    if (reply.length > maxLen + 50) {
+        reply = reply.slice(0, maxLen).replace(/\s+\S*$/, '') + '…';
+    }
+    return { reply, raw: text, usage: result.usage, cost };
+}

package/dist/social/browser.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Native Playwright-core wrapper for Franklin's social subsystem.
+ *
+ * Mirrors the 9 browser primitives social-bot exposes via its `browse` CLI
+ * (open, snapshot, click, type, press, scroll, screenshot, getUrl, close).
+ * Persistent context so login state survives across runs:
+ *
+ *   ~/.blockrun/social-chrome-profile/
+ *
+ * Unlike social-bot's shell=True subprocess calls, every interaction goes
+ * through Playwright's argv-based API — no shell injection surface even if
+ * the LLM generates `$(rm -rf /)` as reply text.
+ */
+export declare const SOCIAL_PROFILE_DIR: string;
+/**
+ * Ref assigned to every interactive AX node. Format matches social-bot:
+ *   [depth-index]
+ * e.g. [0-3], [2-17]. Depth is the tree nesting level; index is the
+ * order within that level.
+ */
+export interface AxRef {
+    id: string;
+    role: string;
+    name: string;
+    selector: string;
+}
+interface AxNode {
+    role?: string;
+    name?: string;
+    value?: string;
+    description?: string;
+    children?: AxNode[];
+}
+/**
+ * Walk an AX tree and produce:
+ *   1. A flat text dump with [depth-idx] refs (for regex-based element finding)
+ *   2. A map of ref ID → role/name/selector for click-by-ref lookups
+ *
+ * The flat text shape intentionally mirrors social-bot's `browse snapshot`
+ * output so code patterns and regexes are directly portable.
+ */
+export declare function serializeAxTree(root: AxNode): {
+    tree: string;
+    refs: Map<string, AxRef>;
+};
+export interface BrowserOptions {
+    headless?: boolean;
+    channel?: 'chrome' | 'chromium' | 'msedge';
+    slowMo?: number;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+}
+/**
+ * Franklin's social browser driver. Lazy-imports playwright-core so the
+ * rest of the CLI stays fast to start.
+ */
+export declare class SocialBrowser {
+    private context;
+    private page;
+    private lastRefs;
+    private opts;
+    constructor(opts?: BrowserOptions);
+    launch(): Promise<void>;
+    close(): Promise<void>;
+    open(url: string): Promise<void>;
+    /**
+     * Capture the page as a flat [N-M] ref tree (social-bot style).
+     * Also stores the ref map internally so click(ref) can find the node.
+     */
+    snapshot(): Promise<string>;
+    /**
+     * Click by ref from the last snapshot. Throws if the ref isn't known.
+     * The ref map is reset on every snapshot() call.
+     */
+    click(ref: string): Promise<void>;
+    clickXY(x: number, y: number): Promise<void>;
+    /**
+     * Type text into the currently focused element. Safe against any content
+     * in `text` — Playwright passes it as argv, not through a shell.
+     */
+    type(text: string): Promise<void>;
+    press(key: string): Promise<void>;
+    scroll(x: number, y: number, dx: number, dy: number): Promise<void>;
+    screenshot(filePath: string): Promise<void>;
+    getUrl(): Promise<string>;
+    getTitle(): Promise<string>;
+    waitForTimeout(ms: number): Promise<void>;
+    /**
+     * Block until the user closes the browser tab (used by the login flow).
+     * Resolves when the context is closed.
+     */
+    waitForClose(): Promise<void>;
+    private requirePage;
+}
+export {};

package/dist/social/browser.js

@@ -0,0 +1,219 @@
+/**
+ * Native Playwright-core wrapper for Franklin's social subsystem.
+ *
+ * Mirrors the 9 browser primitives social-bot exposes via its `browse` CLI
+ * (open, snapshot, click, type, press, scroll, screenshot, getUrl, close).
+ * Persistent context so login state survives across runs:
+ *
+ *   ~/.blockrun/social-chrome-profile/
+ *
+ * Unlike social-bot's shell=True subprocess calls, every interaction goes
+ * through Playwright's argv-based API — no shell injection surface even if
+ * the LLM generates `$(rm -rf /)` as reply text.
+ */
+import path from 'node:path';
+import fs from 'node:fs';
+import os from 'node:os';
+// ─── Persistent profile location ───────────────────────────────────────────
+export const SOCIAL_PROFILE_DIR = path.join(os.homedir(), '.blockrun', 'social-chrome-profile');
+function ensureProfileDir() {
+    if (!fs.existsSync(SOCIAL_PROFILE_DIR)) {
+        fs.mkdirSync(SOCIAL_PROFILE_DIR, { recursive: true });
+    }
+}
+/**
+ * Walk an AX tree and produce:
+ *   1. A flat text dump with [depth-idx] refs (for regex-based element finding)
+ *   2. A map of ref ID → role/name/selector for click-by-ref lookups
+ *
+ * The flat text shape intentionally mirrors social-bot's `browse snapshot`
+ * output so code patterns and regexes are directly portable.
+ */
+export function serializeAxTree(root) {
+    const lines = [];
+    const refs = new Map();
+    // Counter per-depth so each depth gets sequential indexes
+    const depthCounters = [];
+    // Counter per (role,name) to disambiguate multiple same-named elements
+    const nameOccurrences = new Map();
+    function walk(node, depth) {
+        if (!node)
+            return;
+        const role = node.role || '';
+        const name = (node.name || '').trim().slice(0, 120);
+        // Skip uninteresting nodes — they'd pollute the tree
+        const isInteresting = role && role !== 'none' && role !== 'presentation' && role !== 'generic';
+        if (isInteresting) {
+            while (depthCounters.length <= depth)
+                depthCounters.push(0);
+            const idx = depthCounters[depth]++;
+            const id = `${depth}-${idx}`;
+            const labelStr = name || (node.value || '').trim().slice(0, 120);
+            const indent = '  '.repeat(depth);
+            lines.push(`${indent}[${id}] ${role}: ${labelStr}`);
+            // Build a Playwright locator. Prefer getByRole+name, fall back to
+            // nth match if there are duplicates.
+            const key = `${role}||${labelStr}`;
+            const occ = nameOccurrences.get(key) || 0;
+            nameOccurrences.set(key, occ + 1);
+            let selector;
+            if (labelStr) {
+                // Escape quotes in the name
+                const escaped = labelStr.replace(/"/g, '\\"');
+                selector = occ === 0
+                    ? `role=${role}[name="${escaped}"]`
+                    : `role=${role}[name="${escaped}"] >> nth=${occ}`;
+            }
+            else {
+                selector = `role=${role} >> nth=${idx}`;
+            }
+            refs.set(id, { id, role, name: labelStr, selector });
+        }
+        if (node.children) {
+            for (const child of node.children) {
+                walk(child, isInteresting ? depth + 1 : depth);
+            }
+        }
+    }
+    walk(root, 0);
+    return { tree: lines.join('\n'), refs };
+}
+/**
+ * Franklin's social browser driver. Lazy-imports playwright-core so the
+ * rest of the CLI stays fast to start.
+ */
+export class SocialBrowser {
+    context = null;
+    page = null;
+    lastRefs = new Map();
+    opts;
+    constructor(opts = {}) {
+        this.opts = {
+            headless: opts.headless ?? false,
+            channel: opts.channel ?? 'chrome',
+            slowMo: opts.slowMo ?? 150,
+            viewport: opts.viewport ?? { width: 1280, height: 900 },
+        };
+    }
+    async launch() {
+        ensureProfileDir();
+        // Lazy import — playwright-core is ~2MB and we don't want to pay the
+        // import cost on every franklin command (e.g. `franklin --version`)
+        const { chromium } = await import('playwright-core');
+        try {
+            this.context = await chromium.launchPersistentContext(SOCIAL_PROFILE_DIR, {
+                headless: this.opts.headless,
+                channel: this.opts.channel,
+                slowMo: this.opts.slowMo,
+                viewport: this.opts.viewport,
+                // Pretend to be a regular Chrome (not headless fingerprint)
+                args: [
+                    '--disable-blink-features=AutomationControlled',
+                    '--no-default-browser-check',
+                ],
+            });
+        }
+        catch (err) {
+            const msg = err.message;
+            if (msg.includes('Executable doesn') || msg.includes("wasn't found")) {
+                throw new Error(`Chrome/Chromium not found. Run:\n  franklin social setup\n\n` +
+                    `Or install manually:\n  npx playwright install chromium\n\n` +
+                    `Original error: ${msg}`);
+            }
+            throw err;
+        }
+        // Reuse existing tab if any, else open new
+        const existing = this.context.pages();
+        this.page = existing.length > 0 ? existing[0] : await this.context.newPage();
+    }
+    async close() {
+        if (this.context) {
+            await this.context.close().catch(() => { });
+            this.context = null;
+            this.page = null;
+        }
+    }
+    // ─── Primitives ────────────────────────────────────────────────────────
+    async open(url) {
+        this.requirePage();
+        await this.page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 });
+    }
+    /**
+     * Capture the page as a flat [N-M] ref tree (social-bot style).
+     * Also stores the ref map internally so click(ref) can find the node.
+     */
+    async snapshot() {
+        this.requirePage();
+        // Playwright's accessibility snapshot returns a full AX tree
+        const axRoot = await this.page.accessibility.snapshot({ interestingOnly: false });
+        if (!axRoot)
+            return '';
+        const { tree, refs } = serializeAxTree(axRoot);
+        this.lastRefs = refs;
+        return tree;
+    }
+    /**
+     * Click by ref from the last snapshot. Throws if the ref isn't known.
+     * The ref map is reset on every snapshot() call.
+     */
+    async click(ref) {
+        this.requirePage();
+        const axRef = this.lastRefs.get(ref);
+        if (!axRef) {
+            throw new Error(`Unknown ref "${ref}". Refs are only valid until the next snapshot() call. Known refs: ${this.lastRefs.size}`);
+        }
+        await this.page.locator(axRef.selector).first().click({ timeout: 15000 });
+    }
+    async clickXY(x, y) {
+        this.requirePage();
+        await this.page.mouse.click(x, y);
+    }
+    /**
+     * Type text into the currently focused element. Safe against any content
+     * in `text` — Playwright passes it as argv, not through a shell.
+     */
+    async type(text) {
+        this.requirePage();
+        await this.page.keyboard.type(text, { delay: 20 });
+    }
+    async press(key) {
+        this.requirePage();
+        await this.page.keyboard.press(key);
+    }
+    async scroll(x, y, dx, dy) {
+        this.requirePage();
+        await this.page.mouse.move(x, y);
+        await this.page.mouse.wheel(dx, dy);
+    }
+    async screenshot(filePath) {
+        this.requirePage();
+        await this.page.screenshot({ path: filePath, fullPage: false });
+    }
+    async getUrl() {
+        this.requirePage();
+        return this.page.url();
+    }
+    async getTitle() {
+        this.requirePage();
+        return this.page.title();
+    }
+    async waitForTimeout(ms) {
+        this.requirePage();
+        await this.page.waitForTimeout(ms);
+    }
+    /**
+     * Block until the user closes the browser tab (used by the login flow).
+     * Resolves when the context is closed.
+     */
+    async waitForClose() {
+        this.requirePage();
+        await new Promise((resolve) => {
+            this.context.on('close', () => resolve());
+            this.page.on('close', () => resolve());
+        });
+    }
+    requirePage() {
+        if (!this.page)
+            throw new Error('SocialBrowser not launched — call launch() first');
+    }
+}

package/dist/social/config.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Typed config for Franklin's social subsystem.
+ * Stored at ~/.blockrun/social-config.json. Default written on first run.
+ */
+export interface ProductConfig {
+    name: string;
+    description: string;
+    trigger_keywords: string[];
+}
+export interface SocialConfig {
+    version: 1;
+    handle: string;
+    products: ProductConfig[];
+    x: {
+        search_queries: string[];
+        daily_target: number;
+        min_delay_seconds: number;
+        max_length: number;
+        login_detection: string;
+    };
+    reply_style: {
+        rules: string[];
+        model_tier: 'free' | 'cheap' | 'premium';
+    };
+}
+export declare const CONFIG_PATH: string;
+/**
+ * Load config from disk. If missing, write defaults and return them.
+ * Returns the parsed config or throws on malformed JSON.
+ */
+export declare function loadConfig(): SocialConfig;
+/**
+ * Persist config back to disk.
+ */
+export declare function saveConfig(cfg: SocialConfig): void;
+/**
+ * Whether the config is "ready" to run — has a handle and at least one
+ * product with keywords.
+ */
+export declare function isConfigReady(cfg: SocialConfig): {
+    ready: boolean;
+    reason?: string;
+};

package/dist/social/config.js

@@ -0,0 +1,83 @@
+/**
+ * Typed config for Franklin's social subsystem.
+ * Stored at ~/.blockrun/social-config.json. Default written on first run.
+ */
+import path from 'node:path';
+import fs from 'node:fs';
+import os from 'node:os';
+export const CONFIG_PATH = path.join(os.homedir(), '.blockrun', 'social-config.json');
+const DEFAULT_CONFIG = {
+    version: 1,
+    handle: '',
+    products: [
+        {
+            name: 'Your Product',
+            description: 'Replace this with a one-paragraph description of what your product does, ' +
+                'who it is for, and what pain it solves. Franklin will use this verbatim as ' +
+                'the AI persona when replying to relevant posts.',
+            trigger_keywords: [],
+        },
+    ],
+    x: {
+        search_queries: [],
+        daily_target: 20,
+        min_delay_seconds: 300,
+        max_length: 260,
+        login_detection: '',
+    },
+    reply_style: {
+        rules: [
+            'Sound like a real human with experience, not a bot',
+            'Be specific — reference details from the post you are replying to',
+            'Maximum 2-3 sentences, conversational tone',
+            'No marketing speak, no emojis, no hashtags',
+            'If the product fits naturally, mention it once and only once',
+            'If the product does not fit, reply with just: SKIP',
+        ],
+        model_tier: 'cheap',
+    },
+};
+/**
+ * Load config from disk. If missing, write defaults and return them.
+ * Returns the parsed config or throws on malformed JSON.
+ */
+export function loadConfig() {
+    const dir = path.dirname(CONFIG_PATH);
+    if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true });
+    if (!fs.existsSync(CONFIG_PATH)) {
+        fs.writeFileSync(CONFIG_PATH, JSON.stringify(DEFAULT_CONFIG, null, 2));
+        return { ...DEFAULT_CONFIG };
+    }
+    const raw = fs.readFileSync(CONFIG_PATH, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (parsed.version !== 1) {
+        throw new Error(`Unsupported social config version ${parsed.version} (expected 1)`);
+    }
+    return parsed;
+}
+/**
+ * Persist config back to disk.
+ */
+export function saveConfig(cfg) {
+    const dir = path.dirname(CONFIG_PATH);
+    if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(CONFIG_PATH, JSON.stringify(cfg, null, 2));
+}
+/**
+ * Whether the config is "ready" to run — has a handle and at least one
+ * product with keywords.
+ */
+export function isConfigReady(cfg) {
+    if (!cfg.handle)
+        return { ready: false, reason: 'handle not set' };
+    if (cfg.products.length === 0)
+        return { ready: false, reason: 'no products configured' };
+    const hasKeywords = cfg.products.some((p) => p.trigger_keywords.length > 0);
+    if (!hasKeywords)
+        return { ready: false, reason: 'no trigger keywords on any product' };
+    if (cfg.x.search_queries.length === 0)
+        return { ready: false, reason: 'no x.search_queries configured' };
+    return { ready: true };
+}