mini-coder 0.5.14 → 0.6.1

package/src/session.ts

@@ -1,1337 +1,86 @@
-/**
- * Session persistence layer.
- *
- * Stores sessions and their message histories in a single SQLite database
- * via `bun:sqlite`. Messages are stored as JSON-serialized pi-ai {@link Message}
- * objects grouped by turn number. Cumulative token/cost stats are computed
- * from the message history rather than stored separately.
- *
- * @module
- */
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import type { Message } from "@mariozechner/pi-ai";
+import { Value } from "typebox/value";
+import { SESSIONS_DIR } from "./shared";
+import { type Session, SessionSchema } from "./types";
 
-import { Database } from "bun:sqlite";
-import type {
-  AssistantMessage,
-  Message,
-  UserMessage,
-} from "@mariozechner/pi-ai";
-import {
-  getAssistantUsage,
-  isUiMessage,
-  type PersistedMessage,
-  parsePersistedMessage,
-  readAssistantUsage,
-  readFirstUserPreview,
-  type UiInfoFormat,
-  type UiInfoMessage,
-  type UiMessage,
-  type UiTodoMessage,
-} from "./session-message.ts";
-import type { TodoItem } from "./tools.ts";
+// TODO: sessions are json files in SESSIONS_DIR inside of DATA_DIR, use a 10 length `secureRandomString()` for the ids.
 
