@blockrun/franklin 3.2.3 → 3.3.0

package/dist/learnings/extractor.js

@@ -0,0 +1,234 @@
+/**
+ * Extract user preferences from a completed session trace.
+ * Uses a cheap model to analyze the conversation and produce learnings.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { loadLearnings, mergeLearning, saveLearnings } from './store.js';
+// Cheapest models that reliably output structured JSON
+const EXTRACTION_MODELS = [
+    'google/gemini-2.5-flash-lite',
+    'google/gemini-2.5-flash',
+    'nvidia/nemotron-super-49b',
+];
+const VALID_CATEGORIES = new Set([
+    'language', 'model_preference', 'tool_pattern', 'coding_style',
+    'communication', 'domain', 'correction', 'workflow', 'other',
+]);
+const EXTRACTION_PROMPT = `You are analyzing a conversation between a user and an AI coding agent. Extract user preferences and behavioral patterns that would help personalize future interactions.
+
+Analyze for:
+1. Language — what language does the user write in? (English, Chinese, mixed?)
+2. Model preferences — did they switch models or express a preference?
+3. Coding style — did they correct the agent's code style? (naming, formatting, conventions)
+4. Communication — are they terse or verbose? Do they want explanations or just code?
+5. Domain — what tech stack, frameworks, or project type?
+6. Corrections — did they repeatedly correct the same agent behavior?
+7. Workflow — do they prefer short tasks or long planning sessions?
+
+Rules:
+- ONLY extract signals clearly supported by evidence in the conversation.
+- Do NOT speculate. If evidence is weak, set confidence below 0.5.
+- If the conversation is too short or generic, return an empty array.
+- Each learning should be one clear, actionable sentence.
+
+Respond with ONLY a JSON object (no markdown fences, no commentary):
+{"learnings":[{"learning":"...","category":"language|model_preference|tool_pattern|coding_style|communication|domain|correction|workflow|other","confidence":0.5}]}`;
+/**
+ * Condense session history into a compact text for extraction.
+ * Only includes user messages and assistant text — skips tool calls/results.
+ */
+function condenseHistory(history) {
+    const parts = [];
+    let chars = 0;
+    const CAP = 4000;
+    for (const msg of history) {
+        if (chars >= CAP)
+            break;
+        const role = msg.role === 'user' ? 'User' : 'Assistant';
+        let text = '';
+        if (typeof msg.content === 'string') {
+            text = msg.content;
+        }
+        else if (Array.isArray(msg.content)) {
+            text = msg.content
+                .filter(p => p.type === 'text')
+                .map(p => p.text)
+                .join('\n');
+        }
+        if (!text.trim())
+            continue;
+        // Truncate long messages
+        if (text.length > 500)
+            text = text.slice(0, 500) + '…';
+        const line = `${role}: ${text}`;
+        parts.push(line);
+        chars += line.length;
+    }
+    return parts.join('\n\n');
+}
+/**
+ * Parse JSON from LLM response, handling common quirks
+ * (markdown fences, trailing commas, commentary).
+ */
+function parseExtraction(raw) {
+    // Strip markdown fences
+    let cleaned = raw.replace(/```json\s*/gi, '').replace(/```\s*/g, '').trim();
+    // Find the JSON object
+    const start = cleaned.indexOf('{');
+    const end = cleaned.lastIndexOf('}');
+    if (start === -1 || end === -1)
+        return { learnings: [] };
+    cleaned = cleaned.slice(start, end + 1);
+    const parsed = JSON.parse(cleaned);
+    if (!Array.isArray(parsed.learnings))
+        return { learnings: [] };
+    // Validate and sanitize each entry
+    return {
+        learnings: parsed.learnings
+            .filter((l) => typeof l.learning === 'string' &&
+            typeof l.category === 'string' &&
+            VALID_CATEGORIES.has(l.category) &&
+            typeof l.confidence === 'number' &&
+            l.confidence >= 0.1 && l.confidence <= 1.0 &&
+            l.learning.length > 5)
+            .map((l) => ({
+            learning: l.learning.slice(0, 200),
+            category: l.category,
+            confidence: Math.round(l.confidence * 100) / 100,
+        })),
+    };
+}
+// ─── Onboarding: bootstrap from Claude Code config ───────────────────────
+const BOOTSTRAP_PROMPT = `You are analyzing a user's AI coding agent configuration file (CLAUDE.md). Extract user preferences that would help personalize a different AI agent's behavior.
+
+Analyze for:
+1. Language — what language do they communicate in?
+2. Coding style — naming conventions, formatting, lint rules, type annotations?
+3. Communication — how do they want the agent to behave? (terse? formal? call them something?)
+4. Domain — what tech stack, frameworks, languages do they work with?
+5. Workflow — any specific git, commit, or deployment preferences?
+6. Corrections — any explicit "do NOT" rules or anti-patterns?
+7. Other — any other clear preferences?
+
+Rules:
+- Extract EVERY explicit preference. These are user-written rules, so confidence is high (0.8-1.0).
+- Each learning should be one clear, actionable sentence.
+- Do NOT include project-specific paths or secrets.
+- Do NOT include things that are tool-specific to Claude Code and wouldn't apply to another agent.
+
+Respond with ONLY a JSON object (no markdown fences, no commentary):
+{"learnings":[{"learning":"...","category":"language|model_preference|tool_pattern|coding_style|communication|domain|correction|workflow|other","confidence":0.9}]}`;
+/**
+ * Scan for Claude Code configuration and bootstrap learnings from it.
+ * Only runs once — skips if learnings already exist.
+ */
+export async function bootstrapFromClaudeConfig(client) {
+    // Only bootstrap if no learnings exist yet (first run)
+    const existing = loadLearnings();
+    if (existing.length > 0)
+        return 0;
+    // Scan for Claude Code config files
+    const configPaths = [
+        path.join(os.homedir(), '.claude', 'CLAUDE.md'),
+        path.join(process.cwd(), 'CLAUDE.md'),
+        path.join(process.cwd(), '.claude', 'CLAUDE.md'),
+    ];
+    const contents = [];
+    for (const p of configPaths) {
+        try {
+            const text = fs.readFileSync(p, 'utf-8').trim();
+            if (text && text.length > 20) {
+                contents.push(`--- ${p} ---\n${text}`);
+            }
+        }
+        catch { /* file doesn't exist */ }
+    }
+    if (contents.length === 0)
+        return 0;
+    // Cap total content
+    let combined = contents.join('\n\n');
+    if (combined.length > 6000)
+        combined = combined.slice(0, 6000) + '\n…(truncated)';
+    // Extract learnings
+    let result = null;
+    for (const model of EXTRACTION_MODELS) {
+        try {
+            const response = await client.complete({
+                model,
+                messages: [{ role: 'user', content: combined }],
+                system: BOOTSTRAP_PROMPT,
+                max_tokens: 1500,
+                temperature: 0.2,
+            });
+            const text = response.content
+                .filter((p) => p.type === 'text')
+                .map((p) => p.text)
+                .join('');
+            result = parseExtraction(text);
+            break;
+        }
+        catch {
+            continue;
+        }
+    }
+    if (!result || result.learnings.length === 0)
+        return 0;
+    // Save all bootstrapped learnings
+    let learnings = loadLearnings();
+    for (const entry of result.learnings) {
+        learnings = mergeLearning(learnings, {
+            ...entry,
+            source_session: 'bootstrap:claude-config',
+        });
+    }
+    saveLearnings(learnings);
+    return result.learnings.length;
+}
+// ─── Session extraction ──────────────────────────────────────────────────
+/**
+ * Extract learnings from a completed session.
+ * Runs asynchronously — caller should fire-and-forget.
+ */
+export async function extractLearnings(history, sessionId, client) {
+    // Skip very short sessions
+    if (history.length < 4)
+        return;
+    const condensed = condenseHistory(history);
+    if (condensed.length < 100)
+        return; // Too little content
+    // Try each model until one succeeds
+    let result = null;
+    for (const model of EXTRACTION_MODELS) {
+        try {
+            const response = await client.complete({
+                model,
+                messages: [{ role: 'user', content: condensed }],
+                system: EXTRACTION_PROMPT,
+                max_tokens: 1000,
+                temperature: 0.3,
+            });
+            const text = response.content
+                .filter((p) => p.type === 'text')
+                .map((p) => p.text)
+                .join('');
+            result = parseExtraction(text);
+            break;
+        }
+        catch {
+            continue; // Try next model
+        }
+    }
+    if (!result || result.learnings.length === 0)
+        return;
+    // Merge with existing learnings
+    let existing = loadLearnings();
+    for (const entry of result.learnings) {
+        existing = mergeLearning(existing, {
+            ...entry,
+            source_session: sessionId,
+        });
+    }
+    saveLearnings(existing);
+}

