@neerajvipparla/agentbridge 0.1.0

package/src/ledger/git-ledger.js

@@ -0,0 +1,220 @@
+// src/ledger/git-ledger.js
+//
+// A tiny local git repo used purely as a versioned ledger of every fork
+// agentbridge performs. It is NOT your project's own git repo - it lives
+// under .agentbridge/ledger inside the project directory (add
+// .agentbridge/ to .gitignore if you don't want it alongside your code repo,
+// or point --ledger elsewhere).
+//
+// Each fork produces one commit containing:
+//   claude/<session-id>.jsonl   - byte-for-byte copy of the source transcript
+//   opencode/<session-id>.json  - the converted OpenCode import payload
+//
+// This gives you a diffable, revertible history of every fork, and is the
+// foundation phase 2 (bidirectional sync) will build on: sync conflicts can
+// be reasoned about as diffs between ledger commits instead of ad hoc state.
+
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+export function ledgerPath(projectDir) {
+  return path.join(projectDir, ".agentbridge", "ledger");
+}
+
+function writeLedgerData(ledgerDir, subdir, sessionId, ext, source) {
+  const dest = path.join(ledgerDir, subdir, `${sessionId}.${ext}`);
+  if (source.path) {
+    // Raw source: byte-for-byte copy.
+    fs.copyFileSync(source.path, dest);
+  } else if (ext === "jsonl") {
+    // Claude-format data: an array of JSONL entries.
+    const lines = Array.isArray(source.data)
+      ? source.data.map((e) => JSON.stringify(e)).join("\n") + "\n"
+      : source.data + "\n";
+    fs.writeFileSync(dest, lines);
+  } else {
+    // OpenCode-format data: a JSON object.
+    fs.writeFileSync(dest, JSON.stringify(source.data, null, 2) + "\n");
+  }
+  return dest;
+}
+
+function countMessages(claudeSource, opencodeSource) {
+  if (claudeSource.data && Array.isArray(claudeSource.data)) {
+    return claudeSource.data.length;
+  }
+  if (opencodeSource.data && Array.isArray(opencodeSource.data.messages)) {
+    return opencodeSource.data.messages.length;
+  }
+  return 0;
+}
+
+const MAPPING_FILE = "mapping.json";
+
+function git(cwd, args) {
+  return execFileSync("git", args, { cwd, stdio: ["ignore", "pipe", "pipe"] })
+    .toString()
+    .trim();
+}
+
+function readMapping(ledgerDir) {
+  const p = path.join(ledgerDir, MAPPING_FILE);
+  if (!fs.existsSync(p)) return { pairs: [] };
+  try {
+    const data = JSON.parse(fs.readFileSync(p, "utf8"));
+    return { pairs: Array.isArray(data.pairs) ? data.pairs : [] };
+  } catch {
+    return { pairs: [] };
+  }
+}
+
+function writeMapping(ledgerDir, mapping) {
+  const p = path.join(ledgerDir, MAPPING_FILE);
+  fs.writeFileSync(p, JSON.stringify(mapping, null, 2) + "\n");
+}
+
+function updateMapping(mapping, claudeId, opencodeId) {
+  if (!claudeId || !opencodeId) return;
+  const existing = mapping.pairs.find(
+    (p) => p.claudeId === claudeId || p.opencodeId === opencodeId
+  );
+  if (existing) {
+    existing.claudeId = claudeId;
+    existing.opencodeId = opencodeId;
+  } else {
+    mapping.pairs.push({ claudeId, opencodeId });
+  }
+}
+
+export function findMapping(ledgerDir, { claudeId, opencodeId } = {}) {
+  const mapping = readMapping(ledgerDir);
+  return mapping.pairs.find(
+    (p) => (claudeId && p.claudeId === claudeId) || (opencodeId && p.opencodeId === opencodeId)
+  );
+}
+
+export function ensureLedger(ledgerDir) {
+  fs.mkdirSync(ledgerDir, { recursive: true });
+  fs.mkdirSync(path.join(ledgerDir, "claude"), { recursive: true });
+  fs.mkdirSync(path.join(ledgerDir, "opencode"), { recursive: true });
+  if (!fs.existsSync(path.join(ledgerDir, ".git"))) {
+    git(ledgerDir, ["init", "-q"]);
+    // Local, tool-only identity so this works even with no global git config.
+    git(ledgerDir, ["config", "user.email", "agentbridge@local"]);
+    git(ledgerDir, ["config", "user.name", "agentbridge"]);
+  }
+}
+
+export function readLedgerFiles(ledgerDir, sessionId) {
+  const claudePath = path.join(ledgerDir, "claude", `${sessionId}.jsonl`);
+  const opencodePath = path.join(ledgerDir, "opencode", `${sessionId}.json`);
+  const claude = fs.existsSync(claudePath)
+    ? fs.readFileSync(claudePath, "utf8").split("\n").filter(Boolean).map(JSON.parse)
+    : null;
+  const opencode = fs.existsSync(opencodePath)
+    ? JSON.parse(fs.readFileSync(opencodePath, "utf8"))
+    : null;
+  return { claude, opencode };
+}
+
+/**
+ * Read the ledger state for a session pair, trying both the Claude and OpenCode
+ * ids. Forward forks key files by Claude id; reverse forks key by OpenCode id.
+ */
+export function readLedgerPair(ledgerDir, claudeId, opencodeId) {
+  const a = readLedgerFiles(ledgerDir, claudeId);
+  const b = readLedgerFiles(ledgerDir, opencodeId);
+  // Prefer the more recently modified claude file if both exist.
+  const aClaudePath = path.join(ledgerDir, "claude", `${claudeId}.jsonl`);
+  const bClaudePath = path.join(ledgerDir, "claude", `${opencodeId}.jsonl`);
+  const aTime = fs.existsSync(aClaudePath) ? fs.statSync(aClaudePath).mtimeMs : 0;
+  const bTime = fs.existsSync(bClaudePath) ? fs.statSync(bClaudePath).mtimeMs : 0;
+  const preferB = bTime > aTime;
+  return {
+    claude: (preferB ? b.claude : null) ?? a.claude,
+    opencode: (preferB ? b.opencode : null) ?? a.opencode,
+  };
+}
+
+/**
+ * Write the raw + converted files and commit them.
+ *
+ * One of the two sources is always the raw source (provided as a file path) and
+ * the other is the converted form (provided as data), but the ledger stores
+ * both representations keyed by the source session id regardless of direction.
+ *
+ * @param {object} claudeSource - either { path: string } or { data: object[] }
+ * @param {object} opencodeSource - either { path: string } or { data: object }
+ * @returns {{hash:string, changed:boolean}}
+ */
+export function commitFork(ledgerDir, { sessionId, claudeId, opencodeId, claudeSource, opencodeSource, direction }) {
+  ensureLedger(ledgerDir);
+
+  writeLedgerData(ledgerDir, "claude", sessionId, "jsonl", claudeSource);
+  writeLedgerData(ledgerDir, "opencode", sessionId, "json", opencodeSource);
+
+  // Record the bidirectional id mapping for sync.
+  let resolvedClaudeId = claudeId;
+  if (!resolvedClaudeId) {
+    if (Array.isArray(claudeSource.data)) {
+      resolvedClaudeId = claudeSource.data[0]?.sessionId;
+    } else if (claudeSource.path) {
+      resolvedClaudeId = path.basename(claudeSource.path).replace(/\.jsonl$/, "");
+    }
+  }
+  let resolvedOpenCodeId = opencodeId;
+  if (!resolvedOpenCodeId) {
+    if (opencodeSource.data && typeof opencodeSource.data === "object" && opencodeSource.data.info?.id) {
+      resolvedOpenCodeId = opencodeSource.data.info.id;
+    }
+  }
+  const mapping = readMapping(ledgerDir);
+  updateMapping(mapping, resolvedClaudeId, resolvedOpenCodeId);
+  writeMapping(ledgerDir, mapping);
+
+  git(ledgerDir, ["add", "-A"]);
+
+  const messageCount = countMessages(claudeSource, opencodeSource);
+  const summary = `fork ${direction}: ${sessionId} (${messageCount} messages)`;
+
+  // Nothing to commit (re-forking an unchanged session) shouldn't be an error.
+  try {
+    git(ledgerDir, ["commit", "-q", "-m", summary]);
+  } catch (err) {
+    const msg = err.stdout?.toString() ?? err.message;
+    if (/nothing to commit/i.test(msg)) {
+      return { hash: git(ledgerDir, ["rev-parse", "HEAD"]), changed: false };
+    }
+    throw err;
+  }
+
+  return { hash: git(ledgerDir, ["rev-parse", "HEAD"]), changed: true };
+}
+
+export function log(ledgerDir, limit = 20) {
+  // Reading history shouldn't create anything: if no ledger exists yet, there
+  // are simply no forks to show.
+  if (!fs.existsSync(path.join(ledgerDir, ".git"))) return [];
+
+  let out;
+  try {
+    out = git(ledgerDir, [
+      "log",
+      `-${limit}`,
+      "--pretty=format:%H|%ad|%s",
+      "--date=iso-strict",
+    ]);
+  } catch (err) {
+    // A freshly `git init`ed repo with no commits makes `git log` exit 128
+    // ("does not have any commits yet") - treat that as an empty history.
+    const msg = (err.stderr?.toString() ?? "") + (err.stdout?.toString() ?? "") + (err.message ?? "");
+    if (/does not have any commits|unknown revision|bad default revision/i.test(msg)) return [];
+    throw err;
+  }
+  if (!out) return [];
+  return out.split("\n").map((line) => {
+    const [hash, date, ...rest] = line.split("|");
+    return { hash, date, message: rest.join("|") };
+  });
+}

