feat: session persistence with /sessions and /resume commands (v1.5.0)

Author: 1bcMax

dist/agent/loop.js

@@ -11,6 +11,7 @@ import { StreamingExecutor } from './streaming-executor.js';
 import { optimizeHistory, CAPPED_MAX_TOKENS, ESCALATED_MAX_TOKENS } from './optimize.js';
 import { recordUsage } from '../stats/tracker.js';
 import { estimateCost } from '../pricing.js';
+import { createSessionId, appendToSession, updateSessionMeta, pruneOldSessions, listSessions, loadSessionHistory, } from '../session/storage.js';
 // ─── Main Entry Point ──────────────────────────────────────────────────────
 /**
  * Run the agent loop.
@@ -208,12 +209,52 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
     const workDir = config.workingDir ?? process.cwd();
     const permissions = new PermissionManager(config.permissionMode ?? 'default');
     const history = [];
+    // Session persistence
+    const sessionId = createSessionId();
+    let turnCount = 0;
+    pruneOldSessions(); // Cleanup old sessions on start
     while (true) {
         const input = await getUserInput();
         if (input === null)
             break; // User wants to exit
         if (input === '')
             continue; // Empty input → re-prompt
+        // Handle /sessions — list saved sessions
+        if (input === '/sessions') {
+            const sessions = listSessions();
+            if (sessions.length === 0) {
+                onEvent({ kind: 'text_delta', text: 'No saved sessions.\n' });
+            }
+            else {
+                let text = `**${sessions.length} saved sessions:**\n\n`;
+                for (const s of sessions.slice(0, 10)) {
+                    const date = new Date(s.updatedAt).toLocaleString();
+                    const dir = s.workDir ? ` — ${s.workDir.split('/').pop()}` : '';
+                    text += `  ${s.id}  ${s.model}  ${s.turnCount} turns  ${date}${dir}\n`;
+                }
+                if (sessions.length > 10)
+                    text += `  ... and ${sessions.length - 10} more\n`;
+                text += '\nUse /resume <session-id> to continue a session.\n';
+                onEvent({ kind: 'text_delta', text });
+            }
+            onEvent({ kind: 'turn_done', reason: 'completed' });
+            continue;
+        }
+        // Handle /resume <id> — restore session history
+        if (input.startsWith('/resume ')) {
+            const targetId = input.slice(8).trim();
+            const restored = loadSessionHistory(targetId);
+            if (restored.length === 0) {
+                onEvent({ kind: 'text_delta', text: `Session "${targetId}" not found or empty.\n` });
+            }
+            else {
+                history.length = 0;
+                history.push(...restored);
+                onEvent({ kind: 'text_delta', text: `Restored ${restored.length} messages from ${targetId}. Continue where you left off.\n` });
+            }
+            onEvent({ kind: 'turn_done', reason: 'completed' });
+            continue;
+        }
         // Handle /compact command — force compaction without sending to model
         if (input === '/compact') {
             const beforeTokens = estimateHistoryTokens(history);
@@ -231,15 +272,17 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
             continue;
         }
         history.push({ role: 'user', content: input });
+        appendToSession(sessionId, { role: 'user', content: input });
+        turnCount++;
         const abort = new AbortController();
         onAbortReady?.(() => abort.abort());
-        let turnCount = 0;
+        let loopCount = 0;
         let recoveryAttempts = 0;
         let maxTokensOverride;
         const lastActivity = Date.now();
         // Agent loop for this user message
-        while (turnCount < maxTurns) {
-            turnCount++;
+        while (loopCount < maxTurns) {
+            loopCount++;
             // ── Token optimization pipeline ──
             // 1. Strip thinking, budget tool results, time-based cleanup
             const optimized = optimizeHistory(history, {
@@ -392,6 +435,14 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
             history.push({ role: 'assistant', content: responseParts });
             // No more capabilities → done with this user message
             if (invocations.length === 0) {
+                // Save session on completed turn
+                appendToSession(sessionId, { role: 'assistant', content: responseParts });
+                updateSessionMeta(sessionId, {
+                    model: config.model,
+                    workDir: config.workingDir || process.cwd(),
+                    turnCount,
+                    messageCount: history.length,
+                });
                 onEvent({ kind: 'turn_done', reason: 'completed' });
                 break;
             }
@@ -409,7 +460,7 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
             }));
             history.push({ role: 'user', content: outcomeContent });
         }
-        if (turnCount >= maxTurns) {
+        if (loopCount >= maxTurns) {
             onEvent({ kind: 'turn_done', reason: 'max_turns' });
         }
     }

dist/session/storage.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Session persistence for runcode.
+ * Saves conversation history as JSONL for resume capability.
+ */
+import type { Dialogue } from '../agent/types.js';
+export interface SessionMeta {
+    id: string;
+    model: string;
+    workDir: string;
+    createdAt: number;
+    updatedAt: number;
+    turnCount: number;
+    messageCount: number;
+}
+/**
+ * Create a new session ID based on timestamp.
+ */
+export declare function createSessionId(): string;
+/**
+ * Save a message to the session transcript (append-only JSONL).
+ */
+export declare function appendToSession(sessionId: string, message: Dialogue): void;
+/**
+ * Update session metadata.
+ */
+export declare function updateSessionMeta(sessionId: string, meta: Partial<SessionMeta>): void;
+/**
+ * Load session metadata.
+ */
+export declare function loadSessionMeta(sessionId: string): SessionMeta | null;
+/**
+ * Load full session history from JSONL.
+ */
+export declare function loadSessionHistory(sessionId: string): Dialogue[];
+/**
+ * List all saved sessions, newest first.
+ */
+export declare function listSessions(): SessionMeta[];
+/**
+ * Prune old sessions beyond MAX_SESSIONS.
+ */
+export declare function pruneOldSessions(): void;