package/dist/learnings/index.d.ts

@@ -0,0 +1,3 @@
+export type { Learning, LearningCategory, ExtractionResult } from './types.js';
+export { loadLearnings, saveLearnings, mergeLearning, decayLearnings, formatForPrompt } from './store.js';
+export { extractLearnings, bootstrapFromClaudeConfig } from './extractor.js';

package/dist/learnings/index.js

@@ -0,0 +1,2 @@
+export { loadLearnings, saveLearnings, mergeLearning, decayLearnings, formatForPrompt } from './store.js';
+export { extractLearnings, bootstrapFromClaudeConfig } from './extractor.js';

package/dist/learnings/store.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Persistence layer for per-user learnings.
+ * Stored as JSONL at ~/.blockrun/learnings.jsonl.
+ */
+import type { Learning, LearningCategory } from './types.js';
+export declare function loadLearnings(): Learning[];
+export declare function saveLearnings(learnings: Learning[]): void;
+export declare function mergeLearning(existing: Learning[], newEntry: {
+    learning: string;
+    category: LearningCategory;
+    confidence: number;
+    source_session: string;
+}): Learning[];
+export declare function decayLearnings(learnings: Learning[]): Learning[];
+export declare function formatForPrompt(learnings: Learning[]): string;

package/dist/learnings/store.js