package/src/readers/claude-reader.js

@@ -0,0 +1,186 @@
+// src/readers/claude-reader.js
+//
+// Reads Claude Code's local session storage.
+//
+// Claude Code stores one JSONL file per session under:
+//   ~/.claude/projects/<encoded-cwd>/<session-uuid>.jsonl
+// where <encoded-cwd> is the absolute working directory with "/" (and other
+// path separators) replaced by "-".
+//
+// Each line is one JSON object ("entry"). The fields we rely on:
+//   type          "user" | "assistant" | "summary" | ...
+//   uuid          this entry's id
+//   parentUuid    previous entry's id (linear chain, ignoring branches)
+//   sessionId     the session this entry belongs to
+//   timestamp     ISO-8601 string
+//   isSidechain   true for subagent/background-task turns
+//   isMeta        true for Claude Code's own system/meta messages
+//   cwd           working directory Claude Code was run from
+//   gitBranch     git branch at the time, if any
+//   version       Claude Code version string
+//   message       { role, content, model, usage, ... }
+//     content is either a plain string or an array of content blocks:
+//       { type: "text", text }
+//       { type: "thinking", thinking }
+//       { type: "tool_use", id, name, input }
+//       { type: "tool_result", tool_use_id, content, is_error }
+//   toolUseResult sometimes carries the raw tool result payload for a
+//                 preceding tool_use (attached to the *next* "user" entry)
+
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+export function claudeProjectsDir() {
+  return path.join(os.homedir(), ".claude", "projects");
+}
+
+/**
+ * Claude Code's own encoding of an absolute path into a directory name.
+ *
+ * Claude Code names each project directory after its absolute cwd with EVERY
+ * non-alphanumeric character replaced by "-" (not just the path separators).
+ * Dots, underscores, spaces, etc. all become "-", and runs are NOT collapsed:
+ *   /Users/me/.config/my_app  ->  -Users-me--config-my-app
+ * Verified against real directory names under ~/.claude/projects. An earlier
+ * version replaced only "/" and "\", which silently found nothing for any
+ * project whose path contained a ".", "_", space, or other punctuation.
+ */
+export function encodeProjectPath(absPath) {
+  return absPath.replace(/[^a-zA-Z0-9]/g, "-");
+}
+
+/** Find the project directory for a given cwd, or null if none exists. */
+export function findProjectDir(cwd = process.cwd()) {
+  const base = claudeProjectsDir();
+  const candidate = path.join(base, encodeProjectPath(path.resolve(cwd)));
+  return fs.existsSync(candidate) ? candidate : null;
+}
+
+/** List session files (main sessions only, not agent-*.jsonl subagent files) for a project dir. */
+export function listSessions(projectDir) {
+  if (!fs.existsSync(projectDir)) return [];
+  return fs
+    .readdirSync(projectDir)
+    .filter((f) => f.endsWith(".jsonl") && !f.startsWith("agent-"))
+    .map((f) => {
+      const full = path.join(projectDir, f);
+      const stat = fs.statSync(full);
+      return { id: f.replace(/\.jsonl$/, ""), file: full, mtime: stat.mtimeMs };
+    })
+    .sort((a, b) => b.mtime - a.mtime); // newest first
+}
+
+/** Find the most recently modified session for a project dir. */
+export function findLatestSession(cwd = process.cwd()) {
+  const dir = findProjectDir(cwd);
+  if (!dir) return null;
+  const sessions = listSessions(dir);
+  return sessions[0] || null;
+}
+
+/** Locate a specific session by id, searching all projects if needed. */
+export function findSessionById(sessionId, cwd = process.cwd()) {
+  const dir = findProjectDir(cwd);
+  if (dir) {
+    const direct = path.join(dir, `${sessionId}.jsonl`);
+    if (fs.existsSync(direct)) return { id: sessionId, file: direct };
+  }
+  // Fall back to scanning every project directory.
+  const base = claudeProjectsDir();
+  if (!fs.existsSync(base)) return null;
+  for (const projectName of fs.readdirSync(base)) {
+    const full = path.join(base, projectName, `${sessionId}.jsonl`);
+    if (fs.existsSync(full)) return { id: sessionId, file: full };
+  }
+  return null;
+}
+
+/** Parse a session JSONL file into an ordered list of entries. Skips malformed lines. */
+export function parseSessionFile(filePath) {
+  const raw = fs.readFileSync(filePath, "utf8");
+  const entries = [];
+  for (const line of raw.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      entries.push(JSON.parse(trimmed));
+    } catch {
+      // Corrupt/partial line (e.g. a crash mid-write) - skip it rather than fail the whole fork.
+    }
+  }
+  return entries;
+}
+
+/**
+ * Reduce raw entries to the linear conversation Claude Code would render:
+ * drop sidechains (subagent turns) and meta entries, keep user/assistant only.
+ */
+export function toConversation(entries) {
+  return entries.filter(
+    (e) => !e.isSidechain && !e.isMeta && (e.type === "user" || e.type === "assistant")
+  );
+}
+
+/** List every project directory Claude Code has recorded sessions for. */
+export function listAllProjectDirs() {
+  const base = claudeProjectsDir();
+  if (!fs.existsSync(base)) return [];
+  return fs
+    .readdirSync(base)
+    .map((name) => path.join(base, name))
+    .filter((full) => fs.statSync(full).isDirectory());
+}
+
+/** Best-effort plain-text preview of a single content block or string. */
+function previewText(content) {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    const textBlock = content.find((b) => b.type === "text" && b.text);
+    if (textBlock) return textBlock.text;
+    const toolBlock = content.find((b) => b.type === "tool_use");
+    if (toolBlock) return `[used tool: ${toolBlock.name}]`;
+  }
+  return "";
+}
+
+/**
+ * Build a short, human-readable summary of a session for browsing:
+ * first user message, how many turns, when it was last touched.
+ */
+export function summarizeSession(entries) {
+  const convo = toConversation(entries);
+  const firstUser = convo.find((e) => e.type === "user");
+  const lastEntry = convo[convo.length - 1];
+  const firstLine = firstUser ? previewText(firstUser.message?.content).split("\n")[0] : "(empty)";
+  return {
+    messageCount: convo.length,
+    firstMessage: firstLine.slice(0, 120),
+    lastTimestamp: lastEntry?.timestamp ?? null,
+    cwd: entries.find((e) => e.cwd)?.cwd ?? null,
+    gitBranch: entries.find((e) => e.gitBranch)?.gitBranch ?? null,
+  };
+}
+
+/** Render a full transcript preview (for `agentbridge show`). */
+export function renderTranscript(entries) {
+  const convo = toConversation(entries);
+  const lines = [];
+  for (const e of convo) {
+    const who = e.type === "user" ? "You" : "Claude";
+    const blocks = Array.isArray(e.message?.content) ? e.message.content : null;
+    if (blocks) {
+      for (const b of blocks) {
+        if (b.type === "text" && b.text) lines.push(`[${who}] ${b.text}`);
+        else if (b.type === "tool_use") lines.push(`[${who}] → tool: ${b.name}(${JSON.stringify(b.input)})`);
+        else if (b.type === "tool_result") lines.push(`[tool result] ${previewText(b.content).slice(0, 300)}`);
+        else if (b.type === "thinking") lines.push(`[${who} thinking] ${b.thinking}`);
+      }
+    } else if (typeof e.message?.content === "string" && e.message.content) {
+      lines.push(`[${who}] ${e.message.content}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+

package/src/readers/opencode-reader.js

@@ -0,0 +1,270 @@
+// src/readers/opencode-reader.js
+//
+// Reads OpenCode's local session storage via the `opencode` CLI.
+//
+// OpenCode's internal storage format (SQLite files under ~/.config/opencode/
+// etc.) has changed before and may change again. The stable read surface is the
+// `opencode` CLI: `session list --format json` and `export <id>` both return
+// JSON matching the import/export contract this tool already uses.
+
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createRequire } from "node:module";
+
+let DatabaseSync;
+function getDatabaseSync() {
+  if (DatabaseSync) return DatabaseSync;
+  try {
+    const require = createRequire(import.meta.url);
+    ({ DatabaseSync } = require("node:sqlite"));
+  } catch {
+    // node:sqlite is only available in Node.js 22.5+. Fall back to CLI export.
+  }
+  return DatabaseSync;
+}
+
+function run(args, maxBytes = 100 * 1024 * 1024) {
+  try {
+    return execFileSync("opencode", args, {
+      stdio: ["ignore", "pipe", "pipe"],
+      maxBuffer: maxBytes,
+    })
+      .toString()
+      .trim();
+  } catch (err) {
+    const stderr = err.stderr?.toString() ?? "";
+    const stdout = err.stdout?.toString() ?? "";
+    throw new Error(
+      `opencode ${args.join(" ")} failed: ${stderr || stdout || err.message}`
+    );
+  }
+}
+
+/**
+ * Run an opencode subcommand whose stdout can be large and parse it from a
+ * temp file. execFileSync's pipe buffer sometimes truncates multi-hundred-KB
+ * JSON; writing straight to a file descriptor avoids that.
+ */
+function runToFile(args) {
+  const tmpFile = path.join(os.tmpdir(), `agentbridge-${args.join("-")}-${Date.now()}.json`);
+  const fd = fs.openSync(tmpFile, "w");
+  try {
+    execFileSync("opencode", args, {
+      stdio: ["ignore", fd, "pipe"],
+    });
+  } catch (err) {
+    const stderr = err.stderr?.toString() ?? "";
+    throw new Error(`opencode ${args.join(" ")} failed: ${stderr || err.message}`);
+  } finally {
+    fs.closeSync(fd);
+  }
+  try {
+    const content = fs.readFileSync(tmpFile, "utf8");
+    fs.unlinkSync(tmpFile);
+    return content;
+  } catch (err) {
+    throw new Error(`Failed to read opencode output from ${tmpFile}: ${err.message}`);
+  }
+}
+
+/** List all OpenCode sessions, newest first (by `updated` time). */
+export function listSessions() {
+  const out = run(["session", "list", "--format", "json"]);
+  const sessions = out ? JSON.parse(out) : [];
+  if (!Array.isArray(sessions)) return [];
+  return sessions
+    .map((s) => ({
+      id: s.id,
+      title: s.title ?? "Untitled",
+      directory: s.directory,
+      created: s.created,
+      updated: s.updated,
+      session: exportSession(s.id),
+    }))
+    .sort((a, b) => b.updated - a.updated);
+}
+
+/** List OpenCode sessions whose directory matches the given project path. */
+export function listSessionsForDir(dir) {
+  const resolved = path.resolve(dir);
+  return listSessions().filter((s) => s.directory === resolved);
+}
+
+/** Find the most recently updated OpenCode session. */
+export function findLatestSession() {
+  const sessions = listSessions();
+  return sessions[0] ? { id: sessions[0].id, session: exportSession(sessions[0].id) } : null;
+}
+
+function openCodeDbPath() {
+  const home = os.homedir();
+  if (process.platform === "darwin" || process.platform === "linux") {
+    return path.join(home, ".local", "share", "opencode", "opencode.db");
+  }
+  if (process.platform === "win32") {
+    return path.join(process.env.LOCALAPPDATA || home, "opencode", "opencode.db");
+  }
+  return path.join(home, ".local", "share", "opencode", "opencode.db");
+}
+
+/**
+ * Read a session straight from OpenCode's SQLite database.
+ *
+ * This is a fallback / augmentation for `opencode export`. The CLI export has
+ * proven unreliable in live situations (while the OpenCode server is running,
+ * or when an imported session is continued): it can return empty parts, drop
+ * imported messages, or only reflect the server's in-memory state. The SQLite
+ * file is the durable source of truth, so reading it directly is more robust.
+ *
+ * Returns `null` if the database is unavailable, the schema is unexpected, or
+ * the session is not found, so callers can fall back to CLI export.
+ */
+export function readSessionFromDatabase(sessionId, dbPathOverride) {
+  const DatabaseSync = getDatabaseSync();
+  if (!DatabaseSync) return null;
+  const dbPath = dbPathOverride || openCodeDbPath();
+  if (!fs.existsSync(dbPath)) return null;
+
+  let db;
+  try {
+    db = new DatabaseSync(dbPath, { readOnly: true });
+  } catch {
+    return null;
+  }
+
+  try {
+    // Message rows are stored as JSON blobs with a shape like:
+    //   {"role":"user", "time":{"created":...}, "agent":..., "model":...}
+    //   {"role":"assistant", "parentID":"...", "time":{...}, "tokens":...}
+    // The `id` column is the message id, but it is not duplicated inside the
+    // JSON blob, so we inject it as `info.id` (and `info.sessionID`, etc.) to
+    // match the public export shape.
+    const messageStmt = db.prepare(
+      "SELECT id, data FROM message WHERE session_id = ? ORDER BY time_created, id"
+    );
+    const messageRows = messageStmt.all(sessionId);
+    if (messageRows.length === 0) return null;
+
+    const partStmt = db.prepare(
+      "SELECT id, message_id, data FROM part WHERE session_id = ? ORDER BY time_created, id"
+    );
+    const partRows = partStmt.all(sessionId);
+
+    const partsByMessage = new Map();
+    for (const p of partRows) {
+      const list = partsByMessage.get(p.message_id) || [];
+      const partData = JSON.parse(p.data);
+      list.push({ ...partData, id: p.id, sessionID: sessionId, messageID: p.message_id });
+      partsByMessage.set(p.message_id, list);
+    }
+
+    const messages = [];
+    for (const row of messageRows) {
+      const msgData = JSON.parse(row.data);
+      const info = {
+        id: row.id,
+        sessionID: sessionId,
+        ...msgData,
+        time: msgData.time,
+      };
+      const parts = partsByMessage.get(row.id) || [];
+      messages.push({ info, parts });
+    }
+
+    const sessionStmt = db.prepare(
+      "SELECT id, title, directory, version, time_created, time_updated FROM session WHERE id = ?"
+    );
+    const sessionRow = sessionStmt.get(sessionId);
+    if (!sessionRow) return null;
+
+    const info = {
+      id: sessionRow.id,
+      title: sessionRow.title,
+      directory: sessionRow.directory,
+      version: sessionRow.version,
+      time: {
+        created: sessionRow.time_created,
+        updated: sessionRow.time_updated,
+      },
+    };
+
+    return { info, messages };
+  } catch {
+    // Schema or data shape changed; fall back to CLI export.
+    return null;
+  } finally {
+    try {
+      db.close();
+    } catch {
+      /* ignore */
+    }
+  }
+}
+
+/**
+ * Export one OpenCode session as JSON (the same shape `opencode import` accepts).
+ *
+ * We prefer the SQLite database reader because the CLI `export` is lossy when
+ * the OpenCode server is running or when an imported session is continued. The
+ * CLI export is kept as a fallback for portability / future schema changes.
+ */
+export function exportSession(sessionId) {
+  const fromDb = readSessionFromDatabase(sessionId);
+  if (fromDb) return fromDb;
+  const out = runToFile(["export", sessionId]);
+  return JSON.parse(out);
+}
+
+/** Find a specific OpenCode session by id and export it. */
+export function findSessionById(sessionId) {
+  const s = listSessions().find((x) => x.id === sessionId);
+  if (s) return { id: s.id, session: exportSession(s.id) };
+  // OpenCode's session list can lag behind imports; try exporting directly.
+  try {
+    return { id: sessionId, session: exportSession(sessionId) };
+  } catch {
+    return null;
+  }
+}
+
+/** Best-effort plain-text preview of a single OpenCode part. */
+function previewText(part) {
+  if (part.type === "text" && part.text) return part.text;
+  if (part.type === "reasoning" && part.text) return part.text;
+  if (part.type === "tool") return `[used tool: ${part.tool}]`;
+  return "";
+}
+
+/**
+ * Build a short, human-readable summary of an OpenCode session for browsing:
+ * first user message, how many messages, when it was last touched.
+ */
+export function summarizeSession(session) {
+  const messages = session.messages ?? [];
+  const firstUser = messages.find((m) => m.info?.role === "user");
+  const firstPart = firstUser?.parts?.find((p) => previewText(p));
+  const firstLine = firstPart ? previewText(firstPart).split("\n")[0] : "(empty)";
+  return {
+    messageCount: messages.length,
+    firstMessage: firstLine.slice(0, 120),
+    lastTimestamp: session.info?.time?.updated ? new Date(session.info.time.updated).toISOString() : null,
+    cwd: session.info?.directory ?? null,
+  };
+}
+
+/** Render a full transcript preview (for `agentbridge show`). */
+export function renderTranscript(session) {
+  const lines = [];
+  for (const m of session.messages ?? []) {
+    const who = m.info?.role === "user" ? "You" : "OpenCode";
+    for (const p of m.parts ?? []) {
+      if (p.type === "text" && p.text) lines.push(`[${who}] ${p.text}`);
+      else if (p.type === "reasoning" && p.text) lines.push(`[${who} thinking] ${p.text}`);
+      else if (p.type === "tool") lines.push(`[${who}] → tool: ${p.tool}(${JSON.stringify(p.state?.input ?? {})})`);
+      else if (p.type === "tool" && p.state?.output) lines.push(`[tool result] ${String(p.state.output).slice(0, 300)}`);
+    }
+  }
+  return lines.join("\n");
+}