@blockrun/franklin 3.3.3 → 3.5.0

package/dist/router/selector.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Model selector for the learned router.
+ *
+ * Scoring formula (4 factors):
+ *   score = w_quality    * norm_quality
+ *         + w_cost       * (1 - norm_cost)
+ *         + w_latency    * (1 - norm_latency)
+ *         + w_efficiency * norm_efficiency
+ *
+ * Efficiency = how few tool calls a model needs to complete a task.
+ * A model that does it in 5 calls is better than one that loops 85 times.
+ * Measured as 1/avg_tool_calls_per_turn (higher = more efficient).
+ *
+ * Profile weights:
+ *   auto    — balanced: quality 0.2, cost 0.3, latency 0.25, efficiency 0.25
+ *   eco     — cost-first: quality 0.1, cost 0.6, latency 0.15, efficiency 0.15
+ *   premium — quality-first: quality 0.4, cost 0.1, latency 0.25, efficiency 0.25
+ *   free    — best efficiency among free models
+ */
+import type { Category } from './categories.js';
+import type { RoutingProfile } from './index.js';
+export interface ModelScore {
+    model: string;
+    elo: number;
+    avg_cost_per_1k?: number;
+    avg_latency_ms?: number;
+    avg_tool_calls_per_turn?: number;
+    requests?: number;
+    unique_users?: number;
+}
+export interface LearnedWeights {
+    version: number;
+    trained_on: number;
+    trained_at: string;
+    categories: string[];
+    category_keywords?: Record<string, string[]>;
+    model_scores: Record<string, ModelScore[]>;
+}
+export interface SelectionResult {
+    model: string;
+    score: number;
+    expectedCost: number;
+    expectedLatency: number;
+    category: Category;
+}
+export declare function selectModel(category: Category, profile: RoutingProfile, weights: LearnedWeights): SelectionResult | null;

package/dist/router/selector.js

