pi-resume 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,68 @@
+# pi-fast-resume
+
+Fast session resume for [pi coding agent](https://pi.dev) without reading all `.jsonl` files.
+
+## Problem
+
+Built-in `/resume` reads and parses **every line** of every session file to build the picker. With hundreds of sessions this is slow.
+
+## Solution
+
+Two commands that use `stat()` + lazy partial reads:
+
+| Command | What it does | Speed |
+|---------|-------------|-------|
+| `/r2` | Instantly switch to the most recent session | <50ms (stat-only) |
+| `/rs` | Paginated picker: last 20, with tier navigation | <200ms first page |
+
+## Install
+
+```bash
+pi install npm:pi-fast-resume
+```
+
+## Commands
+
+### `/r2` — Instant Resume
+
+Switches to the most recent session (by mtime) in one step. No picker, no parsing.
+
+### `/rs` — Smart Resume
+
+Shows a paginated list of recent sessions:
+
+- **Relative time** (e.g., "2h ago"), **file size**, **session name or first message**
+- **`▼ Load more...`** — next page within current filter
+- **`▼ Show 14d`** — expand to 14 days
+- **`▼ Show all`** — remove day filter entirely
+
+Auto-escalates: if 7d is empty, jumps to 14d, then all.
+
+### Configuration
+
+```
+/rs set page 30    # Sessions per page (1-50, default: 20)
+/rs set days 14    # Day filter for first tier (0-30, 0 = no filter, default: 7)
+```
+
+Config is stored in `~/.pi/agent/extensions/pi-fast-resume/config.json`.
+
+## How it works
+
+1. **`/r2`**: `readdir` → `stat` each `.jsonl` → sort by mtime → `switchSession(newest)`
+2. **`/rs`**: Same stat scan, then read only the **first ~50 lines** of each file on the current page to extract session name and first user message
+
+No full file parsing. No `buildSessionInfo()`. No reading message content beyond the first user message.
+
+## Development
+
+```bash
+git clone https://github.com/spex66/pi-fast-resume.git
+cd pi-fast-resume
+npm install
+npm test
+```
+
+## License
+
+MIT

package/extensions/index.ts

@@ -0,0 +1,158 @@
+/**
+ * pi-fast-resume — fast session resume without reading all .jsonl files.
+ *
+ * Commands:
+ *   /r2              — instantly switch to the most recent session (stat-only)
+ *   /rs              — paginated session picker (last 20, "Load more", tier filter)
+ *   /rs set page N   — set page size (1-50)
+ *   /rs set days N   — set maxDays filter (0-30, 0 = no limit)
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { statScan, scanPage, readSessionMeta } from "../src/scanner.ts";
+import { formatEntry, truncate, sessionLabel } from "../src/format.ts";
+import { loadConfig, saveConfig } from "../src/config.ts";
+import { getSessionDir } from "../src/session-dir.ts";
+
+const DAY_TIERS = [7, 14, 0] as const;
+
+export default function (pi: ExtensionAPI) {
+  pi.registerCommand("r2", {
+    description: "Instantly resume the most recent session",
+    handler: async (_args: string, ctx: any) => {
+      const sessionDir = getSessionDir(ctx.cwd);
+      const files = await statScan(sessionDir);
+
+      if (files.length === 0) {
+        ctx.ui.notify("No sessions found", "error");
+        return;
+      }
+
+      const currentFile = ctx.sessionManager.getSessionFile() ?? undefined;
+      const target = files.find((f: { file: string }) => f.file !== currentFile);
+
+      if (!target) {
+        ctx.ui.notify("No other sessions to resume", "info");
+        return;
+      }
+
+      const meta = await readSessionMeta(target.file, target);
+      await ctx.switchSession(target.file, {
+        withSession: async (newCtx: any) => {
+          newCtx.ui.notify(`Resumed: ${truncate(sessionLabel(meta), 50)}`, "info");
+        },
+      });
+    },
+  });
+
+  pi.registerCommand("rs", {
+    description: "Smart resume: paginated session picker (last 20, Load more, tier filter)",
+    handler: async (args: string, ctx: any) => {
+      const parts = (args || "").trim().split(/\s+/);
+      const cfg = loadConfig();
+
+      // /rs set page N | /rs set days N
+      if (parts[0] === "set") {
+        const key = parts[1];
+        const val = parseInt(parts[2], 10);
+
+        if (key === "page" && !isNaN(val) && val >= 1 && val <= 50) {
+          cfg.pageSize = val;
+          saveConfig(cfg);
+          ctx.ui.notify(`Page size set to ${val}`, "info");
+          return;
+        }
+        if (key === "days" && !isNaN(val) && val >= 0 && val <= 30) {
+          cfg.maxDays = val;
+          saveConfig(cfg);
+          ctx.ui.notify(val === 0 ? "Day filter disabled" : `Max days set to ${val}`, "info");
+          return;
+        }
+
+        ctx.ui.notify("Usage: /rs set page N (1-50) | /rs set days N (0-30)", "error");
+        return;
+      }
+
+      const sessionDir = getSessionDir(ctx.cwd);
+      const currentFile = ctx.sessionManager.getSessionFile() ?? undefined;
+
+      let tierIndex = 0;
+      let offset = 0;
+
+      while (true) {
+        const currentDays = DAY_TIERS[tierIndex] ?? 0;
+        const nextTierDays = DAY_TIERS[tierIndex + 1];
+
+        const { entries, total, hasMore } = await scanPage(
+          sessionDir,
+          offset,
+          cfg.pageSize,
+          currentDays > 0 ? currentDays : undefined,
+          currentFile,
+        );
+
+        if (entries.length === 0 && offset === 0) {
+          if (tierIndex < DAY_TIERS.length - 1) {
+            tierIndex++;
+            continue;
+          }
+          ctx.ui.notify("No sessions found", "info");
+          return;
+        }
+
+        const items: string[] = entries.map((e) => formatEntry(e));
+
+        if (hasMore) {
+          const remaining = total - offset - entries.length;
+          items.push(`▼ Load more... (${remaining} remaining)`);
+        }
+
+        if (nextTierDays !== undefined) {
+          const tierLabel = nextTierDays > 0 ? `${nextTierDays}d` : "all";
+          items.push(`▼ Show ${tierLabel}`);
+        }
+
+        const filterLabel = currentDays > 0 ? ` (last ${currentDays}d)` : "";
+        const rangeLabel =
+          offset === 0
+            ? `Sessions 1-${entries.length} of ${total}${filterLabel}`
+            : `Sessions ${offset + 1}-${offset + entries.length} of ${total}${filterLabel}`;
+
+        const choice = await ctx.ui.select(rangeLabel, items);
+
+        if (choice === undefined || choice === null) return;
+
+        const choiceIndex = items.indexOf(choice);
+
+        if (hasMore && choiceIndex === entries.length) {
+          offset += cfg.pageSize;
+          continue;
+        }
+
+        if (choice.startsWith("▼ Show ") && nextTierDays !== undefined) {
+          tierIndex++;
+          offset = 0;
+          continue;
+        }
+
+        if (choiceIndex >= 0 && choiceIndex < entries.length) {
+          const selected = entries[choiceIndex];
+          if (!selected) return;
+
+          const result = await ctx.switchSession(selected.file, {
+            withSession: async (newCtx: any) => {
+              newCtx.ui.notify(`Resumed: ${truncate(sessionLabel(selected), 50)}`, "info");
+            },
+          });
+
+          if (result.cancelled) {
+            ctx.ui.notify("Session switch was cancelled", "info");
+          }
+          return;
+        }
+
+        return;
+      }
+    },
+  });
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "pi-resume",
+  "version": "1.0.0",
+  "description": "Fast session resume for pi coding agent — /r2 instant resume, /rs paginated picker",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "session",
+    "resume"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/spex66/pi-fast-resume.git"
+  },
+  "files": [
+    "extensions",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/index.ts"
+    ]
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typescript": "^5.0.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "node --experimental-vm-modules --test tests/*.test.ts",
+    "check": "npm run typecheck && npm pack --dry-run",
+    "prepublishOnly": "npm run check"
+  }
+}

package/src/config.ts

@@ -0,0 +1,51 @@
+/**
+ * Config management. Stores user prefs in ~/.pi/agent/extensions/pi-fast-resume/config.json.
+ * Creates defaults at runtime — nothing shipped in the package.
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+
+const CONFIG_DIR = join(
+  process.env.PI_CODING_AGENT_DIR || join(process.env.HOME || "~", ".pi", "agent"),
+  "extensions",
+  "pi-fast-resume",
+);
+const CONFIG_PATH = join(CONFIG_DIR, "config.json");
+
+export interface Config {
+  pageSize: number;
+  maxDays: number;
+}
+
+const DEFAULTS: Config = { pageSize: 20, maxDays: 7 };
+const MIN_PAGE = 1;
+const MAX_PAGE = 50;
+const MIN_DAYS = 0;
+const MAX_DAYS = 30;
+
+export function clampPage(n: number): number {
+  return Math.min(MAX_PAGE, Math.max(MIN_PAGE, n));
+}
+
+export function clampDays(n: number): number {
+  return Math.min(MAX_DAYS, Math.max(MIN_DAYS, n));
+}
+
+export function loadConfig(): Config {
+  try {
+    if (existsSync(CONFIG_PATH)) {
+      const raw = JSON.parse(readFileSync(CONFIG_PATH, "utf-8"));
+      return {
+        pageSize: clampPage(Number(raw.pageSize) || DEFAULTS.pageSize),
+        maxDays: clampDays(Number(raw.maxDays) || DEFAULTS.maxDays),
+      };
+    }
+  } catch {}
+  return { ...DEFAULTS };
+}
+
+export function saveConfig(cfg: Config): void {
+  if (!existsSync(CONFIG_DIR)) mkdirSync(CONFIG_DIR, { recursive: true });
+  writeFileSync(CONFIG_PATH, JSON.stringify(cfg, null, 2) + "\n");
+}

package/src/format.ts

@@ -0,0 +1,34 @@
+/**
+ * Pure formatting functions. No pi SDK dependency.
+ */
+
+import type { SessionEntry } from "./scanner.ts";
+
+export function formatSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes}B`;
+  if (bytes < 1048576) return `${(bytes / 1024).toFixed(0)}KB`;
+  return `${(bytes / 1048576).toFixed(1)}MB`;
+}
+
+export function formatAge(mtime: Date): string {
+  const diff = Date.now() - mtime.getTime();
+  const mins = Math.floor(diff / 60000);
+  if (mins < 1) return "just now";
+  if (mins < 60) return `${mins}m ago`;
+  const hours = Math.floor(mins / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  return `${days}d ago`;
+}
+
+export function truncate(text: string, max: number): string {
+  return text.length > max ? text.slice(0, max - 3) + "..." : text;
+}
+
+export function sessionLabel(e: SessionEntry): string {
+  return e.name || e.firstMessage || e.id || "untitled";
+}
+
+export function formatEntry(e: SessionEntry): string {
+  return `${formatAge(e.mtime).padEnd(10)} ${formatSize(e.size).padEnd(8)} ${truncate(sessionLabel(e), 60)}`;
+}

package/src/scanner.ts

@@ -0,0 +1,167 @@
+/**
+ * Fast session scanner using stat + lazy header parse.
+ *
+ * Key principle: never read full .jsonl files.
+ * - stat() for mtime/size sorting
+ * - First ~50 lines for header, session_info, first user message
+ */
+
+import { readdir, stat } from "node:fs/promises";
+import { createReadStream } from "node:fs";
+import { createInterface } from "node:readline";
+import { join } from "node:path";
+
+export interface SessionEntry {
+  file: string;
+  mtime: Date;
+  size: number;
+  id?: string;
+  timestamp?: string;
+  cwd?: string;
+  name?: string;
+  firstMessage?: string;
+}
+
+export interface StatResult {
+  file: string;
+  mtime: Date;
+  size: number;
+}
+
+/**
+ * Fast stat-only scan: readdir + stat, sorted by mtime desc.
+ * No file content is read.
+ */
+export async function statScan(sessionDir: string): Promise<StatResult[]> {
+  let entries: string[];
+  try {
+    entries = await readdir(sessionDir);
+  } catch {
+    return [];
+  }
+
+  const jsonlFiles = entries.filter((f) => f.endsWith(".jsonl"));
+
+  const results = await Promise.all(
+    jsonlFiles.map(async (f) => {
+      const fullPath = join(sessionDir, f);
+      try {
+        const s = await stat(fullPath);
+        if (!s.isFile()) return null;
+        return { file: fullPath, mtime: s.mtime, size: s.size };
+      } catch {
+        return null;
+      }
+    }),
+  );
+
+  const valid = results.filter((r): r is StatResult => r !== null);
+  valid.sort((a, b) => b.mtime.getTime() - a.mtime.getTime());
+  return valid;
+}
+
+/**
+ * Read session metadata from first ~50 lines of a .jsonl file.
+ * Caller provides mtime/size from prior stat() to avoid double-stat.
+ */
+export async function readSessionMeta(
+  filePath: string,
+  known?: { mtime: Date; size: number },
+): Promise<SessionEntry> {
+  const entry: SessionEntry = {
+    file: filePath,
+    mtime: known?.mtime ?? new Date(0),
+    size: known?.size ?? 0,
+  };
+
+  if (!known) {
+    try {
+      const s = await stat(filePath);
+      entry.mtime = s.mtime;
+      entry.size = s.size;
+    } catch {}
+  }
+
+  const MAX_LINES = 50;
+  let lineCount = 0;
+
+  try {
+    const rl = createInterface({
+      input: createReadStream(filePath, { encoding: "utf8" }),
+      crlfDelay: Infinity,
+    });
+
+    for await (const line of rl) {
+      lineCount++;
+      if (lineCount > MAX_LINES) break;
+
+      try {
+        const parsed = JSON.parse(line);
+
+        if (parsed.type === "session" && !entry.id) {
+          entry.id = parsed.id;
+          entry.timestamp = parsed.timestamp;
+          entry.cwd = parsed.cwd;
+          continue;
+        }
+
+        if (parsed.type === "session_info" && parsed.name) {
+          entry.name = parsed.name.trim();
+          continue;
+        }
+
+        if (!entry.firstMessage && parsed.type === "message") {
+          const msg = parsed.message;
+          if (msg?.role === "user" && Array.isArray(msg.content)) {
+            for (const block of msg.content) {
+              if (block.type === "text" && block.text) {
+                entry.firstMessage = block.text.slice(0, 80).replace(/\n/g, " ");
+                break;
+              }
+            }
+          }
+        }
+      } catch {
+        // skip unparseable lines
+      }
+
+      if (entry.id && entry.firstMessage) break;
+    }
+
+    rl.close();
+  } catch {}
+
+  return entry;
+}
+
+/**
+ * Scan a page of sessions with metadata.
+ * Pass known mtime/size from statScan to avoid double stat().
+ */
+export async function scanPage(
+  sessionDir: string,
+  offset: number,
+  limit: number,
+  maxDays?: number,
+  excludeFile?: string,
+): Promise<{ entries: SessionEntry[]; total: number; hasMore: boolean }> {
+  const all = await statScan(sessionDir);
+
+  let filtered = all;
+  if (maxDays && maxDays > 0) {
+    const cutoff = Date.now() - maxDays * 86400_000;
+    filtered = all.filter((f) => f.mtime.getTime() > cutoff);
+  }
+
+  if (excludeFile) {
+    filtered = filtered.filter((f) => f.file !== excludeFile);
+  }
+
+  const total = filtered.length;
+  const page = filtered.slice(offset, offset + limit);
+  const hasMore = offset + limit < total;
+
+  const entries = await Promise.all(page.map((f) => readSessionMeta(f.file, f)));
+
+  return { entries, total, hasMore };
+}

package/src/session-dir.ts

@@ -0,0 +1,15 @@
+/**
+ * Resolve the pi session directory for a given cwd.
+ * Mirrors pi's internal encoding: --<path-with-dashes>--
+ */
+
+import { join } from "node:path";
+
+export function getSessionDir(cwd: string): string {
+  const resolved = cwd.replace(/^\//, "").replace(/[/\\:]/g, "-");
+  return join(
+    process.env.PI_CODING_AGENT_DIR || join(process.env.HOME || "~", ".pi", "agent"),
+    "sessions",
+    `--${resolved}--`,
+  );
+}