@@ -0,0 +1,130 @@
+/**
+ * Persistence layer for per-user learnings.
+ * Stored as JSONL at ~/.blockrun/learnings.jsonl.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { BLOCKRUN_DIR } from '../config.js';
+const LEARNINGS_PATH = path.join(BLOCKRUN_DIR, 'learnings.jsonl');
+const MAX_LEARNINGS = 50;
+const DECAY_AFTER_DAYS = 30;
+const DECAY_AMOUNT = 0.15;
+const PRUNE_THRESHOLD = 0.2;
+const MERGE_SIMILARITY = 0.6;
+// ─── Load / Save ──────────────────────────────────────────────────────────
+export function loadLearnings() {
+    try {
+        const raw = fs.readFileSync(LEARNINGS_PATH, 'utf-8');
+        const results = [];
+        for (const line of raw.split('\n')) {
+            if (!line.trim())
+                continue;
+            try {
+                results.push(JSON.parse(line));
+            }
+            catch { /* skip corrupted lines */ }
+        }
+        return results;
+    }
+    catch {
+        return [];
+    }
+}
+export function saveLearnings(learnings) {
+    fs.mkdirSync(BLOCKRUN_DIR, { recursive: true });
+    const tmpPath = LEARNINGS_PATH + '.tmp';
+    const content = learnings.map(l => JSON.stringify(l)).join('\n') + '\n';
+    fs.writeFileSync(tmpPath, content);
+    fs.renameSync(tmpPath, LEARNINGS_PATH);
+}
+// ─── Merge / Dedup ────────────────────────────────────────────────────────
+function tokenize(text) {
+    return new Set(text.toLowerCase().replace(/[^\w\s]/g, '').split(/\s+/).filter(w => w.length > 2));
+}
+function jaccardSimilarity(a, b) {
+    if (a.size === 0 && b.size === 0)
+        return 1;
+    let intersection = 0;
+    for (const w of a)
+        if (b.has(w))
+            intersection++;
+    return intersection / (a.size + b.size - intersection);
+}
+export function mergeLearning(existing, newEntry) {
+    const now = Date.now();
+    const newTokens = tokenize(newEntry.learning);
+    // Find similar existing learning in same category
+    for (const entry of existing) {
+        if (entry.category !== newEntry.category)
+            continue;
+        const similarity = jaccardSimilarity(tokenize(entry.learning), newTokens);
+        if (similarity >= MERGE_SIMILARITY) {
+            // Merge: boost confidence, update timestamp
+            entry.times_confirmed++;
+            entry.last_confirmed = now;
+            entry.confidence = Math.min(entry.confidence + 0.1, 1.0);
+            // Prefer more specific wording
+            if (newEntry.learning.length > entry.learning.length) {
+                entry.learning = newEntry.learning;
+            }
+            return existing;
+        }
+    }
+    // No match — insert new
+    existing.push({
+        id: crypto.randomBytes(8).toString('hex'),
+        learning: newEntry.learning,
+        category: newEntry.category,
+        confidence: newEntry.confidence,
+        source_session: newEntry.source_session,
+        created_at: now,
+        last_confirmed: now,
+        times_confirmed: 1,
+    });
+    // Cap at MAX_LEARNINGS — drop lowest-scoring
+    if (existing.length > MAX_LEARNINGS) {
+        existing.sort((a, b) => score(b) - score(a));
+        existing.length = MAX_LEARNINGS;
+    }
+    return existing;
+}
+function score(l) {
+    return l.confidence * Math.log2(l.times_confirmed + 1);
+}
+// ─── Decay ────────────────────────────────────────────────────────────────
+export function decayLearnings(learnings) {
+    const now = Date.now();
+    const cutoff = DECAY_AFTER_DAYS * 24 * 60 * 60 * 1000;
+    return learnings.filter(l => {
+        if (l.times_confirmed >= 3)
+            return true; // Immune to time decay
+        if (now - l.last_confirmed > cutoff) {
+            l.confidence -= DECAY_AMOUNT;
+            return l.confidence >= PRUNE_THRESHOLD;
+        }
+        return true;
+    });
+}
+// ─── Format for System Prompt ─────────────────────────────────────────────
+const MAX_PROMPT_CHARS = 2000; // ~500 tokens
+export function formatForPrompt(learnings) {
+    if (learnings.length === 0)
+        return '';
+    const sorted = [...learnings].sort((a, b) => score(b) - score(a));
+    const lines = [];
+    let chars = 0;
+    const header = '# Personal Context\nPreferences learned from previous sessions:\n';
+    chars += header.length;
+    for (const l of sorted) {
+        const conf = l.confidence >= 0.8 ? '●' : l.confidence >= 0.5 ? '◐' : '○';
+        const line = `- ${conf} ${l.learning}`;
+        if (chars + line.length + 1 > MAX_PROMPT_CHARS)
+            break;
+        lines.push(line);
+        chars += line.length + 1;
+    }
+    if (lines.length === 0)
+        return '';
+    return header + lines.join('\n');
+}