-export type {
-  PersistedMessage,
-  UiInfoFormat,
-  UiInfoMessage,
-  UiMessage,
-  UiTodoMessage,
-};
-export { getAssistantUsage };
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-/**
- * A persisted session record.
- *
- * Represents a single conversation scoped to a working directory.
- * The `model` and `effort` fields reflect the values at session creation —
- * the user may switch models mid-session via `/model`, but the session
- * record is not updated (individual assistant messages carry their own model).
- */
-export interface Session {
-  /** Unique session identifier (UUID). */
-  id: string;
-  /** Working directory the session is scoped to. */
-  cwd: string;
-  /** Provider/model string at creation time, e.g. `"anthropic/claude-sonnet-4-20250514"`. */
-  model: string | null;
-  /** Thinking effort level at creation time. */
-  effort: string | null;
-  /** ID of the session this was forked from, or `null` if original. */
-  forkedFrom: string | null;
-  /** Unix timestamp in milliseconds when the session was created. */
-  createdAt: number;
-  /** Unix timestamp in milliseconds, updated on each new message. */
-  updatedAt: number;
-}
-
-/** Session row used by the `/session` picker. */
-export interface SessionListEntry extends Session {
-  /** First conversational user message collapsed into a single-line preview, or `null` when none exists. */
-  firstUserPreview: string | null;
-}
-
-/**
- * Cumulative input/output token and cost statistics for a session.
- *
- * Computed by summing `usage` fields from all {@link AssistantMessage}s
- * in the session's history. Not stored — derived on load and maintained
- * in-memory during the session. These feed the status bar's cumulative
- * `in`, `out`, and `$cost` values; current context usage is estimated
- * separately from the current model-visible history.
- */
-export interface SessionStats {
-  /** Total input tokens across all assistant messages. */
-  totalInput: number;
-  /** Total output tokens across all assistant messages. */
-  totalOutput: number;
-  /** Total cost in dollars across all assistant messages. */
-  totalCost: number;
-}
-
-/** One persisted synthetic summary that replaces an older compacted context prefix. */
-export interface SessionCompaction {
-  /** Monotonic compaction row id. */
-  id: number;
-  /** Session that owns this compaction. */
-  sessionId: string;
-  /** Message-row id of the last raw message covered by the summary. */
-  messageEndId: number;
-  /** Synthetic user message injected into future model context. */
-  summaryMessage: UserMessage;
-  /** Unix timestamp in milliseconds when the compaction was created. */
-  createdAt: number;
-}
-
-/** One uncompacted model-visible session message paired with its SQLite row id. */
-export interface SessionModelMessageRow {
-  /** Monotonic message row id. */
-  id: number;
-  /** Persisted model-visible message. */
-  message: Message;
-}
-
-/** A raw submitted prompt stored for global input-history search. */
-interface PromptHistoryEntry {
-  /** Monotonic row id. */
-  id: number;
-  /** Exact raw prompt text as submitted by the user. */
-  text: string;
-  /** Working directory where the prompt was submitted. */
-  cwd: string;
-  /** Originating session id when available. */
-  sessionId: string | null;
-  /** Unix timestamp in milliseconds when the prompt was submitted. */
-  createdAt: number;
-}
-
-/** Options for appending a raw prompt-history entry. */
-interface AppendPromptHistoryOpts {
-  /** Exact raw prompt text as submitted by the user. */
-  text: string;
-  /** Working directory where the prompt was submitted. */
-  cwd: string;
-  /** Originating session id when available. */
-  sessionId?: string;
+export async function ensureSessionsDir(): Promise<void> {
+  await mkdir(SESSIONS_DIR, { recursive: true });
 }
 
-/** Options for creating a new session. */
-interface CreateSessionOpts {
-  /** Working directory to scope the session to. */
-  cwd: string;
-  /** Provider/model identifier, e.g. `"anthropic/claude-sonnet-4-20250514"`. */
-  model?: string;
-  /** Thinking effort level, e.g. `"medium"`. */
-  effort?: string;
-}
-
-// ---------------------------------------------------------------------------
-// Internal row types (map directly to SQLite column names)
-// ---------------------------------------------------------------------------
-
-/** Row shape returned by `SELECT * FROM sessions`. */
-type SessionRow = {
-  id: string;
-  cwd: string;
-  model: string | null;
-  effort: string | null;
-  forked_from: string | null;
-  created_at: number;
-  updated_at: number;
-};
-
-/** Row shape returned by the `/session` picker query. */
-type SessionListRow = SessionRow & {
-  first_user_message_data: string | null;
-};
-
-/** Row shape for `SELECT MAX(turn)` queries. */
-type MaxTurnRow = { max_turn: number | null };
-
-/** Row shape for `SELECT id, data` message queries. */
-type StoredMessageRow = {
-  id: number;
-  data: string;
-};
-
-/** Row shape returned by `SELECT * FROM session_compactions`. */
-type SessionCompactionRow = {
-  id: number;
-  session_id: string;
-  message_end_id: number;
-  summary_data: string;
-  usage_data: string | null;
-  created_at: number;
-};
-
-/** Row shape for `SELECT message_end_id` compaction queries. */
-type CompactionEndRow = { message_end_id: number };
-
-/** Row shape returned by `SELECT id` message queries. */
-type MessageIdRow = { id: number };
-
-/** Row shape for `SELECT data` queries. */
-type DataRow = { data: string };
-
-const SQLITE_BUSY_TIMEOUT_MS = 1_000;
-
-/** Row shape returned by `SELECT * FROM prompt_history`. */
-type PromptHistoryRow = {
-  id: number;
-  text: string;
-  cwd: string;
-  session_id: string | null;
-  created_at: number;
-};
-
-// ---------------------------------------------------------------------------
-// SQL
-// ---------------------------------------------------------------------------
+// readSession: writes the session
+export async function getSession(id: string): Promise<Session | undefined> {
+  const file = Bun.file(join(SESSIONS_DIR, `${id}.json`));
 
-const SQL = {
-  listSessions: `
-    SELECT
-      sessions.*,
-      (
-        SELECT data
-        FROM messages
-        WHERE session_id = sessions.id AND turn IS NOT NULL
-        ORDER BY id
-        LIMIT 1
-      ) AS first_user_message_data
-    FROM sessions
-    WHERE cwd = ?
-    ORDER BY updated_at DESC, rowid DESC
-  `,
-  maxTurn: "SELECT MAX(turn) as max_turn FROM messages WHERE session_id = ?",
-  loadMessages: "SELECT data FROM messages WHERE session_id = ? ORDER BY id",
-  loadStoredMessagesAfterId:
-    "SELECT id, data FROM messages WHERE session_id = ? AND id > ? ORDER BY id",
-  listCompactions:
-    "SELECT * FROM session_compactions WHERE session_id = ? ORDER BY message_end_id, id",
-  latestCompactionEnd:
-    "SELECT message_end_id FROM session_compactions WHERE session_id = ? ORDER BY message_end_id DESC, id DESC LIMIT 1",
-  firstMessageIdForTurn:
-    "SELECT id FROM messages WHERE session_id = ? AND turn = ? ORDER BY id LIMIT 1",
-  listMessageIds: "SELECT id FROM messages WHERE session_id = ? ORDER BY id",
-  listPromptHistory:
-    "SELECT * FROM prompt_history ORDER BY created_at DESC, id DESC LIMIT ?",
-} as const;
-
-const SCHEMA = `
-CREATE TABLE IF NOT EXISTS sessions (
-  id          TEXT PRIMARY KEY,
-  cwd         TEXT NOT NULL,
-  model       TEXT,
-  effort      TEXT,
-  forked_from TEXT,
-  created_at  INTEGER NOT NULL,
-  updated_at  INTEGER NOT NULL
-);
-
-CREATE INDEX IF NOT EXISTS idx_sessions_cwd ON sessions(cwd);
-
-CREATE TABLE IF NOT EXISTS messages (
-  id          INTEGER PRIMARY KEY AUTOINCREMENT,
-  session_id  TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
-  turn        INTEGER,
-  data        TEXT NOT NULL,
-  created_at  INTEGER NOT NULL
-);
-
-CREATE INDEX IF NOT EXISTS idx_messages_session ON messages(session_id, turn);
-
-CREATE TABLE IF NOT EXISTS session_compactions (
-  id             INTEGER PRIMARY KEY AUTOINCREMENT,
-  session_id     TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
-  message_end_id INTEGER NOT NULL,
-  summary_data   TEXT NOT NULL,
-  usage_data     TEXT,
-  created_at     INTEGER NOT NULL
-);
-
-CREATE INDEX IF NOT EXISTS idx_session_compactions_session ON session_compactions(session_id, message_end_id);
-
-CREATE TABLE IF NOT EXISTS prompt_history (
-  id          INTEGER PRIMARY KEY AUTOINCREMENT,
-  text        TEXT NOT NULL,
-  cwd         TEXT NOT NULL,
-  session_id  TEXT,
-  created_at  INTEGER NOT NULL
-);
-
-CREATE INDEX IF NOT EXISTS idx_prompt_history_created_at ON prompt_history(created_at, id);
-`;
-
-// ---------------------------------------------------------------------------
-// Database
-// ---------------------------------------------------------------------------
-
-/**
- * Open (or create) the SQLite database and ensure the schema exists.
- *
- * Enables WAL journal mode for concurrent read performance and foreign
- * keys for cascade deletes. Pass `":memory:"` for an in-memory database
- * (useful in tests).
- *
- * @param path - File path for the database, or `":memory:"` for in-memory.
- * @returns An open {@link Database} handle. The caller is responsible for
- *          closing it when done.
- *
- * @example
- * ```ts
- * const db = openDatabase("~/.config/mini-coder/mini-coder.db");
- * // ... use db ...
- * db.close();
- * ```
- */
-function ensureSessionCompactionUsageColumn(db: Database): void {
-  try {
-    db.run("ALTER TABLE session_compactions ADD COLUMN usage_data TEXT");
-  } catch (error) {
-    if (
-      !(error instanceof Error) ||
-      !error.message.includes("duplicate column name: usage_data")
-    ) {
-      throw error;
-    }
+  if (!(await file.exists())) {
+    return;
   }
-}
 
-export function openDatabase(path: string): Database {
-  const db = new Database(path);
-  db.run("PRAGMA journal_mode = WAL");
-  db.run(`PRAGMA busy_timeout = ${SQLITE_BUSY_TIMEOUT_MS}`);
-  db.run("PRAGMA foreign_keys = ON");
-  db.exec(SCHEMA);
-  ensureSessionCompactionUsageColumn(db);
-  return db;
-}
+  const sessionJson = await file.text();
+  const parsed = JSON.parse(sessionJson) as unknown;
+  const valid = Value.Check(SessionSchema, parsed);
 
-// ---------------------------------------------------------------------------
-// Session CRUD
-// ---------------------------------------------------------------------------
-
-function generateId(): string {
-  return crypto.randomUUID();
+  if (valid) return parsed;
+  return;
 }
 
-/**
- * Create a new session record.
- *
- * @param db - Open database handle.
- * @param opts - Session options (cwd is required; model and effort are optional).
- * @returns The newly created {@link Session}.
- */
-export function createSession(db: Database, opts: CreateSessionOpts): Session {
-  const id = generateId();
-  const now = Date.now();
-  db.run(
-    "INSERT INTO sessions (id, cwd, model, effort, forked_from, created_at, updated_at) VALUES (?, ?, ?, ?, NULL, ?, ?)",
-    [id, opts.cwd, opts.model ?? null, opts.effort ?? null, now, now],
-  );
-  return {
-    id,
-    cwd: opts.cwd,
-    model: opts.model ?? null,
-    effort: opts.effort ?? null,
-    forkedFrom: null,
-    createdAt: now,
-    updatedAt: now,
-  };
-}
-
-/**
- * Retrieve a session by its ID.
- *
- * @param db - Open database handle.
- * @param id - The session UUID.
- * @returns The {@link Session}, or `null` if not found.
- */
-export function getSession(db: Database, id: string): Session | null {
-  const row = db
-    .query<SessionRow, [string]>("SELECT * FROM sessions WHERE id = ?")
-    .get(id);
-  if (!row) return null;
-  return {
-    id: row.id,
-    cwd: row.cwd,
-    model: row.model,
-    effort: row.effort,
-    forkedFrom: row.forked_from,
-    createdAt: row.created_at,
-    updatedAt: row.updated_at,
-  };
+function latestMessageTimestamp(session: Session): number {
+  return Math.max(0, ...session.messages.map((message) => message.timestamp));
 }
 
-/**
- * List sessions for a working directory, most recently updated first.
- *
- * @param db - Open database handle.
- * @param cwd - Working directory to filter by.
- * @returns Session rows ordered by `updatedAt` descending, enriched with the first-user preview.
- */
-export function listSessions(db: Database, cwd: string): SessionListEntry[] {
-  const rows = db.query<SessionListRow, [string]>(SQL.listSessions).all(cwd);
-  return rows.map((row) => ({
-    id: row.id,
-    cwd: row.cwd,
-    model: row.model,
-    effort: row.effort,
-    forkedFrom: row.forked_from,
-    createdAt: row.created_at,
-    updatedAt: row.updated_at,
-    firstUserPreview: readFirstUserPreview(row.first_user_message_data),
-  }));
-}
-
-/**
- * Delete a session and all its messages (via foreign key cascade).
- *
- * @param db - Open database handle.
- * @param id - The session UUID to delete.
- */
-export function deleteSession(db: Database, id: string): void {
-  db.run("DELETE FROM sessions WHERE id = ?", [id]);
-}
-
-/**
- * Keep only the most recent sessions for a CWD, deleting the rest.
- *
- * Sessions are ordered by `updated_at DESC`; those beyond `keep` are
- * deleted (cascade removes their messages too). No-op if the count is
- * already within the limit.
- *
- * @param db - Open database handle.
- * @param cwd - Working directory to scope the truncation to.
- * @param keep - Maximum number of sessions to retain.
- */
-export function truncateSessions(
-  db: Database,
-  cwd: string,
-  keep: number,
-): void {
-  db.run(
-    `DELETE FROM sessions WHERE id IN (
-       SELECT id FROM sessions WHERE cwd = ?
-       ORDER BY updated_at DESC, rowid DESC
-       LIMIT -1 OFFSET ?
-     )`,
-    [cwd, keep],
-  );
-}
+export async function listSessionsForCwd(): Promise<Session[]> {
+  const sessions: Session[] = [];
+  const sessionFiles = new Bun.Glob("*.json");
+  const cwd = process.cwd();
 
-// ---------------------------------------------------------------------------
-// Messages
-// ---------------------------------------------------------------------------
-
-/**
- * Create a persisted UI info message.
- *
- * @param content - Display text shown in the conversation log.
- * @param format - Optional rich-text format hint for the content.
- * @returns A new {@link UiInfoMessage}.
- */
-export function createUiMessage(
-  content: string,
-  format?: UiInfoFormat,
-): UiInfoMessage {
-  return {
-    role: "ui",
-    kind: "info",
-    content,
-    ...(format ? { format } : {}),
-    timestamp: Date.now(),
-  };
-}
-
-/**
- * Create a persisted UI todo snapshot message.
- *
- * @param todos - Todo snapshot rendered in the conversation log.
- * @returns A new {@link UiTodoMessage}.
- */
-export function createUiTodoMessage(todos: readonly TodoItem[]): UiTodoMessage {
-  return {
-    role: "ui",
-    kind: "todo",
-    todos: todos.map((todo) => ({ ...todo })),
-    timestamp: Date.now(),
-  };
-}
-
-/**
- * Filter persisted session history down to model-visible pi-ai messages.
- *
- * @param messages - Persisted session history.
- * @returns Only the pi-ai {@link Message} entries.
- */
-export function filterModelMessages(
-  messages: readonly PersistedMessage[],
-): Message[] {
-  return messages.filter(
-    (message): message is Message => !isUiMessage(message),
-  );
-}
-
-function runInImmediateTransaction<T>(db: Database, callback: () => T): T {
-  if (db.inTransaction) {
-    return callback();
-  }
-
-  db.run("BEGIN IMMEDIATE");
   try {
-    const result = callback();
-    db.run("COMMIT");
-    return result;
-  } catch (error) {
-    if (db.inTransaction) {
+    for await (const entry of sessionFiles.scan({
+      cwd: SESSIONS_DIR,
+      dot: true,
+    })) {
       try {
-        db.run("ROLLBACK");
-      } catch (rollbackError) {
-        throw new AggregateError(
-          [error, rollbackError],
-          "Failed to roll back SQLite transaction",
-        );
+        const sessionJson = await Bun.file(join(SESSIONS_DIR, entry)).text();
+        const parsed = JSON.parse(sessionJson) as unknown;
+
+        if (Value.Check(SessionSchema, parsed) && cwd === parsed.cwd) {
+          sessions.push(parsed);
+        }
+      } catch {
+        // Ignore invalid session files.
       }
     }
-    throw error;
-  }
-}
-
-function parseCompactionSummaryMessage(data: string): UserMessage | null {
-  const message = parsePersistedMessage(data);
-  return message?.role === "user" ? message : null;
-}
-
-function parseCompactionUsage(
-  data: string | null,
-): AssistantMessage["usage"] | null {
-  if (!data) {
-    return null;
-  }
-
-  try {
-    return readAssistantUsage(JSON.parse(data) as unknown);
   } catch {
-    return null;
+    return [];
   }
-}
-
-function getLatestCompactionEndId(db: Database, sessionId: string): number {
-  const row = db
-    .query<CompactionEndRow, [string]>(SQL.latestCompactionEnd)
-    .get(sessionId);
-  return row?.message_end_id ?? 0;
-}
-
-function listMessageIds(db: Database, sessionId: string): number[] {
-  return db
-    .query<MessageIdRow, [string]>(SQL.listMessageIds)
-    .all(sessionId)
-    .map((row) => row.id);
-}
-
-/**
- * List persisted compaction summaries for a session in replacement order.
- *
- * @param db - Open database handle.
- * @param sessionId - Session whose compactions should be listed.
- * @returns Parsed compaction summaries ordered by covered message range.
- */
-export function listSessionCompactions(
-  db: Database,
-  sessionId: string,
-): SessionCompaction[] {
-  const rows = db
-    .query<SessionCompactionRow, [string]>(SQL.listCompactions)
-    .all(sessionId);
-  const compactions: SessionCompaction[] = [];
-
-  for (const row of rows) {
-    const summaryMessage = parseCompactionSummaryMessage(row.summary_data);
-    if (!summaryMessage) {
-      continue;
-    }
-
-    compactions.push({
-      id: row.id,
-      sessionId: row.session_id,
-      messageEndId: row.message_end_id,
-      summaryMessage,
-      createdAt: row.created_at,
-    });
-  }
-
-  return compactions;
-}
-
-/**
- * Persist one synthetic compaction summary for future model-context rebuilds.
- *
- * @param db - Open database handle.
- * @param sessionId - Session that owns the compaction.
- * @param messageEndId - Last raw message-row id covered by the summary.
- * @param summaryMessage - Synthetic user message that replaces that prefix in context.
- * @param summaryUsage - Optional usage for the hidden summarization model call.
- * @returns The stored {@link SessionCompaction}.
- */
-export function appendSessionCompaction(
-  db: Database,
-  sessionId: string,
-  messageEndId: number,
-  summaryMessage: UserMessage,
-  summaryUsage?: AssistantMessage["usage"],
-): SessionCompaction {
-  return runInImmediateTransaction(db, () => {
-    const now = Date.now();
-    const result = db.run(
-      "INSERT INTO session_compactions (session_id, message_end_id, summary_data, usage_data, created_at) VALUES (?, ?, ?, ?, ?)",
-      [
-        sessionId,
-        messageEndId,
-        JSON.stringify(summaryMessage),
-        summaryUsage ? JSON.stringify(summaryUsage) : null,
-        now,
-      ],
-    );
-
-    return {
-      id: Number(result.lastInsertRowid),
-      sessionId,
-      messageEndId,
-      summaryMessage,
-      createdAt: now,
-    };
-  });
-}
-
-/**
- * Load raw model-visible messages that have not yet been compacted.
- *
- * @param db - Open database handle.
- * @param sessionId - Session whose uncompacted message tail should be loaded.
- * @returns Model-visible message rows after the latest compaction boundary.
- */
-export function loadUncompactedModelMessages(
-  db: Database,
-  sessionId: string,
-): SessionModelMessageRow[] {
-  const latestCompactionEndId = getLatestCompactionEndId(db, sessionId);
-  const rows = db
-    .query<StoredMessageRow, [string, number]>(SQL.loadStoredMessagesAfterId)
-    .all(sessionId, latestCompactionEndId);
-  const messages: SessionModelMessageRow[] = [];
-
-  for (const row of rows) {
-    const message = parsePersistedMessage(row.data);
-    if (!message || isUiMessage(message)) {
-      continue;
-    }
-
-    messages.push({ id: row.id, message });
-  }
-
-  return messages;
-}
-
-/**
- * Rebuild the model-visible session context using persisted compaction summaries.
- *
- * @param db - Open database handle.
- * @param sessionId - Session whose compacted model context should be loaded.
- * @returns Synthetic compaction summaries followed by the uncompacted message tail.
- */
-export function loadCompactedModelMessages(
-  db: Database,
-  sessionId: string,
-): Message[] {
-  return [
-    ...listSessionCompactions(db, sessionId).map(
-      (compaction) => compaction.summaryMessage,
-    ),
-    ...loadUncompactedModelMessages(db, sessionId).map((row) => row.message),
-  ];
-}
-
-/**
- * Compute the next-request context-token estimate for a persisted session.
- *
- * @param db - Open database handle.
- * @param sessionId - Session whose compacted model context should be estimated.
- * @returns Estimated context tokens for the next request.
- */
-export function computeSessionContextTokens(
-  db: Database,
-  sessionId: string,
-): number {
-  return computeContextTokens(loadCompactedModelMessages(db, sessionId));
-}
-
-/**
- * Append a UI-only message to a session's history.
- *
- * UI messages are persisted with `turn = NULL` so they remain visible in
- * history without participating in conversational turn numbering or `/undo`.
- *
- * @param db - Open database handle.
- * @param sessionId - The session to append to.
- * @param message - The UI-only message to persist.
- * @param turn - Ignored for UI messages.
- * @returns `null`, since UI messages do not belong to conversational turns.
- */
-export function appendMessage(
-  db: Database,
-  sessionId: string,
-  message: UiMessage,
-  turn?: number,
-): null;
-
-/**
- * Append a conversational message to a session's history.
- *
- * Turn numbering rules:
- * - When `turn` is **omitted**, a new turn is started with `MAX(turn) + 1`
- *   (or `1` for the first message). This is used for user messages.
- * - When `turn` is **provided**, the message joins that existing turn.
- *   This is used for assistant and tool-result messages that belong to
- *   the same agent loop as the initiating user message.
- *
- * Also updates the session's `updatedAt` timestamp.
- *
- * @param db - Open database handle.
- * @param sessionId - The session to append to.
- * @param message - A model-visible pi-ai message.
- * @param turn - Explicit turn number to join. Omit to start a new turn.
- * @returns The conversational turn number the message was stored with.
- */
-export function appendMessage(
-  db: Database,
-  sessionId: string,
-  message: Message,
-  turn?: number,
-): number;
-
-/**
- * Append a persisted message to a session's history.
- *
- * UI messages always store `turn = NULL`. Conversational messages either start
- * a new turn or join an existing one, depending on `turn`.
- *
- * @param db - Open database handle.
- * @param sessionId - The session to append to.
- * @param message - Persisted message to store.
- * @param turn - Explicit conversational turn to join.
- * @returns The assigned conversational turn number, or `null` for UI messages.
- */
-export function appendMessage(
-  db: Database,
-  sessionId: string,
-  message: PersistedMessage,
-  turn?: number,
-): number | null;
-
-/**
- * Append a persisted message to a session's history.
- *
- * UI messages always store `turn = NULL`. Conversational messages either start
- * a new turn or join an existing one, depending on `turn`.
- *
- * @param db - Open database handle.
- * @param sessionId - The session to append to.
- * @param message - Persisted message to store.
- * @param turn - Explicit conversational turn to join.
- * @returns The assigned conversational turn number, or `null` for UI messages.
- */
-export function appendMessage(
-  db: Database,
-  sessionId: string,
-  message: PersistedMessage,
-  turn?: number,
-): number | null {
-  return runInImmediateTransaction(db, () => {
-    const now = Date.now();
-
-    let effectiveTurn: number | null;
-    if (isUiMessage(message)) {
-      effectiveTurn = null;
-    } else if (turn !== undefined) {
-      effectiveTurn = turn;
-    } else {
-      const row = db.query<MaxTurnRow, [string]>(SQL.maxTurn).get(sessionId);
-      effectiveTurn = (row?.max_turn ?? 0) + 1;
-    }
-
-    db.run(
-      "INSERT INTO messages (session_id, turn, data, created_at) VALUES (?, ?, ?, ?)",
-      [sessionId, effectiveTurn, JSON.stringify(message), now],
-    );
-    db.run("UPDATE sessions SET updated_at = ? WHERE id = ?", [now, sessionId]);
 
-    return effectiveTurn;
-  });
-}
-
-/**
- * Load all messages for a session in insertion order.
- *
- * Messages are deserialized from their JSON representation back into
- * persisted app messages. Invalid rows are skipped so corrupted session data
- * does not crash the app. The ordering matches the original append order
- * (by autoincrement `id`), preserving the conversation flow.
- *
- * @param db - Open database handle.
- * @param sessionId - The session to load messages for.
- * @returns An array of {@link PersistedMessage} objects, empty if the session
- *          has no messages or does not exist.
- */
-export function loadMessages(
-  db: Database,
-  sessionId: string,
-): PersistedMessage[] {
-  const rows = db.query<DataRow, [string]>(SQL.loadMessages).all(sessionId);
-  const messages: PersistedMessage[] = [];
-
-  for (const row of rows) {
-    const message = parsePersistedMessage(row.data);
-    if (message) {
-      messages.push(message);
-    }
-  }
-
-  return messages;
-}
-
-// ---------------------------------------------------------------------------
-// Prompt history
-// ---------------------------------------------------------------------------
-
-/**
- * Append a raw submitted prompt to the global prompt-history table.
- *
- * This history is separate from conversational turn state: it is global,
- * append-only, and not affected by `/undo`.
- *
- * @param db - Open database handle.
- * @param opts - Prompt-history fields to persist.
- * @returns The stored {@link PromptHistoryEntry}.
- */
-export function appendPromptHistory(
-  db: Database,
-  opts: AppendPromptHistoryOpts,
-): PromptHistoryEntry {
-  const now = Date.now();
-  const result = db.run(
-    "INSERT INTO prompt_history (text, cwd, session_id, created_at) VALUES (?, ?, ?, ?)",
-    [opts.text, opts.cwd, opts.sessionId ?? null, now],
-  );
-
-  return {
-    id: Number(result.lastInsertRowid),
-    text: opts.text,
-    cwd: opts.cwd,
-    sessionId: opts.sessionId ?? null,
-    createdAt: now,
-  };
-}
-
-/**
- * List raw submitted prompts newest first.
- *
- * @param db - Open database handle.
- * @param limit - Maximum number of entries to return.
- * @returns Prompt-history entries ordered newest first.
- */
-export function listPromptHistory(
-  db: Database,
-  limit = Number.MAX_SAFE_INTEGER,
-): PromptHistoryEntry[] {
-  const rows = db
-    .query<PromptHistoryRow, [number]>(SQL.listPromptHistory)
-    .all(limit);
-  return rows.map((row) => ({
-    id: row.id,
-    text: row.text,
-    cwd: row.cwd,
-    sessionId: row.session_id,
-    createdAt: row.created_at,
-  }));
-}
-
-/**
- * Keep only the newest prompt-history rows.
- *
- * @param db - Open database handle.
- * @param keep - Maximum number of prompt-history rows to retain.
- */
-export function truncatePromptHistory(db: Database, keep: number): void {
-  db.run(
-    `DELETE FROM prompt_history WHERE id IN (
-       SELECT id FROM prompt_history
-       ORDER BY created_at DESC, id DESC
-       LIMIT -1 OFFSET ?
-     )`,
-    [keep],
-  );
-}
-
-// ---------------------------------------------------------------------------
-// Undo
-// ---------------------------------------------------------------------------
-
-/**
- * Remove the last turn from a session's history.
- *
- * Deletes **all** messages with the highest turn number — the user message
- * and every assistant/tool-result message that followed in the same agent
- * loop. This is a context-only operation; filesystem changes are not reverted.
- *
- * @param db - Open database handle.
- * @param sessionId - The session to undo in.
- * @returns `true` if a turn was removed, `false` if the session had no messages.
- */
-export function undoLastTurn(db: Database, sessionId: string): boolean {
-  return runInImmediateTransaction(db, () => {
-    const row = db.query<MaxTurnRow, [string]>(SQL.maxTurn).get(sessionId);
-    if (!row?.max_turn) {
-      return false;
-    }
-
-    const firstMessageRow = db
-      .query<MessageIdRow, [string, number]>(SQL.firstMessageIdForTurn)
-      .get(sessionId, row.max_turn);
-
-    db.run("DELETE FROM messages WHERE session_id = ? AND turn = ?", [
-      sessionId,
-      row.max_turn,
-    ]);
-
-    if (firstMessageRow) {
-      db.run(
-        "DELETE FROM session_compactions WHERE session_id = ? AND message_end_id >= ?",
-        [sessionId, firstMessageRow.id],
-      );
-    }
-
-    return true;
-  });
-}
-
-// ---------------------------------------------------------------------------
-// Fork
-// ---------------------------------------------------------------------------
-
-/**
- * Fork a session into a new independent copy.
- *
- * Creates a new session with the same `cwd`, `model`, and `effort` as the
- * source, then copies all messages preserving their turn numbers plus any
- * persisted compaction summaries with remapped message-row boundaries. The
- * new session's `forkedFrom` field points back to the source. The original
- * session is not modified.
- *
- * @param db - Open database handle.
- * @param sourceId - The session to fork from.
- * @returns The newly created {@link Session}.
- * @throws If the source session does not exist.
- */
-export function forkSession(db: Database, sourceId: string): Session {
-  const source = getSession(db, sourceId);
-  if (!source) throw new Error(`Session not found: ${sourceId}`);
-
-  return runInImmediateTransaction(db, () => {
-    const id = generateId();
-    const now = Date.now();
-
-    db.run(
-      "INSERT INTO sessions (id, cwd, model, effort, forked_from, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?)",
-      [id, source.cwd, source.model, source.effort, sourceId, now, now],
-    );
-
-    const sourceMessageIds = listMessageIds(db, sourceId);
-
-    db.run(
-      "INSERT INTO messages (session_id, turn, data, created_at) SELECT ?, turn, data, created_at FROM messages WHERE session_id = ? ORDER BY id",
-      [id, sourceId],
-    );
-
-    const forkedMessageIds = listMessageIds(db, id);
-    const forkedMessageIdBySourceId = new Map<number, number>();
-    for (let index = 0; index < sourceMessageIds.length; index += 1) {
-      const sourceMessageId = sourceMessageIds[index];
-      const forkedMessageId = forkedMessageIds[index];
-      if (sourceMessageId === undefined || forkedMessageId === undefined) {
-        continue;
-      }
-      forkedMessageIdBySourceId.set(sourceMessageId, forkedMessageId);
-    }
-
-    const sourceCompactions = db
-      .query<SessionCompactionRow, [string]>(SQL.listCompactions)
-      .all(sourceId);
-    for (const compaction of sourceCompactions) {
-      const forkedMessageEndId = forkedMessageIdBySourceId.get(
-        compaction.message_end_id,
-      );
-      if (forkedMessageEndId === undefined) {
-        continue;
-      }
-
-      db.run(
-        "INSERT INTO session_compactions (session_id, message_end_id, summary_data, usage_data, created_at) VALUES (?, ?, ?, ?, ?)",
-        [
-          id,
-          forkedMessageEndId,
-          compaction.summary_data,
-          compaction.usage_data,
-          compaction.created_at,
-        ],
-      );
-    }
-
-    return {
-      id,
-      cwd: source.cwd,
-      model: source.model,
-      effort: source.effort,
-      forkedFrom: sourceId,
-      createdAt: now,
-      updatedAt: now,
-    };
-  });
-}
-
-// ---------------------------------------------------------------------------
-// Stats
-// ---------------------------------------------------------------------------
-
-function addUsageToStats(
-  stats: SessionStats,
-  usage: AssistantMessage["usage"],
-): SessionStats {
-  return {
-    totalInput: stats.totalInput + usage.input,
-    totalOutput: stats.totalOutput + usage.output,
-    totalCost: stats.totalCost + usage.cost.total,
-  };
-}
-
-/**
- * Add one persisted message's assistant usage to cumulative session stats.
- *
- * Non-assistant messages and assistant messages without valid `usage` are
- * ignored and return the original totals unchanged.
- *
- * @param stats - Running cumulative session totals.
- * @param message - Persisted message to fold into the totals.
- * @returns Updated cumulative session stats.
- */
-export function addMessageToStats(
-  stats: SessionStats,
-  message: PersistedMessage,
-): SessionStats {
-  const usage = getAssistantUsage(message);
-  return usage ? addUsageToStats(stats, usage) : stats;
-}
-
-/** Create a zeroed cumulative session-stats object. */
-export function createEmptySessionStats(): SessionStats {
-  return {
-    totalInput: 0,
-    totalOutput: 0,
-    totalCost: 0,
-  };
-}
-
-/**
- * Compute cumulative token and cost statistics from a message history.
- *
- * @param messages - Full persisted session history.
- * @returns Aggregated cumulative session stats.
- */
-export function computeStats(
-  messages: readonly PersistedMessage[],
-): SessionStats {
-  let stats = createEmptySessionStats();
-
-  for (const message of messages) {
-    stats = addMessageToStats(stats, message);
-  }
-
-  return stats;
-}
-
-/**
- * Compute cumulative session stats including persisted compaction-summary calls.
- *
- * @param db - Open database handle.
- * @param sessionId - Session whose cumulative stats should be loaded.
- * @returns Aggregated cumulative session stats for visible turns plus compactions.
- */
-export function computeSessionStats(
-  db: Database,
-  sessionId: string,
-): SessionStats {
-  let stats = computeStats(loadMessages(db, sessionId));
-
-  const compactionRows = db
-    .query<SessionCompactionRow, [string]>(SQL.listCompactions)
-    .all(sessionId);
-  for (const row of compactionRows) {
-    const usage = parseCompactionUsage(row.usage_data);
-    if (usage) {
-      stats = addUsageToStats(stats, usage);
-    }
-  }
-
-  return stats;
-}
-
-// ---------------------------------------------------------------------------
-// Context estimation
-// ---------------------------------------------------------------------------
-
-/** Conservative fixed estimate for an image block's token footprint. */
-const ESTIMATED_IMAGE_TOKENS = 1_200;
-
-/** Calculate context tokens from assistant usage, falling back when `totalTokens` is zero. */
-function calculateUsageTokens(usage: AssistantMessage["usage"]): number {
-  return (
-    usage.totalTokens ||
-    usage.input + usage.output + usage.cacheRead + usage.cacheWrite
+  return sessions.sort(
+    (a, b) => latestMessageTimestamp(b) - latestMessageTimestamp(a),
   );
 }
 
-/** Estimate token usage from a character count using a conservative chars/4 heuristic. */
-function estimateCharacterTokens(charCount: number): number {
-  return Math.ceil(charCount / 4);
+export async function saveSession(s: Session) {
+  await ensureSessionsDir();
+  const file = Bun.file(join(SESSIONS_DIR, `${s.id}.json`));
+  await Bun.write(file, JSON.stringify(s));
 }
 
-type UserMultipartContent = Exclude<
-  Extract<Message, { role: "user" }>["content"],
-  string
->;
-type TextOrImageContentBlock =
-  | UserMultipartContent[number]
-  | Extract<Message, { role: "toolResult" }>["content"][number];
-
-function estimateTextOrImageContentTokens(
-  content: readonly TextOrImageContentBlock[],
-): number {
-  let chars = 0;
-  let imageTokens = 0;
-
-  for (const block of content) {
-    if (block.type === "text") {
-      chars += block.text.length;
-      continue;
-    }
-    if (block.type === "image") {
-      imageTokens += ESTIMATED_IMAGE_TOKENS;
-    }
+// updateSession: finds and appends to the existing setting file
+export async function updateSession(id: string, messages: Message[]) {
+  const existing = await getSession(id);
+  if (existing) {
+    existing.messages = messages;
+    await saveSession(existing);
+    return;
   }
 
-  return estimateCharacterTokens(chars) + imageTokens;
-}
-
-function estimateUserMessageTokens(
-  message: Extract<Message, { role: "user" }>,
-): number {
-  if (typeof message.content === "string") {
-    return estimateCharacterTokens(message.content.length);
-  }
-  return estimateTextOrImageContentTokens(message.content);
-}
-
-function estimateAssistantBlockCharacters(
-  block: Extract<Message, { role: "assistant" }>["content"][number],
-): number {
-  if (block.type === "text") {
-    return block.text.length;
-  }
-  if (block.type === "thinking") {
-    return block.thinking.length;
-  }
-  return block.name.length + JSON.stringify(block.arguments).length;
-}
-
-function estimateAssistantMessageTokens(
-  message: Extract<Message, { role: "assistant" }>,
-): number {
-  const chars = message.content.reduce((total, block) => {
-    return total + estimateAssistantBlockCharacters(block);
-  }, 0);
-  return estimateCharacterTokens(chars);
-}
-
-function estimateToolResultMessageTokens(
-  message: Extract<Message, { role: "toolResult" }>,
-): number {
-  return estimateTextOrImageContentTokens(message.content);
-}
-
-/** Estimate token usage for a model-visible message. */
-function estimateMessageTokens(message: Message): number {
-  switch (message.role) {
-    case "user":
-      return estimateUserMessageTokens(message);
-    case "assistant":
-      return estimateAssistantMessageTokens(message);
-    case "toolResult":
-      return estimateToolResultMessageTokens(message);
-  }
-}
-
-interface ContextTokenOptions {
-  /** Ignore assistant usage anchors and estimate every message directly. */
-  ignoreAssistantUsage?: boolean;
-}
-
-/**
- * Fold one persisted message into the running context estimate for the next request.
- *
- * Assistant messages with valid usage anchor the full model-visible context for
- * that point in the transcript, so they replace the running estimate unless the
- * caller explicitly disables those anchors. All other model-visible messages are
- * added incrementally using the same conservative estimation logic used before
- * the first valid assistant usage appears.
- *
- * @param contextTokens - Running estimate before this message.
- * @param message - Persisted message to fold into the estimate.
- * @param options - Optional estimation behavior overrides.
- * @returns Updated context-token estimate.
- */
-export function addMessageToContextTokens(
-  contextTokens: number,
-  message: PersistedMessage,
-  options?: ContextTokenOptions,
-): number {
-  if (message.role === "ui") {
-    return contextTokens;
-  }
-
-  const usage = getAssistantUsage(message);
-  if (
-    !options?.ignoreAssistantUsage &&
-    message.role === "assistant" &&
-    usage &&
-    message.stopReason !== "aborted" &&
-    message.stopReason !== "error"
-  ) {
-    return calculateUsageTokens(usage);
-  }
-
-  return contextTokens + estimateMessageTokens(message);
-}
-
-/**
- * Estimate the current model-visible context size for the next request.
- *
- * Recomputed on session-load boundaries and maintained incrementally during an
- * active turn so render-time status-bar updates do not need to rescan the full
- * message history.
- *
- * @param messages - Full persisted session history.
- * @param options - Optional estimation behavior overrides.
- * @returns Estimated context tokens visible to the next model request.
- */
-export function computeContextTokens(
-  messages: readonly PersistedMessage[],
-  options?: ContextTokenOptions,
-): number {
-  let contextTokens = 0;
-
-  for (const message of messages) {
-    contextTokens = addMessageToContextTokens(contextTokens, message, options);
-  }
-
-  return contextTokens;
-}
-
-interface MutableConversationState {
-  messages: PersistedMessage[];
-  stats: SessionStats;
-  contextTokens: number;
-}
-
-/**
- * Derive the in-memory conversation snapshot for a persisted message history.
- *
- * @param messages - Persisted messages to expose in memory.
- * @returns Message history plus derived stats and context-token estimate.
- */
-export function createConversationSnapshot(messages: PersistedMessage[] = []): {
-  messages: PersistedMessage[];
-  stats: SessionStats;
-  contextTokens: number;
-} {
-  return {
+  const s = {
+    id,
+    cwd: process.cwd(),
     messages,
-    stats: computeStats(messages),
-    contextTokens: computeContextTokens(messages),
   };
-}
-
-/**
- * Replace the current in-memory conversation state from a message history.
- *
- * @param state - Mutable conversation state.
- * @param messages - Replacement persisted message history.
- */
-export function replaceConversationState<T extends MutableConversationState>(
-  state: T,
-  messages: PersistedMessage[],
-): void {
-  const snapshot = createConversationSnapshot(messages);
-  state.messages = snapshot.messages;
-  state.stats = snapshot.stats;
-  state.contextTokens = snapshot.contextTokens;
-}
-
-/**
- * Clear the current in-memory conversation state.
- *
- * @param state - Mutable conversation state.
- */
-export function clearConversationState<T extends MutableConversationState>(
-  state: T,
-): void {
-  replaceConversationState(state, []);
-}
 
-/**
- * Append one persisted message to the in-memory conversation state.
- *
- * @param state - Mutable conversation state.
- * @param message - Message to append.
- */
-export function appendConversationMessage<T extends MutableConversationState>(
-  state: T,
-  message: PersistedMessage,
-): void {
-  state.messages.push(message);
-  state.stats = addMessageToStats(state.stats, message);
-  state.contextTokens = addMessageToContextTokens(state.contextTokens, message);
+  await saveSession(s);
 }