@@ -0,0 +1,106 @@
+/**
+ * Model selector for the learned router.
+ *
+ * Scoring formula (4 factors):
+ *   score = w_quality    * norm_quality
+ *         + w_cost       * (1 - norm_cost)
+ *         + w_latency    * (1 - norm_latency)
+ *         + w_efficiency * norm_efficiency
+ *
+ * Efficiency = how few tool calls a model needs to complete a task.
+ * A model that does it in 5 calls is better than one that loops 85 times.
+ * Measured as 1/avg_tool_calls_per_turn (higher = more efficient).
+ *
+ * Profile weights:
+ *   auto    — balanced: quality 0.2, cost 0.3, latency 0.25, efficiency 0.25
+ *   eco     — cost-first: quality 0.1, cost 0.6, latency 0.15, efficiency 0.15
+ *   premium — quality-first: quality 0.4, cost 0.1, latency 0.25, efficiency 0.25
+ *   free    — best efficiency among free models
+ */
+import { MODEL_PRICING } from '../pricing.js';
+const PROFILE_WEIGHTS = {
+    auto: { quality: 0.20, cost: 0.30, latency: 0.25, efficiency: 0.25 },
+    eco: { quality: 0.10, cost: 0.60, latency: 0.15, efficiency: 0.15 },
+    premium: { quality: 0.40, cost: 0.10, latency: 0.25, efficiency: 0.25 },
+};
+export function selectModel(category, profile, weights) {
+    const candidates = weights.model_scores[category];
+    if (!candidates || candidates.length === 0)
+        return null;
+    // Enrich with pricing data and defaults
+    const enriched = candidates.map(c => {
+        const pricing = MODEL_PRICING[c.model];
+        const costPer1K = pricing
+            ? (pricing.input + pricing.output) / 2 / 1000
+            : c.avg_cost_per_1k ?? 0.005;
+        const latencyMs = c.avg_latency_ms ?? 2000;
+        // Efficiency: 1/avg_tool_calls (higher = better). Default 10 calls/turn if unknown.
+        const toolCallsPerTurn = c.avg_tool_calls_per_turn ?? 10;
+        const efficiency = 1 / Math.max(1, toolCallsPerTurn);
+        return { ...c, costPer1K, latencyMs, efficiency };
+    });
+    // Filter to models we can actually route to
+    const available = enriched.filter(c => MODEL_PRICING[c.model]);
+    if (available.length === 0)
+        return null;
+    // ── Free profile: best efficiency + latency among free models ──
+    if (profile === 'free') {
+        const free = available.filter(c => c.costPer1K === 0);
+        if (free.length === 0)
+            return null;
+        // Score free models by efficiency (60%) + latency (40%)
+        const maxLat = Math.max(...free.map(c => c.latencyMs)) || 1;
+        const maxEff = Math.max(...free.map(c => c.efficiency)) || 1;
+        const selected = free.reduce((best, c) => {
+            const s = 0.6 * (c.efficiency / maxEff) + 0.4 * (1 - c.latencyMs / maxLat);
+            const bestS = 0.6 * (best.efficiency / maxEff) + 0.4 * (1 - best.latencyMs / maxLat);
+            return s > bestS ? c : best;
+        });
+        return {
+            model: selected.model,
+            score: selected.efficiency,
+            expectedCost: 0,
+            expectedLatency: selected.latencyMs,
+            category,
+        };
+    }
+    // ── Scored profiles: auto / eco / premium ──
+    const w = PROFILE_WEIGHTS[profile] ?? PROFILE_WEIGHTS.auto;
+    // Compute normalization bounds
+    const elos = available.map(c => c.elo);
+    const costs = available.map(c => c.costPer1K);
+    const latencies = available.map(c => c.latencyMs);
+    const efficiencies = available.map(c => c.efficiency);
+    const minElo = Math.min(...elos);
+    const maxElo = Math.max(...elos);
+    const maxCost = Math.max(...costs);
+    const maxLatency = Math.max(...latencies);
+    const maxEfficiency = Math.max(...efficiencies);
+    const eloRange = maxElo - minElo || 1;
+    const costRange = maxCost || 1;
+    const latencyRange = maxLatency || 1;
+    const efficiencyRange = maxEfficiency || 1;
+    let bestScore = -Infinity;
+    let selected = available[0];
+    for (const c of available) {
+        const normQuality = (c.elo - minElo) / eloRange;
+        const normCost = c.costPer1K / costRange;
+        const normLatency = c.latencyMs / latencyRange;
+        const normEfficiency = c.efficiency / efficiencyRange;
+        const score = w.quality * normQuality +
+            w.cost * (1 - normCost) +
+            w.latency * (1 - normLatency) +
+            w.efficiency * normEfficiency;
+        if (score > bestScore) {
+            bestScore = score;
+            selected = c;
+        }
+    }
+    return {
+        model: selected.model,
+        score: bestScore,
+        expectedCost: selected.costPer1K,
+        expectedLatency: selected.latencyMs,
+        category,
+    };
+}

package/dist/session/storage.d.ts

@@ -1,5 +1,5 @@
 /**
- * Session persistence for runcode.
+ * Session persistence for Franklin.
  * Saves conversation history as JSONL for resume capability.
  */
 import type { Dialogue } from '../agent/types.js';
@@ -11,6 +11,10 @@ export interface SessionMeta {
     updatedAt: number;
     turnCount: number;
     messageCount: number;
+    inputTokens?: number;
+    outputTokens?: number;
+    costUsd?: number;
+    savedVsOpusUsd?: number;
 }
 /** Get the absolute path to a session's JSONL file (for external readers like search). */
 export declare function getSessionFilePath(id: string): string;

package/dist/session/storage.js

@@ -1,5 +1,5 @@
 /**
- * Session persistence for runcode.
+ * Session persistence for Franklin.
  * Saves conversation history as JSONL for resume capability.
  */
 import fs from 'node:fs';
@@ -88,6 +88,10 @@ export function updateSessionMeta(sessionId, meta) {
             updatedAt: Date.now(),
             turnCount: meta.turnCount ?? existing?.turnCount ?? 0,
             messageCount: meta.messageCount ?? existing?.messageCount ?? 0,
+            inputTokens: meta.inputTokens ?? existing?.inputTokens ?? 0,
+            outputTokens: meta.outputTokens ?? existing?.outputTokens ?? 0,
+            costUsd: meta.costUsd ?? existing?.costUsd ?? 0,
+            savedVsOpusUsd: meta.savedVsOpusUsd ?? existing?.savedVsOpusUsd ?? 0,
         };
         fs.writeFileSync(metaPath(sessionId), JSON.stringify(updated, null, 2));
     });
