@blockrun/franklin 3.0.0

package/dist/mcp/config.js

@@ -0,0 +1,138 @@
+/**
+ * MCP configuration management for runcode.
+ * Loads MCP server configs from:
+ * 1. Global: ~/.blockrun/mcp.json
+ * 2. Project: .mcp.json in working directory
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+import { BLOCKRUN_DIR } from '../config.js';
+const GLOBAL_MCP_FILE = path.join(BLOCKRUN_DIR, 'mcp.json');
+/**
+ * Load MCP server configurations from global + project files.
+ * Project config overrides global for same server name.
+ */
+// Built-in MCP server: @blockrun/mcp available when globally installed
+// Uses `blockrun-mcp` binary instead of `npx` for fast startup
+const BUILTIN_MCP_SERVERS = {
+    blockrun: {
+        transport: 'stdio',
+        command: 'blockrun-mcp',
+        args: [],
+        label: 'BlockRun (built-in)',
+    },
+    unbrowse: {
+        transport: 'stdio',
+        command: 'unbrowse',
+        args: ['mcp'],
+        label: 'Unbrowse (built-in)',
+    },
+};
+function isCommandAvailable(cmd) {
+    try {
+        execSync(`which ${cmd}`, { stdio: 'pipe' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function loadMcpConfig(workDir) {
+    // Start with built-in servers (only if their binary is available)
+    const servers = {};
+    for (const [name, config] of Object.entries(BUILTIN_MCP_SERVERS)) {
+        if (config.command && isCommandAvailable(config.command)) {
+            servers[name] = config;
+        }
+    }
+    // 1. Global config
+    try {
+        if (fs.existsSync(GLOBAL_MCP_FILE)) {
+            const raw = JSON.parse(fs.readFileSync(GLOBAL_MCP_FILE, 'utf-8'));
+            if (raw.mcpServers && typeof raw.mcpServers === 'object') {
+                Object.assign(servers, raw.mcpServers);
+            }
+        }
+    }
+    catch {
+        // Ignore corrupt global config
+    }
+    // 2. Project config (.mcp.json in working directory)
+    // Security: project configs can execute arbitrary commands via stdio transport.
+    // Only load if a trust marker exists (user has explicitly opted in).
+    const projectMcpFile = path.join(workDir, '.mcp.json');
+    const trustMarker = path.join(BLOCKRUN_DIR, 'trusted-projects.json');
+    try {
+        if (fs.existsSync(projectMcpFile)) {
+            // Check if this project directory is trusted
+            let trusted = false;
+            try {
+                if (fs.existsSync(trustMarker)) {
+                    const trustedDirs = JSON.parse(fs.readFileSync(trustMarker, 'utf-8'));
+                    trusted = Array.isArray(trustedDirs) && trustedDirs.includes(workDir);
+                }
+            }
+            catch { /* not trusted */ }
+            if (trusted) {
+                const raw = JSON.parse(fs.readFileSync(projectMcpFile, 'utf-8'));
+                if (raw.mcpServers && typeof raw.mcpServers === 'object') {
+                    Object.assign(servers, raw.mcpServers);
+                }
+            }
+            // If not trusted, silently skip project config (user must run /mcp trust)
+        }
+    }
+    catch {
+        // Ignore corrupt project config
+    }
+    return { mcpServers: servers };
+}
+/**
+ * Save a server config to the global MCP config.
+ */
+export function saveMcpServer(name, config) {
+    const existing = loadGlobalMcpConfig();
+    existing.mcpServers[name] = config;
+    fs.mkdirSync(BLOCKRUN_DIR, { recursive: true });
+    fs.writeFileSync(GLOBAL_MCP_FILE, JSON.stringify(existing, null, 2) + '\n');
+}
+/**
+ * Remove a server from the global MCP config.
+ */
+export function removeMcpServer(name) {
+    const existing = loadGlobalMcpConfig();
+    if (!(name in existing.mcpServers))
+        return false;
+    delete existing.mcpServers[name];
+    fs.writeFileSync(GLOBAL_MCP_FILE, JSON.stringify(existing, null, 2) + '\n');
+    return true;
+}
+/**
+ * Trust a project directory to load its .mcp.json.
+ */
+export function trustProjectDir(workDir) {
+    const trustMarker = path.join(BLOCKRUN_DIR, 'trusted-projects.json');
+    let trusted = [];
+    try {
+        if (fs.existsSync(trustMarker)) {
+            trusted = JSON.parse(fs.readFileSync(trustMarker, 'utf-8'));
+        }
+    }
+    catch { /* fresh */ }
+    if (!trusted.includes(workDir)) {
+        trusted.push(workDir);
+        fs.mkdirSync(BLOCKRUN_DIR, { recursive: true });
+        fs.writeFileSync(trustMarker, JSON.stringify(trusted, null, 2));
+    }
+}
+function loadGlobalMcpConfig() {
+    try {
+        if (fs.existsSync(GLOBAL_MCP_FILE)) {
+            const raw = JSON.parse(fs.readFileSync(GLOBAL_MCP_FILE, 'utf-8'));
+            return { mcpServers: raw.mcpServers || {} };
+        }
+    }
+    catch { /* fresh */ }
+    return { mcpServers: {} };
+}

package/dist/plugin-sdk/channel.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Channel contract — abstraction over messaging/social platforms.
+ *
+ * Channels are platforms where messages can be searched and posted:
+ * Reddit, X/Twitter, Telegram, Slack, Discord, HackerNews, etc.
+ *
+ * Workflows interact with channels through this contract — never with
+ * platform-specific code directly.
+ */
+/** A message to be posted on a channel */
+export interface ChannelMessage {
+    /** Plain text content */
+    text: string;
+    /** Optional image URL or local path */
+    image?: string;
+    /** Reply to a specific post (URL or platform-specific id) */
+    inReplyTo?: string;
+    /** Platform-specific metadata (e.g. subreddit name for Reddit) */
+    metadata?: Record<string, unknown>;
+}
+/** A post discovered via channel search */
+export interface ChannelPost {
+    /** Post URL */
+    url: string;
+    /** Post id (platform-specific) */
+    id: string;
+    /** Post title (or first line for X) */
+    title: string;
+    /** Post body */
+    body: string;
+    /** Author username */
+    author?: string;
+    /** Created timestamp (ISO) */
+    createdAt?: string;
+    /** Engagement metrics */
+    score?: number;
+    /** Reply/comment count */
+    commentCount?: number;
+    /** Platform identifier */
+    platform: string;
+    /** Platform-specific raw data */
+    raw?: Record<string, unknown>;
+}
+/** Channel search result wrapper */
+export interface ChannelSearchResult {
+    posts: ChannelPost[];
+    /** Total found (may be larger than posts.length if paginated) */
+    total: number;
+}
+/** Channel context provided by core */
+export interface ChannelContext {
+    /** Channel-specific auth/config from user settings */
+    auth?: ChannelAuth;
+    /** Logger */
+    log: (message: string) => void;
+    /** Dry-run mode — channels should not actually post */
+    dryRun: boolean;
+}
+/** Auth blob — channel-specific shape */
+export interface ChannelAuth {
+    /** Auth method */
+    method: 'browser' | 'api' | 'oauth' | 'none';
+    /** Browser cookies (for browser auth) */
+    cookies?: string;
+    /** API token (for api auth) */
+    token?: string;
+    /** OAuth refresh token */
+    refreshToken?: string;
+    /** Username on the platform */
+    username?: string;
+    /** Platform-specific extra fields */
+    extra?: Record<string, unknown>;
+}
+/**
+ * Channel interface — implemented by channel plugins.
+ * Each channel knows how to search and post on its platform.
+ */
+export interface Channel {
+    /** Channel id (e.g. "reddit", "x", "telegram") */
+    readonly id: string;
+    /** Display name */
+    readonly name: string;
+    /** Search posts on this channel */
+    search(query: string, ctx: ChannelContext, options?: {
+        maxResults?: number;
+        /** Platform-specific scope (e.g. subreddit for Reddit) */
+        scope?: string[];
+    }): Promise<ChannelSearchResult>;
+    /** Post a message (or reply) on this channel */
+    post(message: ChannelMessage, ctx: ChannelContext): Promise<{
+        /** URL of the posted message */
+        url: string;
+        /** Platform-specific id */
+        id: string;
+    }>;
+    /** Check if the channel is properly authenticated */
+    isAuthenticated(ctx: ChannelContext): Promise<boolean>;
+    /** Optional: rate limiting hint (min seconds between posts) */
+    readonly minDelaySeconds?: number;
+}

package/dist/plugin-sdk/channel.js

@@ -0,0 +1,10 @@
+/**
+ * Channel contract — abstraction over messaging/social platforms.
+ *
+ * Channels are platforms where messages can be searched and posted:
+ * Reddit, X/Twitter, Telegram, Slack, Discord, HackerNews, etc.
+ *
+ * Workflows interact with channels through this contract — never with
+ * platform-specific code directly.
+ */
+export {};

package/dist/plugin-sdk/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * RunCode Plugin SDK — public surface for plugins.
+ *
+ * Plugins import ONLY from '@blockrun/runcode/plugin-sdk' (or this barrel).
+ * They MUST NOT import from src/** of core or other plugins.
+ *
+ * Core stays plugin-agnostic: adding a plugin should never require editing core.
+ */
+export type { Plugin, PluginManifest, PluginContext, PluginCommand, PluginCommandHandler, } from './plugin.js';
+export type { Workflow, WorkflowStep, WorkflowStepContext, WorkflowStepResult, WorkflowResult, WorkflowConfig, ModelTier, ModelTierConfig, WorkflowStepStatus, OnboardingQuestion, } from './workflow.js';
+export { DEFAULT_MODEL_TIERS } from './workflow.js';
+export type { Channel, ChannelContext, ChannelMessage, ChannelPost, ChannelSearchResult, ChannelAuth, } from './channel.js';
+export type { WorkflowTracker, TrackedAction, WorkflowStats, } from './tracker.js';
+export type { SearchResult } from './search.js';

package/dist/plugin-sdk/index.js

@@ -0,0 +1,9 @@
+/**
+ * RunCode Plugin SDK — public surface for plugins.
+ *
+ * Plugins import ONLY from '@blockrun/runcode/plugin-sdk' (or this barrel).
+ * They MUST NOT import from src/** of core or other plugins.
+ *
+ * Core stays plugin-agnostic: adding a plugin should never require editing core.
+ */
+export { DEFAULT_MODEL_TIERS } from './workflow.js';

package/dist/plugin-sdk/plugin.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Plugin contract — what every plugin must export.
+ *
+ * Plugins are discovered by their manifest file (plugin.json) and loaded
+ * dynamically. Core code never references plugins by name.
+ */
+import type { Workflow } from './workflow.js';
+import type { Channel } from './channel.js';
+/** Plugin manifest (plugin.json) */
+export interface PluginManifest {
+    /** Unique plugin id (e.g. "social", "trading") */
+    id: string;
+    /** Display name */
+    name: string;
+    /** Short description */
+    description: string;
+    /** Semantic version */
+    version: string;
+    /** Plugin type — what surfaces it provides */
+    provides: PluginProvides;
+    /** Entry point (relative to manifest) */
+    entry: string;
+    /** Author info */
+    author?: string;
+    /** Homepage URL */
+    homepage?: string;
+    /** License */
+    license?: string;
+    /** Required runcode version (semver range) */
+    runcodeVersion?: string;
+}
+export interface PluginProvides {
+    /** This plugin contributes one or more workflows (e.g. "social", "trading") */
+    workflows?: string[];
+    /** This plugin contributes channels (e.g. "reddit", "x", "telegram") */
+    channels?: string[];
+    /** This plugin contributes CLI commands */
+    commands?: string[];
+}
+/** Plugin entry point — exported as default from plugin's entry file */
+export interface Plugin {
+    /** Manifest (loaded from plugin.json — plugin doesn't need to repeat it) */
+    manifest: PluginManifest;
+    /** Workflows this plugin provides (mapped by workflow id) */
+    workflows?: Record<string, () => Workflow>;
+    /** Channels this plugin provides (mapped by channel id) */
+    channels?: Record<string, () => Channel>;
+    /** Custom CLI commands */
+    commands?: PluginCommand[];
+    /** Called once when plugin is loaded (optional) */
+    onLoad?: (ctx: PluginContext) => void | Promise<void>;
+    /** Called when plugin is unloaded (optional) */
+    onUnload?: () => void | Promise<void>;
+}
+/** Context passed to plugin lifecycle hooks */
+export interface PluginContext {
+    /** RunCode version */
+    runcodeVersion: string;
+    /** Plugin's own data directory (~/.blockrun/plugins/<id>/) */
+    dataDir: string;
+    /** Path to plugin's installation directory */
+    pluginDir: string;
+    /** Logger */
+    log: (message: string) => void;
+}
+/** A CLI command contributed by a plugin */
+export interface PluginCommand {
+    /** Command name (e.g. "init", "run", "stats") */
+    name: string;
+    /** Description shown in help */
+    description: string;
+    /** Optional flags */
+    options?: Array<{
+        flag: string;
+        description: string;
+    }>;
+    /** Handler — receives parsed args and plugin context */
+    handler: PluginCommandHandler;
+}
+export type PluginCommandHandler = (args: {
+    /** Positional arguments */
+    positional: string[];
+    /** Parsed flags */
+    flags: Record<string, string | boolean>;
+    /** Plugin context */
+    ctx: PluginContext;
+}) => Promise<void> | void;

package/dist/plugin-sdk/plugin.js

@@ -0,0 +1,7 @@
+/**
+ * Plugin contract — what every plugin must export.
+ *
+ * Plugins are discovered by their manifest file (plugin.json) and loaded
+ * dynamically. Core code never references plugins by name.
+ */
+export {};

package/dist/plugin-sdk/search.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Search result type — used by both web search (Exa/WebSearch) and channels.
+ */
+export interface SearchResult {
+    title: string;
+    url: string;
+    snippet: string;
+    source: string;
+    author?: string;
+    timestamp?: string;
+    score?: number;
+    commentCount?: number;
+}

package/dist/plugin-sdk/search.js

@@ -0,0 +1,4 @@
+/**
+ * Search result type — used by both web search (Exa/WebSearch) and channels.
+ */
+export {};

package/dist/plugin-sdk/tracker.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Tracker contract — workflows record actions for dedup, stats, and history.
+ * Core provides a default implementation; plugins use it via WorkflowStepContext.
+ */
+export interface TrackedAction {
+    workflow: string;
+    action: string;
+    key: string;
+    metadata: Record<string, unknown>;
+    costUsd: number;
+    createdAt: string;
+}
+export interface WorkflowStats {
+    totalRuns: number;
+    totalActions: number;
+    totalCostUsd: number;
+    todayActions: number;
+    todayCostUsd: number;
+    lastRun?: string;
+    byAction: Record<string, number>;
+}
+export interface WorkflowTracker {
+    trackAction(action: string, key: string, metadata: Record<string, unknown>, costUsd?: number): void;
+    isDuplicate(key: string): boolean;
+    getStats(): WorkflowStats;
+    getByAction(action: string): TrackedAction[];
+}

package/dist/plugin-sdk/tracker.js

@@ -0,0 +1,5 @@
+/**
+ * Tracker contract — workflows record actions for dedup, stats, and history.
+ * Core provides a default implementation; plugins use it via WorkflowStepContext.
+ */
+export {};

package/dist/plugin-sdk/workflow.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Workflow contract — public surface for plugins implementing workflows.
+ *
+ * A workflow is a multi-step AI process: search → filter → generate → execute → track.
+ * Plugins implement Workflow; core orchestrates execution and provides infrastructure.
+ */
+import type { SearchResult } from './search.js';
+import type { ChannelMessage } from './channel.js';
+/** Model selection tier — workflows pick tier per step, core resolves to actual model */
+export type ModelTier = 'free' | 'cheap' | 'premium' | 'none';
+/** Maps tier names to actual model identifiers */
+export interface ModelTierConfig {
+    free: string;
+    cheap: string;
+    premium: string;
+}
+export declare const DEFAULT_MODEL_TIERS: ModelTierConfig;
+/** Context provided to each workflow step by core */
+export interface WorkflowStepContext {
+    /** Accumulated data from previous steps (mutable across steps) */
+    data: Record<string, unknown>;
+    /** Call an LLM at the specified tier */
+    callModel: (tier: ModelTier, prompt: string, system?: string) => Promise<string>;
+    /** Generate an image (DALL-E / Flux) */
+    generateImage?: (prompt: string) => Promise<string>;
+    /** Search the web (Exa neural / WebSearch fallback) */
+    search: (query: string, options?: {
+        sources?: string[];
+        maxResults?: number;
+    }) => Promise<SearchResult[]>;
+    /** Send a message via a channel (e.g. reddit, x, telegram) */
+    sendMessage?: (channelId: string, message: ChannelMessage) => Promise<void>;
+    /** Log progress (visible to user) */
+    log: (message: string) => void;
+    /** Track an action in the workflow's database */
+    track: (action: string, metadata: Record<string, unknown>) => Promise<void>;
+    /** Check if a key was already processed (dedup) */
+    isDuplicate: (key: string) => Promise<boolean>;
+    /** Dry-run mode — skip side effects */
+    dryRun: boolean;
+    /** Workflow config (typed by the workflow) */
+    config: WorkflowConfig;
+}
+/** Result of executing one step */
+export interface WorkflowStepResult {
+    /** Data to merge into shared context for subsequent steps */
+    data?: Record<string, unknown>;
+    /** Human-readable summary of what this step did */
+    summary?: string;
+    /** If true, abort the workflow */
+    abort?: boolean;
+    /** Cost of this step in USD */
+    cost?: number;
+}
+/** A single step in a workflow */
+export interface WorkflowStep {
+    /** Step name (used for tracking and display) */
+    name: string;
+    /** Which model tier this step uses (or 'none', or 'dynamic' for runtime decision) */
+    modelTier: ModelTier | 'dynamic';
+    /** Execute this step */
+    execute: (ctx: WorkflowStepContext) => Promise<WorkflowStepResult>;
+    /** Skip this step in dry-run mode (e.g. posting) */
+    skipInDryRun?: boolean;
+}
+/** Base workflow config — workflows extend this with their own fields */
+export interface WorkflowConfig {
+    /** Workflow id (matches plugin id) */
+    name: string;
+    /** Model tier mapping */
+    models: ModelTierConfig;
+    /** Optional schedule */
+    schedule?: {
+        cron?: string;
+        dailyTime?: string;
+        budgetCapUsd?: number;
+    };
+    /** Allow workflow-specific fields */
+    [key: string]: unknown;
+}
+export interface WorkflowResult {
+    steps: Array<{
+        name: string;
+        summary: string;
+        cost: number;
+        status?: WorkflowStepStatus;
+    }>;
+    totalCost: number;
+    itemsProcessed: number;
+    durationMs: number;
+    dryRun: boolean;
+}
+/** Normalized status for step rendering/reporting */
+export type WorkflowStepStatus = 'ok' | 'error' | 'aborted' | 'skipped';
+/**
+ * The Workflow interface plugins implement.
+ * Core's WorkflowRunner orchestrates execution of any Workflow.
+ */
+export interface Workflow {
+    /** Workflow id (e.g. "social", "trading") */
+    readonly id: string;
+    /** Display name */
+    readonly name: string;
+    /** Short description */
+    readonly description: string;
+    /** Steps in execution order */
+    readonly steps: WorkflowStep[];
+    /** Default config (used when not yet configured) */
+    defaultConfig(): WorkflowConfig;
+    /** Onboarding questions for first-time setup */
+    readonly onboardingQuestions: OnboardingQuestion[];
+    /** Build config from onboarding answers (may call cheap LLM to auto-generate) */
+    buildConfigFromAnswers(answers: Record<string, string>, llm: (prompt: string) => Promise<string>): Promise<WorkflowConfig>;
+    /** Optional: lifecycle hook before workflow runs (e.g. to load state) */
+    beforeRun?(config: WorkflowConfig): Promise<void>;
+    /** Optional: lifecycle hook after workflow runs */
+    afterRun?(result: WorkflowResult): Promise<void>;
+}
+/** Question for interactive onboarding */
+export interface OnboardingQuestion {
+    id: string;
+    prompt: string;
+    type: 'text' | 'select' | 'multi-select';
+    options?: string[];
+    default?: string;
+}

package/dist/plugin-sdk/workflow.js

@@ -0,0 +1,11 @@
+/**
+ * Workflow contract — public surface for plugins implementing workflows.
+ *
+ * A workflow is a multi-step AI process: search → filter → generate → execute → track.
+ * Plugins implement Workflow; core orchestrates execution and provides infrastructure.
+ */
+export const DEFAULT_MODEL_TIERS = {
+    free: 'nvidia/nemotron-ultra-253b',
+    cheap: 'zai/glm-5.1',
+    premium: 'anthropic/claude-sonnet-4.6',
+};

package/dist/plugins/registry.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Plugin Registry — discovers, loads, and manages plugins.
+ *
+ * Core stays plugin-agnostic: it knows about the *interface*, not specific plugins.
+ * Plugins are discovered from:
+ *   1. Bundled: <runcode>/plugins-bundled/* (ships with runcode)
+ *   2. User: ~/.blockrun/plugins/* (installed via `runcode plugin install`)
+ *   3. Local dev: $RUNCODE_PLUGINS_DIR/* (env var for development)
+ */
+import type { Plugin, PluginManifest } from '../plugin-sdk/plugin.js';
+export declare function getBundledPluginsDir(): string;
+export declare function getUserPluginsDir(): string;
+interface LoadedPlugin {
+    manifest: PluginManifest;
+    pluginDir: string;
+    plugin: Plugin;
+}
+/** Find all plugin manifests across discovery paths */
+export declare function discoverPluginManifests(): Array<{
+    manifest: PluginManifest;
+    dir: string;
+}>;
+/** Load a single plugin from its directory */
+export declare function loadPlugin(manifest: PluginManifest, pluginDir: string): Promise<Plugin | null>;
+/** Discover and load all plugins. Returns the loaded registry. */
+export declare function loadAllPlugins(): Promise<Map<string, LoadedPlugin>>;
+export declare function getPlugin(id: string): LoadedPlugin | undefined;
+export declare function listPlugins(): LoadedPlugin[];
+/** Get all plugins that provide workflows */
+export declare function listWorkflowPlugins(): LoadedPlugin[];
+/** Get all plugins that provide channels */
+export declare function listChannelPlugins(): LoadedPlugin[];
+export {};