@100xprompt/brain 0.0.0-stage → 0.1.1

package/LICENSE

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

package/README.md

@@ -1,3 +1,236 @@
-# Temporary Holding Version
+# brain
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+One working session, any AI coding tool. Start in Claude Code, carry on in Codex, Cursor or another tool, and switch
+back, with the same session. brain also keeps what each project has learned across tools, trims what a long session
+sends back to the model, and can route your tools through the 100xprompt gateway.
+
+Nothing calls a model to do any of this, and nothing changes in your tools until you run a command that says so.
+
+Runs on [Bun](https://bun.sh) 1.3 or later. Built and tested on macOS.
+
+## Install
+
+```bash
+bun add -g @100xprompt/brain
+brain --version
+```
+
+Or run it without installing:
+
+```bash
+bunx @100xprompt/brain session list --here
+```
+
+Hooks and MCP entries installed from a `bunx` run start that same version later, so they keep working after Bun's
+temporary copy is gone. No Bun yet? `curl -fsSL https://bun.sh/install | bash`.
+
+## Quick start
+
+```bash
+brain session list --here                          # sessions from every tool, for this project, newest first
+brain session continue <id> --in codex --dry-run   # what would be written, and what would not carry over
+brain session continue <id> --in codex             # a new Codex session that picks up where that one stopped
+brain session handoff --in claude-code             # the newest session from another tool in this folder
+```
+
+`<id>` is `<tool>:<session id>` as `list` prints it, or a unique start of the session id.
+
+## Moving a session
+
+`continue` writes the session into the target the best way that target allows:
+
+- **Native** (a new session in the tool's own storage, opened like any other): Claude Code, Codex, Gemini CLI, Copilot
+  Chat in VS Code, the Copilot CLI, Cline (in VS Code, Cursor, Windsurf, and its CLI), Roo Code (in VS Code, Cursor,
+  Windsurf), Antigravity, Aider, Amazon Q (CLI and IDE), Auggie, Codebuff, Continue, Crush, Devin CLI, Factory Droid,
+  Grok CLI, Hermes Agent, iFlow CLI, Kimi Code, Kiro (CLI and IDE), Letta Code, Mastra Code, Muse Code, Oh My Pi,
+  OpenHands CLI, PearAI, Pi, Qoder CLI, Qwen Code, Tabnine CLI, Void and Zed.
+- **Import** (through the tool's own import): 100xprompt, OpenCode, Cursor, Goose, Kilo Code, Kilo CLI and Mistral Vibe.
+- **Brief**: the Cursor CLI, and any other tool (`--in any`: a Markdown file to paste).
+
+A native or import writer writes only for the tool versions its format was checked against, and some need the app
+closed (VS Code); otherwise, and whenever the tool is missing, the session goes as a brief. `brain session targets`
+shows what each tool on this machine gets right now, and `brain session list` shows every session brain can read.
+
+A **brief** is built without a model call: where the session came from, the goal, where it stands, files changed, the
+last commands, the latest requests, and as many recent turns as fit the target. It is saved as a pending handoff, copied
+to the clipboard where the system has one, and, where the session-start hook is installed (`brain session hooks
+install`, for Claude Code, Codex, Cursor and Gemini CLI), given to the model by the target's next session in the same
+project.
+
+## Saving tokens
+
+On real sessions, tool calls and their output are about four fifths of the tokens; what was said is about a tenth.
+
+- **Lean sessions.** A big tool call or result becomes a one-line digest with a short preview, and the full text stays on
+  disk (`~/.brain/blobs/`). `continue` does this by itself on long sessions (`--lean` / `--full` override; `--budget
+  <tokens>` trims in steps until the session fits). The model gets the text back only when it asks, through the
+  `brain_expand` tool (or `brain expand <id>`).
+- **Project memory.** What a session settled (decisions, constraints, preferences, files, failed approaches, commands) is
+  distilled into small items kept per project, so a session in any tool can recall them with `brain_recall`. Memory needs
+  [Chitta](https://www.npmjs.com/package/@100xprompt/chitta) (`bun add -g @100xprompt/chitta`, found next to brain, in a
+  global install, or at `$BRAIN_CHITTA`); without it everything else works, except a Teams server.
+- **What every request reloads.** `brain tokens audit` checks, without changing anything, what a project sends with every
+  request: instruction files, MCP servers, ignore files.
+
+```bash
+brain mcp install                  # brain_recall and brain_expand in Claude Code, Codex, Cursor, Gemini CLI, OpenCode, VS Code
+brain memory sync --here           # distill this project's earlier sessions (a few per run; nothing is processed twice)
+brain memory search "how do we run the tests"
+brain tokens audit
+```
+
+## The 100xprompt gateway
+
+Point a coding tool at the 100xprompt gateway, and back. Signing in works like `100xprompt auth login`: your browser opens,
+you sign in to 100xprompt and confirm, and the key comes back to brain by itself.
+
+```bash
+brain gateway login                              # sign in in the browser
+brain gateway connect --tool codex --dry-run     # show what would change
+brain gateway connect --tool codex               # any tool in the table below (signs in first if needed)
+brain gateway status
+brain gateway disconnect --tool codex            # put back exactly what was there
+brain gateway logout
+```
+
+- Connecting changes which model the tool uses: it runs on 100xprompt Pro by default (`--model flash` for 100xprompt
+  Flash), billed to your 100xprompt account. Context editing is on by default; `--no-context-edit` turns it off and is
+  remembered for later connects until `--context-edit`.
+- Before changing anything, `connect` checks that the gateway accepts your key the way that tool sends it (a free check
+  that generates nothing). If your account's quota is used up, it still connects and tells you, in the gateway's words.
+- Only the settings brain owns are written; the value each had before is recorded and put back by `disconnect`. The key
+  lives in `~/.brain/gateway.key`, readable only by you, and is never printed.
+- On a machine without a browser (SSH): `brain gateway login --no-browser` prints the address. Open it anywhere, then
+  paste the key from the page's Copy key button (input is hidden). For scripts and CI: `--key-env VAR`. To reuse the
+  100xprompt CLI's sign-in: `--from-cli`.
+- Each sign-in makes a new key on your account. Signing in again also updates every copy of the key that a connected tool
+  keeps in its own config.
+
+| Tool (`--tool`) | How it gets the key | Context editing | Checked with the real tool |
+|---|---|---|---|
+| Claude Code (`claude-code`) | reads brain's key file at start | yes | yes |
+| Codex (`codex`) | copy in its config, made private | yes | yes |
+| OpenCode (`opencode`) | reads brain's key file | yes | yes |
+| Gemini CLI (`gemini-cli`) | copy in `~/.gemini/.env`, private | no | yes (needs the gateway update that accepts `x-goog-api-key`) |
+| Aider (`aider`) | copy in its model settings, private | yes | yes |
+| Cline CLI (`cline-sdk`) | copy in its providers file, private | yes | yes |
+| Continue (`continue`) | copy in `~/.continue/.env`, private | yes | yes (`cn`) |
+| Copilot CLI (`copilot-cli`) | copy in its providers file, private | yes | yes |
+| Copilot Chat in VS Code (`vscode-copilot`) | copy in VS Code's model list, private | yes | from the extension's code; pick "100xprompt Pro" once in the model picker |
+| Crush (`crush`) | reads brain's key file | yes | yes |
+| Factory Droid (`factory-droid`) | reads brain's key file | yes | yes |
+| Goose (`goose`) | reads brain's key file | yes | yes |
+| Grok CLI (`grok-cli`) | copy in its config, private | yes | yes |
+| Hermes Agent (`hermes`) | copy in `~/.hermes/.env`, private | yes | yes |
+| iFlow CLI (`iflow-cli`) | copy in its settings, private | no | yes |
+| Kilo CLI and Kilo Code (`kilo-cli`, `kilo-code`) | reads brain's key file | yes | yes |
+| Kimi Code (`kimi-code`) | copy in its config, private | yes | yes |
+| Letta Code (`letta-code`) | reads brain's key file (a provider mod; local agents only) | yes | from its source |
+| Mastra Code (`mastracode`) | copy in its settings, private | no | from its source |
+| Mistral Vibe (`mistral-vibe`) | copy in `~/.vibe/.env`, private | yes | yes |
+| Oh My Pi (`omp`) | reads brain's key file | yes | from its source |
+| OpenHands (`openhands`) | copy in its settings, private | yes | yes |
+| PearAI (`pearai`) | copy in `~/.pearai/.env`, private | yes | from its source |
+| Pi (`pi`) | reads brain's key file | yes | yes |
+| Qwen Code (`qwen-code`) | copy in `~/.qwen/.env`, private | yes | yes |
+
+"Checked with the real tool" means the real program, pointed at a local stand-in gateway, sent its request to the gateway's
+route with the key and the gateway's model, and `disconnect` gave every file back byte for byte (its original mode too).
+
+Some tools cannot be pointed at the gateway from a file brain can safely write and cleanly undo, so they have no connector:
+Cursor and the Cursor CLI, Windsurf, Antigravity, Amazon Q, Kiro, Auggie, Tabnine, Devin and Muse Code (their vendor's own
+servers only); Zed (the key only in the keychain or its launch environment); Void (settings encrypted in the app's state);
+Roo Code and the Cline extension (they keep the key in the editor's own storage, so disconnect could not take it back);
+Codebuff and Qoder (custom endpoints only through their own sign-in or the keychain). The reason and its source are in each
+tool's file under `src/gateway/connectors/`.
+
+Gemini CLI loads only the first `.env` it finds from the project folder up: in a project with its own `.env`, put the
+gateway lines there or export them. Letta Code uses the gateway for its local agents only (cloud agents call models from
+Letta's servers). Tools that read brain's key file stop working after `logout` until the next `login`; Kilo refuses to start
+without it.
+
+## Dashboard
+
+Signed in to the gateway, brain sends a short report of this machine to your 100xprompt account, shown in the console's
+Brain view (https://100xprompt.com/dashboard?view=brain): the coding tools found here, their session counts, which are
+connected to the gateway or have brain's MCP tools and hooks, your gateway settings, memory counts, and every chat brain
+moved from one tool into another (when, from and to which tool, the way, its title and its project folder's name). Never
+chat text, file contents, full paths or keys.
+
+```bash
+brain dashboard              # count sessions, send the report now, open the Brain view (--no-open prints the address)
+brain dashboard status       # on or off, and when the last report went out
+brain dashboard off          # send nothing from this machine (brain dashboard on to start again)
+```
+
+The report goes out in the background, at most every 30 seconds, after a command that changes it (`gateway login`,
+`connect`, `disconnect`, `session continue`, `handoff`, `mcp install`/`uninstall`, `session hooks install`/`uninstall`),
+and never makes that command wait or fail. The first time, brain prints what it sends and how to stop it.
+`BRAIN_NO_REPORT=1` also turns it off. The conversion log is `~/.brain/logs/conversions.jsonl`, readable only by you.
+
+## Teams
+
+Memory can live on one shared server instead of each person's machine, with who may see what enforced there.
+
+```bash
+# on the server (it needs Chitta: bun add -g @100xprompt/chitta)
+brain org admin init --db org.db --org-id acme --org-name Acme --admin-id ana --admin-name Ana   # once; prints the admin token
+brain org admin serve --db org.db --host 0.0.0.0 --allow-remote --tls-cert cert.pem --tls-key key.pem
+
+# on each person's machine
+brain org login --server https://<server>:4500 --token <token>
+brain org promote --source <session> --to team --team backend
+```
+
+Every item has a scope: `private` (the default; only its owner, not even an admin), `project`, `team` or `org`. Sharing
+is an explicit, logged act. Roles are `viewer`, `editor` and `admin`; admins set policy (widest scope, paths and terms that
+are never shared, retention) and read the audit log. Only distilled, secret-filtered memory items cross the wire: never
+full tool output, raw turns or attachments. With no login, brain stays entirely local.
+
+`admin serve` listens on 127.0.0.1 unless told otherwise: to reach it from other machines, use `--allow-remote` with TLS
+(`--tls-cert`/`--tls-key`), or keep it local behind a TLS proxy (`--trust-proxy`). An encrypted database (`init
+--encrypt`) also needs `libsql` installed next to Chitta. `brain org help` lists every option.
+
+## Safety
+
+- Reading a session never changes a tool's files: SQLite stores are copied (with their write-ahead logs) and the copy is
+  read. To see which version is installed, `targets` and `--dry-run` start each installed tool with `--version`.
+- Continuing always writes a **new** session; the source is never changed, so switching back is continuing the original.
+- Writers check the installed tool version against the one their format was verified on, and fall back to the brief otherwise.
+- `--dry-run` shows what would be written. Hooks, MCP entries and gateway settings are merged with your own, backed up
+  first, and removed exactly by the matching `uninstall` or `disconnect`.
+
+## Commands
+
+```
+brain session list | show | export | continue | handoff | targets | hooks
+brain memory ingest | search | status | forget | sync
+brain mcp serve | install | uninstall | status
+brain tokens audit | lookups
+brain gateway login | logout | connect | disconnect | status | tools
+brain dashboard [push | on | off | status]
+brain org login | logout | whoami | status | promote | demote | forget | admin ...
+brain expand <id>
+brain --version
+```
+
+`brain --help` lists every command with its main options; `brain gateway`, `brain mcp` and `brain org help` show the rest
+of theirs.
+
+## Known limits
+
+- Built and tested on macOS. Linux and Windows are not tested yet.
+- Each writer is checked against specific versions, for example Claude Code 2.1.296 to 2.1.319 (a newer 2.1.x is
+  accepted with a note), Codex 0.147.0, Gemini CLI 0.33.1 and 0.67.0, Cursor 3.27 and 3.29, VS Code 1.144 with Copilot
+  Chat 0.72, OpenCode 2.2.6, Zed 1.26.2 and 1.27.0, Aider 0.86.2. A tool at another version gets the brief instead.
+- Into Codex: tool names from Claude Code (`Read`, `Grep`, `Agent`, MCP calls) stay as they are, and subagent transcripts
+  are not carried. Pasted images are.
+- Into Claude Code: reasoning and subagent transcripts are not written.
+- Cursor is reached through its own import of Claude Code sessions (for the folder it has open), not by writing to
+  Cursor's database; the brief opens in Cursor's chat when that is not possible.
+- Session-start hooks were checked against each tool's installed code, not yet inside every live tool. Codex asks you to
+  trust a new hook once.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@100xprompt/brain",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "One working session, any AI coding tool: move sessions between Claude Code, Codex, Cursor, Gemini CLI, OpenCode and more, keep what projects learned, spend fewer tokens. Runs on Bun. By 100xprompt.",
+  "license": "MIT",
+  "author": "Nipurn Agarwal",
+  "homepage": "https://www.npmjs.com/package/@100xprompt/brain",
+  "keywords": [
+    "ai-coding",
+    "coding-agent",
+    "claude-code",
+    "codex",
+    "cursor",
+    "gemini-cli",
+    "opencode",
+    "session",
+    "handoff",
+    "context",
+    "memory",
+    "mcp",
+    "tokens",
+    "100xprompt"
+  ],
+  "type": "module",
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "bin": {
+    "brain": "./src/cli.ts"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "brain": "bun run src/cli.ts",
+    "test": "bun test --timeout 60000",
+    "typecheck": "tsc --noEmit -p .",
+    "wire": "bun wire/run.ts"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.4.4",
+    "oidc-provider": "9.13.3",
+    "typescript": "5.8.2"
+  }
+}

package/src/adapters/aider/index.ts

@@ -0,0 +1,8 @@
+import type { Reader, Writer } from "../types.ts"
+import { aiderReader } from "./reader.ts"
+import { aiderNativeWriter } from "./writer.ts"
+
+// Aider: reads each run of a project's .aider.chat.history.md as a session, and continues any session as a
+// new run in that history, which `aider --restore-chat-history` hands to the model.
+export const readers: Reader[] = [aiderReader]
+export const writers: Writer[] = [aiderNativeWriter]

package/src/adapters/aider/reader.ts

@@ -0,0 +1,129 @@
+import { createHash } from "node:crypto"
+import { readFileSync, statSync } from "node:fs"
+import { dirname } from "node:path"
+import type { Session, Turn } from "../../session/types.ts"
+import { header, lossCounter, noteModel } from "../../session/util.ts"
+import type { Reader, SessionRef } from "../types.ts"
+import { CONTINUED_NOTE, LABEL, SUMMARY_PREFIX, TOOL, type Run, assistantText, findHistories, parseRuns, userText } from "./records.ts"
+
+// Aider sessions. Aider has no session list or ids: every project keeps one history file and each launch
+// appends a run to it, so a run ("# aider chat started at ...") is read as one session. That is also what
+// a launch without --restore-chat-history sees: a fresh chat. Ids are made from the file and the run's start.
+
+/** "2026-11-08 10:00:00" (local time, as Aider writes it) → ISO. */
+const runTime = (stamp: string | undefined) => {
+  if (!stamp) return undefined
+  const t = new Date(stamp.replace(" ", "T"))
+  return Number.isFinite(t.getTime()) ? t.toISOString() : undefined
+}
+
+const fileKey = (path: string) => createHash("sha1").update(path).digest("hex").slice(0, 8)
+
+/** The id of a run: the file's key and the run's start (YYYYMMDDhhmmss), with its index when two share a second. */
+export function runId(path: string, run: Run, runs: Run[]): string {
+  const stamp = (run.startedAt ?? "00000000000000").replace(/\D/g, "")
+  const twin = runs.filter((r) => r.startedAt === run.startedAt).length > 1
+  return `${fileKey(path)}-${stamp}${twin || !run.startedAt ? `-${run.index}` : ""}`
+}
+
+/** Runs that hold conversation, not only Aider's startup notices. */
+const talked = (run: Run) => run.messages.some((m) => m.role !== "tool")
+
+function readText(path: string): string {
+  try {
+    return readFileSync(path, "utf8")
+  } catch (e) {
+    throw new Error(`cannot read the Aider history ${path}: ${(e as Error).message}`)
+  }
+}
+
+/** One run as a portable session. */
+export function runSession(path: string, run: Run, runs: Run[], updatedAt?: string): Session {
+  const id = runId(path, run, runs)
+  const h = header(TOOL, id, { sourcePath: path, project: { cwd: dirname(path) }, startedAt: runTime(run.startedAt), updatedAt })
+  const lost = lossCounter()
+  const turns: Turn[] = []
+  for (const [i, m] of run.messages.entries()) {
+    if (m.role === "tool") {
+      // Aider's own notices: never sent to the model. Kept: the model it ran, its version, and the files it edited.
+      for (const line of m.content.split("\n")) {
+        const model = line.match(/^(?:Main model|Model): (\S+)/)?.[1]
+        if (model) noteModel(h, model)
+        const version = line.match(/^Aider v(\d+\.\d+\.\d+\S*)/)?.[1]
+        if (version) h.toolVersion ??= version
+        const edited = line.match(/^Applied edit to (.+?)\s*$/)?.[1]
+        if (edited) turns.push({ kind: "file_edit", path: edited })
+      }
+      continue
+    }
+    if (m.role === "user") {
+      const text = userText(m.content)
+      if (!text) continue
+      const note = i === run.messages.findIndex((x) => x.role === "user") ? text.match(CONTINUED_NOTE) : null
+      if (note) {
+        h.parent = { id: note[1]!.replace(/[.,]$/, ""), kind: "continued" }
+        continue
+      }
+      if (text.startsWith(SUMMARY_PREFIX.trim())) {
+        turns.push({ kind: "compaction", summary: text.slice(SUMMARY_PREFIX.trim().length).trim() })
+        continue
+      }
+      turns.push({ kind: "user", text })
+      continue
+    }
+    const text = assistantText(m.content)
+    if (text) turns.push({ kind: "assistant", text, ...(h.models.length ? { model: h.models[h.models.length - 1] } : {}) })
+  }
+  if (!turns.some((t) => t.kind === "user" || t.kind === "assistant")) lost.add("runs with only Aider's own notices")
+  lost.flush(h)
+  const first = turns.find((t) => t.kind === "user") as Extract<Turn, { kind: "user" }> | undefined
+  if (first) h.title = first.text.replace(/\s+/g, " ").trim().slice(0, 80)
+  return { header: h, turns }
+}
+
+export const aiderReader: Reader = {
+  tool: TOOL,
+  label: LABEL,
+
+  async list(home: string): Promise<SessionRef[]> {
+    const refs: SessionRef[] = []
+    for (const path of findHistories(home)) {
+      let text: string
+      let mtime: string | undefined
+      try {
+        text = readFileSync(path, "utf8")
+        mtime = statSync(path).mtime.toISOString()
+      } catch {
+        continue
+      }
+      const runs = parseRuns(text)
+      runs.forEach((run, i) => {
+        if (!talked(run)) return
+        const next = runs.slice(i + 1).find((r) => r.startedAt)
+        const first = run.messages.find((m) => m.role === "user" && !CONTINUED_NOTE.test(userText(m.content)))
+        refs.push({
+          tool: TOOL,
+          sourceId: runId(path, run, runs),
+          path,
+          cwd: dirname(path),
+          updatedAt: (next ? runTime(next.startedAt) : mtime) ?? runTime(run.startedAt),
+          ...(first ? { title: userText(first.content).replace(/\s+/g, " ").trim().slice(0, 80) } : {}),
+          extra: { run: run.index },
+        })
+      })
+    }
+    return refs.sort((a, b) => (b.updatedAt ?? "").localeCompare(a.updatedAt ?? ""))
+  },
+
+  async read(ref: SessionRef): Promise<Session> {
+    const runs = parseRuns(readText(ref.path))
+    const run = runs.find((r) => runId(ref.path, r, runs) === ref.sourceId) ?? runs.find((r) => r.index === ref.extra?.run)
+    if (!run) throw new Error(`no run ${ref.sourceId} in the Aider history ${ref.path}`)
+    let updatedAt: string | undefined
+    try {
+      updatedAt = statSync(ref.path).mtime.toISOString()
+    } catch {}
+    const next = runs.slice(run.index + 1).find((r) => r.startedAt)
+    return runSession(ref.path, run, runs, next ? runTime(next.startedAt) : updatedAt)
+  },
+}