@@ -142,7 +146,9 @@ export function listSessions() {
             }
             catch { /* skip corrupted */ }
         }
-        return metas.sort((a, b) => b.updatedAt - a.updatedAt);
+        // Filter out ghost sessions (0 messages)
+        const filtered = metas.filter(m => m.messageCount > 0);
+        return filtered.sort((a, b) => b.updatedAt - a.updatedAt);
     }
     catch {
         return [];
@@ -172,4 +178,20 @@ export function pruneOldSessions(activeSessionId) {
         }
         catch { /* ok */ }
     }
+    // Also clean up ghost sessions (0 messages, older than 5 minutes)
+    const fiveMinAgo = Date.now() - 5 * 60 * 1000;
+    for (const s of sessions) {
+        if (s.id === activeSessionId)
+            continue;
+        if (s.messageCount === 0 && s.createdAt < fiveMinAgo) {
+            try {
+                fs.unlinkSync(sessionPath(s.id));
+            }
+            catch { /* ok */ }
+            try {
+                fs.unlinkSync(metaPath(s.id));
+            }
+            catch { /* ok */ }
+        }
+    }
 }

package/dist/social/a11y.d.ts

@@ -51,4 +51,4 @@ export declare function extractArticleBlocks(tree: string): Array<{
  * This doubles as the "this is a tweet" signal in social-bot — the only link
  * inside an article block with this label shape is the permalink to the tweet.
  */
-export declare const X_TIME_LINK_PATTERN = "(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)\\s+\\d+|\\d+[smhd]|just now|now";
+export declare const X_TIME_LINK_PATTERN = "(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)\\s+\\d+(?:,?\\s+\\d{4})?|\\d+[smhd]|\\d+\\s+(?:second|minute|hour|day|week|month|year)s?\\s+ago|just now|now|yesterday|\\d{1,2}:\\d{2}\\s*[AaPp][Mm]|\\d{4}\u5E74\\d{1,2}\u6708\\d{1,2}\u65E5";

package/dist/social/a11y.js

@@ -83,7 +83,11 @@ export function extractArticleBlocks(tree) {
  * This doubles as the "this is a tweet" signal in social-bot — the only link
  * inside an article block with this label shape is the permalink to the tweet.
  */
-export const X_TIME_LINK_PATTERN = '(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)\\s+\\d+|\\d+[smhd]|just now|now';
+// Matches all known X time-link formats:
+//   "Mar 16", "Apr 12, 2026", "5h", "5m", "2d", "30s", "just now", "now"
+//   "31 seconds ago", "35 minutes ago", "4 hours ago" (full-word format)
+//   "Yesterday", "Apr 12", "12:30 AM", "2026年4月12日" (CJK)
+export const X_TIME_LINK_PATTERN = '(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)\\s+\\d+(?:,?\\s+\\d{4})?|\\d+[smhd]|\\d+\\s+(?:second|minute|hour|day|week|month|year)s?\\s+ago|just now|now|yesterday|\\d{1,2}:\\d{2}\\s*[AaPp][Mm]|\\d{4}年\\d{1,2}月\\d{1,2}日';
 function escapeRegex(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }

package/dist/social/browser.d.ts

@@ -87,6 +87,11 @@ export declare class SocialBrowser {
     getUrl(): Promise<string>;
     getTitle(): Promise<string>;
     waitForTimeout(ms: number): Promise<void>;
+    /**
+     * Resolve a ref from the last snapshot to its href attribute.
+     * Returns the href string, or null if the ref isn't a link or has no href.
+     */
+    getHref(ref: string): Promise<string | null>;
     /**
      * Block until the user closes the browser tab (used by the login flow).
      * Resolves when the context is closed.

package/dist/social/browser.js

@@ -201,6 +201,28 @@ export class SocialBrowser {
         this.requirePage();
         await this.page.waitForTimeout(ms);
     }
+    /**
+     * Resolve a ref from the last snapshot to its href attribute.
+     * Returns the href string, or null if the ref isn't a link or has no href.
+     */
+    async getHref(ref) {
+        this.requirePage();
+        const axRef = this.lastRefs.get(ref);
+        if (!axRef)
+            return null;
+        try {
+            const el = this.page.locator(axRef.selector).first();
+            // Try the element itself, then walk up to find the nearest <a>
+            const href = await el.evaluate((node) => {
+                const anchor = node.closest('a') || (node.tagName === 'A' ? node : null);
+                return anchor ? anchor.href : null;
+            });
+            return href;
+        }
+        catch {
+            return null;
+        }
+    }
     /**
      * Block until the user closes the browser tab (used by the login flow).
      * Resolves when the context is closed.

package/dist/social/preflight.d.ts

@@ -6,6 +6,10 @@ 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.
+ *
+ * Login detection order:
+ * 1. Check Cookies DB for auth_token (fast, no browser needed)
+ * 2. Fallback: open x.com/home and check AX tree for login_detection string
  */
 export declare function checkSocialReady(): Promise<{
     ready: boolean;

package/dist/social/preflight.js

@@ -2,11 +2,38 @@
  * Pre-flight checks before social tools can run.
  * Validates config readiness and browser login state.
  */
+import fs from 'node:fs';
+import path from 'node:path';
 import { loadConfig, isConfigReady } from './config.js';
 import { browserPool } from './browser-pool.js';
+import { SOCIAL_PROFILE_DIR } from './browser.js';
+/**
+ * Quick cookie check — verify auth_token exists in the profile's Cookies DB.
+ * Much faster and more reliable than loading X in a browser and inspecting
+ * the accessibility tree for a username string.
+ */
+function hasSavedAuthCookie() {
+    const cookiesPath = path.join(SOCIAL_PROFILE_DIR, 'Default', 'Cookies');
+    if (!fs.existsSync(cookiesPath))
+        return false;
+    try {
+        // Read the SQLite file as binary and look for the auth_token cookie.
+        // This avoids requiring sqlite3 as a dependency — the cookie name is
+        // stored as plain text in the DB file.
+        const raw = fs.readFileSync(cookiesPath);
+        return raw.includes('auth_token');
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * 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.
+ *
+ * Login detection order:
+ * 1. Check Cookies DB for auth_token (fast, no browser needed)
+ * 2. Fallback: open x.com/home and check AX tree for login_detection string
  */
 export async function checkSocialReady() {
     const cfg = loadConfig();
@@ -14,13 +41,25 @@ export async function checkSocialReady() {
     if (!configStatus.ready) {
         return { ready: false, reason: configStatus.reason };
     }
+    // Fast path: check saved cookies first
+    if (!hasSavedAuthCookie()) {
+        return { ready: false, reason: 'Not logged in to X (no auth_token cookie). Run: franklin social login x' };
+    }
+    // Cookies exist — browser login should work. Open browser for caller to use.
     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' };
+    // If login_detection is set, verify it as a secondary check.
+    // But don't fail if cookies exist — X may just not show the handle in AX tree.
+    if (cfg.x.login_detection && !tree.includes(cfg.x.login_detection)) {
+        // Check if we're actually on the home feed (not redirected to login page)
+        const isLoginPage = tree.includes('Sign in') && tree.includes('Create account');
+        if (isLoginPage) {
+            browserPool.releaseBrowser();
+            return { ready: false, reason: 'Cookie expired. Run: franklin social login x' };
+        }
+        // Cookies valid, just handle not found in AX tree — proceed anyway
     }
     return { ready: true, browser };
 }

package/dist/stats/failures.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Structured failure logging for self-evolution analysis.
+ * Append-only JSONL at ~/.blockrun/failures.jsonl (capped 500 records).
+ */
+export interface FailureRecord {
+    timestamp: number;
+    model: string;
+    failureType: 'tool_error' | 'model_error' | 'permission_denied' | 'agent_loop';
+    toolName?: string;
+    errorMessage: string;
+    recoveryAction?: string;
+}
+export declare function recordFailure(record: FailureRecord): void;
+export declare function loadFailures(limit?: number): FailureRecord[];
+export declare function getFailureStats(): {
+    byTool: Map<string, number>;
+    byType: Map<string, number>;
+    total: number;
+    recentFailures: FailureRecord[];
+};

package/dist/stats/failures.js

@@ -0,0 +1,63 @@
+/**
+ * Structured failure logging for self-evolution analysis.
+ * Append-only JSONL at ~/.blockrun/failures.jsonl (capped 500 records).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { BLOCKRUN_DIR } from '../config.js';
+const FAILURES_FILE = path.join(BLOCKRUN_DIR, 'failures.jsonl');
+const MAX_RECORDS = 500;
+export function recordFailure(record) {
+    try {
+        fs.mkdirSync(path.dirname(FAILURES_FILE), { recursive: true });
+        fs.appendFileSync(FAILURES_FILE, JSON.stringify(record) + '\n');
+        // Trim to MAX_RECORDS (only check periodically to avoid constant reads)
+        if (Math.random() < 0.1) {
+            trimFailures();
+        }
+    }
+    catch {
+        // Fire-and-forget — never block the critical path
+    }
+}
+function trimFailures() {
+    try {
+        if (!fs.existsSync(FAILURES_FILE))
+            return;
+        const lines = fs.readFileSync(FAILURES_FILE, 'utf-8').trim().split('\n');
+        if (lines.length > MAX_RECORDS) {
+            const trimmed = lines.slice(-MAX_RECORDS).join('\n') + '\n';
+            fs.writeFileSync(FAILURES_FILE, trimmed);
+        }
+    }
+    catch {
+        // ignore
+    }
+}
+export function loadFailures(limit = 100) {
+    try {
+        if (!fs.existsSync(FAILURES_FILE))
+            return [];
+        const lines = fs.readFileSync(FAILURES_FILE, 'utf-8').trim().split('\n').filter(Boolean);
+        return lines.slice(-limit).map(l => JSON.parse(l));
+    }
+    catch {
+        return [];
+    }
+}
+export function getFailureStats() {
+    const records = loadFailures(500);
+    const byTool = new Map();
+    const byType = new Map();
+    for (const r of records) {
+        if (r.toolName)
+            byTool.set(r.toolName, (byTool.get(r.toolName) ?? 0) + 1);
+        byType.set(r.failureType, (byType.get(r.failureType) ?? 0) + 1);
+    }
+    return {
+        byTool,
+        byType,
+        total: records.length,
+        recentFailures: records.slice(-10),
+    };
+}

package/dist/stats/format.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Shared formatting utilities for token counts, costs, and model names.
+ */
+export declare function formatTokens(n: number): string;
+export declare function formatUsd(n: number): string;
+export declare function shortModelName(model: string): string;

package/dist/stats/format.js

@@ -0,0 +1,23 @@
+/**
+ * Shared formatting utilities for token counts, costs, and model names.
+ */
+export function formatTokens(n) {
+    if (n < 1000)
+        return String(n);
+    if (n < 1_000_000)
+        return `${(n / 1000).toFixed(1)}K`;
+    return `${(n / 1_000_000).toFixed(2)}M`;
+}
+export function formatUsd(n) {
+    if (n === 0)
+        return '$0';
+    if (n < 0.01)
+        return `$${n.toFixed(4)}`;
+    if (n < 1)
+        return `$${n.toFixed(3)}`;
+    return `$${n.toFixed(2)}`;
+}
+export function shortModelName(model) {
+    const idx = model.indexOf('/');
+    return idx > -1 ? model.slice(idx + 1) : model;
+}

package/dist/stats/insights.js

@@ -13,6 +13,7 @@
  */
 import { loadStats } from './tracker.js';
 import { OPUS_PRICING, MODEL_PRICING } from '../pricing.js';
+import { formatTokens, formatUsd, shortModelName } from './format.js';
 // ─── Generate Report ──────────────────────────────────────────────────────
 export function generateInsights(days = 30) {
     const stats = loadStats();
@@ -113,27 +114,6 @@ function sparkline(values) {
     const chars = ['▁', '▂', '▃', '▄', '▅', '▆', '▇', '█'];
     return values.map(v => chars[Math.min(7, Math.floor((v / max) * 8))]).join('');
 }
-function formatUsd(n) {
-    if (n === 0)
-        return '$0';
-    if (n < 0.01)
-        return `$${n.toFixed(4)}`;
-    if (n < 1)
-        return `$${n.toFixed(3)}`;
-    return `$${n.toFixed(2)}`;
-}
-function formatTokens(n) {
-    if (n < 1000)
-        return String(n);
-    if (n < 1_000_000)
-        return `${(n / 1000).toFixed(1)}K`;
-    return `${(n / 1_000_000).toFixed(2)}M`;
-}
-function shortModelName(model) {
-    // Strip provider prefix for display
-    const idx = model.indexOf('/');
-    return idx > -1 ? model.slice(idx + 1) : model;
-}
 export function formatInsights(report, days) {
     const sep = '─'.repeat(60);
     const lines = [];

package/dist/stats/session-tracker.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Session-scoped per-model usage tracking.
+ * In-memory only — resets on new session. Used by /cost and UI footer.
+ */
+export interface SessionModelUsage {
+    requests: number;
+    inputTokens: number;
+    outputTokens: number;
+    costUsd: number;
+    lastTier?: string;
+}
+export declare function recordSessionUsage(model: string, inputTokens: number, outputTokens: number, costUsd: number, tier?: string): void;
+export declare function getSessionModelBreakdown(): Array<{
+    model: string;
+    requests: number;
+    inputTokens: number;
+    outputTokens: number;
+    costUsd: number;
+    lastTier?: string;
+}>;
+export declare function resetSession(): void;

package/dist/stats/session-tracker.js

@@ -0,0 +1,28 @@
+/**
+ * Session-scoped per-model usage tracking.
+ * In-memory only — resets on new session. Used by /cost and UI footer.
+ */
+const sessionModels = new Map();
+export function recordSessionUsage(model, inputTokens, outputTokens, costUsd, tier) {
+    const existing = sessionModels.get(model) ?? {
+        requests: 0,
+        inputTokens: 0,
+        outputTokens: 0,
+        costUsd: 0,
+    };
+    existing.requests++;
+    existing.inputTokens += inputTokens;
+    existing.outputTokens += outputTokens;
+    existing.costUsd += costUsd;
+    if (tier)
+        existing.lastTier = tier;
+    sessionModels.set(model, existing);
+}
+export function getSessionModelBreakdown() {
+    return Array.from(sessionModels.entries())
+        .map(([model, usage]) => ({ model, ...usage }))
+        .sort((a, b) => b.costUsd - a.costUsd);
+}
+export function resetSession() {
+    sessionModels.clear();
+}

package/dist/stats/tracker.d.ts

@@ -1,5 +1,5 @@
 /**
- * Usage tracking for runcode
+ * Usage tracking for Franklin
  * Records all requests with cost, tokens, and latency for stats display
  */
 export declare function getStatsFilePath(): string;

package/dist/stats/tracker.js

@@ -1,5 +1,5 @@
 /**
- * Usage tracking for runcode
+ * Usage tracking for Franklin
  * Records all requests with cost, tokens, and latency for stats display
  */
 import fs from 'node:fs';

package/dist/tools/bash.d.ts

@@ -1,5 +1,18 @@
 /**
  * Bash capability — execute shell commands with timeout and output capture.
  */
-import type { CapabilityHandler } from '../agent/types.js';
+import type { CapabilityHandler, CapabilityResult } from '../agent/types.js';
+interface BackgroundTask {
+    id: string;
+    command: string;
+    description: string;
+    startedAt: number;
+    status: 'running' | 'completed' | 'failed';
+    result?: CapabilityResult;
+}
+/** Get a background task's result (called by the agent to check status). */
+export declare function getBackgroundTask(id: string): BackgroundTask | undefined;
+/** List all background tasks. */
+export declare function listBackgroundTasks(): BackgroundTask[];
 export declare const bashCapability: CapabilityHandler;
+export {};