dist/session/storage.js

@@ -0,0 +1,116 @@
+/**
+ * Session persistence for runcode.
+ * Saves conversation history as JSONL for resume capability.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { BLOCKRUN_DIR } from '../config.js';
+const SESSIONS_DIR = path.join(BLOCKRUN_DIR, 'sessions');
+const MAX_SESSIONS = 20; // Keep last 20 sessions
+function ensureDir() {
+    fs.mkdirSync(SESSIONS_DIR, { recursive: true });
+}
+function sessionPath(id) {
+    return path.join(SESSIONS_DIR, `${id}.jsonl`);
+}
+function metaPath(id) {
+    return path.join(SESSIONS_DIR, `${id}.meta.json`);
+}
+/**
+ * Create a new session ID based on timestamp.
+ */
+export function createSessionId() {
+    const now = new Date();
+    const ts = now.toISOString().replace(/[:.]/g, '-').slice(0, 19);
+    return `session-${ts}`;
+}
+/**
+ * Save a message to the session transcript (append-only JSONL).
+ */
+export function appendToSession(sessionId, message) {
+    ensureDir();
+    const line = JSON.stringify(message) + '\n';
+    fs.appendFileSync(sessionPath(sessionId), line);
+}
+/**
+ * Update session metadata.
+ */
+export function updateSessionMeta(sessionId, meta) {
+    ensureDir();
+    const existing = loadSessionMeta(sessionId);
+    const updated = {
+        id: sessionId,
+        model: meta.model || existing?.model || 'unknown',
+        workDir: meta.workDir || existing?.workDir || '',
+        createdAt: existing?.createdAt || Date.now(),
+        updatedAt: Date.now(),
+        turnCount: meta.turnCount ?? existing?.turnCount ?? 0,
+        messageCount: meta.messageCount ?? existing?.messageCount ?? 0,
+    };
+    fs.writeFileSync(metaPath(sessionId), JSON.stringify(updated, null, 2));
+}
+/**
+ * Load session metadata.
+ */
+export function loadSessionMeta(sessionId) {
+    try {
+        return JSON.parse(fs.readFileSync(metaPath(sessionId), 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Load full session history from JSONL.
+ */
+export function loadSessionHistory(sessionId) {
+    try {
+        const content = fs.readFileSync(sessionPath(sessionId), 'utf-8');
+        const lines = content.trim().split('\n').filter(Boolean);
+        return lines.map(line => JSON.parse(line));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * List all saved sessions, newest first.
+ */
+export function listSessions() {
+    ensureDir();
+    try {
+        const files = fs.readdirSync(SESSIONS_DIR)
+            .filter(f => f.endsWith('.meta.json'));
+        const metas = [];
+        for (const file of files) {
+            try {
+                const meta = JSON.parse(fs.readFileSync(path.join(SESSIONS_DIR, file), 'utf-8'));
+                metas.push(meta);
+            }
+            catch { /* skip corrupted */ }
+        }
+        return metas.sort((a, b) => b.updatedAt - a.updatedAt);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Prune old sessions beyond MAX_SESSIONS.
+ */
+export function pruneOldSessions() {
+    const sessions = listSessions();
+    if (sessions.length <= MAX_SESSIONS)
+        return;
+    const toDelete = sessions.slice(MAX_SESSIONS);
+    for (const s of toDelete) {
+        try {
+            fs.unlinkSync(sessionPath(s.id));
+        }
+        catch { /* ok */ }
+        try {
+            fs.unlinkSync(metaPath(s.id));
+        }
+        catch { /* ok */ }
+    }
+}

dist/ui/app.js

@@ -167,6 +167,12 @@ function RunCodeApp({ initialModel, workDir, walletAddress, walletBalance, chain
                     setShowHelp(true);
                     setShowWallet(false);
                     return;
+                case '/sessions':
+                    setStreamText('');
+                    setWaiting(true);
+                    setReady(false);
+                    onSubmit('/sessions');
+                    return;
                 case '/clear':
                     setStreamText('');
                     setTools(new Map());
@@ -199,6 +205,14 @@ function RunCodeApp({ initialModel, workDir, walletAddress, walletBalance, chain
                     onSubmit('/compact');
                     return;
                 default:
+                    // Commands with arguments that pass through to the loop
+                    if (trimmed.startsWith('/resume ')) {
+                        setStreamText('');
+                        setWaiting(true);
+                        setReady(false);
+                        onSubmit(trimmed);
+                        return;
+                    }
                     setStatusMsg(`Unknown command: ${cmd}. Try /help`);
                     setTimeout(() => setStatusMsg(''), 3000);
                     return;
@@ -296,7 +310,7 @@ function RunCodeApp({ initialModel, workDir, walletAddress, walletBalance, chain
                 }), _jsx(Text, { children: " " })] }));
     }
     // ── Normal Mode ──
-    return (_jsxs(Box, { flexDirection: "column", children: [statusMsg && (_jsx(Box, { marginLeft: 2, children: _jsx(Text, { color: "green", children: statusMsg }) })), showHelp && (_jsxs(Box, { flexDirection: "column", marginLeft: 2, marginTop: 1, marginBottom: 1, children: [_jsx(Text, { bold: true, children: "Commands" }), _jsx(Text, { children: " " }), _jsxs(Text, { children: ["  ", _jsx(Text, { color: "cyan", children: "/model" }), " [name]  Switch model (picker if no name)"] }), _jsxs(Text, { children: ["  ", _jsx(Text, { color: "cyan", children: "/wallet" }), "        Show wallet address & balance"] }), _jsxs(Text, { children: ["  ", _jsx(Text, { color: "cyan", children: "/cost" }), "          Session cost & savings"] }), _jsxs(Text, { children: ["  ", _jsx(Text, { color: "cyan", children: "/retry" }), "         Retry the last prompt"] }), _jsxs(Text, { children: ["  ", _jsx(Text, { color: "cyan", children: "/compact" }), "       Compress conversation history"] }), _jsxs(Text, { children: ["  ", _jsx(Text, { color: "cyan", children: "/clear" }), "         Clear conversation display"] }), _jsxs(Text, { children: ["  ", _jsx(Text, { color: "cyan", children: "/help" }), "          This help"] }), _jsxs(Text, { children: ["  ", _jsx(Text, { color: "cyan", children: "/exit" }), "          Quit"] }), _jsx(Text, { children: " " }), _jsx(Text, { dimColor: true, children: "  Shortcuts: sonnet, opus, gpt, gemini, deepseek, flash, free, r1, o4, nano, mini, haiku" })] })), showWallet && (_jsxs(Box, { flexDirection: "column", marginLeft: 2, marginTop: 1, marginBottom: 1, children: [_jsx(Text, { bold: true, children: "Wallet" }), _jsx(Text, { children: " " }), _jsxs(Text, { children: ["  Chain:   ", _jsx(Text, { color: "magenta", children: chain })] }), _jsxs(Text, { children: ["  Address: ", _jsx(Text, { color: "cyan", children: walletAddress })] }), _jsxs(Text, { children: ["  Balance: ", _jsx(Text, { color: "green", children: balance })] })] })), Array.from(tools.values()).map((tool, i) => (_jsx(Box, { marginLeft: 1, children: tool.done ? (tool.error
+    return (_jsxs(Box, { flexDirection: "column", children: [statusMsg && (_jsx(Box, { marginLeft: 2, children: _jsx(Text, { color: "green", children: statusMsg }) })), showHelp && (_jsxs(Box, { flexDirection: "column", marginLeft: 2, marginTop: 1, marginBottom: 1, children: [_jsx(Text, { bold: true, children: "Commands" }), _jsx(Text, { children: " " }), _jsxs(Text, { children: ["  ", _jsx(Text, { color: "cyan", children: "/model" }), " [name]  Switch model (picker if no name)"] }), _jsxs(Text, { children: ["  ", _jsx(Text, { color: "cyan", children: "/wallet" }), "        Show wallet address & balance"] }), _jsxs(Text, { children: ["  ", _jsx(Text, { color: "cyan", children: "/cost" }), "          Session cost & savings"] }), _jsxs(Text, { children: ["  ", _jsx(Text, { color: "cyan", children: "/retry" }), "         Retry the last prompt"] }), _jsxs(Text, { children: ["  ", _jsx(Text, { color: "cyan", children: "/compact" }), "       Compress conversation history"] }), _jsxs(Text, { children: ["  ", _jsx(Text, { color: "cyan", children: "/sessions" }), "      List saved sessions"] }), _jsxs(Text, { children: ["  ", _jsx(Text, { color: "cyan", children: "/resume" }), " id     Resume a saved session"] }), _jsxs(Text, { children: ["  ", _jsx(Text, { color: "cyan", children: "/clear" }), "         Clear conversation display"] }), _jsxs(Text, { children: ["  ", _jsx(Text, { color: "cyan", children: "/help" }), "          This help"] }), _jsxs(Text, { children: ["  ", _jsx(Text, { color: "cyan", children: "/exit" }), "          Quit"] }), _jsx(Text, { children: " " }), _jsx(Text, { dimColor: true, children: "  Shortcuts: sonnet, opus, gpt, gemini, deepseek, flash, free, r1, o4, nano, mini, haiku" })] })), showWallet && (_jsxs(Box, { flexDirection: "column", marginLeft: 2, marginTop: 1, marginBottom: 1, children: [_jsx(Text, { bold: true, children: "Wallet" }), _jsx(Text, { children: " " }), _jsxs(Text, { children: ["  Chain:   ", _jsx(Text, { color: "magenta", children: chain })] }), _jsxs(Text, { children: ["  Address: ", _jsx(Text, { color: "cyan", children: walletAddress })] }), _jsxs(Text, { children: ["  Balance: ", _jsx(Text, { color: "green", children: balance })] })] })), Array.from(tools.values()).map((tool, i) => (_jsx(Box, { marginLeft: 1, children: tool.done ? (tool.error
                     ? _jsxs(Text, { color: "red", children: ["  \u2717 ", tool.name, " ", _jsxs(Text, { dimColor: true, children: [tool.elapsed, "ms"] })] })
                     : _jsxs(Text, { color: "green", children: ["  \u2713 ", tool.name, " ", _jsxs(Text, { dimColor: true, children: [tool.elapsed, "ms \u2014 ", tool.preview.slice(0, 200), tool.preview.length > 200 ? '...' : ''] })] })) : (_jsxs(Text, { color: "cyan", children: ["  ", _jsx(Spinner, { type: "dots" }), " ", tool.name, "... ", _jsxs(Text, { dimColor: true, children: [Math.round((Date.now() - tool.startTime) / 1000), "s"] })] })) }, i))), thinking && (_jsxs(Box, { flexDirection: "column", marginLeft: 1, children: [_jsxs(Text, { color: "magenta", children: ["  ", _jsx(Spinner, { type: "dots" }), " thinking..."] }), thinkingText && (_jsxs(Text, { dimColor: true, wrap: "truncate-end", children: ["  ", thinkingText.split('\n').pop()?.slice(0, 80)] }))] })), waiting && !thinking && tools.size === 0 && (_jsx(Box, { marginLeft: 1, children: _jsxs(Text, { color: "yellow", children: ["  ", _jsx(Spinner, { type: "dots" }), " ", _jsx(Text, { dimColor: true, children: currentModel })] }) })), streamText && (_jsx(Box, { marginTop: 0, marginBottom: 0, children: _jsx(Text, { children: streamText }) })), ready && (turnTokens.input > 0 || turnTokens.output > 0) && streamText && (_jsx(Box, { marginLeft: 1, marginTop: 0, children: _jsxs(Text, { dimColor: true, children: [turnTokens.input.toLocaleString(), " in / ", turnTokens.output.toLocaleString(), " out", totalCost > 0 ? `  ·  $${totalCost.toFixed(4)} session` : ''] }) })), ready && (_jsx(InputBox, { input: input, setInput: setInput, onSubmit: handleSubmit, model: currentModel, balance: balance, focused: mode === 'input' }))] }));
 }

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/runcode",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "RunCode — AI coding agent powered by 41+ models. Pay per use with USDC.",
   "type": "module",
   "bin": {