omp-mobile 0.4.1 → 0.4.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omp-mobile",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "The computer side of OMP Mobile: runs oh-my-pi sessions and serves them to the phone app over Tailscale.",
   "keywords": [
     "mobile",

package/src/omp-sessions.mjs

@@ -16,7 +16,7 @@ const TITLE_SCAN_BYTES = 512 * 1024;
 const CHUNK_BYTES = 64 * 1024;
 const LSOF_TIMEOUT_MS = 5_000;
 
-/** @typedef {{id: string, title: string, cwd: string, createdAt: number, updatedAt: number, sessionFile: string}} OmpSession */
+/** @typedef {{id: string, title: string, cwd: string, createdAt: number, updatedAt: number, size: number, sessionFile: string}} OmpSession */
 
 /** Text of an OMP message content field (string or content-part array). */
 function textOfContent(content) {
@@ -103,6 +103,8 @@ export async function readSessionFile(file) {
       cwd: header.cwd,
       createdAt: Number.isFinite(created) ? created : info.birthtimeMs,
       updatedAt: info.mtimeMs,
+      // With the time, what tells this daemon's own omp leaving the file from someone writing it.
+      size: info.size,
       sessionFile: file,
     };
   } finally {

package/src/server.mjs

@@ -8,8 +8,8 @@
  * to be exposed to the public internet.
  */
 import { STATUS_CODES, createServer } from "node:http";
-import { existsSync, mkdirSync, readFileSync, realpathSync, statSync, unlinkSync, writeFileSync } from "node:fs";
-import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { createHash, randomBytes } from "node:crypto";
 import { homedir, hostname, platform } from "node:os";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -20,6 +20,7 @@ import { Admission, Tailscale, isLoopbackHost } from "./admission.mjs";
 import { AttentionTracker, serveEvents } from "./attention.mjs";
 import { listOmpSessions, oneLine, promptTitle, sessionOwners } from "./omp-sessions.mjs";
 import { askOwnerToLeave, forksOf, isOmpCommand, processInfo, sessionBusy, takeoverFarewell, tellTerminal } from "./takeover.mjs";
+import { TranscriptStore, deltaBody, deltaQuery } from "./transcripts.mjs";
 
 const { version: VERSION } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
 const PROTOCOL = 1;
@@ -55,6 +56,21 @@ const HEARTBEAT_MS = 20_000;
 /** A live omp nobody has looked at for this long is closed; the next open resumes it. */
 const IDLE_SESSION_MS = 30 * 60_000;
 const REAP_INTERVAL_MS = 60_000;
+/** Messages a live session keeps in memory; older ones leave its front (its `base` counts them). */
+const MAX_LIVE_MESSAGES = 5_000;
+/** Events that are a session being used: a turn and what it streams. State and setting echoes are not. */
+const ACTIVITY_EVENT = /^(agent_|turn_|message_|tool_execution_|auto_compaction_|auto_retry_)/;
+/**
+ * The fields of a tool result's `details` the app reads: an edit's diff, a
+ * read's line count, a command's run time, a screenshot's file. The rest
+ * (an edit's old and new text, a read's display copy) repeats what the
+ * result already says, and was a fifth of a long session's snapshot.
+ */
+const PHONE_DETAILS = ["diff", "totalLines", "wallTimeMs", "mediaPath"];
+/** Inline images shorter than this (base64 characters) stay inline: a reference would save nothing. */
+const STASH_MIN_CHARS = 4_096;
+/** Stashed images untouched this long are dropped at start; the session file still has them. */
+const BLOB_CACHE_MAX_AGE_MS = 30 * 24 * 60 * 60_000;
 /** Image types a phone may attach to a prompt: what the camera and the photo picker produce. */
 const PROMPT_IMAGE_TYPES = new Set(["image/jpeg", "image/png", "image/webp", "image/gif"]);
 /** At most this many images per prompt, each at most this many decoded bytes. */
@@ -89,9 +105,11 @@ export function promptImages(value) {
  * the computer it talks to can do. `prompt-images`: `prompt` frames carry `images`;
  * `takeover`: `POST /sessions/:id/takeover` continues a session another omp process holds;
  * `heartbeat`: session sockets get a `ping` frame every 20 s, so the app can
- * treat a silent link as gone.
+ * treat a silent link as gone; `transcript-sync`: a session socket's `since`/`last`
+ * ask for a delta snapshot (`from`, `total`), and `GET /sessions/:id/transcript`
+ * answers the same without starting an omp.
  */
-const FEATURES = ["prompt-images", "takeover", "heartbeat"];
+const FEATURES = ["prompt-images", "takeover", "heartbeat", "transcript-sync"];
 /** Who a phone continues a session on, as the terminal it leaves is told. */
 const DEFAULT_DEVICE = "OMP Mobile";
 /** Close code after an `open_failed` frame: the session socket opened only to say why the session could not. */
@@ -284,6 +302,127 @@ export function ensureWorkingDirectory(cwd) {
   }
 }
 
+/**
+ * Write an inline image to the daemon's blob cache under its SHA-256 and
+ * answer the `blob:sha256:` reference the app loads from `/blobs`; undefined
+ * leaves the image inline (too small, already a reference, not base64, no disk).
+ * @param {{data?: unknown}} part
+ * @param {string} blobDir
+ */
+function stashImage(part, blobDir) {
+  const data = part.data;
+  if (typeof data !== "string" || data.length < STASH_MIN_CHARS || data.startsWith("blob:") || data.startsWith("data:")) return undefined;
+  const bytes = Buffer.from(data, "base64");
+  if (bytes.length === 0) return undefined;
+  const hash = createHash("sha256").update(bytes).digest("hex");
+  const path = join(blobDir, hash);
+  try {
+    if (!existsSync(path)) {
+      mkdirSync(blobDir, { recursive: true, mode: 0o700 });
+      writeFileSync(path, bytes, { mode: 0o600 });
+    }
+  } catch {
+    return undefined;
+  }
+  return `blob:sha256:${hash}`;
+}
+
+/**
+ * A message as a snapshot carries it to the phone: inline images moved to
+ * the blob cache and sent as references (the app loads only the ones it
+ * shows), and tool details cut to {@link PHONE_DETAILS}. A long session's
+ * snapshot was mostly base64 screenshots and copies of edited text --
+ * megabytes the phone downloaded, parsed and cached before it showed anything.
+ * Live events still carry messages whole.
+ * @param {any} message
+ * @param {string | undefined} blobDir no stashing when undefined
+ */
+export function phoneMessage(message, blobDir) {
+  if (message === null || typeof message !== "object") return message;
+  let next = message;
+  if (blobDir !== undefined && Array.isArray(message.content)) {
+    let changed = false;
+    const content = message.content.map((part) => {
+      const ref = part !== null && typeof part === "object" && part.type === "image" ? stashImage(part, blobDir) : undefined;
+      if (ref === undefined) return part;
+      changed = true;
+      return { ...part, data: ref };
+    });
+    if (changed) next = { ...next, content };
+  }
+  const tool = message.role === "toolResult" || message.role === "tool";
+  if (tool && message.details !== null && typeof message.details === "object" && !Array.isArray(message.details)) {
+    const details = {};
+    for (const key of PHONE_DETAILS) if (key in message.details) details[key] = message.details[key];
+    next = { ...next, details };
+  }
+  return next;
+}
+
+/** Drop stashed images older than {@link BLOB_CACHE_MAX_AGE_MS}; the next open of their session stashes them again. */
+export function pruneBlobCache(blobDir, now = Date.now()) {
+  let names;
+  try {
+    names = readdirSync(blobDir);
+  } catch {
+    return 0;
+  }
+  let dropped = 0;
+  for (const name of names) {
+    if (!BLOB_NAME.test(name)) continue;
+    const path = join(blobDir, name);
+    try {
+      if (now - statSync(path).mtimeMs > BLOB_CACHE_MAX_AGE_MS) {
+        unlinkSync(path);
+        dropped += 1;
+      }
+    } catch {
+      // Gone already.
+    }
+  }
+  return dropped;
+}
+
+/**
+ * When the messages were last written: the newest timestamp OMP stamped on
+ * them, or undefined when none carries one.
+ * @param {readonly any[]} messages
+ */
+export function lastActivity(messages) {
+  let latest;
+  for (let i = messages.length - 1; i >= 0 && i >= messages.length - 50; i -= 1) {
+    const at = Number(messages[i]?.timestamp);
+    if (Number.isFinite(at) && at > 0 && (latest === undefined || at > latest)) latest = at;
+  }
+  return latest;
+}
+
+/**
+ * When a session the daemon knows but has no omp for was last used: what the
+ * registry says, or its file's time when something wrote the file since --
+ * unless the file is exactly as this daemon's own omp left it on exit (omp
+ * rewrites the whole file as it closes; that is not anyone using it).
+ * @param {{updatedAt?: number, closedFile?: {mtimeMs: number, size: number}} | undefined} stored
+ * @param {{updatedAt: number, size?: number} | undefined} scanned
+ */
+export function dormantActivity(stored, scanned) {
+  const known = Number(stored?.updatedAt) || 0;
+  if (scanned === undefined || !(scanned.updatedAt > known)) return known;
+  const closed = stored?.closedFile;
+  if (closed !== undefined && closed !== null && closed.mtimeMs === scanned.updatedAt && closed.size === scanned.size) return known;
+  return scanned.updatedAt;
+}
+
+/** A file's time and size, as `TranscriptStore` checks them; undefined when it cannot be read. */
+function fileState(path) {
+  try {
+    const info = statSync(path);
+    return info.isFile() ? { mtimeMs: info.mtimeMs, size: info.size } : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 function storedSummary(stored) {
   return {
     id: stored.id,
@@ -335,13 +474,14 @@ export function blobType(bytes) {
 }
 
 /** A stored image: `GET /blobs/<sha256>[.ext]`, authenticated like every other route. */
-function sendBlob(res, ompHome, name) {
+function sendBlob(res, dirs, name) {
   if (!BLOB_NAME.test(name)) {
     sendJson(res, 400, { error: "bad blob name" });
     return;
   }
-  const path = join(ompHome, "agent", "blobs", name);
-  if (!existsSync(path) || !statSync(path).isFile()) {
+  // OMP's own store first, then the images this daemon stashed from snapshots.
+  const path = dirs.map((dir) => join(dir, name)).find((candidate) => existsSync(candidate) && statSync(candidate).isFile());
+  if (path === undefined) {
     sendJson(res, 404, { error: "no such blob" });
     return;
   }
@@ -410,6 +550,10 @@ class SessionEntry {
     this.id = "";
     this.state = null;
     this.messages = [];
+    /** How many messages left the front of `messages` (the cap): `messages[0]` is the transcript's message `base`. */
+    this.base = 0;
+    /** The session file as this omp left it on exit, so its rewrite is not taken for activity. */
+    this.closedFile = undefined;
     this.createdAt = Date.now();
     this.updatedAt = this.createdAt;
     this.title = cwd.split("/").filter(Boolean).at(-1) ?? "session";
@@ -425,15 +569,28 @@ class SessionEntry {
     this.closed = false;
     /** When the last phone left; undefined while one is connected. The reaper reads it. */
     this.idleSince = undefined;
+    /** Where inline images go (see `phoneMessage`); undefined keeps them inline. */
+    this.blobDir = undefined;
+    /**
+     * Hears the omp process exit, once its session file is final (the daemon saves the transcript).
+     * @type {((entry: SessionEntry) => void) | undefined}
+     */
+    this.onClosed = undefined;
   }
 
-  async hydrate() {
+  /**
+   * @param {number} [knownActivity] when the session was last used, as the daemon knew it before this omp
+   */
+  async hydrate(knownActivity) {
     const [state, messages] = await Promise.all([this.rpc.getState(), this.rpc.getMessages()]);
     this.state = state;
-    this.messages = Array.isArray(messages.messages) ? messages.messages : [];
+    this.messages = Array.isArray(messages.messages) ? messages.messages.map((message) => phoneMessage(message, this.blobDir)) : [];
+    this.base = 0;
     this.id = state.sessionId ?? "";
     this.title = titleOf(this.messages, state, this.cwd);
-    this.updatedAt = Date.now();
+    // Opening a session is not using it: it is as recent as its last message (a new one: now).
+    const known = Math.max(lastActivity(this.messages) ?? 0, Number(knownActivity) || 0);
+    this.updatedAt = known > 0 ? known : Date.now();
     return this;
   }
 
@@ -453,12 +610,13 @@ class SessionEntry {
     };
   }
 
-  snapshot() {
-    return {
-      session: this.summary(),
-      state: this.state,
-      messages: this.messages,
-    };
+  /**
+   * What a phone is sent on open: everything, or only the messages after the
+   * ones it holds when its copy lines up (see `deltaBody`).
+   * @param {{since: number, last: string}} [held]
+   */
+  snapshot(held) {
+    return deltaBody({ session: this.summary(), state: this.state, messages: this.messages, base: this.base }, held);
   }
 
   broadcast(payload) {
@@ -472,7 +630,6 @@ class SessionEntry {
   async refreshState() {
     try {
       this.state = await this.rpc.getState();
-      this.updatedAt = Date.now();
       this.broadcast({ type: "state", state: this.state });
     } catch {
       // The process may be exiting; the close event tells clients.
@@ -481,10 +638,15 @@ class SessionEntry {
 
   bind() {
     this.rpc.on("event", (event) => {
-      this.updatedAt = Date.now();
+      if (typeof event?.type === "string" && ACTIVITY_EVENT.test(event.type)) this.updatedAt = Date.now();
       if (event.type === "message_end" && event.message) {
-        this.messages.push(event.message);
-        if (this.messages.length > 5_000) this.messages.splice(0, this.messages.length - 5_000);
+        this.messages.push(phoneMessage(event.message, this.blobDir));
+        if (this.messages.length > MAX_LIVE_MESSAGES) {
+          // Indices stay the transcript's: a phone's `since` still lines up after the front is dropped.
+          const dropped = this.messages.length - MAX_LIVE_MESSAGES;
+          this.messages.splice(0, dropped);
+          this.base += dropped;
+        }
         // The first prompt names a session that was created untitled.
         const title = titleOf(this.messages, this.state, this.cwd);
         if (title !== this.title) {
@@ -511,6 +673,11 @@ class SessionEntry {
     this.rpc.on("closed", ({ reason, stderr }) => {
       this.closed = true;
       this.broadcast({ type: "closed", reason, stderr: stderr.slice(-2_000) });
+      try {
+        this.onClosed?.(this);
+      } catch {
+        // Saving the transcript is a shortcut; the session file has everything.
+      }
     });
     this.rpc.on("protocol-error", (payload) => this.broadcast({ type: "protocol-error", ...payload }));
   }
@@ -570,8 +737,14 @@ class Daemon {
     this.starting = new Map();
     /** Takeovers in flight, so two phones asking at once ask the owner once. @type {Map<string, Promise<object>>} */
     this.takingOver = new Map();
+    /** Images stashed out of snapshots, served by `/blobs` next to OMP's own store. */
+    this.blobDir = options.blobDir ?? join(dirname(options.registryFile ?? DEFAULT_REGISTRY_FILE), "blobs");
+    /** Transcripts of sessions whose omp exited, served by `/transcript` without starting one. */
+    this.transcripts = new TranscriptStore(options.transcriptDir ?? join(dirname(options.registryFile ?? DEFAULT_REGISTRY_FILE), "transcripts"));
     this.server = createServer((req, res) => void this.admitHttp(req, res));
-    this.wsServer = new WebSocketServer({ noServer: true });
+    // Compressed frames: a snapshot is JSON text, several times smaller deflated, and
+    // the phone's WebSocket client (OkHttp) asks for permessage-deflate on its own.
+    this.wsServer = new WebSocketServer({ noServer: true, perMessageDeflate: { threshold: 1_024 } });
     this.server.on("upgrade", (req, socket, head) => void this.admitUpgrade(req, socket, head));
   }
 
@@ -643,7 +816,7 @@ class Daemon {
     this.noteClient(req);
     const blob = /^\/blobs\/([0-9a-f]{64})(?:\.[a-z0-9]+)?$/.exec(url.pathname);
     if (blob !== null && req.method === "GET") {
-      sendBlob(res, this.options.ompHome, blob[1]);
+      sendBlob(res, [join(this.options.ompHome, "agent", "blobs"), this.blobDir], blob[1]);
       return;
     }
     if (url.pathname === "/status" && req.method === "GET") {
@@ -690,6 +863,11 @@ class Daemon {
         sendJson(res, 200, await this.takeOver(decodeURIComponent(takeover[1]), device));
         return;
       }
+      const transcript = /^\/sessions\/([^/]+)\/transcript$/.exec(url.pathname);
+      if (transcript !== null && req.method === "GET") {
+        sendJson(res, 200, this.transcript(decodeURIComponent(transcript[1]), deltaQuery(url.searchParams)));
+        return;
+      }
       const match = /^\/sessions\/([^/]+)$/.exec(url.pathname);
       if (match !== null) {
         const id = decodeURIComponent(match[1]);
@@ -700,8 +878,13 @@ class Daemon {
         }
         if (req.method === "DELETE") {
           const live = this.sessions.get(id);
-          if (live !== undefined) this.attention.forget(live);
+          if (live !== undefined) {
+            this.attention.forget(live);
+            // Closed for good: its exit must not save it, or bring it back into the registry.
+            live.onClosed = undefined;
+          }
           live?.close();
+          this.transcripts.remove(id);
           this.forgetOwners();
           this.sessions.delete(id);
           this.registry.delete(id);
@@ -736,6 +919,10 @@ class Daemon {
     const others = found
       .filter((session) => !known.has(session.id))
       .map((session) => ({ ...session, status: "idle", origin: "omp" }));
+    // A dormant session is as recent as its file when a terminal omp wrote it since, not when our own omp's exit did.
+    for (const session of dormant) {
+      session.updatedAt = dormantActivity(this.registry.get(session.id), this.ompSessions.get(session.id));
+    }
     const marked = await Promise.all(
       [...dormant, ...others].map(async (session) => {
         const pid = owners?.get(session.id);
@@ -792,6 +979,31 @@ class Daemon {
     this.ownerLookup = { at: 0, owners: undefined };
   }
 
+  /**
+   * A session's transcript without starting an omp: a live session's from
+   * memory, a closed one's from its saved copy while its session file is
+   * unchanged; otherwise a 404 the phone skips.
+   * @param {string} id
+   * @param {{since: number, last: string}} held
+   */
+  transcript(id, held) {
+    const live = this.sessions.get(id);
+    if (live !== undefined && !live.closed) return live.snapshot(held);
+    const known = this.registry.get(id)?.sessionFile ?? this.ompSessions.get(id)?.sessionFile;
+    const saved = this.transcripts.read(id, typeof known === "string" ? known : undefined);
+    if (saved === undefined) throw httpError(404, "not cached");
+    return deltaBody(saved, held);
+  }
+
+  /** The omp of a session exited: save its transcript and when it was last active. */
+  sessionClosed(entry) {
+    if (entry.id === "") return;
+    const sessionFile = entry.state?.sessionFile;
+    entry.closedFile = typeof sessionFile === "string" ? fileState(sessionFile) : undefined;
+    this.transcripts.write(entry.id, { sessionFile, messages: entry.messages, base: entry.base, state: entry.state, session: entry.summary() });
+    if (this.registry.has(entry.id)) this.remember(entry);
+  }
+
   remember(entry) {
     this.registry.set(entry.id, {
       id: entry.id,
@@ -801,6 +1013,8 @@ class Daemon {
       createdAt: entry.createdAt,
       updatedAt: entry.updatedAt,
       sessionFile: entry.state?.sessionFile,
+      // Set once its omp exited: the file as that omp left it (see `dormantActivity`).
+      ...(entry.closedFile !== undefined ? { closedFile: entry.closedFile } : {}),
     });
     saveRegistry(this.options.registryFile, this.registry);
   }
@@ -853,10 +1067,14 @@ class Daemon {
     try {
       await rpc.start();
       const entry = new SessionEntry(stored.cwd, rpc);
-      await entry.hydrate();
+      entry.blobDir = this.blobDir;
+      await entry.hydrate(this.registry.has(id) ? dormantActivity(this.registry.get(id), this.ompSessions.get(id)) : stored.updatedAt);
       entry.id = id;
+      // Idle from now for the reaper, until a phone attaches: its last activity may be long ago.
+      entry.idleSince = Date.now();
       entry.onChange = (changed) => this.remember(changed);
       entry.onBroadcast = (source, payload) => this.attention.observe(source, payload);
+      entry.onClosed = (closed) => this.sessionClosed(closed);
       entry.bind();
       this.sessions.set(id, entry);
       this.remember(entry);
@@ -929,10 +1147,13 @@ class Daemon {
     try {
       await rpc.start();
       const entry = new SessionEntry(cwd, rpc);
+      entry.blobDir = this.blobDir;
       await entry.hydrate();
       if (entry.id === "") throw new Error("omp returned no session id");
+      entry.idleSince = Date.now();
       entry.onChange = (changed) => this.remember(changed);
       entry.onBroadcast = (source, payload) => this.attention.observe(source, payload);
+      entry.onClosed = (closed) => this.sessionClosed(closed);
       entry.bind();
       this.sessions.set(entry.id, entry);
       this.remember(entry);
@@ -958,6 +1179,8 @@ class Daemon {
     }
     this.noteClient(req);
     const id = decodeURIComponent(match[1]);
+    // What the phone already holds, read now: the snapshot is cut against it once the session is open.
+    const held = deltaQuery(url.searchParams);
     // Finish the handshake before the session is open: a slow omp can take
     // tens of seconds, and a phone's WebSocket client gives up after ~10 s --
     // then retries, starting another omp every time. The snapshot (or
@@ -990,7 +1213,7 @@ class Daemon {
           if (ws.readyState !== 1) return;
           live.clients.add(ws);
           live.idleSince = undefined;
-          ws.send(JSON.stringify({ type: "snapshot", ...live.snapshot() }));
+          ws.send(JSON.stringify({ type: "snapshot", ...live.snapshot(held) }));
           // A dialog opened before this client connected (it may have come from a notification tap).
           for (const request of live.openRequests()) ws.send(JSON.stringify({ type: "approval", request }));
           for (const data of early) void this.handleClientMessage(live, ws, data);
@@ -1118,8 +1341,10 @@ class Daemon {
     });
   }
 
-  /** Keepalive pings and the idle-session reaper, once the daemon listens. */
+  /** Keepalive pings and the idle-session reaper, once the daemon listens; old stashed images go. */
   startTimers() {
+    pruneBlobCache(this.blobDir);
+    this.transcripts.prune();
     this.heartbeat = setInterval(() => this.pingClients(), this.options.heartbeatMs ?? HEARTBEAT_MS);
     this.heartbeat.unref?.();
     this.reaper = setInterval(() => this.reapIdleSessions(), this.options.reapIntervalMs ?? REAP_INTERVAL_MS);
@@ -1293,4 +1518,4 @@ if (isMain) {
   });
 }
 
-export { Daemon, SessionEntry, VERSION, PROTOCOL, parseArgs, resolveIdentity };
+export { Daemon, SessionEntry, VERSION, PROTOCOL, FEATURES, parseArgs, resolveIdentity };

package/src/transcripts.mjs

@@ -0,0 +1,227 @@
+/**
+ * The daemon's saved transcripts: the slim messages of each session it had
+ * open, written when the session's omp exits (the reaper, the daemon
+ * stopping, omp leaving on its own), so a phone can read a recent session
+ * without the daemon starting an omp for it.
+ *
+ * A record is valid while the session file it was read from has the same
+ * modification time and size: anything that wrote the session since (a
+ * terminal omp, a resume elsewhere) makes it stale, and it is not served.
+ * Records are kept while their session was active in the last
+ * {@link RECENT_MS}; nothing is evicted by count.
+ */
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** How long after its last activity a session's transcript is kept, on the computer and on the phone. */
+export const RECENT_MS = 24 * 60 * 60_000;
+const VERSION = 1;
+const NAME = /^[A-Za-z0-9_-]{1,140}\.json$/;
+/** A temporary file left by a write that never finished (a crash) is dropped after this long. */
+const TEMP_MAX_AGE_MS = 60_000;
+let writes = 0;
+
+/**
+ * What identifies one message well enough to line a phone's copy up with the
+ * daemon's: OMP stamps every message, and tool results and replies carry ids.
+ * The app computes the same string (`app/src/cache.ts`).
+ * @param {any} message
+ */
+export function fingerprint(message) {
+  if (message === null || typeof message !== "object") return "";
+  const id = typeof message.toolCallId === "string" ? message.toolCallId : typeof message.responseId === "string" ? message.responseId : "";
+  return `${String(message.role ?? "")}:${String(message.timestamp ?? "")}:${id}`;
+}
+
+/**
+ * Where a phone that holds the first `since` messages (the last of them
+ * fingerprinted `last`) can continue: `since` when its copy lines up with
+ * `messages` there, else 0 (send everything). Indices are the transcript's:
+ * `messages` start at `base`, the count a long session dropped from its front.
+ * @param {readonly any[]} messages
+ * @param {number} since
+ * @param {string} last
+ * @param {number} [base]
+ */
+export function deltaFrom(messages, since, last, base = 0) {
+  if (!Array.isArray(messages) || !Number.isSafeInteger(since) || since <= base || since > base + messages.length) return 0;
+  if (typeof last !== "string" || last === "") return 0;
+  return fingerprint(messages[since - 1 - base]) === last ? since : 0;
+}
+
+/**
+ * The `since` and `last` query parameters, as a phone sends them; anything
+ * malformed reads as "nothing held" (a whole transcript).
+ * @param {URLSearchParams} searchParams
+ */
+export function deltaQuery(searchParams) {
+  const raw = searchParams.get("since") ?? "";
+  const since = /^\d{1,9}$/.test(raw) ? Number(raw) : 0;
+  return { since, last: searchParams.get("last") ?? "" };
+}
+
+/**
+ * The body of a snapshot frame or a `/transcript` answer: the messages after
+ * what the phone holds when its copy lines up, else all of them. `from` is the
+ * index of the first message sent (0: the whole transcript), `total` how many
+ * the transcript has. A session past the daemon's cap holds only its last
+ * messages, from index `base` on: a delta is still cut at the phone's `since`,
+ * and everything is sent as a whole transcript of what is held, with `base`
+ * saying where in the session it starts.
+ * @param {{session: any, state: any, messages: any[], base?: number}} transcript
+ * @param {{since: number, last: string}} [held]
+ */
+export function deltaBody({ session, state, messages, base = 0 }, held = { since: 0, last: "" }) {
+  const start = Number.isSafeInteger(base) && base > 0 ? base : 0;
+  const from = deltaFrom(messages, held.since, held.last, start);
+  if (from > 0) return { session, state, from, total: start + messages.length, messages: messages.slice(from - start) };
+  return { session, state, from: 0, total: messages.length, messages, ...(start > 0 ? { base: start } : {}) };
+}
+
+function fileState(path) {
+  try {
+    const info = statSync(path);
+    return info.isFile() ? { mtimeMs: info.mtimeMs, size: info.size } : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** A record that still describes its session file as it is now. */
+function current(record) {
+  if (typeof record?.sessionFile !== "string") return false;
+  const now = fileState(record.sessionFile);
+  return now !== undefined && now.mtimeMs === record.file?.mtimeMs && now.size === record.file?.size;
+}
+
+export class TranscriptStore {
+  /** @param {string} dir */
+  constructor(dir) {
+    this.dir = dir;
+  }
+
+  /** @param {string} id */
+  path(id) {
+    const safe = id.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 120);
+    // Two ids that differ only in characters a file name cannot carry must not share a file.
+    const name = safe === id ? safe : `${safe}-${createHash("sha256").update(id).digest("hex").slice(0, 16)}`;
+    return join(this.dir, `${name}.json`);
+  }
+
+  /**
+   * Save a session's slim messages against the current state of its file:
+   * call it once omp has exited, when the file is final. Best effort: a full
+   * disk only loses the shortcut.
+   * @param {string} id
+   * @param {{sessionFile?: string, messages: any[], state: any, session: any, base?: number}} record
+   * @returns {boolean} whether it was saved
+   */
+  write(id, { sessionFile, messages, state, session, base = 0 }) {
+    if (typeof id !== "string" || id === "" || typeof sessionFile !== "string" || !Array.isArray(messages)) return false;
+    const file = fileState(sessionFile);
+    if (file === undefined) return false;
+    const path = this.path(id);
+    writes += 1;
+    const temporary = `${path}.${process.pid}-${writes}.tmp`;
+    // No omp runs for it any more: nothing streams and nothing waits for an answer.
+    const record = {
+      v: VERSION,
+      id,
+      sessionFile,
+      file,
+      savedAt: Date.now(),
+      // When the session was last used: omp rewrites its file as it exits, so the file's time is not that.
+      activeAt: Number(session?.updatedAt) || file.mtimeMs,
+      base: Number.isSafeInteger(base) && base > 0 ? base : 0,
+      messages,
+      state: state !== null && typeof state === "object" ? { ...state, isStreaming: false } : state,
+      session: { ...session, status: "idle", waiting: 0 },
+    };
+    try {
+      mkdirSync(this.dir, { recursive: true, mode: 0o700 });
+      writeFileSync(temporary, JSON.stringify(record), { mode: 0o600 });
+      renameSync(temporary, path);
+      return true;
+    } catch {
+      try {
+        unlinkSync(temporary);
+      } catch {
+        // Never written.
+      }
+      return false;
+    }
+  }
+
+  /**
+   * A saved transcript that still matches its session file, else undefined.
+   * Its session is dated by its last activity, not by the file: the file was
+   * last written by the omp exiting.
+   * @param {string} id
+   * @param {string | undefined} sessionFile the file the session is known by now, when known
+   */
+  read(id, sessionFile) {
+    let record;
+    try {
+      record = JSON.parse(readFileSync(this.path(id), "utf8"));
+    } catch {
+      return undefined;
+    }
+    if (record?.v !== VERSION || record.id !== id || !Array.isArray(record.messages)) return undefined;
+    if (sessionFile !== undefined && record.sessionFile !== sessionFile) return undefined;
+    if (!current(record)) return undefined;
+    const session = record.session !== null && typeof record.session === "object" ? record.session : { id };
+    return { ...record, session: { ...session, updatedAt: Number(session.updatedAt) || record.file.mtimeMs } };
+  }
+
+  /** @param {string} id */
+  remove(id) {
+    try {
+      unlinkSync(this.path(id));
+    } catch {
+      // Never saved.
+    }
+  }
+
+  /**
+   * Drop transcripts whose session has been quiet longer than
+   * {@link RECENT_MS}, and those that can never be served again (their
+   * session file changed or is gone, or the record is unreadable).
+   */
+  prune(now = Date.now()) {
+    let names;
+    try {
+      names = readdirSync(this.dir);
+    } catch {
+      return 0;
+    }
+    let dropped = 0;
+    for (const name of names) {
+      const path = join(this.dir, name);
+      if (name.endsWith(".tmp")) {
+        try {
+          if (now - statSync(path).mtimeMs > TEMP_MAX_AGE_MS) unlinkSync(path);
+        } catch {
+          // Gone already.
+        }
+        continue;
+      }
+      if (!NAME.test(name)) continue;
+      let record;
+      try {
+        record = JSON.parse(readFileSync(path, "utf8"));
+      } catch {
+        record = undefined;
+      }
+      const activeAt = Number(record?.activeAt) || 0;
+      if (record?.v === VERSION && now - activeAt <= RECENT_MS && current(record)) continue;
+      try {
+        unlinkSync(path);
+        dropped += 1;
+      } catch {
+        // Gone already.
+      }
+    }
+    return dropped;
+  }
+}