package/dist/learnings/types.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Types for Franklin's per-user self-evolution system.
+ *
+ * Each user's Franklin learns preferences from session traces and
+ * injects them into the system prompt on next startup.
+ */
+export interface Learning {
+    id: string;
+    learning: string;
+    category: LearningCategory;
+    confidence: number;
+    source_session: string;
+    created_at: number;
+    last_confirmed: number;
+    times_confirmed: number;
+}
+export type LearningCategory = 'language' | 'model_preference' | 'tool_pattern' | 'coding_style' | 'communication' | 'domain' | 'correction' | 'workflow' | 'other';
+export interface ExtractionResult {
+    learnings: Array<{
+        learning: string;
+        category: LearningCategory;
+        confidence: number;
+    }>;
+}

package/dist/learnings/types.js

@@ -0,0 +1,7 @@
+/**
+ * Types for Franklin's per-user self-evolution system.
+ *
+ * Each user's Franklin learns preferences from session traces and
+ * injects them into the system prompt on next startup.
+ */
+export {};

package/dist/narrative/state.d.ts

@@ -0,0 +1,30 @@
+export interface SignalRecord {
+    asset: string;
+    direction: 'bullish' | 'bearish' | 'neutral';
+    confidence: number;
+    summary: string;
+    ts: string;
+}
+export interface PostRecord {
+    platform: string;
+    url: string;
+    text: string;
+    referencesAssets?: string[];
+    ts: string;
+}
+export interface BudgetEnvelope {
+    dailyCapUsd: number;
+    spentTodayUsd: number;
+    date: string;
+}
+export interface NarrativeState {
+    watchlist: string[];
+    recentSignals: SignalRecord[];
+    recentPosts: PostRecord[];
+    budget: BudgetEnvelope;
+}
+export declare function loadNarrative(): NarrativeState;
+export declare function saveNarrative(s: NarrativeState): void;
+export declare function updateNarrative(patch: Partial<NarrativeState>): NarrativeState;
+export declare function addSignal(signal: SignalRecord): void;
+export declare function addPost(post: PostRecord): void;

package/dist/narrative/state.js

@@ -0,0 +1,69 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import os from 'node:os';
+const STORE_DIR = path.join(os.homedir(), '.blockrun');
+const STATE_PATH = path.join(STORE_DIR, 'narrative.json');
+const MAX_ENTRIES = 50;
+let loaded = false;
+let state;
+function today() {
+    return new Date().toISOString().slice(0, 10);
+}
+function defaults() {
+    return {
+        watchlist: [],
+        recentSignals: [],
+        recentPosts: [],
+        budget: { dailyCapUsd: 10, spentTodayUsd: 0, date: today() },
+    };
+}
+export function loadNarrative() {
+    if (loaded)
+        return state;
+    fs.mkdirSync(STORE_DIR, { recursive: true });
+    if (fs.existsSync(STATE_PATH)) {
+        try {
+            state = JSON.parse(fs.readFileSync(STATE_PATH, 'utf8'));
+        }
+        catch {
+            state = defaults();
+        }
+    }
+    else {
+        state = defaults();
+    }
+    if (state.budget.date !== today()) {
+        state.budget.spentTodayUsd = 0;
+        state.budget.date = today();
+    }
+    loaded = true;
+    return state;
+}
+export function saveNarrative(s) {
+    fs.mkdirSync(STORE_DIR, { recursive: true });
+    fs.writeFileSync(STATE_PATH, JSON.stringify(s, null, 2) + '\n');
+    state = s;
+    loaded = true;
+}
+export function updateNarrative(patch) {
+    const cur = loadNarrative();
+    const merged = { ...cur, ...patch };
+    if (patch.recentSignals) {
+        merged.recentSignals = [...patch.recentSignals, ...cur.recentSignals].slice(0, MAX_ENTRIES);
+    }
+    if (patch.recentPosts) {
+        merged.recentPosts = [...patch.recentPosts, ...cur.recentPosts].slice(0, MAX_ENTRIES);
+    }
+    saveNarrative(merged);
+    return merged;
+}
+export function addSignal(signal) {
+    const cur = loadNarrative();
+    cur.recentSignals = [signal, ...cur.recentSignals].slice(0, MAX_ENTRIES);
+    saveNarrative(cur);
+}
+export function addPost(post) {
+    const cur = loadNarrative();
+    cur.recentPosts = [post, ...cur.recentPosts].slice(0, MAX_ENTRIES);
+    saveNarrative(cur);
+}

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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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>;